This article lists all steps to migrate an Incorta solution from one environment (Dev or UAT) to another environment (UAT or PROD).
What you should know before reading this article
We recommend that you be familiar with these Incorta concepts before exploring this topic further.
These concepts apply to all versions 4.5+ and version 5.0 of Incorta for customers who implement Incorta on-premises or in their own cloud.
Setting up a New Environment
Suppose you have your development tenant ready, and you want to move it to UAT, or you want to set up your Production environment for the first time. You have two options at this stage:
- Export the full tenant and import it to the new installation.
- Export the objects (data sources, schemas, dashboards) that you want to promote from the Dev environment selectively and import them to a fresh tenant in UAT or Prod.
If your Dev environment is clean enough, and does not have many extra schemas and dashboards, we suggest you go for option 1, because it is easier and takes less time. You may have to do some clean up after importing the tenant, but that should not be hard. This can be done the first time you are setting up the UAT (or Prod) environment of course. After the first migration, using option 2 is usually the better option so as not to introduce unwanted configurations into your upper, and in theory, cleaner environments. If your Dev environment has a lot of extra objects or you are only ready to migrate a subset of the objects you have built, we suggest you go for option 2 even the first time you are creating a new environment.
Migrating a Full Tenant
If you are migrating from UAT to Prod, and you are planning to keep the same data source name in Prod as in UAT then you can migrate the full tenant, using export/import, for a faster migration. Incremental migration/overwrite of schemas and dashboards will work fine after this from UAT to Prod, without having to export/import the full tenant every time you want to change any of these two types of objects. Here are the steps for a full tenant migration:
- Suppose you have a tenant called MyDevTenant in Dev, and you want to import it to UAT, and name it MyTestTenant.
- Export the full tenant from Dev using /tmt.sh --clnm <cluster name> --export MyDevTenant Dev_backup.zip
- $ cd <incorta_home>/cmc/tmt
- $ ./tmt.sh --clnm <cluster name> --export MyDevTenant Dev_backup.zip
- Move the file to the UAT machine
- Import the tenant into UAT, using
- $ cd <incorta_home>/cmc/tmt
- $ ./tmt.sh --clnm <cluster name> --import Dev_backup.zip -on MyTestTenant -op <new tenant’s path>
- The option -op allows you to specify a new path for the tenant’s folder. This is part of the installation, which may be different in UAT compared to Dev.
- The option -on allows you to rename the tenant. You can skip this option if you want to keep the same name as in Dev.
- Similarly, you can change the admin username and pwd during this import if you like. For additional information on parameters you can provide during the import, please check Incorta documentation.
- Restart Analytics service to confirm loading of tenant
- Change the source database(s) to point to the new UAT data source(s). Please note that it can be very burdensome to update all the tables if you change data source names, therefore we suggest you choose the consistent data source names from the beginning, so you do not have to change them when migrating from Dev to UAT or to Prod.
- Copy all required data source files (csv/xlsx) from the Dev environment (<IncortaHome>/tenants/MyTestTenant/data) to the UAT environment (<IncortaHome>/tenants/MyUATTenant/data). Data files are not exported with the tenant.
- Import users, groups and user/group assignments from Production database (if different from UAT ones). This can be done using the scripts ldap_sync, db_sync or self_sync available under <IncortaHome>/IncortaNode/bin directory.
- Notice that users created during testing will be exported as part of the tenant export. Running the sync script in the new environment will not remove them from the UAT tenant. If the test groups are not in the UAT LDAP server, the users will be removed from the old groups in UAT, so they will lose access to the dashboards and schemas they had access to in Dev environment.
- Share dashboards with groups. Incorta recommends sharing all objects like schemas and dashboards with groups not users. This will make it easier to add new users and share objects without having to do it for every individual user. You just need to group users the right way, so all users in the same group will share the same set of dashboards (or schemas).
- When sharing objects, you have the option to give members of a group View only privilege, or Share (View + Share) or Edit (View + Share + Edit) privilege.
Migrating Objects Separately
If you have a running UAT instance, you can migrate new/modified objects of the following type by using Command Line Interface (CLI) commands. This allows the Incorta administrator to schedule the migration of objects developed in UAT to Production on a preset schedule and without having to access Incorta through the URL. Objects of the following types can be migrated:
- Data Sources
- Session variables
- Physical schemas
- Business Schemas
All the commands for these actions can be found on the Incorta Documentation site, under the CLI Guide. Here is a general description of the steps for this style of migration:
- Go to <IncortaHome>/IncortaNode/bin directory
- Find file incorta.sh. It contains sample scripts for export and import of most object types.
- If you cannot find the right command for your object type, look in the same folder for a different sample file, like export_session_variable_sample.sh and export_datasource_sample.sh.
- Create another shell file for exporting your objects from test tenant. Since the connection information of the source and target Incorta environments has to be hard coded as a parameter in the script, you will need one for export and one for import.
- Create a separate shell file to import the same objects to the UAT tenant.
- Please notice that when importing schemas, you need to add the ‘true’ option at the end, to overwrite any existing schema with the same name already in UAT.
- If you want to preserve scheduled refresh jobs in UAT for the same schema, please make sure you export the schema without the scheduled jobs from Dev.
Validation After Migration
It is important to check a few things after a migration to verify that nothing has been broken
- After every migration, make sure to test all data source connections
- After every migration, make sure to test all session variables.
- If a business schema is modified after an initial migration, please make sure you update it in the target environment. It is important to keep Physical schemas, Business schemas and Dashboards in sync at all times.