Functions export

Function File system structure

IMPORTANT

In the snapshot ZIP file, any directories with names starting with '@' have special meaning. They define the structure of the snapshot file. Names of other directories (not starting with '@') are part of import data. For example, they may be interpreted as parts of the domain element's name 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)

‍

@functions/ directory

Located in a top-level zip file directory and contains the function content.

There are two subdirectories of the @functions/ directory:

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

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

‍

@global/ directory

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

‍

@profiles/ directory

Located under @functions 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, 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 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 subdirectory 1/. Each version directory may contain files or directories which define individual functions.

Structure of files and directories defining individual functions

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

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

/@functions/@global/motor/premium/annual.js

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

/@functions/@profiles/PROPERTY/@regions/REGION1/2/motor/premium/annual.js

File names and extensions

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

• .js is the extension for Rhino functions
• .groovy is the extension for Groovy functions.

The letter case in the extension does not matter. For example, .groovy, .gRooVy and .GROOVY are valid extensions for Groovy function.

Files with different extensions are not imported. A warning message will be produced if such file is in the directory where valid files with the definition of function are expected.

Definition file structure

Overall file structure

Files with the definition of function (both Rhino and Groovy) have the following structure:

/*
Starting block comment containing the definition of function tags (categories) and arguments
*/ 
 
 
function code

Comment defining attributes of function

Each file starts with a block comment (/*...*/) defining attributes of the function. The content of this comment is in the Toml configuration file format. Example of the valid comment:

/*
# DO NOT REMOVE, MOVE OR MODIFY THIS COMMENT
# unless you know what you're doing. Incorrect content will cause error during import.
# IMPORTANT: these escape sequences MUST be used inside this comment: '/' -> '\/', '\' -> '\\'
 
categories = ["CAT1","CAT2"]
 
[[arguments]]
name = "ctx"
type = "SPECIFIED_CLASS"
className = "org.smartparam.engine.core.context.ParamContext"
 
[[arguments]]
name = "argument1"
type = "BOOLEAN"
 
[[arguments]]
name = "argument2"
type = "INTEGER"
 
*/ 
 
return 1;

Comments

Lines starting with # contain a comment, which is ignored. The example above contains a comment with message automatically generated during export of the snapshot.

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: [] .

Definition of arguments

Definition of each argument comes after a list tag [[arguments]]. The definition has obligatory fields: name (the name of the argument) and type (data type). Currently supported data types are:

• "BOOLEAN",
• "INTEGER",
• "BIG_DECIMAL",
• "DATE",
• "STRING",
• "OBJECT",
• "SPECIFIED_CLASS",
• "EXTERNAL_CLASS".

If the type is "SPECIFIED_CLASS" or "EXTERNAL_CLASS", the third field className is present. This field contains the full name of the class, surrounded by double quotes ("...").

Required ctx argument

The list of arguments must contain the definition of the ctx argument, which should be identical to:

[[arguments]]
name = "ctx"
type = "SPECIFIED_CLASS"
className = "org.smartparam.engine.core.context.ParamContext"

Function body

The body of the function can be separated from the initial comment by up to two newline characters, which are not imported. Any new-line characters exceeding the two are included in the function body.

Encoding

File with the definition of a function is encoded using UTF-8 and should not be changed.

Exporting Function in Hyperon Studio

To export function in Hyperon Studio, go to Tools → Snapshot Export, check Function checkbox, choose profiles from which function 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 Function via REST

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

To export functions 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
   "functions": {              // if this node is present, functions will be exported for "PROFILE_1" 
        "fromSession": true,   // it will export only functions from user's session, which also starts with either "demo." or "test2" prefix
        "nameStartsWith": ["demo.", "test2"]
   },
}

‍