Staging

Introduction to staging in ConSol CM

Staging is the procedure 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

Staging allows to transfer data between ConSol CM systems. A scene file is exported from the source system and imported to the target system. This file can include both configuration and runtime data.

The customization of ConSol CM for a specific customer usually involves several ConSol CM systems, e.g. a development system, a test / integration system and a production system.

Since ConSol CM works with transfer keys for all objects, it is highly recommended to transfer data by using a scene. Do not implement the same functionality in both systems, because the created objects will have different transfer keys which will result in duplicate objects in case a transfer is performed later on.

Available settings for exports

The scope of the export, i.e. which objects will be included in the scene file, is determined by the selections which you make on the export page. If you select an option which has dependencies to other options, these options are selected automatically, so that you can see which objects will be exported with your current selection.

The available export options are grouped in several sections.

Runtime data

The options in this section export runtime data, as actual cases, contacts and resources, and the related configuration.

• All data
  Exports all runtime and configuration data, except for the system documentation.
• Single case
  Enter the name of the case in the field Case name. This case and all configuration data, except for the system documentation, is exported. You can select the Anonymized checkbox to anonymize the data as follows:
  • Content of case fields (except some values as list values)
  • Case attachments
  • Case history
  • Content of contact fields
  • Contact history

  This option should be used for bug analysis only.

• All data except cases
  Exports all contacts and resources, and all configuration data, except for the system documentation.
• Contact data
  Exports all contacts and the contact data model.
• Resource data
  Exports all resources and the resource data model.

Configuration data

The options in this section export configuration data.

• All
  Exports all configuration data except for the system documentation.
• Users
  Exports all users, including portal user profiles, and the references to their assigned roles.
• Sorted lists definitions
  Exports all lists.
• Hierarchical lists definitions
  Exports all hierarchical lists. This includes the used lists and the data fields.
• Scripts
  Exports all scripts.
• Webhooks
  Exports all webhook configurations and integration scripts.
• Templates
  Exports all templates created in the Web Admin Suite.
• Customer data models
  Exports the customer data models, including data fields, actions, relations and portal user profiles.
• Resource data models
  Exports the resource data models, including data fields, actions and relations.

• Queue-based data
  Exports queues, lists, scripts, data models, portal user profiles and text classes, and objects for which no specific export option exists, e.g., roles. Select the queues which should be exported in the Queues to export field below.

  You can use the All queues option to select all queues.

• Text classes
  Exports text classes and visibility configurations.
• Page customizations
  Exports all page customizations which have been defined specifically for the system. These are the values which are stored in the database tables cmas_web_customization and cmas_web_customization_values. Default values are exported only if they were set to another value and have been changed back to the default value manually by clicking the Update button.
• Web forms
  Exports all web forms.
• Skin and web resource files
  Exports the content of the design and resources folders of the ConSol CM data directory.
• Text templates
  Exports all text templates, i.e. the templates created in the Web Client.
• Document templates
  Exports all document templates.
• Client configurations
  Exports all client configurations.

Workflows

When the export contains workflows, the options in the Workflows panel become active. There are two options:

• Only the newest deployed version
  
  Exports only the installed versions of the workflows, i.e. only one version of each workflow is included in the export.
• All workflow versions
  
  Exports all versions of all workflows, i.e. both the currently installed version and all older versions are included in the export.

  Depending on the number of workflows stored in the system, the export might take very long and result in a large scene file. Usually, it is not required to export all workflow versions.

System documentation

Contains one option to export the system documentation. This option is independent of all other options. The export file can be used to generate a system documentation in the Documentation Generator section of the Admin Tool.

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.

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.

Basic tasks

Staging involves three tasks:

• Export the data of the source system to a file, see Exporting a scene.
• Import a scene file to the current system, see Importing a scene.
• Transfer cases after a failed workflow deployment, see Transferring cases.

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

Exporting a scene

Please proceed as follows to export a scene:

1. Make the desired settings on the Export page, see Available settings for exports.
2. Click the Export button. Once the export has finished, you can save the file using your browser.

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.

Advanced tasks

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.