Help & DocumentationSystem AdministrationMaintenance Managing Multiple InstancesMigrate Metadata from One Metric Insights Instance to Another (Manual Version)

Migrate Metadata from One Metric Insights Instance to Another (Manual Version)

It is possible to migrate metadata from one instance to another using Import/Export Utility. The idea is that you have a development instance for creating and testing new Elements. Once those Elements are ready for production you can push them from the development system to one or more production systems. This utility can also be used to copy Elements between multiple production instances.

The migration procedure comprises the following processes:

  1. Export (dump) an Element definition from a source instance (for example, development environment) to a .tar.gz file.
  2. Import (load) an Element definition to a target instance (for example, production environment) from a .tar.gz file.
  3. Revert import (rollback) to a bring the target instance to a previous migration state.

All import and export changes are stored in Import/Export History section.

Additionally, Import/Export Utility can work in conjunction with Export Locations allowing for import to and export from a GitHub repository.

The list of metadata supported for migration:

  • Elements
  • Datasets
  • User maps
  • Portal Pages (including Layouts, Templates, and Assets)
  • Bursts
  • Folders
  • Custom Fields
  • Email Templates

The article includes the following sections:

The Data Source for the migrated metadata must exist in both environments.

Export Procedure

The export procedure can be:

  • Custom: manually choose a metadata directly in Export Editor and then export it. This article describes Custom Export.
  • Scheduled: manually preselect metadata for export in object Editors and them export it on demand via [Run Scheduled Export]. The process is very similar to custom migration. For more information on Scheduled Migration, refer to this article.

1. Create New Export Operation

Access Admin > Utilities > Import/Export

Select [+New Custom Export]

2. Select a Metadata Type to Be Exported

This example shows adding a Portal Page, but the process is intuitive and essentially the same for other types.

NOTE: Dependent Portal Page Layouts, Templates, and Assets will be added to Export automatically.

  1. Select the required metadata via the corresponding add button
  2. [Start Exporting].
    • The objects included in the export list will be automatically downloaded as one .tar.gz archive as shown on the screen below.

Export Exceptions and Limitations

Element
  • An Element is migrated with its Custom Fields and their Sections.
  • An Element displays correct value sourced from a Dataset that uses a User Map after the migration.
Dataset

It is not possible to migrate CSV Datasets with it's data. When an Element with a Custom Field sourced from CSV Dataset is imported, there will be no data in the Dataset and no values in the Custom Field (linkage to Dataset and column remains).

Custom Field
  • A Custom Field is migrated with its values (also values that are selected in an Element) and a Section it belongs to. If the Section is imported from a source instance, but there is already the Section with the same name on a target instance, the Section will be updated.
  • A Custom Field Section is migrated without Permissions and only with those Custom Fields that are added to the export list.
  • A Custom Field is migrated without its Elements.
  • All new or updated Sections are located at the bottom of the Custom Field Sections list.
  • If a Custom Field is included in, for example, Risk Section on a source instance and the same Custom Field has, for example, Default Section on a target instance, then after the migration it will exist in the migrated Risk Section.
  • If a Custom Field uses Source Dataset for values on a source instance, the Dataset will be migrated with the Custom Field to a target instance. If the Source Dataset uses a User Map on a source instance, the User Map will be migrated with the Dataset and the Custom Field to a target instance.
  • All Custom Fields settings are migrated for all Custom Fields types (Single, Multi, Text).
  • While migrating a Custom Field with "User" type, the system searches for values of this Custom Field by a username.
  • After the migration the Custom Field Editor linkage to Dataset, column and hyperlink is the same as on a source instance.
  • History tab of an imported Custom Field becomes empty on a target instance after the migration process .
Portal Pages

Portal Pages can be migrated along with all types of Entities:

  • Dataset Entity and Dataset itself;
  • Data Source Entity (with linkage to the selected Data Source if it exists on a target system);
  • Custom Script Entity and Custom Script itself, including all parameters;
  • Internal Entity with correct settings.

Exceptions:

  1. Git credentials are not migrated with Portal Page.
    • If a Portal Page is created on a target system upon import, Git credentials won't be migrated.
    • If a Portal Page is updated on a target system upon import, Git credentials won't be updated.
  2. If Portal Page A inherits access of Portal Page B and Portal Page A is imported to a target system, then Portal Page B won't be migrated. If Portal Page B exists on a target system, access will be inherited.
Logic of Overriding Matching Metadata

When metadata is imported from one instance to another, the system searches for the matching records by comparing data in the source_system_name and source_system_element_id columns of the instance database table and import archive. If there is matching data, the element is over-ridden with a version from the import archive.

If there is data mismatch in source_system_name and source_system_element_id but the element_id on the import instance has been already reserved, the Element is imported with a new vacant element_id.

Migration Logic for Email Templates

Email Templates are migrated without Permissions and attached Dataset(s). If you want to include the branding images into the migration process, they must have the following format:  

<img src='$IMAGE:{"type":"branding","file":"<%=digestTemplate.utf8_to_b64('mdlz-footer.png')%>"

A target instance is checked against a pair of conditions "Name-Type" and:

  1. if an Email Template of any type (Default/Not-Default) is migrated from a source instance and there is no Email Template with the same name and type on a target instance, then a new non-default Template will be created on a target system.  
  2. if an Email Template is migrated from a source instance and there is Email Template with the same name and type on a target instance, the Template on a target system will be updated with the information form the source system.  

Configure an Export Location to Import a .tar.gz File to a GitHub Repository

You can create a default export location for storing .tar.gz files in it. Every time when a .tar.gz file is exported, it is added into this location automatically. Then you can import the .tar.gz file from it to a GitHub repository. If you have several default locations, the .tar.gz file is added into all of them.

1. Create an Export Location

Access Admin > Utilities > Export Locations

  1. [+ New Export Location]
  2. Enter an Export Location name
  3. [Save]

2. Configure an Export Location

  1. Specify if you want to Use this Export Location as default for All Exports
  2. Enter the GitHub username
  3. Provide the GitHub email address
  4. Type in the GitHub password
  5. Specify the repository URL for uploading the exported .tar.gz files
  6. Optionally, enter the repository subfolder for uploading the exported .tar.gz files
  7. Optionally, provide the repository branch name. Since you can have several versions of the exported .tar.gz files, it is possible to keep them in different branches.  Enter the repository branch name
  8. Optionally, enter a tag to fetch a specific version
  9. Optionally. The webhook works only in case GitHub can send notifications to a specific server that is not secured by VPN. If you do not want to synchronize the local repository manually, enter the webhook secret. In this case, when an exported .tar.gz file is downloaded to the repository, the repository sends a corresponding notification to an URL specified in Payload URL field in GitHub under the Webhook section
  10. [Save]

3. Choose the Files for Import

Access the Files tab of the required Export Location

  1. If you have not added the webhook while configuring an Export Location, click [Synchronize Local Repository]
  2. Click the .tag.gz file that you want to import

6. Import the .tar.gz File to a GitHub Repository

  1. If this .tar.gz file includes User Maps, enable Overwrite Existing Usermaps to create new User Maps if they don't exist on a target system. Existing User Maps will not be updated.  
  2. Enable If object exists: When match on ID is not possible, match on name if you want the system to update the existing object with the same name, but with a different ID
  3. Choose when Data for these elements is to be collected
  4. [Import]

Import Procedure

1. Create New Import Operation

Access Admin > Utilities > Import/Export

  1. [+ New Import]
  2. [Browse] and choose the downloaded .tar.gz
  3. If this .tar.gz file includes User Maps, enable Overwrite Existing Usermaps to create new User Maps if they don't exist on a target system. Existing User Maps will not be updated.
  4. Enable If object exists: When match on ID is not possible, match on name if you want the system to update the existing object with the same name, but with a different ID
  5. Choose when Data for these elements is to be collected
  6. [Import]

2. Check the Imported Metadata

  1. Once the import is generated, the success message with the list of elements is displayed
  2. [Done]

It is recommended to check each Element message and ensure that there are no errors. The fact is that there may be inconsistencies between available Data Sources across staging and production environments which will cause the Element to have an error when attempting to refresh.

Rollback Procedure

1. Revert an Import Operation

Access Admin > Utilities > Import/Export History

  1. Click the arrow icon next to required imported .tar.gz file
  2. [Revert]

Access Import/Export History Section

There are 2 ways to access Import/Export History:

From the Status Monitor Screen
  1. Click Import/Export History
  2. Click [a new location]
From the Admin Menu

Access Admin > Utilities > Import/Export History