Tags import

File system tag import algorithm

If the Hyperon database already contains a tag with the same name as an imported tag, the existing tag will be substituted by the imported tag. If the snapshot file does not contain a definition of tag with the same name as an existing tag, the existing tag will not be modified.

File system directories

The whole file system structure must be compatible with the export format mentioned here: Tag file system structure. If any additional files/directories are present in Hyperon directories:

• @tags
• @access (only additional directories)
• @basic (only additional directories)

they are ignored during import.

‍

Order of processing

Tags without access control are imported after tags with access control.

IMPORTANT

If both @access/ and @basic/ folders contain a tag definition file with the same name, the tag with access control will be imported first. The second import from the @basic/ folder will override the tag created by the first import. As a result, the system will contain only the definition without access control.

Tag description file

The description file structure must be compatible with the export format mentioned here: Tag file system structure. Files with different extensions are considered invalid and generate import errors.

Validation

In case of a Toml parsing error, tag import is aborted and the overall status of tag's import is ERROR. In this situation, remaining files with the definition of tags are not imported.

If the file contains a definition of values other than description, for example:

opis = "a valid description must be in description element, not opis",

they will be ignored and the user will be notified of the fact with a warning message.

Status of individual tag import

Currently, supported statuses of individual tag import are:

If the import status is ERROR, the individual tag import result contains a message describing the error.

In addition, if there is an error while reading the definition of the tag from file, the import is aborted and

• the tag which caused the error is not imported,
• remaining unimported tags are also not imported,
• import results for individual tags are not presented,
• only the overall import result with status ERROR is shown.

Example situations when this kind of error occurs:

• file reading error,
• invalid format of the tag definition file (not a valid Toml).

More information about the nature of the error could be found in Hyperon's log.

Importing tags 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.

{
    "importStatus": "OK",
    "jobResults": {
        "TAG": {
            "jobStatus": "OK",
            "totalElementsCount": 2,
            "invalidElementsCount": 0,
            "importResults": [
                {
                    "tagCode": "PROPERTY",
                    "status": "OK",
                    "action": "CREATED"
                },
                {
                    "tagCode": "SYSTEM",
                    "status": "OK",
                    "action": "UPDATED"
                }
            ]
        }
    }
}

Results of importing tags are included in field jobResults.TAG 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.
• totalElementsCount - counter of all executed imports, including those executed with error or warning
• invalidElementsCount - counter of all imports which ended with the status ERROR or WARNING,
• importResults - an array of individual import results.

Individual import result

Individual import result has the following fields:

• tagCode - code of the imported tag
• message - optional field. It contains the message which should help establish the source of potential errors.
• status - status of the individual import. possible values are:
• OK - import executed correctly without any warnings
• WARNING - import was completed but there were some warnings due to unusual situation
• ERROR - import was not completed due to an error
• action - performed action. Possible values are:
• CREATED - if the tag did not exist in the system before import,
• UPDATED - if the tag already existed.
  

Known limitations - importing tags from snapshot

National characters in names of tags

Using characters outside the standard US-ASCII set is discouraged, due to the limitations associated with the encoding of filenames in ZIP files. Please note that in Hyperon Studio it is possible to create tags with names containing such characters. 

Mechanism of tag snapshot import assumes the file names in the ZIP file are UTF-8 encoded. However, in practice, this encoding depends on the tool used to create the ZIP file, operating system, and national settings. In particular, the standard "compressed folder" utility in Windows produces files with a different encoding of file names. The information about the encoding of filenames is not included in the ZIP file. These file names cannot be read by snapshot importer. if an unreadable file name is encountered during tag's import, the operation of importing tags is aborted and the overall status of tag's import is ERROR. In this situation, remaining files with the definition of tags are not imported.

Names differing by letter case

It is not possible to import or export two tags if both are with or without access control and have names differing only by letter case. For example, it is not possible to have two access control tags "mytag" and "myTag" in one snapshot file.

This limitation is associated with the limitation on the ZIP filesystem - it is not possible to have in one directory two files with names differing only by letter case. In the example above, we would have to have two files: mytag.tag and mytag.tag in the same folder.

Incomplete import result - missing file path

Currently, the information about the file path is missing from the individual import result presented in Hyperon Studio.