Parameters import

Parameter import algorithm

Parameter definition file

Definition file must be compatible with export format mentioned here: Parameter File system structure

File names and extensions

The name of the file, excluding the extension, is the last segment of the parameters' code. The extension determines the type of the parameter:

• .def is the extension for parameter definition
• .mat is the extension for the parameter matrix

Algorithm for the analysis of parameter changes

What happens if the Hyperon database already contains some profiles

General rules for dealing with a situation where the database already contains a parameter with the same code are:

1. if the two parameters are identical, the import is skipped, else:
2. if it is possible to create imported parameter without changing existing version, it is done, else
3. existing versions are substituted by the imported parameter.

IMPORTANT

Parameters are considered identical if they have identical fields, levels (names and types), matrix, region version (or are both global), tags.

The existence of the parameter is established from the perspective of the current user, i.e. taking into account all changes introduced in the current user's work session. If the import is done through the REST endpoint, the current user is the user authenticated in the POST import request.

Parameters from one snapshot are imported one-by-one. From the perspective of importing individual parameters, the state of the database already includes changes introduced by preceding imports from the same snapshot import operation.

Summary of operations in case of the existing parameter with the same fields and matrix:

IMPORTANT

If the snapshot ZIP contains two parameters with the same code but attached to different regions, the result will depend on the order of processing the import, which is not guaranteed. If the regions are in the same profile, the second import will remove the parameter created by the first import. If the regions are in different profiles, the second import will not execute, with status ERROR. In such cases, the snapshot file does not contain a valid structure of parameters and should be corrected.

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

{
    "jobResults": {
        "PARAM": {
            "jobStatus": "ERROR",
            "totalElementsCount": 3,
            "invalidElementsCount": 1,
            "skippedElementsCount": 1,
            "importResults": [
                                {
                    "parameterCode": "eAgent.life.dictionary.profession",
                    "path": "/@params/@global/eAgent/life/dictionary/profession.def",
                    "message": "Bez zmian, plik pominięty",
                    "status": "SKIP"
                },
{
                    "parameterCode": "eAgent.prop.template",
                    "status": "OK"
                },
                {
                    "parameterCode": "demo.motor.coverage.position",
                    "profileCode": "PROPERTY",
                    "regionCode": "life",
                    "version": "2",
                    "path": "/@params/@profiles/PROPERTY/@regions/life/2/demo/motor/coverage/position.def",
                    "message": "brak wersji: 2 dla regionu: life w profilu: PROPERTY",
                    "status": "ERROR"
                }
            ]
        }
    },
    "importStatus": "ERROR"
}

‍

Results of importing functions are included in field jobResults.PARAM and have two entries:

jobStatus - overall status of the parameter's import job. Possible values are:

• SKIP - if there were no parameters to import or all imports were skipped for reason other than error,
• OK - if not all imports were skipped and imports not skipped  were completed correctly,
• WARNING - if there was at least one individual parameter import which was completed but with warnings, and the remaining imports were completed correctly without warning or skipped for reason other than error,
• ERROR - if there were some imports not completed because of an error.

totalElementsCount - counter of all executed imports, including those skipped, executed with error or warning

importResults - an array of individual import results.

Individual import result

Individual import result has the following fields:

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
• SKIP - import was not executed for reason other than error, for example, because identical function already existed, or in directory structure found the file with unknown extension
• ERROR - import was not completed due to an error

parameterCode - code of the imported parameter

message - the optional field presents only if the import status is not OK. It contains the message which should help establish why the status is not OK.

profileCode - the optional field presents only for parameters attached to the region. It contains the profile code.

regionCode - the optional field presents only for parameters attached to the region. It contains the region code.

path - the path within the ZIP snapshot file to the file(s) with the definition of the imported parameter. If there are multiple files with a different extension, a wildcard is used (e.g. /@params/@global/coverage/isAvailable.*).

version - the optional field presents only for functions attached to the region. It contains the code of the region version.

Known limitations - importing parameters from snapshot

National characters in profile, region or version names

Using characters outside the standard US-ASCII set is discouraged, due to the limitations associated with the encoding of paths in ZIP files.

No such validation for the names of profiles, regions or region versions.

Mechanism of parameter snapshot import assumes the paths 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, standard "compressed folder" utility in Windows produces files with different encoding of path names. The information about the encoding of paths is not included in the ZIP file. These paths cannot be read by snapshot importer, so such files or directories will not be processed. The information about encountering unreadable path during import of snapshot parameter will be logged to Hyperon log, but without the path (since it is unreadable).

Names differing by letter case

It is not possible to import or export two parameters attached to the same region version (or both global) with the first different name segments differing by letter case. For example, it is not possible to have parameters

motor.coverage.position

motor.Coverage.productionYear

since the first different segment of the name is premium, and the difference is only by letter case: "C" vs. "c".

This limitation is associated with the limitation on the ZIP file system - it is not possible to have in one directory two files or sub-directories with names differing only by letter case (in the example above, we would have to have two sub-directories: coverage/ and Coverage/ in the same folder).

Parameters in more than one profile

Currently, Hyperon does not support having the same parameter in multiple profiles. Although it is possible to create such parameters, it is strongly discouraged, because it may lead to errors and inconsistencies. The mechanism of snapshot import will prevent such situations, by skipping import of a parameter attached to a region if a parameter with the same name, but attached to a region in a different profile, already exists in the system. The existence of such parameter is determined from the perspective of the user performing the import: all changes made in the current user's session are taken into account.

In particular, if the snapshot ZIP file contains the definition of two parameters with the same code, but in different profiles, the second processed file will not be imported, because the parameter already exists in the current user's session, but in a different profile.

Autocommit for parameters

Snapshot import of parameters during session publishing will not detect conflicts with other user's session that was published.