Profile and Context import

Algorithm for the import of profiles from snapshot

• Elements included in profile import,
• interaction of imported elements with existing content.

Imported elements

The following elements are included in the import of profiles:

• profiles,
• regions,
• versions of the regions,
• time schedules for regions,
• context definitions.

When exporting profiles in Hyperon Studio, the user has the possibility to exclude context definitions from the result. See the export description for details.

Treatment of unexpected elements in the snapshot ZIP file

The structure of the directory with profile content is described here. If a directory inside the @profile directory contains an unexpected element, that element is ignored during import. Examples of unexpected elements:

• any file located directly in the @profiles directory (this directory should contain only sub-directories for each profile),
• any file with name different than context.def, located directly in individual profile directory (this directory should contain only the @regions subdirectory and the file context.def),
• any file located directly inside @regions directory (it should contain only subdirectories for regions),
• any subdirectory of the @versions directory (it should only contain *.ver files for each region version).

Importing existing elements

(Profiles, regions, and versions)

If Hyperon already contains an element that is imported, the import is skipped and the existing element is left unchanged. However, the import will proceeds with sub-elements of the skipped element. For example, if the database already contains a region that is imported, the region will not be replaced with a new one, but the import will proceed with versions of that region.

Identification of the element in Hyperon is based on its name and place in the structure of profiles, regions and versions:

• import of profile is skipped if a profile with the same name already exists in the database
• import of region is skipped, if the database contains a region with the same name inside profile with the same name as the profile which contains the imported region
• import of region version is skipped if already exists a region version with the same number inside region with the same name, which is inside profile with the same name.

Description of an element is not taken into account when establishing whether it already exists.

IMPORTANT

Import does not change description of existing profiles, regions or versions.

Context definition

Existing context definition for a profile is replaced with an imported version. However, if the context file does not exist or is empty, the import of context is skipped and existing context for the profile is left unchanged.

Time schedule for a region

The existing time schedule for a region is replaced with the imported version. However, if the file with schedule definition does not exist for a particular region, the schedule is not imported and the existing schedule is left unchanged.

Importing new elements

New elements (profiles, regions, versions, context definitions and time schedules for regions) are added to the database. Import of new elements does not affect existing objects or the attachment of existing objects to profiles, regions or versions. For example, if there is a function attached to an existing version of the region, the import mechanism will not attach that function to new versions imported from the snapshot.

IMPORTANT

This behavior is different from the situation when new region versions are added manually in Hyperon Studio. For example, in Studio a function attached to an existing region version is automatically attached to any newly added version of that region.

Import status for individual elements

Currently supported import statuses for individual elements (profiles, regions, versions, contexts or schedule elements):

In case of status different than OK, an import message provides additional information about the problem. If it is not sufficient, further details can be found in Hyperon's log.

Importing profiles from snapshot 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": {
        "PROFILE": {
            "jobStatus": "OK",
            "totalElementsCount": 12,
            "invalidElementsCount": 0,
            "skippedElementsCount": 7,
            "importResults": [
                {
                    "profileCode": "PROFILE1",
                    "message": "Profile PROFILE1 already exists",
                    "status": "SKIP",
                    "regionImportResult": [
                        {
                            "status": "SKIP",
                            "message": "Region REGION2 already exists in profile PROFILE1",
                            "regionCode": "REGION2",
                            "regionVersionImportResult": [
                                {
                                    "status": "SKIP",
                                    "message": "Version 1 already exists for region REGION2 in profile PROFILE1",
                                    "version": "1"
                                }
                            ],
                            "versionScheduleImportResult": [
                                {
                                    "status": "SKIP",
                                    "message": "Identical schedule already exists for region REGION2 in profile PROFILE1"
                                }
                            ]
                        },
                        {
                            "status": "SKIP",
                            "message": "Region REGION1 already exists in profile PROFILE1",
                            "regionCode": "REGION1",
                            "regionVersionImportResult": [
                                {
                                    "status": "OK",
                                    "version": "2"
                                },
                                {
                                    "status": "SKIP",
                                    "message": "Version 1 already exists for region REGION1 in profile PROFILE1",
                                    "version": "1"
                                }
                            ],
                            "versionScheduleImportResult": [
                                {
                                    "status": "OK",
                                    "version": "1"
                                },
                                {
                                    "status": "OK",
                                    "version": "2"
                                }
                            ]
                        }
                    ],
                    "contextImportResult": {
                        "importStatus": "SKIP",
                        "message": "Profile PROFILE1 does not have a context"
                    }
                },
                {
                    "profileCode": "PROFILE2",
                    "status": "OK",
                    "action": "CREATED",
                    "contextImportResult": {
                        "importStatus": "OK"
                    }
                }
            ]
        }
    }
}

Import status fields

There are import status fields on various levels of the response body, called jobStatus, status or importStatus. These fields can have one of the following values:

• OK - operation was completed without errors,
• WARNING - there was a non-standard situation which requires users attention,
• SKIP - import was skipped for reason other than error,
• ERROR - There was an import error.

Message fields

Fields called message contain additional information about the import action. Depending on the place in the response body, a message can be omitted if the import status is OK.

Result of importing profiles

The result of the import of profiles is included in the field jobResults.PROFILE. It contains the following fields:

• jobStatus - the overall status of the import of profiles,
• totalElementsCount - the overall number of processed elements
• invalidElementsCount - number of elements processed with status WARNING or ERROR
• skippedElementsCount - number of elements processed with status SKIP
• message - optional text message,
• importResults - list of results for each imported profile.

Profile import result

The result for individual profile contains the following fields:

• profileCode - the code of imported profile
• message - optional text message
• status - status of importing profile
• action - optional  field, action performed by the importer. Possible values are CREATED - if the profile was not present before or UPDATED if the profile already existed and was updated. If the profile was neither created nor updated, this field is not included. Modification of regions for the profile is not considered as an update of the profile itself.
• regionImportResult - an optional list of results of importing individual regions within the profile. This field is not included in the snapshot ZIP file does not contain any region definitions for the profile.
• contextImportResult - result of importing context definition for the profile.

Context import result

The result of importing context definition has the following fields:

• importStatus - status of importing the definition of context,
• message - optional text message.

Region import result

The result of importing individual region has the following fields:

• status - status of importing the region
• message - optional text message
• regionCode - the code of imported region
• regionVersionImportResult - list of import results for the versions of the region
• versionScheduleImportResult - list of import results for the entries of the time schedule for the region

Region version import result

The result of importing a version of region contains the following fields:

• status - status of importing region version,
• message - optional text message,
• version - version number.

IMPORTANT

Region versions are usually numbered with integer numbers "1", "2", ..., but version "numbers" can also be strings not representing numbers. For example "MY_VERSION" is a valid region version "number".

Schedule entry import result

The result of importing the time schedule for a region is a list of results for each entry (line) of the schedule. Individual entry result has the following fields:

• status - status of importing schedule entry,
• message - optional text message,
• version - optional region version number.

If the schedule is empty, the version field is not included.

Known limitations - importing profiles from snapshot

National characters in profile, region or version names

In Hyperon Studio it is possible to create names of profiles, regions or region versions with characters outside the standard US_ASCII set, but that will likely cause problems with import of snapshot. This is associated with the limitations of encoding paths in ZIP files.

Mechanism of profile 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, the standard "compressed folder" utility in Windows produces files with the different encoding of pathnames. The information about encoding of paths is not included in ZIP file. These paths cannot be read by snapshot importer, so such files or directories will not be processed and the import process will be interrupted.

Importing descriptions of elements

Currently the descriptions of profiles, regions and versions are not imported from the snapshot. For regions imported from snapshot the description is set to a default value "Draft". Profiles and versions of regions imported from snapshot have empty descriptions.

Names differing by letter case

It is not possible to import or export profiles, when two regions within one profile or two versions of the same profile have names that differ only by letter case. For example, the situation where there are regions called REGION1 and Region1 within one profile is not supported by the snapshot mechanism.

This limitation is associated with the limitation on ZIP filesystem - 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: REGION1/ and Region1/ in the same folder).

This limitation is not a problem for profile names, since the profile names in Hyperon can only be in upper case.

Importing empty context

Importing empty context (which is equivalent to deleting context) is not currently supported. If the context file is empty, the importer skips the import of context and the existing context is left unchanged.