Migrate Elements / Datasets / User Maps from one Metric Insights instance to another (manual version)
The Import/Export Utility is a tool to push elements and their related objects from one Metric Insights instance to another. The idea is 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 only caveat when using this function is that the data source for the migrated element must exist in both environments.
This article covers:
Export Procedure - from MI Instance
1. Access Admin > Utilities > Import / Export
Migration is a two step process:
- Export ('dump') the element definition from the source instance (for example, development environment) to a gzip compressed tar archive.
- Import ('load') the Element definition to the target instance (for example, production environment) from the gzip compressed tar archive.
2. Create an Export file with all the necessary data (Elements, Datasets, User Maps)
- In the Import/Export screen click [+ New export]
- Next, you have a choice of adding elements, Datasets, User Maps for export.
The Add Elements to Export Package List pop-up opens.
2.1. Selecting Element(s)
- You may filter filter results by keywords, Category, Dimension or Data Source
- Check the boxes for the elements to be exported
- Click Add to list
2.1.1. Selecting Datasets
Along with the Dataset itself, you also choose which elements built from this Dataset should be included in the export.
- Choose the Dataset from the drop-down list at the top of the pop-up.
- Check the boxes for the elements to be exported.
- Click Add to list. The Dataset is to be added to the Export list.
To add more Datasets, repeat the procedure.
2.1.2. Selecting User Maps
Along with the User Map itself, you also choose which elements to which this User Map is applied should be included in the export.
In the given example, there are no elements to which this User Map is applied, but we still want to export it for further usage.
- Choose the User Map from the drop-down list at the top of the pop-up.
- Click Add to list. The User Map is to be added to the Export list.
To add more User Maps, repeat the procedure.
3. Creating the Export
- Note that selected Elements, Datasets, User Maps appeared in the respective sections
- Click Start exporting at the bottom of the page
4. Download the Archive
- Once the export is generated, the success message with the list of elements is shown
- The file is automatically downloaded to your machine
- Optionally, download the archive for use in the Metric Insights instance where you would like to import the content
1. Import the Archive to a new Instance
- Now open the instance of Metric Insights where you would like to import the elements and navigate to Admin > Utilities > Import/Export
- Click [+ New import]
The Import Elements pop-up opens.
1.1. Choose a file for download
- Click Browse and choose the archive exported from another instance to your local machine.
- Overwrite Existing Usermaps: If this import archive includes User Maps with names identical to the ones on the current instance, should the User Maps on the current instance be overwritten?
- Select when Data for these elements is to be next collected.
- Click Import and the elements / Datasets / User Maps will be uploaded into your new instance.
1.1.1. Check for Imported Elements
- Once the import is generated, the success message with the list of elements is shown.
- If the entity could not be imported, hover over the error message to see the error.
We recommend navigating to the element list and ensuring that the migrated elements have no errors. The reason being 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.
Logic of overriding matching elements
When elements are 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 file. If there is matching data, the element is over-ridden with a version from the import file.
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.