Export and Import in 3.2.0

Configuration file check before importing

A configuration file is checked before importing.


The check results are shown as a list.

 - messages, informing about events you should pay attention to:

  • server restart;
  • replacement and republishing of the organizational structure;
  • merging of objects or documents;
  • import demo version.

 - warnings, informing about events that can affect data integrity:

  • cannot import some metadata or data (e.g. you are importing a configuration, related to a module, which is not activated in the system)

 - errors, informing that the configuration cannot be imported:

  • export/import version is different from the current version
  • the system contains changes that require the server restart
  • metadata (objects, documents or enumerations) naming rules are not followed 
  • other.
Backups
Before importing, back up the database.

Import to Demo version

When importing to demo version only the process data packages will be imported. Metadata packages and data packages, not related to a process will be skipped.

Organizational structure export/import

When you export the organizational structure, the published version is exported.
When importing, the organizational structure will be automatically published and will replace the current one.

 
Pay attention when exporting
Do not select organizational structure export if it is not required.

KPI model export/import

  • When you export the KPI model, the published version is exported.
  • When importing, the KPI model will be automatically published and will replace the current one.

Reports export/import

  • When exporting, the report draft is exported.
  • When importing, the report will not be published automatically.

Process export/import

  • When exporting, the process draft is exported.
  • When importing, the process will not be published automatically.
  • If the name of the imported process matches the name of an existing process, then the imported process will receive a new unique name.

Process import rules

  • If exported objects or enumerations are in a group, created by a user, then this group is exported as well.
  • You cannot import a process if class or table names are already used.

Merging process contexts

When moving processes from one server to another, certain situations may occur that require a special approach.
Example: You create a process on Server1 and move it to Server2. You add a property with the same name to these processes on Server1 and Server2. After that, you import the process from Server2 to Server1.
Such import leads to a conflict. To solve it, it is possible to merge the contexts of the existing and the imported processes.

  • If the system contains a process with the same UID as the imported one, their contexts will be merged.
  • Properties of different types cannot be merged.
  • Properties with different link type cannot be merged.
  • When merging processes, their blocks are merged by UID and name.
  • Properties inside the merged blocks are merged as well.
  • When merging properties, the displayed name of the existing property will be replaced with the name of the imported property.
  • When merging properties the name of the existing property will be replaced with the name of the imported property.
  • When merging properties, UID of the existing property will be saved.
 
Specific feature of merging process contexts
When merging contexts of an existing and imported process, not only the properties and blocks of the existing process are taken into account, but the previously published versions as well.

Custom activities export/import

  • When exporting, the draft of the custom activity is exported.
  • When importing, the custom activity will not be published automatically.
  • If the name of the imported custom activity matches the name of an existing, the imported custom activity will receive a new unique name.

Metadata export/import

  • When exporting objects, documents, and enumerations (metadata), their published versions are exported. When importing, if there are no similar metadata in the system, new metadata are created and published. If there are similar metadata they are merged and published.
  • If exported objects or enumerations are in a group, created by a user, this group will also be exported.
  • If exported objects or enumerations are in a system group, they will be placed in the same system group during import. If there is no such group, they will be placed in the Common Module group.
  • If exported documents are in a group, created by a user, this group will be exported as well.
  • Only user enumerations can be exported/imported.

Merging metadata

When moving data from one server to another, certain situations may occur that require a special approach.
Example 1: You create an object on Server1 and move it to Server2. You add an attribute with the same name to Server1 and Server2. After that, you export the object from Server2 to Server1.
Example 2: You create an object on Server1 and move it to Server2. You rename of one attributes on Server2. After that, you export the object from Server2 to Server1.
Such export/import causes a conflict. To solve it, it is possible to merge metadata and their properties.

Properties, identifying metadata during import
Metadata have some properties that allow to identify them.
• Displayed Name – name, displayed to a user. If displayed names of imported and existing metadata match, it does not mean that metadata match.
• Name – name, used by the system administrator and analysts. If names of imported and existing metadata match, it does not mean that metadata match.
• Unique identifier ( UID ) – number that defines the uniqueness of an object type. If UIDs of imported and existing metadata match, it means that metadata match. Metadata are considered the same if they have the same UID.

Merging objects/documents

  • If the system contains an object/document with the same UID as the imported one, they will be merged.
  • When merging objects/documents, the displayed name of the existing object/document will be replaced with the displayed name of the imported object/document.
  • If imported metadata replace or are merged with the existing, their scripts are merged. The text of the base metadata script is commented and the text of the imported metadata script is added instead.
  • When merging objects/documents, their properties are merged by UID and name.
  • Properties of different types cannot be merged.
  • Properties with different link types cannot be merged.
  • When merging objects/documents, their blocks are merged by UID and name.
  • Properties inside merged blocks are merged as well.
  • When merging properties, the displayed name of the existing property will be replaced with the displayed name of the imported one.
  • When merging properties, the name of the existing property will be replaced with the name of the imported one.
  • When merging properties, the UID of the existing one will be kept.
  • When merging properties, that have 1-N link, the link key UID will be kept.
  • Imported data of the merged objects will also be merged.
Example of merging objects
There is Object1. Its displayed name is "Customers", name - "Customers", Uid - "5882935F-43FB-4288-BE08-45660D4D995F".
Object2 is being imported. Its displayed name is "New Customers", name - "Customers", Uid - "5882935F-43FB-4288-BE08-45660D4D995F".

These two objects have the same names and UIDs. When importing, they will be merged. The resulting merged object's displayed name will be "New Customers", name - "Customers", Uid - "5882935F-43FB-4288-BE08-45660D4D995F".

This example is applicable if an object is exported to a configuration file, its displayed name is changed and then it is imported to a version, exported earlier.
Example of unseccessful merging of objects
There is Object1. Its displayed name is "Customers", name - "Customers", Uid - "5882935F-43FB-4288-BE08-45660D4D995F".
Object2 is being imported. Its displayed name is "Customers", name - "Customers", Uid - "BC4D4F8A-06DD-4A9C-AD37-5097688059EB".

These two objects have the same displayed names and names, but different UIDs. For the system, these are different objects. Since two different objects with the same name cannot exist, Object2 will not be merged with Object1 and imported to the system.

This example is applicable if objects with the same names are created on two servers and one of them is being moved to the other server.
Example of merging properties of merged objects
Existing Object1 and imported Object2 are being merged.

Object1 has:
  • Property1-1, with displayed name - "Full Name", name - "FullName", Uid - "5B341C74-9E74-46BB-B33F-7A727E398A68"
  • Property1-2, with displayed name - "Monthly Salary", name - "Salary", Uid - "E950CCEC-E4D3-420C-BDD2-8E55E013456A"
  • Block1-3, with displayed name - "Payments", name - "Payments", Uid - "E04C077A-A9DF-481C-ABC6-0CB86D6A269F"
Object2 has:
  • Property2-1, with displayed name - "Full Name", name - "FullName", Uid - "5B341C74-9E74-46BB-B33F-7A727E398A68"
  • Property2-2, with displayed name - "Salary", name - "Salary", Uid - "BC4D4F8A-06DD-4A9C-AD37-5097688059EB"
  • Block2-3, with displayed name - "Payments", name - "Payments", Uid - "E04C077A-A9DF-481C-ABC6-0CB86D6A269F" со свойством:
    • Property2-3-1, with displayed name - "Payment", name - "Payment", Uid - "1C8C91EE-9B93-4700-9171-65AE6C686F5D"
Property1-1 will be merged with Property2-1, since they have the same UIDs and names.
Property1-2 will be merged with Property2-2, since their names match.
Block1-3 will be merged with Block2-3, since their UIDs and names match.
Property2-3-1 will be added to the merged block.

The resulting Object3 will have:
  • Property3-1, with displayed name - "Full Name", name - "FullName", Uid - "5B341C74-9E74-46BB-B33F-7A727E398A68"
  • Свойство3-2, with displayed name - "Salary", name - "Salary", Uid - "E950CCEC-E4D3-420C-BDD2-8E55E013456A"
  • Блок3-3, with displayed name - "Payments", name - "Payments", Uid - "E04C077A-A9DF-481C-ABC6-0CB86D6A269F" со свойством:
    • Property3-3-1, with displayed name - "Payment", name - "Payment", Uid - Uid "1C8C91EE-9B93-4700-9171-65AE6C686F5D"
This example is applicable to a situation when an object with FullName property and empty Payments block has been exported to another server. On both servers, a Salary property has been added, but with different displayed name. On the second server, the Payment property has been added to the Payments block. After that, the object has been exported from the second server and imported to the first server.
Example of an unsuccessful merging of properties of merged objects
Existing Object1 and imported Object2 are being merged.

Object1 has:
  • Property1-1 with displayed name - "Payment", name - "Payment", Uid - "8FB17373-020B-4630-AE57-8A3300AEAECB"
Object2 has:
  • Property2-1 with displayed name - "Payment", name "Pmnt", Uid "66D19D1E-D4B2-46F3-86F8-4078434226C7"

Property2-1 cannot be merged with Property1-1 (since they have different names and UIDs), and cannot be added as a second property (since one object cannot contain two properties with the same displayed name). As the result, Object2 will not be imported to the system.

This example is applicable to a situation when you exported an object from one server to another. On the second server, you accidentally deleted the "Payment" property and created a new one with the same displayed name. At the same time, you did not notice that the created name is different. After that, you attempted to move this object back to the first server.

Merging enumerations

  • If the system contains an enumeration with the same UID as the imported, they will be merged.
  • Enumerations with the same UID but different names cannot be merged.
  • When merging enumerations, the displayed name of the existing enumeration will be replaced with the displayed name of the imported enumeration.
  • Enumerations with the same name but different values cannot be merged.
  • When merging enumeration values the displayed name of the existing enumeration will be replaced with the displayed name of the imported value.

Errors while checking the configuration file during import and possible causes

System or configuration file errors

The system contains published objects or documents that require the server restart. To eliminate this error, restart ELMA server.

  • "The system contains published objects that require the server restart. Restart the server and start import again.

The files.xml file is corrupted.

  • "The configuration file of the import files contains invalid data, or the import files are lost"

The config.xml file is corrupted.

  • "The configuration file does not contain data, or the import/export version of the configuration file does not match the current version"
  • "The configuration file does not contain a "ConfigurationData" section"
  • "The configuration file does not contain a "Metadata" section"
  • "The configuration file does not contain a "Data" section"

Metadata import errors

Database structure or configuration file corruption that caused unacceptable attempt to import system enumerations.

  • "The imported enumeration is a system enumeration"
  • "The existing enumeration is a system enumeration"

Merging enumerations with different names is unacceptable. To eliminate the error, rename the enumeration.

  • "The name of the imported enumeration is different from the name of the existing enumeration"
Enumeration names may be used in queries of report data sources
Before renaming an enumeration, make sure that it will not cause reports to misbehave

Enumerations with the same name but different values cannot be merged.

  • "The value of the imported enumeration is different from the value of the existing enumeration"

Impossible to merge enumeration values without violating enumeration creation rules.

  • "Cannot add a value to an enumeration: A value with this name already exists"
  • "Cannot add a value to an enumeration: The value already exists in the enumeration"

Database structure or configuration file is corrupted.

  • "Cannot add a value to an enumeration: The value name must be a valid ID (use only English letters, numbers or underscore)"
  • "Cannot add a value to an enumeration: C# keywords are not allowed"

Database structure or configuration file is corrupted, which caused unacceptable attempt to import system metadata.

  • "Imported system metadata have UID matching the UID of existing user metadata"
  • "Imported system metadata have name not matching the name of existing system metadata"
  • "Imported system metadata have type not matching the type of the existing system metadata"
  • "Imported user metadata have UID matching the UID of the existing system metadata"

Database structure or configuration file is corrupted.

  • "Imported user metadata name is different from the name of the existing user metadata"
  • "Imported user metadata table name is different from the table name of the existing user metadata"

Attempting to import a configuration, not corresponding to the server configuration.

  • "Error reading metadata: Metadata type is not defined"
  • "Error reading metadata: metadata description is missing"

Cannot merge properties of merged objects/documents without violating property naming rules.

  • "Cannot add imported property to metadata: Property with this displayed name already exists"

Database structure or configuration file is corrupted.

  • "Cannot add imported property to metadata: Property name is not specified"
  • "Cannot add imported property to metadata: Property name cannot match an object name"
  • "Cannot add imported property to metadata: Property name must be valid ID (use only English letters, numbers and underscore) "
  • "Cannot add imported property to metadata: Cannot use ID name"
  • "Cannot add imported property to metadata: C# keywords are not allowed"

Cannot merge properties of merged objects/documents without violating property naming rules in the database.

  • "Cannot add imported property to metadata: Property with the field name already exists"

Database structure or configuration file is corrupted.

  • "Cannot add imported property to metadata: Field name cannot start with an underscore"
  • "Cannot add imported property to metadata: Property name must be valid ID (use only English letters, numbers and underscore)"
  • "Cannot add imported property to metadata: Cannot use ID name"

Cannot establish 1-N link, since the linked object does not contain the specified key column.

  • "Cannot add imported property to metadata: Cannot establish 1-N link, key column is missing"

Cannot merge blocks of merged objects/documents without violating naming rules.

  • "Cannot add imported block to metadata: Property with this displayed name already exists"
  • "Cannot add imported block to metadata: Property with this name already exists"
  • "Cannot add imported block to metadata: Object name matches a property name"

Database structure or configuration file is corrupted.

  • "Cannot add imported block to metadata: Property name is not specified"
  • "Cannot add imported block to metadata: Property name cannot match an object name"
  • "Cannot add imported block to metadata: Cannot use ID name"
  • "Cannot add imported block to metadata: C# keywords are not allowed"

Only properties of the same type can be merged.

  • "Type of imported metadata property is different from the type of existing property"
  • "Link type of imported metadata property is different from the link type of existing property"

Database structure or configuration file is corrupted.

  • "Table name is unacceptable: Table name cannot be empty"
  • "Table name is unacceptable: The table name cannot begin with underscore"
  • "Table name is unacceptable: The table name must be valid ID (use only English letters, numbers or underscore)"
  • "Table name is unacceptable: Table name cannot be longer than 28 characters"

Impossible to import an object/document without violating table naming rules in the database.

  • "Table name is unacceptable: Table with this name already exists"

Process import errors

Cannot merge properties of merged contexts without violating property naming rules.

  • "Cannot add the imported property to the context:  Property with this displayed name already exists"
  • "Cannot add the imported property to the context:  Property name is not specified"
  • "Cannot add the imported property to the context:  Property name cannot match an object name"
  • "Cannot add the imported property to the context: Property with this name already exists"
  • "Field names match"

Only properties of the same type can be merged.

  • "The type of imported context property is different from the existing property type"
  • "The link type of imported context property is different from the existing property link type"

Database structure or configuration file is corrupted.

  • "Cannot add the imported property to the context: Property name must be valid ID (use only English letters, numbers and underscore) "
  • "Cannot add the imported property to the context:  Cannot use ID name"
  • "Cannot add the imported property to the context:  C# keywords are not allowed"
  • "Cannot add the imported property to the context: Field name is not specified"
  • "Cannot add the imported property to the context: Property with the field name already exists"
  • "Cannot add the imported property to the context: Field name cannot start with an underscore"
  • "Cannot add the imported property to the context: The field name must be a valid ID (use only English letters, numbers or underscore)"
  • "Cannot add the imported property to the context: Cannot use ID name"

Attempting to import a configuration that does not correspond to the server configuration.

  • "Cannot add the imported property to the context: Property type is absent in the system"

Cannot merge blocks of merged contexts without violating block naming rules.

  • "Cannot add the imported block to the context: Property with this displayed name already exists"
  • "Cannot add the imported block to the context: Property name is not specified"
  • "Cannot add the imported block to the context: Property name cannot match an object name"
  • "Cannot add the imported block to the context: Property with this name already exists"

Database structure or configuration file is corrupted.

  • "Cannot add the imported block to the context: Property name must be valid ID (use only English letters, numbers and underscore) "
  • "Cannot add the imported block to the context: Cannot use ID name"
  • "Cannot add the imported block to the context: C# keywords are not allowed"
  • "Cannot add the imported block to the context: Object name matches the name of a property"