Scripted Migration Utility

It is possible to Migrate Content using our Export/Import Migration Scripts that enable System Admins to setup a content migration pipeline. The article shows an example of how to migrate content from one server to another.

The Scripted Migration process includes two main stages:

Content Export via run.py export
Set Migration for Categories, Folders, Elements, Datasets/User Maps or Portal Pages via their Editors

Migration Capabilities

NOTE: Root privileges are required to run Migration.

MI Elements and Objects	Scripted Migration	Details
Metrics	can be migrated	BEFORE MIGRATION, on the new instance make sure to: Recreate Dimensions for all dimensioned Elements that are migrated. Recreate Dimensions for all Elements with Filters mapped to Dimensions. Establish connectivity to all BI tools (by creating respective connection profiles) that serve as Data Sources for migrated Elements/Objects.
Reports	can be migrated
External Reports	can be migrated
Datasets/Users Maps	can be migrated
Categories	can be migrated
Folders	can be migrated
Apps (Portal Pages)	can be migrated
Bursts	can be migrated
Email Templates	can be migrated
Groups	can be migrated
Business Units	can be migrated
Privilege Sets	can be migrated
Brands	can be migrated
Custom Fields	can be migrated
Dimensions	can be migrated	ALL OBJECTS AND ENTITIES that cannot be migrated directly have to be rebuilt on the new instance.
Plugin Data Sources	NOT SUPPORTED

Key Migration Dependencies

Migration Dependencies
Element/Object IDs	Object/Element IDs are preserved unless there are identical IDs on the new server. In case of existing duplicates, migrated Objects and Elements will be assigned new IDs.
Data Sources	If the migrated content was sourced from a Dataset, the Dataset will be ">Technical/Business Owners	Migrated Objects and Elements will retain their Technical/Business Owners if these Users exist on the new instance. Search for User matches is performed first by email and, if there are no hits, by Username. If there are no matching Users, Migrated Objects/Elements will be assigned a new Owner (the first admin that is found on the new server).

1. Exporting Content

Exporting content involves creating a .tar.gz file with information on all migrated Elements/Objects that can later be uploaded to a different server.

All associated Documents/Previews/Attachaments/JS Templates can be exported in an archive as separate files.

To initiate export, run the following command:

python3.12 /opt/mi/migration-tool/run.py export -c 86 -f  /<directory>/<archive name>.tar.gz

where:

python3.12 is a Python Interpreter (installed during the installation of the MI application);
/opt/mi/migration-tool/run.py is a migration script;
export is a command which should be performed;
-c 86 is a Category parameter followed by Category ID;
-f parameter specifies the name for the output archive;
<directory> where the dump file will be created;
<archive name>.tar.gz is a user-defined archive name.

To export a Category (as an example):

Run run.py export with the desired parameters.
The response of the script will contain an integer, which is the migration_export_log table ID. The table along with migration_export_log_entitiy contains details about the export.
- NOTE: In case of fatal errors, the response will return an error text message. This may happen when the program is not able to connect to the DB or some system migration tables were absent (or corrupted).
Optionally, verify that the Category was saved to the tar.gz archive with the name you specified.
Optionally, view the contents of the exported tar.gz archive.
- In an archive, Documents are stored by Number IDs.
- The actual Document names are stored inside a .json file.

1.1. Optional Parameters for Export

The list of arguments to use at export
-h, --help	Show help message and exit
-e ELEMENTS [ELEMENTS ...], --elements ELEMENTS [ELEMENTS ...]	IDs of Elements
--bursts BURSTS [BURSTS ...]	Burst IDs to dump (space-separated)
-d DATASETS [DATASETS ...], --datasets DATASETS [DATASETS ...]	IDs of Datasets
-f FILE_NAME, --file_name FILE_NAME	Output file name
--exclude-access-maps	Do not export any dependent access maps
--folders FOLDERS [FOLDERS ...]	Folder IDs to dump (space-separated)
--group-sharing	Include sharing user groups for migrated objects
-c CATEGORIES [CATEGORIES ...], --categories CATEGORIES [CATEGORIES ...]	Category ID to dump (space-separated)
-g GROUPS [GROUPS ...], --groups GROUPS [GROUPS ...]	Group IDs to dump (space-separated)
-p PORTAL_PAGES [PORTAL_PAGES ...], --portal-pages PORTAL_PAGES [PORTAL_PAGES ...]	App (Portal Page) IDs to dump (space-separated)
--dimensions DIMENSIONS [DIMENSIONS ...]	Dimension IDs to dump (space-separated)
--digest-templates DIGEST_TEMPLATES [DIGEST_TEMPLATES ...]	Digest Template IDs to dump (space-separated)
--business-unit BUSINESS_UNIT [BUSINESS_UNIT ...]	Business Unit IDs to dump (space-separated)
--privilege-sets PRIVILEGE_SETS [PRIVILEGE_SETS ...]	Privilege Set IDs to dump (comma-separated)
--custom-fields CUSTOM_FIELDS [CUSTOM_FIELDS ...]	Custom Field IDs to dump (comma-separated)
--brands BRANDS [BRANDS ...]	Brand IDs to dump (comma-separated)
--include-folders	If an Element is included in Folder, but that Folder has not been explicitly selected for export, this flag will automatically include the Folder along with the Element.
-s, --scheduled	Include scheduled migration
--skip_external_report	Do not dump External Report
--skip_documents	Do include dump Documents in the outcome archive
--skip_other_external_content	Do not dump Other External Content
-db DB_NAME, --db_name DB_NAME	Database schema name
--update_folder_elements	Update the Folder during the width:47.6936%;">--dump_external_images	Dump the External Report collected images
--folder-backup	Provide backup for a specific Folder. Export folder with related Users, Groups, and Elements. During width:47.6936%;">--text_note [TEXT_NOTE]	Export Notes
--freeze-page-variables	Ignore existing App (Portal Page) Variables on target
--involve-targets	Involve targets for the migrated Element
--update-custom-fields	Forcibly update Custom Field metadata

To migration_ID. The table along with the migration_and migration_tables contains details about the "> The list of arguments to use at background-color:rgb(239, 239, 239);">-h, --help Show this help message and exit -f FILE_NAME, --file_name FILE_NAME

File to load elements from




--test_output
Output as Python dict (for development purposes only)


--restore RESTORE


MigrationRollback PK value




-b BACKUP_DIR, --backup-dir BACKUP_DIR
Directory to back up changed records to


--preserve-access-map
Do not overwrite access map configuration


--burst_create_only
Create new Bursts only. Do not update existed Bursts


--new_entity_topics_only
Create topic only for new entities (Elements, Datasets, Portal Pages, Bursts). Skip topics for existing records


--use_category_owner
For new Elements/Datasets, Owner are set to Category owners. For existing records, Owners are not updated


--reset_certification
For new Elements/Datasets, certified attribute is set to 'N' (reset_certification, last_certified_time as well). For existing records, certified attribute is not updated


-s, --strict
Delete Elements/Topics in the target Category if they are not in the source Category


-m, --match
Load matching Elements


-r, --relax
Keeping data on target system


-n, --no-preserve


Do not preserve IDs


-db DB_NAME, --db_name DB_NAME


Database schema name




--accept_different_versions


Ignore the difference between the system version and the income archive version




--link-groups-to-profiles


Link existing User Groups to migrated branding profiles



      
    3. Rolling Back
      
  
    The rollback command allows users to cancel the  delete
update –> update to the state previous to the 
delete –> restore 

The rollback operation works with the Objects that were involved in ">
The list of arguments to use at rollback


-h, --help


Show this help message and exit


--force
Force rollback for DB-operations




 
  
 
  

      
    4. If Migration Runs with Errors
      
  
    In case Migration runs with errors:

Verify that all the Migration Prerequisites have been met (For details, check the Script Response and Output).
Having eliminated the cause of errors, rerun the upload script to update Migration results.

     Prev: 4.7 Removing a Patch  
   Next: 5.2 Exporting Objects with Import/Export Utility

     Topics
     1. Backing Up and Restoring Metric Insights 4 
    1.1 Backup Your Metric Insights Instance   
  1.2 Restore Your Metric Insights Instance  
  1.3 Clear Metric Insights Data  
  1.4 Creating a System Backup through the UI  
 
 
 
   2. Software Downloads and Licensing 2 
    2.1 Metric Insights License Keys  
  2.2 Access Software Downloads and License Keys via Get MI  
 
 
 
   3. Mail Clients and Browsers supported 1 
    3.1 Mail Clients and Browsers Supported  
 
 
 
   4. Managing your Metric Insights Instance 7 
    4.1 How to Replace an OVA  
  4.2 Confirm that Login Credentials Were Not Corrupted During Upgrade  
  4.3 Connect to Metric Insights server from Windows  
  4.4 Common Problems running Metric Insights virtual machine on Laptops  
  4.5 Moving the MI Database to a Remote DB Server (v6.2+)  
  4.6 Applying Hot Fixes with the Patcher  
  4.7 Removing a Patch  
 
 
 
   5. Managing Multiple Instances 7 
    5.1 Scripted Migration Utility  
  5.2 Exporting Objects with Import/Export Utility  
  5.3 Export Exceptions and Limitations  
  5.4 Configuring Export Location  
  5.5 Importing Objects with Import/Export Utility  
  5.6 Upload/Download App (Portal Page) Assets  
  5.7 Best Practice: Establishing Content Migration Policies  
 
 
 
   6. Monitoring Metric Insights 9 
    6.1 Status Monitor UI  
  6.2 System Notifications for Disk and Database Health  
  6.3 Elements with Errors  
  6.4 Overdue Trigger  
  6.5 Cron is not running  
  6.6 Memory Tables  
  6.7 Track Users Clicking on Links from Emails via ALLOW_EXT_LINK_TRACKING  
  6.8 Track Content Engagement Counts  
  6.9 Audit Log  
 
 
 
   7. Error Codes 7 
    7.1 DP-101: Cannot Connect to Storage Engine  
  7.2 Tableau Error Codes  
  7.3 ThoughtSpot Error Codes  
  7.4 WebDriver Error Codes  
  7.5 MicroStrategy Cube Error Codes  
  7.6 Power BI Error Codes  
  7.7 Domo Error Codes  
 
 
 
   8. Upgrading Metric Insights 1 
    8.1 Applying System Upgrades  
 
 
 
 
 
   Last Updated
 May 28, 2025
 
    
  
  
 Metric Insights on YouTube 
 Watch our videos 
  
 
 
   Other Resources
     Getting Started 4 
   Metric Insights Overview 
 Jump Start Guide for Administrators 
 Jump Start Guide for Regular Users 
 Use Case Workflows 
 
 
 
   Getting Data 9 
   Connecting to Data Sources 
 Sourcing Data from Plugin Data Sources 
 Sourcing Data from SQL Data Sources 
 Automating the Collection of Data 
 API Access 
 Working with Tableau 
 Working with Qlik Sense 
 Working with Microsoft Power BI 
 Working with Google Services 
 
 
 
   Creating Content 8 
   Datasets 
 Creating Basic Metrics and Reports 
 Creating Dimensions 
 Creating Dimensioned Metrics and Reports 
 Governance 
 Apps (Portal Pages) 
 Concierge Service 
 User Maps 
 
 
 
   Alerting 1 
   Alerting  
 
 
 
   Collaboration and Sharing 3 
   Adding Context to Metrics 
 Pushing Information to Users 
 Chatbot Integrations 
 
 
 
   System Administration 11 
   Announcements 
 Controlling Access to Metric Insights 
 Controlling Access within Metric Insights 
 Customer Portal 
 Deployment & Configuration 
 FAQs 
 How-to Videos 
 Identity Profiles 
 Maintenance 
 Managing the Metric Insights Environment 
 Release Notes