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:
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:
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:
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.
To see how to execute import, please go to REST import endpoint.
The response body of the request contains the results of the import in JSON format.
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:
totalElementsCount - counter of all executed imports, including those skipped, executed with error or warning
importResults - an array of individual import results.
Individual import result has the following fields:
status - status of the individual import. possible values are:
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.
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).
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).
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.
Snapshot import of parameters during session publishing will not detect conflicts with other user's session that was published.