Algorithm for domain import
Description
Algorithm for import of domain is composed of two major phases:
- First phase is responsible for analyzing the structure of the zip file and build proper XML structure based on it. Exceptions might happen during this phase. If structure or files are not properly constructed, then the import will stop and results will be shown as detailed messages via GUI. (Fail fast on first error approach)
- The second phase is responsible for analyzing the built XML structure from the first phase and verifying it against definition XML. During this phase, the structure is also validated with Hyperon's domain validation rules. If there are validation errors, then import is stopped (only for one profile!) with adequate messages for domain elements, references or domain types.
Order of processing
The import of domain supports multiple profile processing. In @domains there must be at least one directory with proper profile code, the order doesn't matter.
Supported files and proper structure of zip snapshot for domain
will find here: Domain File system structure
Individual import status
The table below summarizes the statuses of importing a function:
Domain element or domain type successfully imported, no issues to report.
The domain element or type was not imported because of an error. Attempt to import elements was unsuccessful for all files associated with it.
Validation:
Example message (English version)
The path from reference.txt is not matching the direct parent directory of reference.txt file.
example: /CARS[BMW] in reference.txt, but the file is under "AUDI" directory
Reference path element: 'BMW' defined in the file is not the same as the directory name: 'AUDI'
Reading reference.txt file, but path inside a file is missing.
The path from reference.txt is missing: ...\CAR\BMW\reference.txt
Any problem with reading, parsing the content of info.txt or attributes.txt files.
Valid file's name and extension.
The file is not supported: ...\CAR\BMW\referencesss.txt
Missing definition of 'CARS' in @def\[PROFILE_NAME].xml of processed root directory like '@conf\CARS'.
Missing domain type collection code for '@conf\CARS\' in the root type definition
Missing definition of 'CAR' in @def\[PROFILE_NAME].xml of processed type like CAR.
Missing domain wrapper definition for dir: '...\CAR\'
Any problem with the reading directory structure.
There was a problem while processing children: ...\CARS\BMW
Missing root type in the definition XML file.
Example message (English version)
Multiple domain types defined as roots in the configuration.
CAR another type set as main
Another domain type is defined as the root type.
CAR is different than current root type CARS
The collection code in the configuration is not valid with a pattern.
MY_COLLECTION - Code can contain letters, digits, '.', '_', '-' or '+'
Multiple occurrences of the same attribute in definition type
MY_ATTR attribute MY_TYPE multiple occurrences
Empty attribute code in definition type
MY_ATTR_NAME - Field cannot be null Attribute code
Multiple elements in configuration, but in definition type has attribute multiple="false".
AUDI multiple occurrences
The element code in the configuration is not valid with a pattern.
ELEMENT_NAME - Code can contain letters, digits, '.', '_', '-' or '+'
Two child elements are incorrect in one parent that is not multiple and their region/version is the same.
CAR: no collection for the path ...\CARS\...
Two child elements are fine in one parent that is not multiple, as long as they are in different versions of the same region, otherwise, it is not valid. Also, two child elements can't be in different regions of the same collection.
BMW multiple occurrences in collection CAR which allows only one position
There is an attribute in the configuration of an element, but there is no definition of this attribute in XML
CAR with attributes, while type defined without attributes
Multiple attribute codes in one element
CAR attribute number multiple occurrences
There is no definition of an attribute as part of the domain type
CAR attribute number was not defined in the type
Multiple dynamic attribute codes in one element
CAR dynamic attribute number multiple occurrences
Dynamic attribute code can't be null or empty
ATTR_NAME - Field cannot be null Dynamic attribute code
A region defined in element doesn't exist
CAR: region REG_1 not exist
Type domain of element must be set as "PRODUCT" (in XML <typeNature>PRODUCT</typeNature>)
CAR: region set can be started on PRODUCT element
The region in the child is not defined, but its parent is assigned to a region
CAR: without region, while its parent has region set
Reference path is not in a valid format
BMW: reference \CAR[BMW] has an incorrect path
Reference and domain element's other child have the same code
BMW: reference \CAR[BMW] has duplicated occurrence with element BMW
In one domain element, there are two the same references
BMW: reference \CAR[BMW] has duplicated occurrence with another reference BMW
Importing domain with HTTP request
Executing import
To see how to execute import, please go to REST import endpoint
Import result
The response body of the request contains the results of the import in JSON format.
Correct import JSON result
{
"jobResults": {
"DOMAIN": {
"jobStatus": "OK",
"totalElementsCounts": 7,
"invalidElementsCount": 0,
"skippedElementsCount": 0,
"importResults": [
{
"status": "OK",
"domainImportStatus": "\n\n[howManyTypes=4, howManyTypesCreated=0, howManyTypesModified=0, howManyTypesTheSame=4]\n[howManyTypesCollection=3, howManyTypesCollectionCreated=0, howManyTypesCollectionModified=0, howManyTypesCollectionTheSame=3]\n[howManyTypesAttribute=3, howManyTypesAttributeCreated=0, howManyTypesAttributeModified=0, howManyTypesAttributeDeleted=0, howManyTypesAttributeTheSame=3]\n[howManyElements=3, howManyElementsCreated=3, howManyElementsModified=0, howManyElementsTheSame=0, howManyElementsDeleted=0]\n[howManyElementsAttribute=3, howManyElementsAttributeCreated=3, howManyElementsAttributeModified=0, howManyElementsAttributeDeleted=0, howManyElementsAttributeTheSame=0]\n[howManyElementsExtraAttr=0, howManyElementsExtraAttrCreated=0, howManyElementsExtraAttrModified=0, howManyElementsExtraAttrDeleted=0, howManyElementsExtraAttrTheSame=0]",
"valid": true
}
]
}
},
"importStatus": "OK"
}
Validation error during import (invalid import JSON result)
{
"jobResults": {
"DOMAIN": {
"jobStatus": "ERROR",
"message": "Wystąpił problem walidacji",
"totalElementsCounts": 7,
"invalidElementsCount": 1,
"importResults": [
{
"message": "błąd walidacji",
"status": "ERROR",
"domainImportStatus": "null",
"valid": false,
"validationMessages": [
"ELEMENT - prod1: region MIE nie występuje w systemie"
],
"invalidElementsCounter: 1
}
]
}
},
"importStatus": "ERROR"
}
There is possibility to autocommit import, if flag was set to true (by default autocommit is turned off) and there were no validation errors. During session publising errors might occure, then import will still take place, but elements will stay in session. Any problems must be resolved by hand.
Response of import/publish - autocommit is 'true':
{
"importStatus": "ERROR",
"jobResults": {
"DOMAIN": {
"jobStatus": "ERROR",
"message": "Domena nie może zostać opublikowana",
"totalElementsCount": 11,
"invalidElementsCount": 0,
"importResults": [
{
"status": "OK",
"domainImportStatus": "\n\n[howManyTypes=5, howManyTypesCreated=0, howManyTypesModified=0, howManyTypesTheSame=5]\n[howManyTypesCollection=4, howManyTypesCollectionCreated=0, howManyTypesCollectionModified=0, howManyTypesCollectionTheSame=4]\n[howManyTypesAttribute=10, howManyTypesAttributeCreated=0, howManyTypesAttributeModified=0, howManyTypesAttributeDeleted=0, howManyTypesAttributeTheSame=10]\n[howManyElements=6, howManyElementsCreated=0, howManyElementsModified=0, howManyElementsTheSame=6, howManyElementsDeleted=0]\n[howManyElementsAttribute=18, howManyElementsAttributeCreated=0, howManyElementsAttributeModified=0, howManyElementsAttributeDeleted=0, howManyElementsAttributeTheSame=18]\n[howManyElementsExtraAttr=0, howManyElementsExtraAttrCreated=0, howManyElementsExtraAttrModified=0, howManyElementsExtraAttrDeleted=0, howManyElementsExtraAttrTheSame=0]",
"valid": true,
"invalidElementsCount": 0
}
],
"unpublishedChanges": [
{
"path": "TESTOWANIE/PLANS[FULL]/COVERAGES[BI]/",
"message": "Ten element został zmodyfikowany przez: test4 o: 28.01.19 11:41 z operacją: DELETE"
}
]
}
}
}
Results of the importing domain are included in field jobResults.DOMAIN and have the following entries:
jobStatus - overall status of the tag's import job. Possible values are:
- OK - if each individual tag import was either completed correctly without warning or skipped for reason other than error.
- WARNING - if there was at least one individual tag import which was completed with warnings,
- ERROR - if there were some import errors.
message - optional text message
totalElementsCount - (imported domain elements + imported domain types)
invalidElementsCount - number of elements with an import error
importResults - grouped import results for domain
- message - general message info
- status - probably same like jobStatus
- domainImportStatus - if there were some errors, then this field is 'null'. Correct import will result with a lot of information (checkout correct result JSON)
- valid - extra flag, if the import was valid or not
- validationMessages - holds extra validation details for possible import elements, types, attributes or references
unpublishedChanges - grouped messages for publication. It will not appear if the publication was successful, but if there were any publication errors, they will appear in this section
- path - code or path of an element
- message - detailed information, why elements were not published. Probably due to some conflict with other user's session.
Known limitations - importing domain from snapshot
There are some limitations regarding import snapshot domain:
- File reference.txt holds the path to domain element, and its code must be the same as the directory name that holds reference.txt.
- Currently, in the first phase of analyzing tree directory of zip snapshot, there might be some exceptions thrown while processing. These exceptions are only in English right now and they block import.
- Import support "SKIP" phase only for no domain definition (when the Snapshot was exported without domain definition).
- The domain can be only imported when there are no domain elements in the OPEN session on an environment. This is because import will override domain definition. There is no advanced mechanism for this.
