Import

Introduction to imports in ConSol CM

Imports are the second step of the staging procedure to which allows to transfer data between two ConSol CM systems. Data is exported from the source system and imported to the target system using a scene file.

Concepts, terms and definitions

Concept	Other terms	Definition
scene	scenario	ZIP file which contains ConSol CM data for staging
transfer key		Unique identifier of ConSol CM objects
workflow deployment		Process to put a new workflow version into production

Purpose and usage

On the Import page, you can import scene files created on the Staging export or Custom export pages. Depending on the export settings, the files can include different types of configuration and runtime data.

All export and import actions are logged in the file transfer.log.

Available settings for imports

The behavior of the import can be configured in the Extended import settings panel.

Usually, it is not required to change these settings.

The following settings are available:

• Mode
  Determines the behavior if there are errors during the import.
  
  • Abort on error
    The import is canceled when an error occurs. This is the default behavior which should be used during regular work with the system, e.g. to transfer data from a development system to a production system.
  • Ignore errors
    Corrupt data is ignored during the import. This option allows to continue the import even if there are some problems with the data, e.g. a referenced object is not found on the target system. This option can be useful for imports to test systems. If you use it on production systems, you need to solve the detected problems after the import.
    
  • Force import
    Corrupt data is imported into the target system. This option should only be used on development system or by the support team to reproduce errors.

• Delete all existing data
  Removes all existing runtime and configuration data from the database. This option should only be used to set up a completely new system with the provided scene.

  If the system type is “prod” (see system property system.flavour), the import fails if this option is selected.

• Delete annotations not present in the import file
  Removes field settings which are not present in the source system but exist in the target system, e.g. because they have been removed in the development system and this change should be taken over to the production system.

  After the import, you can check which settings have been removed in the Import results section and the server.log file.

Principles of configuration data import

If the option to delete all existing data is not selected, the data import is performed according to the following principles:

• Data is only added, nothing is deleted.

• If the imported scene contains the same field / parameter as the target system, the value from the scene overwrites the value on the target system.
  

  Example: The field priority has the position “0;2” in the imported scene. The target system has the position “2;2” for this field. After the import, the field in the target system has the position “0;2”.

• If the imported scene contains more parameters than the target system, the parameters are added on the target system.

  Example: The imported scene has the setting Visibility with the value Never for the field priority. In the target system, the field priority is present, but does not have the setting. After the import, the field priority has the setting Visibility with the value Never on the target system.

• If the imported scene contains less data / fewer parameters than the target system, the data from the target system is kept. Nothing is deleted.
  

  Example: The field priority in the imported scene does not contain the setting Visibility with the value Never, but the target system does contain the setting. After the import, the target system still has the setting.

• For scripts and templates, the latest version, according to the timestamp, is used. This can be the version from the imported scene or from the target system.

• Objects are identified by internal transfer keys. When an imported scene contains an object with the same name but another transfer key, technically, these are two different objects, and the new object will be added to the target system.

  Example: A user admin exists in both the imported scene and the target system. If the transfer keys are different, there will be one user admin and one user admin (1) in the target system after the import. If such a situation occurs and you want to avoid it for future imports, you need to delete the original user admin from the target system and rename the imported user admin (1) to admin. Then, the problem will not occur again during the next import.

• System properties whose module name starts with custom- are added to the target system during import if they did not exist before. If such a property is already present in the target system, its value is updated with the value from the imported scene. Other system properties are never changed by the import, see Importing and exporting system properties.

Principles of runtime data import

The runtime data import feature is designed for the use with test or development systems only. Large quantities of runtime data, e.g. from production systems, must be exported and imported using ETL tools.

If the option to delete all existing data is not selected, the data import is performed according to the following principle:

• If an object already exists in the target system, as identified by its transfer key, the object will not be modified by the import. No fields of the object are added or deleted, and existing fields are not modified. In this way, existing objects (cases, contacts, resources) are protected from being modified accidentally with test data.

Database transactions

The import of the configuration data from a scene is separated into several database transactions. This helps to limit memory usage on the database server. However, in case of fatal errors during the import, this could result in an inconsistent system state.

The system property cmas-core-server, config.import.global.transaction.enabled can be used to configure the system in a way that all configuration items of a scene are encapsulated in one large database transaction. Therefore, when enabling this option, a fatal error during the import of a configuration item cannot leave the system in an inconsistent state. Instead, the whole encapsulating transaction will be rolled back putting the system configuration-wise into the state before the import. The transaction encapsulation does not include localizations or runtime data which are handled independently of this setting.

Enabling this transaction encapsulation may result in longer import execution times and higher memory requirements on the database server.

Tasks

Importing a scene

Please proceed as follows to import a scene:

1. Click the Select file button on the Import page to select the scene file.

2. If required, make the desired settings in the Extended import settings panel, see Available settings for imports.

3. Click the Import button. A modal window which shows the import progress and the related log messages is opened. Once the import has finished, you can see the results in the Import results panel.

   If the import requires a case transfer, you can check the status on the Workflows page.

Transferring cases

If an error occurs during workflow deployment, you can transfer the cases that could not be transferred into the new workflow using the case transfer feature on the Import page.

1. Click the Transfer cases button. A modal window with the transfer settings is opened.
2. Select the queues for which the cases should be transferred.
3. Select the transfer mode. There are two options:
   • Keep position in process
     The cases try to stay at their current position in the process:
     • If the activity and scope have not been changed, the case remains at its position.
     • If the activity is no longer present, the case goes as far back in the process as necessary to find the last consistent position in the process.
   • Restart process
     All cases go back to the start node of the workflow, i.e. they start the process again.
4. Click Transfer cases. The transfer results are displayed in a modal window once the transfer has finished.