Promoting Forms Between Environments

Overview

This article explains how to transfer forms between your Mirata environments and recommends best practices for each one. In practice, you'll move forms only from Dev to QA and from QA to Production, a process we call promoting forms.

You have three different Mirata environments:

Development (Dev) - Use this for form development
QA - Use this for testing form development. BEST PRACTICE: Move forms to QA only when they are ready for testing. Avoid moving forms in a non-testable state.
Production (Prod) - This is the version your end-users will have.

Migration of Different Admin Tool Elements

Migration from one environment to another occurs in the Admin Tool and is essentially a download/upload process. Below summarizes how to move each type of element.

Element	Move Method
Users	Must keep in sync manually (no download/upload)
Groups	Must keep in sync manually (no download/upload)
Roles	Must keep in sync manually (no download/upload)
Form Types	Must keep in sync manually (no download/upload)
Data Tables	Download/upload
Integration Actions	Download/upload
Connection Info	Download/upload
Dashboards	Download/upload (must provide destination)
Scheduled Jobs	Download/upload
Submission Queries	Download/upload
Form Definitions	Download/upload (must provide destination)
Templates	Download/upload (must provide destination)
Integration Data Mappings	Download/upload
Images	Download/upload

Best Practices

Perform all form development in Dev. DO NOT make any changes directly in the Designer within QA or Production. Always make changes in Dev and then promote to QA and Production using the process described in this article.
DO NOT rename elements once they have been promoted to QA. This prevents ID mismatches between environments, as further explained in the example below.
Always test the forms in the destination environment Inbox once they're moved over to make sure everything was moved over properly.

Promoting a Form Definition to Another Environment

This example demonstrates the typical process of migrating a form between a Dev and a QA environment.

Follow Upload Order

Ensure you upload in the prescribed sequence in step (2) below.

(1) Downloading from Origin Environment

(1.1) Locate Form Definition

In the Admin tool, navigate to the Forms Catalog tab.

In the Forms Catalog, go to the Forms Definitions section by clicking on the first icon on the left pane.

Next, simply find and click on the form that will be migrated. In this scenario the form that is being moved is called 'Test Form 1 Adam.' Once the form is selected, a pane should appear on the right side of the screen (the Form Definition Preview) that looks like the following:

(1.2) Set Environment Destination

Expand the Dependencies dropdown in the Form Definition Preview pane. The origin environment is already populated and not editable. You must enter the Destination, which is the name of the destination environment.

Don't Forget to enter the Destination.

How do you know the name of the destination environment? You can always find the name of the environment you're in by looking in the very bottom right corner. In the below example, the Destination is "mirata-demo".

Typically, your environments will be named like: "mirata-dev", "mirata-qa", and "mirata-prod", where "mirata" is replaced with your company name. Still, it's best practice to double check environment names, because this isn't always the case.

In this example, we're transferring the form definition from mirata-dev to mirata-qa, so we enter the destination like this:

(1.3) Download Zipped Folder

In the Dependencies section, you can view all elements used by this form definition, including other form definitions. Although you can uncheck elements that you don't wish to download, it's usually best to leave them all checked. By default, all elements are checked.

Now that the Destination is populated, it's time to download the form so that it can later be uploaded to the destination environment. On the bottom of the Form Preview Pane, there will be a button that says DOWNLOAD FILE. Click this button.

Once you click this button, there will either be one of the following downloaded to the computer that is being used:

A singular .mfd file. This occurs when the form does not have any dependencies other than the definition.
A ZIP folder (more common). This occurs when the form has dependencies other than the definition. Within the downloads section of the computer, it is necessary to unzip the folder to access all files that were necessary to be migrated.

Here is an example of what the file may look like if downloaded without any dependencies (a single .mfd file):

(1.4) Unzip The Folder

Unzip the folder in your files. This process is slightly different on iOS vs. Windows, but most computers require you to unzip the folder before you can select the files in step 2.

(2) Uploading to Destination Environment

It is now time to navigate to the new environment that the form will be moved to. In this case, it is the mirata-qa environment.

(2.1) Upload in recommended order

It's recommended to upload in the follow order:

Make sure Groups, Roles, and Form Types in the Security tab match those in the original environment. You need to keep them in sync manually as there's no upload or download feature.
Form Definitions
Data Tables
Other elements

Applies to all elements

The below example is for form definitions but the same process works for all elements.

(2.2) Upload Form Definition

Navigate to the Admin tool, and again find the Forms Catalog tab. Once in the Forms Catalog tab (and on the Form Definitions section), there will be an option to "+ ADD FORM" located on the top right of the screen. You will upload through the +ADD FORM button even if this form definition is already present in this environment.

Once the "+ ADD FORM" button is clicked, this window should be visible:

Click the grey box that says "Drag files here, or click to select files" to access the files stored on the computer. If there was a single .mfd file downloaded, simply select the file from the downloaded file. If a ZIP folder was extracted, navigate inside the unzipped folder to find the .mfd file. This process should automatically prohibit the upload of non-.mfd files.

Click GENERATE NEW

Once the file is selected, the following should appear on your Definition Upload screen:

Match Names with IDs

It's important here to double check that the name matches the ID. For example, you DO NOT want the Name to be "Test Form" and the ID to be mirata-qa.form.test-form-1. If they do not match, then someone updated the Name of the form definition in the origin environment after it was created. It's best practice at this point to update the Name in the origin environment so it matches the ID and re-download the files.

The last thing to do is to set the form type. This depends on the form types that are available in the environment, but usually it will be known what form type is necessary prior to migration. In this scenario, the form type is "Mirata Form Type". You should check that the Form Types in QA match Dev before uploading the form definition.

If you add a new form type, you might need to log out and back in to the admin tool to see it in this dropdown.

The last step is to simply hit the "UPLOAD" button at the bottom right of the screen.

If the form definition is already present in the environment, you'll be prompted to decide if you want to override it. Click Yes to proceed.

Once this is done, the new form is viewable in the Forms Definition screen and the Version is incremented by 1.

(2.3) Move Data Tables

If your form references any data tables, upload those tables too. This involves two steps:

First, upload the data table schema
Second, go to the RECORDS tab of the data table and upload the records.

If the data table already exists in the destination environment and you want to update the records in the table, it's recommended to delete the data table and re-upload it new. When doing this, BE SURE that you've (1) downloaded the latest copy from the origin environment and (2) you're deleting it from the correct destination environment.

Similarly, move any related elements such as integration actions and submission queries.

(3) Test in Inbox

As there's many moving pieces and it's possible to miss a step, it's a best practice to always test the forms in the destination environment inbox to ensure everything was moved correctly.