Migration objects

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:

Custom objects
Business objects
Roles
Screen designs: Web and mobile
Saved searches

Then, you migrate the following objects in this order:

Dashboards and widgets
Workflows
Credentials
Global settings
Integrations

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

Custom objects

Migrating custom objects works like migrating standard business objects. You always migrate the entire object as individual records can’t be migrated. The migration can create fields, but not archive fields in the target instance.

Business objects

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

The system will trigger the migration of the selected business objects. 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 business objects before you migrate the roles. As with business objects, 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 inter dependent. While Web screen designs apply to multiple business objects 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.

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.

Migration overview
Planning the migration
Migrating standalone objects
Migrating packages