Importing and Exporting a model

The model Export/Import feature makes it possible to transfer a platform configuration from one environment to another.

A typical use case is maintaining separate pre-production and production environments. Configuration changes can first be implemented and validated in pre-production, then exported and imported into production when ready.

Availability

For information about availability or activation, contact the relevant CSM.

What is part of the model?

It contains configuration elements such as:

• Concepts and fields

• Automations

• Integrations and connectors

• Workflows

• Etc

Some instances can also be considered part of the model.

For example, a workflow status may rely on instances of a Status concept. These status instances define the workflow itself and therefore belong to the model rather than to the business data entered by end users.

Other instances correspond to actual business data created on the platform and are not intended to be transferred between environments.

For each concept, it is therefore important to determine whether its instances are part of the model and should be included in the export.

Export scope

The model is currently exported and imported as a whole. Individual configuration elements such as specific concepts, automations, or workflows cannot be selected independently.

The configurable scope concerns concept instances: instances can be included or excluded from the export.

This distinction is particularly important because importing instances modify data already present in the destination environment.

Export requirements

Platform version

A model can only be imported into an environment running the same platform version as the environment from which it was exported.

Required permissions

The account performing the export and import must have view, create, and edit permissions on all concepts whose instances are included in the export.

During the export, only instances visible to the account performing the operation can be included in the exported model.

These permissions must therefore be available in both the source and destination environments for all concepts concerned by the instance export.

How instances are matched

Import and export rely on UUIDs to identify instances across environments.

When the instances of a concept are included in an export, the import compares the exported instances with those already present in the destination environment based on their UUIDs.

For an instance with the same UUID:

• The existing instance is preserved

• Its values are updated according to the imported model.

For an existing instance with a different UUID:

• The instance is removed when the imported model includes the instances of that concept.

UUIDs cannot be manually changed after instances have been created. Matching is therefore particularly relevant when environments originate from the same initial environment.

Embedded instances

Embedded instances depend on their parent instances.

If an embedded instance has a parent that is not included in the export, the embedded instance cannot be transferred independently. As a result, it is not included in the exported model and will not be imported into the destination environment.

Associations between instances

To transfer associations from the source environment to the destination environment, the instances of both associated concepts must be included in the export.

If the instances of only one of the two concepts are included, associations from the source environment are not transferred.

However, associations already present in the destination environment may be preserved.

When an exported instance already exists in the destination environment with the same UUID, the existing instance is updated rather than deleted and recreated. As a result, its existing associations with instances of concepts excluded from the export are preserved.

For example:

• Instances of concept A are included in the export

• Instances of concept B are excluded from the export

• An instance A1 exists in both environments with the same UUID

• In the destination environment, A1 is already associated with an instance B1

During the import, A1 is updated rather than recreated. The existing association between A1 and B1 is therefore preserved.

If an instance of concept A does not have the same UUID in the destination environment, it will be removed and replaced by the exported instance. In this case, its existing associations are not preserved.

Users and administrator access

The user concept is the only concept whose instances cannot be imported or exported.

This prevents the import process from transferring users between environments.

The account performing the import also always retains administrator access. If the imported configuration would otherwise leave this account outside every administrator group, an administrator group is added to ensure that access to the platform is preserved.

User groups

Groups can be part of the imported model even though users are not.

When groups are imported, existing groups are matched using their UUIDs. When the same group UUID exists in both environments, existing relationships can be preserved.

However, newly imported groups do not automatically contain the users from the source environment, since users themselves are not transferred.

After an import that creates or changes groups, group memberships in the destination environment should therefore be reviewed. Users may need to be added to the appropriate groups to restore the expected access to platform content.

Fields excluded from duplication

Individual fields can be configured with the Exclude from duplication option.

When this option is enabled, the field value is not transferred when an instance is duplicated. The same behavior applies to model import and export.

For an exported instance:

• Values from standard fields are included in the export

• Values from fields marked Exclude from duplication are not transferred

This is particularly useful for environment-specific values.

For example, a singleton may contain the URL of the current platform so that it can be reused as a constant in automations or emails. Since the URL differs between pre-production and production, the corresponding field can be excluded from duplication.

When a new singleton is introduced through an import and one of its values is excluded from duplication, that value will be empty in the destination environment. The environment-specific value must therefore be configured after the import.

Automation status

The enabled or disabled status of automations is included in the model export and applied during the import.

As a result, an automation enabled in the source environment will also be enabled in the destination environment after the import. Depending on the destination data and configuration, this may cause automations to be triggered unintentionally.

Automations disabled in the source environment remain disabled after the import. For example, automations intentionally disabled in pre-production before an export must be re-enabled in production after each import when they are expected to run there.

Automation statuses should therefore be reviewed before exporting and after importing a model.

Connectors

Connector configuration is partially transferred as part of the model.

The import includes:

• Mappings

• JSON configuration.

Environment-specific constants and secrets are not imported.

Any required connector constants or secrets must therefore be configured in the destination environment after the import.

Applying mapping changes

If an import only changes a connector's mapping, the connector must be restarted for the new mapping to take effect.

Refer to the relevant connector documentation for instructions on how to restart the connector.

Understanding the import summary

Before an import is applied, a summary displays the number of instances that will be created or otherwise affected.

These numbers may be higher than expected because the term instance has a broader technical meaning in this summary than in the usual platform terminology.

For example, in a dashboard:

• A widget is counted as an instance

• Each view associated with a card widget is also be counted as an instance

The number displayed in the import summary therefore does not necessarily correspond to the number of business instances visible through the standard platform interfaces.

After an import

Several checks should be performed after importing a model:

• Review user group memberships. If groups were created or changed by the import, ensure that users in the destination environment belong to the appropriate groups.

• Configure environment-specific singleton values. Values marked Exclude from duplication are not transferred and may need to be populated manually.

• Configure connector constants and secrets. Connector mappings and JSON configuration are imported, but constants and secrets must be defined for the destination environment.

• Restart connectors when required. If only a connector's mapping was changed by the import, restart the connector for the new mapping to take effect. Refer to the relevant connector documentation for restart instructions.

• Validate access and configuration. Confirm that the imported model behaves as expected in the destination environment.

Key considerations

Model import/export is primarily designed to synchronize configuration between environments, such as pre-production and production.

Because some instances can themselves be part of the model, the boundary between configuration and business data must be defined carefully for each concept.

In particular, including a concept's instances means that the imported environment is expected to align with the exported model for that concept. Existing instances with different UUIDs may be removed.

Before running an import, the import summary and the instance scope should therefore always be reviewed carefully.