Planning the migration

To ensure that the migration of the configuration of your source instance completes successfully, you must prepare and configure your source and target instances.

Review the following information, and complete the actions:

 Determine the number of instances

Enable the migration

Ensure that the source and the target instances are identical

Create a migration user

Create an API key for the migration in the target instance

Add the credentials for the migration in the source instance

Add the target instance and the credential name as global settings in the source instance

Ensure that the source and target instances have the same version

Disable configuration changes in the target instance

Action 1: Determine the number of instances

Typically, two instances are sufficient, a development instance and a production instance. Three instances, such as development, staging, and production instances are required only for complex environments.

Action 2: Enable the migration

Submit a request to Oomnitza Support to enable the migration from the source instance. The source instance is the instance where the configuration changes were implemented. For example, to migrate configuration changes from a development instance to a production instance, the development instance must be enabled.

Action 3: Ensure that the source and the target instances are identical

You must start with clean copies of the instances that are included in the migration. Migration only works if the instances, such as the development and the production instance are in sync. This means that all of the objects must be identical. For example, each field in the Data Model has not only the same field name, but also the same unique database identifier. For new customers, Oomnitza deploys identical instances at start-up. Existing customers, who have added additional instances, might want to start by submitting a baselining request to Oomnitza Support which involves copying the configuration of the production instance to the development instance.

Action 4: Create a migration user 

Create a dedicated migration user to perform migrations from the source Oomnitza to the target Oomnitza instance.

To create the migration user, you must log in to the source Oomnitza instance.

When you create the migration user, ensure that you follow these guidelines:

• Username. Create a token user. For username, you do not enter a real email address or an email with a suffix ending in oomnitza.com. For example, you can enter a token username such as [e-mail].
• Role. To perform the migration successfully, you must select the Super Administrator role. 

Adding people records

Action 5: Create an API key for the migration in your target instance

The migration user must have full access privileges to the configuration of the source and the target instances. 

When the migration is run, the migration user will be automatically recorded as the user that ran the migration and the user that changed the migration in the target instance.

Complete these actions:

• Generate an API key.
• Use the API key to create the migration account. 

Generate the API key

To generate an API token, log in to the target instance and complete these steps:

1. Click Configuration > Security > API tokens.
2. Click + to add a new token.
3. Enter the name of the token.
4. Enter the name of the user to whom the token will be assigned.
5. Click SUBMIT. 

The API token is displayed once and cannot be recovered.

For further information, refer to Creating an API token

Action 6: Add the credentials for the migration to Oomnitza in the source instance

In the source instance, add the credentials of the user for the migration to the Oomnitza vault. The credentials that you add to the source instance will point to the target instance, such as your production instance. 

Procedure

1. From the menu, select Configuration > Security >Credentials.
2. Click Add new credential (+).
3. Click Advanced Mode.
4. Enter the name of the credentials such as Migration_To_55. 
5. Enter the owner of the credentials.
6. Click the AUTHORIZATION tab.
7. From the Authorization type list, select API Key. 
8. Enter Authorization2 as the name of the token.
9. Enter the API key that you created in the target instance.
10. Ensure that Add to Header is selected from the Add to list.
11. Click Create.

Action 7: Add the target instance and the credential name as global settings in the source instance

In the source instance, complete these actions.

Add the address of the target instance as a global setting

1. From the menu, select Configuration > General > Global Settings.
2. Click Add new variable (+).
3. Input "migrations.subdomain" as the key name without making any changes to the value. It is important to keep this key name exactly as provided and avoid replacing it with your own subdomain.
4. Enter the address of the target instance as the value.
   

   Example
   Let’s say the address of the target instance is https:// {target_instance} .oomnitza.com You enter the name of the target instance.

5. Click SAVE.

Add the name of the migration credentials as a global setting

1. Repeat steps 1 and 2 above.
2. Enter migrations.credential as the name of the variable.
3. Enter the name of the credentials that you created in the source instance to connect to the target instance.
4. Click SAVE.

Action 8: Ensure that the source and target instances have the same version

The version of the release for the source and the target instances must be the same.

The source and the target instances might be on different release versions for a short period, which can range from a few days to a maximum of two weeks. If the instances have different versions, you’ll get an alert, and the migration will be paused. 

Tip
To view the version of your instance, click User Settings .

Action 9: Disable configuration changes in the target instance

To avoid making changes in the target instance that prevent you from running the migration, you can disable configuration changes in the target instance. 

When you disable configuration changes in the target instance, you will not be able to add or update the customization for objects, change roles, and so on. You can still add saved searches and dashboards.

Procedure

1. Login to the target instance.
2. From the menu, select Configuration > General > Global Settings.
3. Click Add new variable (+).
4. Enter migrations.disableConfig as the name of the variable and set the value to 1.
5. Click SAVE.

Best practice
Disabling configuration changes in the target instance is not mandatory, but it is best practice.

Result

When you complete the planning for migration actions, you’re ready to start the migration.