Parameters export

Parameter File system structure

IMPORTANT

In the snapshot ZIP file any directories with name starting with '@' have special meaning. They define the structure of snapshot file. Names of other directories (not starting with '@') are part of import data. For example, they may be interpreted as parts of domain elements names or names of profiles, depending on where they are in the directory structure.

Directory structure

The part of the directory tree of the snapshot zip file related to functions has the following structure:

/ (root directory of ZIP file)
|
+--Other optional content (directories or files)
|
+–-@functions/
   +--@profiles/
   |  +--PROFILE1/
   |  |  +--@regions/
   |  |     +--REGION1/
   |  |     |  +--VERSION1/
   |  |     |  |  +-- content for profile PROFILE1, region REGION1 and region version VERSION1
   |  |     |  +-- other versions of REGION1...
   |  |     +-- other regions inside PROFILE1...
   |  +-- other profiles...
   +--@global/
      |
      +-- content for global functions (not associated with any region)

‍

@params/ directory

Located in the top-level zip file directory, it contains the parameter content.

There are two subdirectories of the @params/ directory:

• @profiles/ - stores all parameters associated with regions
• @global/ - stores global parameters, not associated with a region

Except for these two subdirectories, the @params/ directory is not supposed to contain any other files or directories.

‍

@global/ directory

Located under @params directory, contains files and directories which define individual parameters.

‍

@profiles/ directory

Located under @params directory, holds content attached to regions. It has further structure, which reflects the structure of profiles, regions, and versions. Each subdirectory of @profiles/ stands for a profile with the same name as the directory name. Except for the profile directories, the @profiles/ directory should not contain any files. Inside each profile directory, there should be a directory called @regions/. Except for the regions/ directory, each profile directory is not supposed to contain any files or directories.

‍

@regions/ directory

It contains only directories. Each subdirectory of @regions/ directory denotes a region (stands for the region with the same name as directory name) with the same name as the directory name. Each region directory should contain a subdirectory for each version of the region, with the same name as the name of the version (for example, version 1 will correspond to subdirecory 1). Each version directory may contain files or directories which define individual parameters.

‍

Structure of files and directories defining individual parameters

The directory structure inside the @global/ directory or inside each individual version directory defines the code of parameter. The path segments correspond to parameter code segments, separated by dot ".". The last segment of the parameter code is the file name without extension. For example, the parameter with code motor.premium.annual corresponds to file annual.def inside directory motor/premium.

If we assume that it is a global parameter, the full path inside the zip file will be:

/@params/@global/motor/premium/annual.def/@params/@global/motor/premium/annual.mat

However, if this parameter were attached to version 2 of region REGION1 of profile PROPERTY, the path would be:

/@parameter/@profiles/PROPERTY/@regions/REGION1/2/motor/premium/annual.def

/@parameter/@profiles/PROPERTY/@regions/REGION1/2/motor/premium/annual.mat

IMPORTNAT

Definition of parameter and his matrix must contains in this same directory.

File names and extensions

The name of the file, excluding the extension, is the last segment of the parameter's code. The last segment of the parameter code consists usually of the two files, definition file with extension .def and matrix file with extension .mat. Exists two types of parameters consists of the one file (alias and parameter with external sources). The extension determines the part of the parameter:

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

The letter case in the extension has a matter. Imported are only files with lowercase extension .def and .mat

Files with different extensions are not imported.

Definition file structure

Overall file structure

Files with the definition of parameter have the following structure:

code = "demo.motor.coverage.availability"
description = ""

nullable = false 
cacheable = true 
distinct = false 
sort = "" 
slave = false 
label = "<no label>"
categories = ["SYSTEM"]

[[inputLevel]]
code = "coverage" 
label = "coverage code" 
type = "string" 
source = "coverage.code" 
union = false 
reverse_matcher = false 

 [[inputLevel]]
code = "option" 
label = "option code" 
type = "string" 
source = "option.code" 
union = false 
reverse_matcher = false 

[[outputLevel]]
code = "available" 
label = "available" 
type = "boolean" 
external = false 
array = false 

Types of levels:

• string
• integer
• number
• date
• boolean
• DateTime

Definition of tags

The definition of tags (categories) attached to the function has the format:

categories = [comma-separated_list_of_categories]

The name of each category must be surrounded by double-quotes ("..."). If there are no tags attached to the function, the list is empty: [] .

Matrix file structure

Overall file structure

Matrix files have the following structure:

#matrix for parameter demo.motor.coverage.availability
coverage ; option ; available
BI ; BRONZE ; no
BI ; GOLD ; yes
BI ; SILVER ; yes              

The first line defines the parameter that is the matrix owner.

The second line defines level names. Level names must match the names in parameter definition. The rest of the file contains matrix rows. Matrix types must be a match to parameter definition types.

The number of rows and level names must match a number of levels in parameter definition.

Level names and rows values are separated ";" character.

In this example parameter and matrix have two input levels (coverage, options) and one output level (available). Input levels are Strings, and the output level is a Boolean.

Encoding/decoding special characters

Some values from matrix entries must be encoded before export to .mat file. Encoding is done by replacing the value with a special sequence of characters: <#encoded_value#></#encoded_value#> During import same values are decoded to their normal value. Currently supported values:

Types of parameters

A standard parameter with the matrix.

He has a classic structure described in Overall file structure. He has two files (definition file and matrix file). Matrix and definition file must have the same path and name. The difference is only in extension. Matrix have .mat extension, and definition have .def extension.

slave (set a false) determines the parameter is the master parameter.

input levels and output levels determine matrix.

Alias

Alias is a parameter which does not have its own data matrix but uses data matrix from another parameter (called master).

Files with alias definition have the following structure:

code = "demo.motor.dict.vehicle.availableMakes"

nullable = false
cacheable = true
distinct = true
sort = "make"
masterName = "demo.motor.dict.vehicle.model"
slave = true
label = "<no label>"

[[inputLevel]]
code = "production_year"
label = "year of production"
type = "integer"
source = "quote.vehicle.productionYear"
matcher = "between/ii"
union = true
reverse_matcher = false

[[outputLevel]]
code = "make"
label = "vehicle's make"
type = "string"
external = false
array = false

[[outputLevel]]
code = "make_id"
label = "make identifier"
type = "integer"
external = false
array = false

• ‍masterName is the name of the master of alias.
• ‍slave (set as true) determines the parameter is an alias.

Global alias must be attached to global master parameter.

IMPORTANT

Alias attached to the concrete profile, region and version must have a master parameter with this same profile, region, and version.

It is not possible to attach global alias to master parameter with profile, region and version and conversely. Also is not possible to attach alias from one profile, region, and version to master parameter from other profile, region, and version.

A parameter with external sources.

This type of parameter doesn’t have a matrix file.

IMPORTANT

This type of parameter is not yet supported in import.

Files with a parameter with external sources definition have the following structure:

code = "demo.motor.dict.vehicle.price"

description = ""
nullable = false
cacheable = true
distinct = false
sort = ""
slave = false
label = " <no label>"

[externalSource]
autoRefresh = false
autoRefreshPeriod = ""
externalInMemQuery = ""
externalNonMemQuery = ""

• ‍slave (set a false) determines if the parameter is the master parameter.

• externalSource determines the parameter uses matrix values from external sources.

Exporting Parameter in Hyperon Studio

To export parameters in Hyperon Studio, go to Tools → Snapshot Export, check Parameter checkbox, choose profiles from which parameter should be exported and click the Export button. A popup window will appear. When the export is finished and no errors occurred, click the Download button to download snapshot in the zip file. If any error during export happens, an error message will be shown and the Download button will be unavailable to click.

Exporting Parameter via REST

Endpoint path, method, response statuses are available here: REST export endpoint

To export parameters via REST, the section below must be present in a REST request

{
   "profiles":["PROFILE_1"],   // which profiles should be used for export. If not present, user's currently selected profile is chosen
     "parameters": {             // if this node is present, parameters will be exported for "PROFILE_1"
        "fromSession": false,  // it will export all parameters, which starts with "demo.motor.coverage"
        "nameStartsWith": ["demo.motor.coverage"]
   }
}