You can use data preservers to protect data on the target instance from being overwritten. If you have custom applications, you must also manually preserve unpublished application content.

Data preservers

Sometimes, it is necessary to preserve some data on an instance targeted for cloning. For example, if the target is a MID Server, you must not overwrite the MID Server [ecc_agent] table. Preserved data is stored on the target instance before cloning begins and is restored on the target instance after cloning.
Warning: You must define data preservers on the source instance. Defining them on the target instance does not preserve the data.
Data preservers typically preserve system settings and themes, such as:
  • Instance-specific authentication settings
  • Bookmark [sys_ui_bookmark]
  • Recent Selection [sys_ui_recent_selection]
  • User Preference [sys_user_preference]
Note: A clone does not support preserving data from a database view.

Do not use data preservers to transfer large sets of data, such as user groups. If you must preserve table data, such as users, groups, and roles, consider exporting the records to a file and importing them after cloning.

Data preservers for Multi-SSO

The system automatically creates the necessary data preservers for cloning when you activate Multiple Provider Single Sign-On integration.
Note: Although you can modify these data preservers, it is good practice not to. The Digest Properties [digest_properties], Identity Providers [sso_properties], and SAML2 Update1 Properties [saml2_update1_properties] tables are required for multiple source, single sign-on (SSO) to function properly. If multiple source, single sign-on is disabled on the target instance, you can safely remove all three data preservers. Remove them at the same time, as the system terminates the clone with an error message when you attempt to clone with one or two of these tables being preserved.

Data preservers for SAML

Preserving SAML SSO-related settings can prevent the target instance from using the wrong issuer and audience parameters when making authentication requests to your IdP. To preserve SAML settings, create data preservers for the following tables:

  • System Property [sys_properties]: to preserve SAML properties.
  • X.509 Certificates [sys_certificate]: to preserve SAML certificates.
  • User [sys_user]: to preserve SAML users.

You also need to preserve properties and users that are involved in SAML.

Preservation of unpublished applications

You cannot use data preservers to save unpublished applications. Instead, application developers must choose how they want to preserve unpublished applications.

The cloning process does not preserve version differences for applications in development. Instead, the system clone only copies the application version installed on the source instance onto the target instance. If the target instance had a development version of the same application, the application will be editable after the clone, but it will be at whatever version was installed on the source instance. If the application was missing from the source instance, the cloning process deletes the application from the target instance.

Create a data preserver

Data preservers maintain specified data on a target instance.

Before you begin

Role required: clone_admin or admin

About this task

Sometimes, preserving certain data on a target instance is desirable. For example, when using a MID Server, you can avoid overwriting the MID Server [ecc_agent] table. Preserved data is stored in a dynamically generated list on the target instance before the clone and restored on the target instance after the clone is complete. You define data preservers on the source instance.

Data preservers are primarily intended to preserve system settings and themes, such as instance-specific authentication settings. Do not use data preservers to transfer large sets of data, such as user groups. If you must preserve table data such as users, groups, and roles, consider exporting the records to a file and importing it after the clone is complete.

Consider whether to preserve the data in the following tables.
  • Bookmark [sys_ui_bookmark]
  • Recent Selection [sys_ui_recent_selection]
  • User Preference [sys_user_preference]

If you set a data preserver on a table where the source instance has more records than the target instance, the data preserved on the target instance also includes the additional records from the source instance.

For example, assume that the data preserver is already in place.
  • In the source instance, the sys_temp table contains 100 records.
  • In the target instance, the sys_temp table contains 20 records.
After the clone, the sys_temp table in the target instance contains 100 records.
  • The 20 records in the target sys_temp table are preserved successfully (per the data preserver specification). These records were part of the 100 records in the source sys_temp table.
  • The source sys_temp table brings over the remaining 80 records to the target sys_temp table.

To resolve this issue and to preserve only the records in the target table, create an exclude table record for the target table, in addition to setting the data preserver on the source table.

Important: Configure preservers on the source instance.

Procedure

  1. On the source instance, navigate to System Clone > Preserve Data.
  2. Click New.
  3. Enter the table label as the Name, for example, User Preference for the [sys_user_preference] table.
    The data preserver must have a table name or it cannot be submitted.
  4. Select the Table to be preserved.
    The data preserver must have a table selected or it cannot be submitted.
  5. Select the Theme check box if the data being preserved is a UI property.
  6. Define the data to be preserved using the Condition Builder .
    You can use conditions to define particular records you want to preserve during a clone. For example, to only preserve particular system properties, you can add conditions for each property name you want to preserve.
    Note: The condition to match regular expressions [match regex] is no longer supported.
    Data preserver with conditions
    Warning: If the clone from backup fails for some reason, the clone process fails over to the legacy clone engine. The legacy clone engine cannot preserve data from extended tables, relationships, hierarchies between tables, and dot-walked queries. You may want to reschedule a system clone or manually transfer data in such cases.
  7. Click Submit.
    If you want to delete the data preserver later, make sure not to modify or delete the following data preserver records:
    • Core Instance Properties
    • Semaphores
    • Email Accounts
    Note: DB views cannot be preserved.

    Preservers cannot be empty, and users will not be able to submit the clone if preservers are empty.

Preserve SAML properties

If you want a clone target instance to keep its existing SAML integration, you must edit the Core Instance Properties data preserver to include the SAML properties.

Before you begin

Role required: admin

Procedure

  1. Navigate to All > System Clone > Preserve Data.
  2. Select Core Instance Properties.
  3. Add the following Conditions.
    • [OR] [Name] [is one of] [glide.authenticate.external, glide.authenticate.external.logout_redirect, glide.authenticate.failed_requirement_redirect]
    • [OR] [Name] [starts with] [glide.authenticate.sso.saml2]
    • [OR] [Name] [starts with] [com.snc.integration.saml_esig]
    SAML system property preservation
    Note: Ensure the Theme check box is cleared so these properties are preserved regardless of whether you preserve the instance theme.
  4. Click Update.

Preserve applications and customizations in development during a system clone

Manually preserve a copy of each application and customization that you currently have in development before you can clone the application version to the target (development) instance.

Before you begin

Ensure that you have write access to the application record.

Ensure that you have access to a source control repository.

Role required: admin

About this task

The cloning process does not preserve version differences for applications and app customizations in development. Instead, the system clones only the copies of the application and app customization versions that are installed on the source instance onto the target instance. If the target instance had a development version of the same application, the application is editable after the clone, but is at the version that was installed on the source instance. If the application was missing from the source instance, the cloning process deletes the application from the target instance.

Procedure

  1. To preserve the application on the clone target instance, do one of these actions:
    Table 1. Version differences between instances
    Application version state Action to take
    The application version on the clone target instance is different than the source instance version. Export each application from the clone target instance. The choices include:
    • Link each application to a source control repository.
      Note: If the application is already linked to a source control repository, commit the latest version to it.
    • Publish each application to an update set.
    The application is available only on the clone target instance.
    The application version on the clone target instance is the same as the source instance. None. The system clone process copies this application version onto the target instance during the clone.
  2. Request a system clone of the source instance to the target instance.
    For example, clone your production instance over your development instance.
  3. After the clone process finishes, log in to the clone target instance.
  4. Note: If source control is linked, then post clone, the platform will automatically retrieve applications and customized applications. If this is disabled via glide.source_control.post_clone_import_enabled you will need to manually retrieve by doing the following.
    If you saved each application to a source control repository, use one of these actions to retrieve them from the source control repository:
    Note: For what to expect after application customization post clone, see Results post cloning for application customizations.
    Table 2. Retrieve applications from a source control repository
    Application installation state Action to take on clone target
    The application and customization were previously installed on the source instance. Apply remote changes from the source control repository.
    The application was never installed on the source instance. Delete the repository configuration (sys_repo_config) and import the customization from the source control repository.
    Table 3. Remote changes after clone
    Field Description
    glide.source_control.post_clone_import_enabled To disable the apply remote changes automation, set to False. The default is True.
    glide.source_control.post_clone_import_delay_time_sec To provide a delay time, which will delay processing of the queue, provide a value. The default is zero.
    glide.source_control.post_clone_import_pause_refresh_time_sec To provide an interval in which the refresh repository job will not run, provide a value. The default is three hours (10800).
  5. If you saved each application to an update set, do one of these actions to retrieve them from the update set:
    Table 4. Retrieve applications from an update set
    Application installation state Action to take on clone target
    The application was previously installed on the source instance.
    1. Delete the application version that was cloned from the source instance.
    2. Load the update set that contains the current application version.
    The application was never installed on the source instance. Load the update set that contains the current application version.

Result

The applications previously in development are available for further development on the clone target instance.

Example: Preserve the Marketing Events application

Let's say that your company previously created version 1.0 of a custom application called Marketing Events. You have already published version 1.0 of the Marketing Events application to the application repository and installed it on your production instance.

Over time, users have submitted enhancement requests for the application, and you decide to develop version 2.0 of the Marketing Events application on a non-production instance to address these requests. As development nears completion, you want to update your non-production instance to the latest copy of production for some comprehensive testing.

Because you previously used a source control integration to develop version 1.0 of the Marketing Events application, you have already linked the Marketing Events application to a source control repository. You commit version 2.0 of the Marketing Events application to the source control repository.

You schedule a clone of the production instance over the development instance. After completion, you log in to the development instance and see that it has version 1.0 of the Marketing Events application, because that was the version installed on the source instance.

Because the application was already installed on the source instance, you apply the remote changes from the source control repository to receive the latest application version. The development instance now has version 2.0 of the Marketing Events application and is available for further development and testing.