Migration object types and dependencies

Learn more about the object types and the dependencies between the types of objects that you can migrate from source to target instances. 

Understanding dependencies in migrations

When you migrate the configuration of an instance to a target instance, it is important that you understand the dependencies between the various items that can be migrated. For example, when you migrate a saved search, you must make sure that all the referenced fields in the business object already exist in the target instance. 

The illustration below shows the dependencies between the various objects:

The validation of dependencies is built into the migration process. To discover dependency violations before you run the migration, you always run the migration in test mode and then you migrate the objects.

Because of the dependencies between the object types, you must migrate the following objects in this order:

1. Data model
2. Roles
3. Screen designs: Web and mobile
4. Saved searches 

Then, you migrate the following objects in this order:

1. Dashboards and widgets
2. Workflows
3. Credentials
4. Global settings
5. Integrations

Dependencies and package migrations

Dependencies between types of objects in package migrations are automatically handled. 

Data model fields

When you migrate an object, such as assets or people, you migrate the configuration of the complete object. The migration can create fields and update fields, but it can’t archive fields in the target instance.

Note
In standalone migrations, you can also select the fields that you want to migrate except for custom system objects such as Currency. For custom system objects, you must migrate all of the fields.

The system will trigger the migration of the selected data model fields. Depending on the size of these objects and the number of objects, this may take some time. 

Roles

When you migrate roles, the role record and its details are migrated from the source to the target instance. This includes all of the authorizations assigned to the role, but not the screen designs, which must be migrated separately. 

Remember

When authorizations depend on specific user attributes, you must migrate the data model fields before you migrate the roles. As with data model fields, existing roles are updated and new roles are added. For roles that were archived, you must also archive them in the target instance. 

Screen designs

Web

When you migrate the web screen design, you can migrate the screen builder settings for a specific role and object to the target instance. The settings for the web user interface are migrated, not the actual mobile screen design. To combine the Roles and Objects for the migration, you use two drop-down lists. You can select multiple combinations to migrate to the target instance. The screen design can only be migrated for primary user interface roles or stand-alone roles.

Create and update operations are supported. Archive operations aren’t supported. To archive a web screen design for a role, log into the target instance and archive the screen design.

Best practice

To avoid data inconsistencies, migrate the objects and roles before you migrate the screen design for an object and role.

Mobile

Mobile screen designs can be migrated before or after Web screen designs because they are not interdependent. While Web screen designs apply to multiple data model fields such as assets, users, and software, mobile screen designs only apply to assets. When you define a mobile design screen by user role, you drag and drop various actions such as add, edit, copy, and search depending on the use case. When you add an action, you can click the action and configure the list of fields that will be displayed on the mobile device.

Let's say, you want to create a screen design for a monitoring role. In such a scenario, you might add edit and search actions and then provide field-level information such as the status, the location, and the received date .

Saved searches

You can migrate selected saved searches in your source instance to your target instance. Only public saved searches can be migrated. Private saved searches can't be migrated. New and updated saved searches are migrated. Saved searches that were archived in the source instance, must also be archived in the target instance. 

With saved searches, it is not necessary that both source and target instances are kept in sync.

Best practice

Create common public saved searches in the source instance and migrate them to the target instance. Saved searches that you reference in subscriptions, data exports, and so on should be created in the source instance.

Dashboards and widgets

You can migrate only new dashboards and widgets to the target instance. You can’t archive dashboards and widgets. To archive dashboards and widgets, you must log into the target instance and archive them. This prevents widgets that were locally added in the target instance from being overwritten or archived by accident.

Like saved searches, dashboards and widgets can be created in your source instance and migrated to your target instance or created in your target instance. 

Workflows

You can migrate workflows to your target instance. And, you can thoroughly test the workflows in your development instance before you migrate them to your production instance. If you use API blocks or global setting references in the workflows that you want to migrate, ensure that these settings also exist with the same names in your target instance. Otherwise, you must update the settings in the target instance after you run the migration. 

Credentials

You can migrate one or more credentials from your source to your target instance. For security reasons, only the shell of the credential record is migrated. That is, the container for the record, which includes the name and description, but not the actual credentials. After you migrate credentials, you must log into the target instance and enter the credentials such as the username and password, API token, and so on. This enables you to design the same workflows and integrations in both instances that reference the same credentials, but access different instances by using credentials and global settings.

API tokens that you generate in Oomnitza are specific to that Oomnitza instance. Let's say you migrate credentials that use an Oomnitza API token from a development or test Oomnitza instance to a production instance. In the production instance, you must edit the credentials and replace the Oomnitza API token with a new API token that you generate in the production instance.     

Global settings

Only new global settings are migrated. Existing global settings and their values aren’t updated during the migration process. This means that you can define different values for global settings for each instance. For example, in your development and production instances, you can connect to different subdomains for specific integrations. 

Integrations

You can migrate extended connector Integrations, including the field mappings and all the other settings to a target instance. Basic connector integrations, which are being replaced with extended connector integrations, can’t be migrated to a target instance. 

Important

If you created parent and child extended connector integrations, you must migrate the parent integration before you migrate the child integrations.

When you migrate an integration, and you include the username for an integration user, you must ensure that the integration user also exists in the target instance and has the appropriate privileges in the target instance to run the integration. 

Best practice

Switch from basic connector integrations to extended connector integrations as soon as they are available.