Before you perform a migration

Before migrating configuration between Catalyst builds, understand which data is copied, which data stays in the Target build and which items need to be set up separately. A migration updates supported configuration; it does not copy the entire Source environment.

Understand the types of data in a Catalyst environment

A Catalyst environment contains four main types of data:

1. Configuration data: System settings and operational configuration.
2. User data: User accounts and related information, including credentials and user permissions.
3. Record data: Object Records and associated information, such as tasks and record permissions.
4. Authentication data: Settings relating to single sign-on and authentication with third-party systems.

A migration copies supported configuration data only. User, record and authentication data are preserved in the Target build rather than being copied from the Source build. There are specific exceptions and mapping behaviours for user assignments, user groups and authentication-related configuration, described below.

The following configuration data is migrated

The Admin Portal migrates these configuration items:

• Object Classes, including:
  • Fields.
  • Display (Views).
  • Forms.
  • Document templates.
  • Permissions, including class and record permission sets.
• Relational modeller configuration.
• Task Templates and Task Group Templates.
• Sequences.
• Integrations.
• Landing page configuration.
• Roles.
• User groups (without their members), including:
  • Permission sets.
  • Permission set assignments.
  • Object Class field (user type) assignments.
• User assignments, subject to the user-matching rules below:
  • Role assignments.
  • Permission set assignments.
  • Object Class field (user type) assignments.
  • Sequencer default task assignments.
  • Task assignment actor Users selections.
  • Send Message actor Users selections.
  • Record Access actor Users selections.
• Company Details.
• Standard authentication configuration.
• Elements.
• Outbound mail setup.

The entries above describe supported configuration, not a copy of the associated live data, user accounts or third-party credentials.

Additional notes: considerations for specific configuration items

Records and their associated tasks

Records and their associated tasks are never migrated. This keeps development or test records in their original environments while live records remain in the live environment.

Authentication Objects

Authentication Objects are not migrated or overwritten. However, Authentication Objects in the Source build must have corresponding objects in the Target build with exactly the same names, even if the Target objects have not yet been fully configured.

During migration, the objects are mapped by name. If a required Authentication Object is missing from the Target build, the migration will fail.

For example, both builds may contain an Authentication Object named DocuSign:

• The Source build may connect to a development, test or sandbox DocuSign environment.
• The Target build may connect to the live DocuSign environment.

Both objects must exist and have the same name, but their environment-specific credentials and settings are not copied over each other.

Authentication Objects are commonly used by Outbound mail setup and API Calls, including connections to third-party services.

Single sign-on

Single sign-on configuration is never migrated. Set it up and test it independently in each build.

Theme

Themes are not migrated. Configure the theme separately in each build.

Users

User accounts, user group membership and user field options are not migrated.

However, certain selections of existing users within configuration can be migrated, including default task assignees, Record Access actors and Send Message actors, where those users exist in both Source and Target builds.

If the selected user does not exist in both builds, the existing Target configuration is retained, even when the Target selection is blank.

This distinction is important: migration may carry over a reference to a user in a configuration field, but it does not create or copy the user account.

User groups

User groups are migrated and matched by name; their membership is not migrated. Configuration that uses user groups—for example, permission settings and Send Message actor selections—can also be migrated.

For example, a user type field named Fee Earner may allow selection from a user group named Fee Earner. The field's user group configuration is migrated, but the Source group's members are not. Source and Target builds can therefore have different users in their respective groups.

Renamed groups in the Source build

If a user group has been renamed in the Source build, migration treats the updated name as a new group:

• A new group with the updated name is created in the Target build, unless a group with that name already exists.
• The old Target group, under its previous name, is removed only if it is unused: it has no members and is not referenced elsewhere in configuration.

Existing groups in the Target build

If a group with the same name already exists in the Target build, the existing group is not modified or deleted, even if its internal ID differs from that of the group in the Source build.

This name-matching rule is specific to user groups; do not assume it overrides the ID requirements that apply to other configuration objects.

Other items to check before migration

• System limits: These do not migrate. Changes must be separately requested for the Target build after they have been checked and tested in the Source build.
• Configuration IDs: Conflicting IDs or field aliases can cause the migration to fail. See The importance of IDs.
• Source and Target selection: Verify that the Source build contains the approved configuration and that the Target build is correct.
• Downtime: All migrations must take place outside working hours; the Target build is likely to become unavailable during the process.

Useful info

For the actions to complete immediately before and during a migration, use Performing a migration.