Configuration Management - Import

In this topic, you will find information regarding configuration management in Instrument and how an Instrument UI configuration from a source system can be imported into an Instrument UI configuration on a target system.

For information related to readying your Instrument UI configuration for import, review the Configuration Management - Export topic, also found in the Administration documentation.

Importing an Instrument UI configuration is accomplished via the Import Manager.

The ability to manage Instrument UI configurations supports an array of use cases. What follows are the most common use cases where an Instrument configuration on a pre-production system is imported into a production system:

Configuration Replacement : Replacement rules can be added in the import STEP XML file to fully replace an existing Instrument configuration with an imported configuration. One use case where this option would be useful is where the admin knows the import configuration should replace all user groups and default configurations. The admin can use replacement rules to specify replacement of all default configurations and user group-owned configurations. This method might be optimal in an instance where a configuration is moved to a live system from a test system from which all the test system configurations are correct and up to date.

When admin users replace an existing Instrument configuration with a new one:

  • existing elements in the target system are updated with the changes made in the source system

  • elements deleted in the source system will also be deleted in the target system

  • elements not in the source system will be deleted from the target system

To apply replacement rules, include any of the three rules shown below to the import STEP XML file:

Copy 
<ReplacementRules>
  <SetupEntities>
    <ReplaceCentralizedConfigurationInstances OwnedBy="UserGroup"/>
    <ReplaceCentralizedConfigurationInstances OwnedBy="Default"/>
    <ReplaceCentralizedConfigurationInstances OwnedBy="User"/>
  </SetupEntities>
</ReplacementRules>

Each of the rules accomplishes a specific replacement task:

  1. <ReplaceCentralizedConfigurationInstances OwnedBy="UserGroup"?> -- This rule removes all user group configurations, but leaves all other configurations untouched.

  2. <ReplaceCentralizedConfigurationInstances OwnedBy="Default"?> -- This rule removes all default configurations, but leaves all other configurations untouched.

  3. <ReplaceCentralizedConfigurationInstances OwnedBy="User"?> -- This rule removes all user configurations, but leaves all other configurations untouched.

In the example use case described above, the admin would apply rules 1 and 2 to the import STEP XML file to replace all configuration but those owned by the users.

Full replacement of an Instrument configuration by an imported configuration will require that all three replacement rules are added to the import configuration file.

Merging configurations: Imports an Instrument configuration from one environment into an Instrument configuration in another environment, retaining important elements of both. To merge configurations, no replacement rules should be applied. For instance, if the admin wants to add Accelerator for Retail to a system in which Accelerator has never been installed, the admin will not use replacement rules as the admin wants the new Accelerator configurations to be added to the existing configurations.

Additionally, if the admin wants to update their existing Accelerator configurations on a system with a new Accelerator package, the admin will also not use replacement rules as they want the new configurations to be merged with existing configurations and, where the configurations match, the new configurations must overwrite the old.

Instrument configuration imports fail in cases where the import cannot create a new setup entity or update an existing setup entity. In all other cases, the import will complete. The import may complete with errors if the imported configuration from the source system refers to any of the following elements absent from the target system:

  • workflows

  • workflow states in an existing workflow, or workflow states in a non-existing workflow

  • perspectives included in a non-existing work area

  • user groups or users

  • object types

In all cases, the ID of the missing object will be reported in the import's execution report.

When importing an Instrument UI configuration from a source system to a target system, it is not possible to import only a selected configuration from the source system to the target system. All work areas, perspectives, and tab configurations configured on the source system will be imported to the target system.

All work areas in the target Instrument UI configuration source system are retained upon import. Because the import process does not allow for admin users to select which work areas to import in the import configuration, all work areas will be imported and will display in the target Instrument UI, (subject to the users granted the appropriate privileges required to view those work areas).

Note: Admin users cannot delete the setup entities that store the centralized configurations.

Additional Considerations for Administrators

For admins importing an Instrument UI from a source system into a target system, there are aspects of the import that are important to be aware of:

  • Because work areas on a target Instrument UI are not overwritten by those on the source system's Instrument UI during import, all work areas deemed unnecessary must be deleted manually by the admin. Deletion of work areas must be done using the configuration tool in Instrument. For more information on managing work areas, refer to the Work Areas topic.

  • Work areas, perspectives, and tabs configured on the target UI that have the same ID as those found on the source UI will be overwritten upon import.

  • If a specific view has been configured for an object type on the target Instrument UI, and a specific view has been configured for the same object type on the source Instrument UI (or vice versa), the two views will be in conflict upon import and will display as an error in the import execution report. Both views will be present in the post-import UI; the admin user will be responsible for reviewing the two views and deleting the unnecessary view.