‘Parameter’ is a concept used commonly in science language (mostly in field of mathematics or physics), that’s why there is many definitions to the word. For Hyperon system parameter is use for parameterization in business processes. Parameter is an element in a model or process (e.g. business), which can have different values depending on needs or criterion, what gives it possibility to influence process behavior.

Tutorial: Hyperon Concepts: Parameters.

Examples  #

Tariff - typical example of business parameter, determines tariff value (parameter value) depending on client properties (criteria), as below:

Then asked “What is the tariff parameter for client 35 years old in five year old contract?” we’ll get answer 0,0750 which goes into further calculations to in the end give total insurance price.

As shown parameters may not only give values as numbers, any combination of signs might be ‘parameter value’.

Here are given name of devices this parameter will give back width and height for graphic dimensions.

Parameterization is a process (or model), its action demands planning in the form of template which, in places chosen by designer, relates to parameters. Here is an example for Parameterization:

  1. Get insurance sum (IS) from client form,
  2. Get parameter TARIFF value for client,
  3. Calculate value of the parameter MIN_CONTRIBUTION for your client
  4. If CNTR

This algorithm for calculation contribution is in the form of template, which uses values of two parameters: TARIFF and MIN_CONTRIBUTION.

Parameter construction #

If you want make any modifications to already existing parameter find the parameter on parameters list (go to Parameterization and Parameter) and click. Then when you will see parameter structure site, next click

in top right corner.

To create parameter go to Parameterization (in main Toolbar) and Parameter, then click on

It will open parameter structure site.

Parameter view is divided in two parts: basic information and matrix (where matrix is visible when parameter definition is provided). In basic information it is optional to fill fields: Description, Region, Tags. Also remember to check checkboxes: Match required, In-memory index, District, External source - as you need. In edition mode you may add IN and OUT levels. IN levels are ones that parameter is looking for in the matrix, OUT levels are those which are given back by parameter. Those are basic information to create parameter, without them you can’t go any further. Columns in matrix are IN and OUT levels according to what was on input. Ability to create matrix depends on defining IN and OUT levels. To enter new positions into matrix click on

in top right corner of the matrix. As an addition in top right corner is icon

to see your latest steps modifying parameter and is it in OPEN or not session (PUBLISHED = closed session).

Operations with parameter

On parameter view there are two toolbars with possible actions, one in top of every section: parameter definition and matrix. Both allow you to make different actions.

First toolbar,

Allows to make actions like:

- Edit - starts editing mode where you may change parameter definition by actions:
  • set region and version,
  • assign tag,
  • add description,
  • add/edit/delete IN and OUT levels,
  • define sorting method - allows to define sorting method for OUT values (ascending or descending),
  • match required - if checked : when in matrix value won't be found will return error, if checked and no match is found in matrix, parameter will return null,
  • in memory index - If not checked then with every call to that parameter, its definition and matrix must be reloaded from database. Which means that, this checkbox is flag if parameter should be storaged in application cache.
  • distinct - filters duplicated records from the result list
  • external source
- Pin - makes hyperlink to parameter on Dashboard
- Duplicate - creates a copy of the parameter
- History - allows to see all published changes, made by all users, for selected parameter
- Export - creates XLSx file and allows to download it
- Import - imports XLSx file (provides validation)
- and more:
  • Rename allows you to change code without going back to parameter list (more about in chapter 5.1.2.5.).
  • Create alias – creates a copy of parameters’ matrix with ability only to make changes about which levels are IN and OUT, value sources. Alias do not own matrix,
  • Find usages - redirects you to global search where you may find every reference to that parameter
  • Remove – deletes parameter

Second toolbar

Allows to make actions only on matrix, like:

  • Edit - this is different kind of edit mode than in other parts of Hyperon module. All changes made in matrix are saved automatically when focus is taken off the field. Which means that there is no CANCEL and no SAVE button, there is STOP EDITING which closes matrix edit mode.
  • Lock input columns - helps when parameter has many levels, locking input columns makes horizontal bar apply only to OUT columns (horizontal bar moves only OUT column, IN levels are locked in default view)
  • Export - exports csv file, this export doesn't include parameter definition, only matrix values
  • Import - imports csv file (provides validation)

CSV Matrix import/export

Matrix export, without parameter definition, is possible from the level of second toolbar (as mentioned in previous chapter).

This kind of export packs only information included in matrix, does not export parameter definition. Which means that in exported file all values in first column may be numbers but there will be no information in file if they should be type Number, Integer, Date or String. That will be validated while import, when parameter definition information are available. CSV file is perfect to make small changes in matrix, it exports faster than XLSx file, and might be opened in any text editor (doesn't require MS Office Excel or any similar program).

On first popup user may decide which delimiter should be used to separate values in matrix. We suggest using:  |  or  .

When next popup appears file is generated and export is available (user should only give path to save the file).

When all changes are made, updated file may be imported to application. Then existing matrix will be overwritten. But while import values in matrix are checked. If any value in record is not as defined, then whole record will not be loaded.

Alias  #

When operation 'Create alias' is chosen exact copy of parameter is created, you need to give it its own unique code. The difference from standard parameter is that matrix is available in read-only mode. That’s because matrix is own by other parameter, original matrix – the one that can be changed is in the original parameter (called "master" parameter)- from which alias was made. Any change made in original matrix is automatically loaded to all aliases.
So why and when create an alias? Well anytime you need to use the same matrix in few parameters and you don’t want to type it again and again to parameter definition. It is also a big advantage when changes need to be made in matrix, used in many parameters, because there will be only one place in which those changes has to be made, in every alias they will update automatically. As said matrix cannot be change in aliases but what may be changed, is character of matrix levels. Any OUT level may be change into IN level and backwards (while edit parameter mode is active click on:

Change IN on OUT

Only matrix content is the same for all aliases.

For example if we go into parameter: demo.motor.dict.vehicle.data

Below parameter definition you will see all aliases (seen from the master perspective). User may see which levels are IN and OUT for every alias, as said not every level has to be used in alias.

Since, in this case, parameter is master of the matrix in section below parameter definition shows only aliases. If you would be set on alias detail view (e.g. demo.motor.dict.vehicle.availableModels), first in that section would be matrix master and next to it aliases:

When, on this list, name of one alias is clicked user will see its’ detail information. On toolbar there is an information that this parameter is an alias to another.

Parameters’ levels  #

To create new level click EDIT button (on the toolbar) and then click ADD IN or ADD OUT button depending on which kind of level is needed. Every level have to has Unique code, Column name, Value type, Value source, optional are columns Matcher, UNION, BLOB, TAB.

Value type:

Then in column 'Value type' choose:

- Integer
- Number – real numbers
- String -for ASCII characters (letters, symbols etc.)
- Date – in one of six formats:
  • 2013-03-13
  • 2013.03.13
  • 2013/03/13
  • 13-03-2013
  • 13.03.2013
  • 13/03/2013
- Datetime
  • 2017-07-31 14:56:07.627
  • 2017.07.31 14:56:07.627
  • 2017/07/31 14:56:07.627
  • 31-07-2017 14:56:07.627
  • 31.07.2017 14:56:07.627
  • 31/07/2017 14:56:07.627
    millisecond part is optional
- Boolean – for values:
  • 'YES' - or 'NO',
  • 'y' or 'n'
  • 'TAK' or 'NIE',
  • 't' or 'n'
  • 'true' or 'false'
  • 't' or 'f'
  • '1' or '0'.

Value source

In column 'Value source' from list we can choose any previously used context path, function or parameter. More information about how to build a context path you will find in Domain > Context. If you wish to call function in Value source column type $f function_name, to set value source as parameter type $p parameter_name.

Matchers

The purpose of matchers is to verify if value IN (argument in parameterization module) is a match to pattern in the matrix cell. For every IN level matcher may but not have to be chosen. Matchers may be applied for any type of data (string, integer, number, date and datetime) we do not recommend using matchers for boolean type, but for now it is still possible.
Matrix is searched through every column from left to right, which means the order of column (levels) is important and should be thought through when matchers are set.

There are few configurations in which we can use matchers:

  • between/ie
  • between/ii
  • contains/all
  • contains/any
  • contains/none
  • in
  • not in
  • text/regex
  • text/like

Matchers type between:

Searched Value (let's call it 'x') is compered to values from A to B.

  • In between/ie compartment left side closed, right side open. If A ≤ x < B then Yes.
  • In between/ii compartment both side closed. If A ≤ x ≤ B then Yes.

The '*' symbol stands for infinity value. What is important: if matcher between is set for datetime then value like : 12.12.2000 in matrix is understood as time interval since 12.12.2000 00:00:00.000 till 12.12.2000 23:59:59.999.

To set intervals you may use symbols ' : ' ' - ' ' , ' as separators.

Matchers type contains:

Searched value and Value in parameter are both sets of numbers. Lets’ say that searched value is set X and value in parameter is set Y.

  • If contains/all : all of X must be in Y to match.
  • If contains/any: at least one of values in X must be in Y to have a match.
  • If contains/none : none of X values can be in Y to have a match.

As separator for list you may use symbol ' ,'.

Important.

If you use a function as aninput level source the result will be automatically converted to the level'stype. In case of collections ex. [A,B,C] and string value type the parsedresult is literally "[A,B,C]" not "A,B,C" (point out to thesquare brackets).  The reason for that isfunction calls toString on the array implicitly.

It can be tricky, to avoidthis form of a  function result. Thefunction should always return proper string representation (not just a simplytoString() call)

As separator for list you may use symbol ' , '.

Matchers in and not in:

Lets’ say that searched value is X and value in parameter is set Y. Searched value must be single element and value in parameter may be a list.

  • If in - among all values from Y is at least one X and it will be a match.
  • If not in - among all values in Y can't appear X value - then it will be a match.

If X will be a list then the result of in matcher will always be false and not in matcher will always be true.

As separator for list you may use symbol ' , '.

Important.

If you use a function as aninput level source the result will be automatically converted to the level'stype. In case of collections ex. [A,B,C] and string value type the parsedresult is literally "[A,B,C]" not "A,B,C" (point out to thesquare brackets).  The reason for that isfunction calls toString on the array implicitly.

It can be tricky, to avoidthis form of a  function result. Thefunction should always return proper string representation (not just a simplytoString() call)

Matchers in and not in are opposite to each other.

The asterix '*' symbol stands for unique fit, always gives positive match.

Matchers type text:

Both of them are useful to search for text, combination of any signs, in selected column. Text/regex is actually the same as Java RegEx. (go to: basic RegEx info, advanced RegEx explanation).

Since Hyperon version 1.6.45 there is a new functionality called 'reverse'. For now it is only available for text/like matcher. Until now when 'in' value was checked using the matrix, we were looking for a match inside the matrix which means that when 'in' value was: 'Dorothy' and in matrix was 'D*' match was found.

When 'reverse' is checked then as 'in' value we can give 'D*' and if in matrix is any 'in' value starting with letter 'D' then a match will be found, like:

Parameter Properties

The list of IN level properties is extracted by application from start context provided by programmer. Context can return specific value for pointed properties. List of available context paths is defined by Context console . Context is contract between user and programmer, it defines what object types will be placed in context and under what keys. (More about Context in Chapter 4.3) Available checkboxes:

UNION
  • In case without matchers: first, system will check value compatibility with cell value, if there is no matching value system will attach cell with '*'
  • In case with matcher: at the beginning system search for any cell with right value (to matcher), if it is not found then system will fit '*' cell. Option UNION will return every solution right for match criterions. When checkbox is not selected will give only first matching cell value.
BLOB

Check if cell value on this level can be more than 500 characters. In case like that values are store in outside matrix – with the same parameters for reading and saving efficiency. For better performance use BLOB only if it’s necessary.

TAB

Use if value is a table of values separated by commas. Then level cells are storage for lists (e.g. 1, 2, 10, 20)

UNION – how it works in detail

Lets’ go further into UNION – how does it work? Well to see what are UNION properties we’ll have to look at few versions of one parameter, only different will be if checkbox UNION was checked or not. Our parameters will be named union.test, union.test1, union.test2 and union.test3. All of them will need information about Status and Age. Where status may be: Child (C), Student (S), Pensioner (P) or Other (O), Age is any integer value. As a result parameter will give percent value of discount for selected status.

In my parameters – YES if checkbox was checked and NO if not (that is the only difference between them):

  • union.test Status - UNION (NO), Age UNION (NO)
  • union.test1 Status – UNION (YES), Age UNION (NO)
  • union.test2 Status – UNION (NO), Age UNION (YES)
  • union.test3 Status – UNION (YES), Age UNION (YES)

For all those parameters matrix was defined:

Then when those parameter will be checked (for example in tester) that will give result as:

Looking closely to each case, let’s follow UNION search. In union.test parameter (no union checkbox was checked) search goes through column status finding best fitting match – that is row 4 or 5 since we were looking for ‘O 55’ and only in those rows ‘O’ may be find. Then goes into matching rows and checks if age is also fitting. Since Age is defined as a range from 50-100 (row 5) and ‘*’ (which is read as any value) in row, best match will be row 5, because ‘*’ is only chosen as best match when all other values don’t match.

In union.test1 checkbox union is checked only for status. In column status matching elements are in rows 4 and 5 as in rows 1 and 2 – because there is ‘*’ which with union checked is read as last, nevertheless still is a match. Those rows will be further evaluated. Because row 4 and 5 have the same Status value are treated as one value with two available paths depending on age, same rule applies to rows 1 and 2. Age criterion is 55, (without union) we are looking for best fit, choice is between range of 50-100 years old or ‘*’. Best match will be row 5 because reading ’*’ as any value has lowest priority for application. And from rows 1 and 2 also only one may be chosen, since in row 2 is age range from 27 to 69 and, in our case, age is 55 so row 2 is a best match, ‘*’ will not be checked since best match was already found.

If Union is checked only for Age ( union.test2 ), in column status matching will follow the rule of ‘best match’, so value will be ‘O’ in rows 4 and 5. Then we’re looking at column Age where union gets all matching values, which means both range of ’50-100’ and ‘*’- even though ‘*’ is considered as last in line, then as a result value, we will get ‘0’ and ‘90’.

In union.test3 operation union is checked for Status and Age level, what means for both of those all matching rows will be chosen. In column Status rows 1,2 (cause value is a ‘*’), 4 and 5 (since value is ‘O’) are a match. Then when we go into those rows and check values for column Age:

  • value ‘*’ in column 1 is a match as range of values ’27-69’ is – for status ‘*’. Which means, parameters returns discount values: ‘100’ and ‘5’
  • value ‘*’ in column 4 is a match as range of values ‘50-100’ is – for status ‘O’ returns values of discounts: ‘0’ and ‘90’

In summary: union gives back all matching to criterion values when without union only the best match is a result. ‘*’ is considered as lowest priority, which means that, without union, value attached to ‘*’ argument will be given as a result only when there is no other matching argument in matrix.

Level order

To change level order in edition mode grab selected level (place cursor on level, click left mouse button and hold) then move this level up or down by moving mouse. Drop level at it new place (let go of left mouse button). Match for the source value in matrix is searched column by column, from left to right. What means that reordering columns (levels) in parameter may alter result.

Parameters with external source  #

Parameter can use internal matrix stored within Hyperon Studio or matrix read from external database. The rule is quite much the same for both. IN and OUT levels must be defined in Hyperon Studio, all the functionalities : matchers, union, reverse, blob and tab (table) can be used as they were before, the only difference is where (or if) the matrix is stored.

When property externalSource is checked  one other property has an influence on which SQL template is performed .

If property in-memory Index is selected parameter's matrix is kept in memory. Only then Auto refresh settings are considered and In-memory SQL template is performed.

If property in-memory Index is not selected, matrix is refreshed (reloaded) with every call to parameter and Non-memory SQL template is performed. The matrix is not stored in memory that can have a significant influence on the parameters performance.

Behaviour of the parameter with external source depending on it's settings is characterized on the chart below.

Types of returned values  #

There are three parameter value types in use, that may be returned by parameter:

  • Single-value
  • Multi-value
  • Multi-row


Parameters List  #

To go to parameters list chose from the main toolbar Parameterization then Parameter. Lines colored blue are the ones that were opened last.

Options available:

  • "Import" to enter already prepared parameter to Hyperon
  • "Mark from file" imports file with codes and select parameters based on the file content
  • "Compare with extract" - imports file with extract and selects parameters based on file content.

On top of the list there is a Filter which allows you to sort parameters by date of publication or user who last made any modifications, next to those fields there is button

to clear all three search fields. If you are looking for specific parameter use Filter line and input searched phrase in right column.

From the level of parameter list you may act on many elements at the time. Just check checkboxes next to parameters you want to act on and then from toolbar, or dropdown list select an action.

Here are few functionalities available for parameters:

  • new parameter - creates new parameter
  • import - requires XLSx file with correct parameter definition
  • Mark from file - require loading txt file with names of parameters, those which are in the file and exists in given Hyperon Studio will be checked on the parameters list
  • Compare with extract - require extracted file, makes a comparison between file and given Hyperon Studio, then returns an information which element are the same, which changed and which are only in file or only on the environment.

Actions which are available if any parameter is selected (checkbox checked):

  • Mass export to XLSx - creates zip file with multiple parameters (first user must check parameters for export)
  • Codes export - exports txt file with names of the parameters
  • Extract - creates extract file, including names of parameters and timestamp of last edition
  • Assign Region - ascribes parameters to region and version, possible for multiple parameters only if non of them is already assign to region
  • Detach Region - deletes ascription to region and version
  • Set tag - allows mark with tag multiple parameters at once
  • remove - deletes all checked parameters

If you want to know how to get parameter value go to Tutorial: Getting parameter value . More on parameters: Tutorial: Using Parameters: Fundamentals.