Introduction

Higson from business perspective

Higson as a Business Rules Management System is a system that helps organizations to manage, execute, and optimize their business rules from a centralized platform.

It is designed to easily handle large decision tables. Higson stands out for its extremely high performance and a designed matching algorithm to search large decision tables (1M rows and more) in a few milliseconds.

What Higson offers?

Higson offers a scripting language that allows users to write short functions that expand the capabilities of decision tables. Both software developers and operational staff can modify such functions or decision tables without touching the application’s code. The changes are immediately reflected in any application that uses the Higson engine.

Key features:

  • Higson Studio - Web UI that lets users to manage easily their business rules
  • Higson Runtime - engine embeddable as a lightweight jar to your business app
  • High performance – all rules are stored in in-memory caches so Higson provide immediately access and possibility to invoke them
  • Time Versioning - create multiple versions of the business logic and schedule them in a timeline
  • Domain Designer - design any domain you want to configure with business logic
  • Decision tables and Parameters - tabular representations for specifying which decisions are made using pre-defined conditions
  • Functions – help define more complex logic in Groovy language

Additional features:

  • Context - rules use the context to reference actual business data needed to evaluate a rule
  • Private session - there is no limit to the number of users working simultaneously; changes are not visible to other users before publishing
  • Dev Mode - special mode to speed up the initial phase of the development; each change is immediately visible to the outside world.
  • Built-in Profiles - monitor the usage of decision tables and DSL scripts or functions
  • Import and Export from/to Excel - import and export configuration and tets cases from/to Excel.
  • Multiple Databases support - Higson uses databases for storing rule configurations; supported databases: Oracle, MS SQL Server, PostgreSQL, MySQL
  • Test features (tester, batch tester) - before publishing changes, user can tests whether the rules work as desired and check the impact on other rules by using a mass tester to perform regression tests

Who and how will use Higson?

There are 3 groups of users, that will use Higson:

  • End User - application business end-user, which may modify values of previously configured domain.
  • Developer - Developer codes your business application with Higson support. Needs to prepare appropriate domain model at your app. Perform initial configuration which business user prepared firstly. Developer may mix Higson features: domain, decision tables, functions to reflect business domain configuration.
  • Business User – main designer of your domain. Initially Business User input final parameters values. Experienced Business User can perform highly sophisticated parameter redesigns without the necessity of application code change.

Here are short descriptions of components in the diagram:

  • Higson Studio - the complex web-based user interface for setting up parametrization. The tool includes parameters and functions repository, domain definition and configuration, testing, and export-import capabilities.
  • Business Application - Java application that has its business logic, parametrization externalized to Higson. The application is e.g. sales portal, product management system, policy life system. The parametrization is accessed via Higson Runtime.
  • Higson Runtime – as an embedded jar library provides to your Business Application robust java API for parameter/function/domain access. The library is responsible for retrieving data from Database schema and caching it as an in-memory index within the Business Application. At fixed intervals the library checks for changes alterations and updates itself asynchronously. That approach significantly expedites parametrization calls.
  • Database - storage for Higson externalized parametrization repository. Data is altered via Higson Studio. Higson Runtime Library accesses the schema in fully read-only mode. Higson supports the most popular SQL Databases.

How Higson can support organizations?

Insurance Industry

Higson helps insurers to start leveraging and embracing data in managing products and offering highly personalized solutions to customers, in real-time. Business and non-IT users can make instant changes and market new products in a matter of minutes. Higson has proved its usage in:

  • insurance underwriting
  • tariff management
  • insurance claims management, etc.

Banking & Finance

Banks also use rules engines to develop new financial products while maintaining pricing accuracy and compliance. As a result, new products enter the market in a matter of days instead of weeks or months. Higson can empower financial institutions to streamline important processes such as:

  • product eligibility
  • credit scoring
  • customer self-service, etc.

Telcom & Media

Telecoms have thousands of products comprising pricing, customer segments, distribution channels, packages, promotions, and subscriptions. Managing such complex portfolios can quickly become difficult and inefficient as new products and variations are introduced. Higson is a powerful product catalog that empowers non-technical business users to build, update, and manage all of their complex products with a single user-friendly interface. As a result, Higson drastically shortens time-to-market, cuts down on expenses, and eliminates potentially costly mistakes.

Industries, such as:

  • Retail
  • Airlines
  • Travels, and even more as a dictionary module.

Security | disclaimer

There are several ways we distribute Higson Studio: as a docker image, in the cloud, as an apache-tomcat ZIP file, or build a war package. Ensuring that any distributed version is secure is critical. Secured distribution reduces the risk of private information leak out and data theft. This article provides information that may help secure the site and its code and server information from attacks and data theft.

HTTP vs HTTPS

As good security practice, it is required to host any distributed version with an SSL certificate. SSL certificates are what enable websites to move from HTTP to HTTPS, which is more secure. SSL certificates make SSL/TLS encryption possible, and they contain the website’s public key and website’s identity. A website needs an SSL certificate to keep user data secure, verify ownership of the website, prevent attackers from creating a fake version of the site.

War distribution

Besides HTTPS, other rules listed below need to be applied. These rules involve only war package distribution - in other distributions, we have already done it for you.

Custom server error page

Any host server should have configured a custom server error page displayed in any case of server error. This page can prevent information leaks like server version, stack trace, etc.

Preventing slow HTTP attacks

Slow HTTP attacks are denial-of-service(DoS) attacks in which the attacker sends HTTP requests in pieces slowly, one at a time to a Web server. If an HTTP request is not complete, or if the transfer rate is very low, the server keeps its resources busy waiting for the rest of the data. When the server’s concurrent connection pool reaches its maximum, this creates a DoS. Slow HTTP attacks are easy to execute because they require only minimal resources from the attacker. We can reduce this by setting proper values of your server request time out, read timeout, headers limit, body limit, etc.

The deployment directory should not have any execute permission.

Folders and files in the server containing deployment of Higson Studio should have set proper edit/write permissions to avoid any edition by outsider users. Undesirable editions could lead to inconsistency in server or Higson data.

Versioning

The numbering of the software version is carried out using numerical designations: “x.y.z”. The numbers “x.y” indicate the version number of the software in Major and Minor notation (e.g. 1.21, 2.1).

The number “z” indicates a Patch version that does not affect the functional scope of the released version, and is intended for technical improvements or removal of noticed bugs.

Software versions marked as LTS (Long-Term-Support) are maintained for at least 18 months from release.

Technical support includes maintenance of LTS versions only.

Current list of LTS versions: 2.2, 2.3, 4.0

You can download the newest version from the Changelog.

Try it out!

DEMO

The demo project includes both:

  • demo application
  • Higson Studio

The demo application is used to collect input data from the end user and show output data from Higson Studio, where all algorithms and business logic is kept. Higson is designed to allow real-time changes in configuration, impacting results returned by the demo app. Higson Studio included in this set has no functional limitation compared to the full version.

Here, You can see Higson in action:

https://www.youtube.com/watch?v=YKl_Tah-AoA

If you are interested in trying out Higson in action our demo application is available here:

https://github.com/hyperon-io/business-rules-motor-insurance

Instruction

Logging

Logging in to application

After entering into the browser application URL, the user will be presented with a login form.

In orded to access application, user need to enter correct login credentials. If the login credentials are correct, user will be redirected to Dashboard panel. If the login information is not correct the acces to application will be denied.

The ‘Remind password’ button allows user to reset and change user’s password. After clicking the button, user will be presented with password reset form.

The next step is to type the e-mail address which is connected to the user’s account. The system will send an e-mail message with a link to reset the password.

Type the password in two separated fields. If everything was done correctly, Higson will confirm the new password for the selected account and lead you back to the login form.

Logging out from application

In order to logout from Higson choose the ‘Logout’ button visible in top righ corner of the screen. That will log the user out of the application.

Dashboard

Dashboard is created by user and by his individual needs, it might be changed by adding or deleting chosen objects from board any time. It’s a shortcut base. To get to it fast, click on ‘Pin’ button. Every ‘pinned’ objects will be seen on Dashboard with (added by you) description.

For example if there is a function like:

If I decide to ‘Pin’ it on my Dashboard, there is one more thing to add – ‘Description’. That is to make it easier for user, to find that element on the Dashboard, when there will be more elements on it.

Now when I go to my Dashboard:

Every window is a shortcut to selected element, with description (or comment as you prefer) of User’s choice. Now you won’t have to go all the way through toolbar operations to find that one function to input changes.

Parameters

Parameter is the basic concept in Higson.
It is conceptually similar to decision table - the term commonly used in rules engines. Each parameter is defined as matrix or table, in which we can configure how parameter’s value depends on the context data.
If application is connected to Higson in proper way, context can provide any data application works on. Parameter’s matrix is unlimited in size and works fast whether it has 1000 rows or 1 million rows. Below you can see parameter called “tariff” which returns tariff factor depending on client’s age and type of agreement:

TYPE OF AGREEMENT (IN) CLIENT’S AGE (IN) TARIFF VALUE (OUT)
A 0 - 30 0.95
A 31 and more 1.20
B 0 - 50 2.25
B 51 and more 3.50
C any 2.90

Value of tariff parameter is defined in Higson, outside of application’s code. You can say that parameter is the basic concept that allows to separate business logic from application’s code.
Following image shows another parameter defined in Higson Studio.

Each parameter has its unique name, configured dependencies and output value. It can return single value, multiple values or even sub-matrix.

Each parameter consists of 4 elements

  • definition of input columns (conditions),
  • definition of output columns (result values),
  • matrix built on input and output columns,
  • meta configuration (caching, sorting, etc.)

Input columns

Each input column (IN) have to be bound to some source. We distinguish 2 types of source:

  • Context source which points to some valid data in the context model - for example policy.insurer.age is valid path to the number which is the age of person insured on the insurance policy we are processing now,
  • Formula source which defines some cascade expression that needs to be executed to obtain source value - for example if we do not have age property in the context model, we can use function that calculates age using policy.insurer.dateOfBirth property from context.

Output columns

Each output column (OUT) holds potential parameter’s value. This potential value will become the result if IN columns in the same row matches the context data (or source in general). Values stored in IN columns are called patterns.

Both IN and OUT columns have:

  • unique code (unique within parameter)
  • data type (text, numeric, boolean, etc.)

Matrix

The heart of the parameter is matrix. Let’s say the matrix has N rows and M columns. First on the left are IN columns (conditions) and OUT columns (result) stands behind them. M is the sum of IN and OUT columns.

Specifics of the matrix contains:

  • Each matrix cell has value consistent with column’s data type.
  • Each IN cell holds pattern that can match or not source value.
  • Each OUT cell can hold literal value (result) or cascade expression that needs to be evaluated.

Meta configuration

In addition to the matrix and columns, each parameter has meta configuration which includes:

  • parameter’s code (unique in the whole Higson installation),
  • match required flag,
  • in-memory index flag,
  • result sorting expression,
  • version indicating version of the region, to which the parameter is assigned,
  • tags for organizational purposes - grouping, filtering, etc.

In-memory index flag is one of the most important configuration aspects. If in-memory index is enabled the whole matrix will be held in memory in the form of compact index. This index structure guarantees O(1) search time if all columns use the default matchers. If some column uses the non-default matcher it may be a bit slower but still fast as no network traffic is needed.

As a rule of thumb we suggest that parameters:

  • with matrix up to 100000 (100k) rows should use the in-memory index,
  • with matrix up to 500k rows - it depends on the values’ selectivity and number of columns (M),
  • with matrix larger than 1 million rows usually should not use the in-memory index.

Example

Consider 2 sample parameters:

Parameter demo.product.discount:

 IN (PRODUCT) 
SOURCE: POLICY.PRODUCT.CODE
MATCHER: DEFAULT
 IN (CLIENT_AGE) 
SOURCE: POLICY.INSURED.AGE
MATCHER: BETWEEN
   
OUT (DISCOUNT)
 
A 0-30 3.95
A 31-50 2.60
A * 2.25
B * 1.50
* * 0.00

Parameter demo.product.fee:

 IN (PRODUCT) 
SOURCE: POLICY.PRODUCT.CODE
MATCHER: DEFAULT
 IN (COVER_CODE) 
SOURCE: COVER.CODE
MATCHER: IN
   
OUT (MIN_FEE)
 
   
OUT (MAX_FEE)
 
A COV1, COV2 1.00 2.00
A COV3 2.00 5.00
A * 0.00 1.00
B COV1 1.50 6.00
B * 2.00 3.00

As you can see:

  • parameter demo.product.discount defines 2 IN columns (conditions) and 1 OUT column (result),
  • parameter demo.product.fee defines 2 IN columns and 2 OUT columns.

Following table describe columns’ definition for demo.product.discount:

COLUMN TYPE COLUMN CODE COLUMN DATA TYPE IN MATCHER
IN product string default
IN client_age integer between
OUT discount number

Following table describe columns’ definition for demo.product.fee:

COLUMN TYPE COLUMN CODE COLUMN DATA TYPE IN MATCHER
IN product string default
IN cover_code string in
OUT min_fee number
OUT max_fee number

Following image shows sample parameter defined in Higson Studio.

Create parameter

To create parameter (go to Parameterization and Parameter) click on

Edit parameter

To make any modifications to already existing parameter find the parameter on parameters list (go to Parameterization and Parameter) and click. On the parameter structure site click the “Edit” button.

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 addIN 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.

Parameter definition 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 stored 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,
    • 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;

Matrix toolbar

Allows to make actions only on matrix, like:

  • Edit - this is different kind of edit mode than in other parts of Higson 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).

Alias in parametrization

Create alias operation creates exact copy of parameter, 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 owned 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. This help you to use the same matrix in few parameters, and you don’t need 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 have 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: 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.

Dictionary

Defining dictionary

To define the decision table as a dictionary there is a checkbox “Dictionary” that needs to be marked.

One output level definition needs to be provided. A simple dictionary definition example is shown below:

Usage of dictionary

After successfully adding a new dictionary, a newtype for any input or output level in the decision table definition can be used:

When some level of the decision table is set to dictionary type, the table matrix allows inserting only values from the selected dictionary. Allowed values are also prompt in the list: Level values provided in matrix inherit type from the dictionary. As in the example for input level, it is Integer.

Restrictions associated with a dictionary type decision table

  • dictionary has exactly one output level
  • dictionary being in use cannot be deleted
  • dictionary cannot be defined as an external source
  • dictionary cannot have region versions assigned to it
  • decisiontable containing input level or several levels defined cannot be marked as a dictionary, only a decision table with one output level can be marked as a dictionary
  • decisiontable being in use as a dictionary cannot be unmarked as a dictionary
  • during import, the parameters defined as dictionaries are loaded first, if the imported parameter/parameters use a dictionary that is not defined and is not included in the imported group, the import will end with an error

Functions

Functions enable you to write code snippets in regular programming language, which let you implement any logic you want. You can write functions where parameter matrix is not enough.

As in the case of parameters, functions can contain logic based on:

  • any element from context,
  • any defined parameter,
  • any defined function.

Higson functions give you convenient API to:

  • handle context
  • read parameters
  • call other functions
  • operate on dates and strings
  • perform math operations
  • perform type conversions
  • log statements to log file
  • use domain objects

Following image shows another function defined in Higson Studio:

Function Logging Levels

It enables users to decide which types of logs are visible when executing a function. Each function has its own logging level. You can check and edit it in each function. It is located in the bottom-right corner of the function screen. It is possible to set a global function logging level which overrides the logging levels of individual functions. In order to do so, User need to create a parameter with code system.function.logging.level.

Such parameter must contain:

  • Input value type set as ‘string’
  • Input value source named ‘code’
  • Input matcher set as ’text/regex'
  • Output value type set as ‘string’

As an output value we can only use: OFF, ERROR, WARN, INFO, DEBUG, TRACE, which corresponds to the logging level.

The function logging level hierarchy is shown on the below diagram:

Warning is displayed on the function screen if the global function logging level overrides the function logging level.

Cascade Expressions: cascade call

Cascade Expressions

There are a few places where users can use either literal value or cascade expression. These places are:

  • parameter’s output cell,
  • parameter’s input cell,
  • domain attribute value,
  • input level’s source value.

There are 2 types of cascade expressions:

  • cascade get - redirects evaluation to given parameter,
  • cascade call - redirects evaluation to given function.

Basic information about cascade call:

  • every cascade call starts with $f symbol, which means cascade to function,
  • when cascading to function, user may pass arguments to that function,
  • when cascading to function, user may extract value from compound result.

Below are 3 basic usages of cascade expressions:

Cascade expression inside parameter’s output cell

Cascade expression used in domain attribute

Cascade expression used in level source

Cascade call

Everywhere a user uses the ‘Cascade call’ expression, it redirects evaluation to a given function and takes the value that function returns.

‘Cascade call’ syntax:

CASCADE STATEMENT MEANING
$f fun evaluates function fun and takes its result
$f fun (1, 5, active) function is called with 3 arguments passed: ‘1’, ‘5’ and ‘active’. Note that arguments are always passed as string values
$f fun (1; 5; A,B,C) if semicolon ‘;’ is present anywhere in arguments expression, Higson will use that semicolon as argument delimiter. In other cases comma ‘,’ will be used as delimiter. Note that this call will pass 3 string arguments: ‘1’, ‘5’, ‘A,B,B’
$f fun (ctx:insured.age, 5) user may pass values taken directly from current context by using ctx:path syntax. Note that this example will take first argument from current context
$f fun [ idx ] if function returns compound result (ParamValue, MultiValue, java array, Collection or Iterable), then cascade call extracts element from position idx, where idx = 0 is first element
$f fun [ code ] if function returns compound result (ParamValue, MultiValue or Map), then cascade call extracts element associated with key = code - result.get(code)
$f fun (1, ctx:prd.code) [factor] fun is called with 2 arguments, first is given as a literal, second is taken from current context from prd.code path. Higson extracts ‘factor’ field from function’s compound result
Implict type conversion

Suppose, you have parameter P with level L1 of type T1, and function F returning value of type T2. If you use cascade call inside P[L1] pointing to F, then:

  • internally cascade call will return value of type T2, internally cascade,
  • next, T2 will be converted to Holder,
    • conversion will meet Higson’s conversion standards, see -dec(), -num(), -str(), -date(), -bool() conversion methods,
    • conversion may be lossy (eg. T1 is integer while T2 is number)

Programming in Higson

Connecting application

To run Higson within your application you have to add it to your framework. Higson can be run within any framework. We prepared example for Spring and Java 11.

More information in the tutorial: Connecting application

Injecting Higson Engine

After connecting application you have to inject Higson Engine (part of Higson Runtime Library) in any place your app connects with business logic:

1
2
@Autowired
private HigsonEngine engine;

Getting parameter value

Parameter is one of the core concepts of Higson. More information in the tutorial: Parameters

Defining values in Higson

Simple parameter definition (with only one input and one output):

PARAMETER CODE: simple.parameter

 INPUT #1  
SOURCE: POLICY.PRODUCT.CODE
MATCHER: DEFAULT
 VALUE TYPE 
SOURCE: POLICY.INSURED.AGE
MATCHER: BETWEEN
   
VALUE SOURCE
 
Swimmer name String swimmer.name

OUTPUT #1

Ranking VALUE TYPE Integer

OUTPUT #1 VALUE TYPE
ranking Integer

PARAMETERS DATA:

SWIMMER NAME RANKING
Ashley 2
Celine 1
Kate 4
Melanie 3

Now imagine you would like to show ranking position for Melanie (last row in matrix above) in your application.

Prepare context

1
2
3
HigsonContext ctx = new HigsonContext(
   "swimmer.name", "Melanie"
);

Execute get method

Finally execute get method and receive parameter value for Melanie

1
2
ParamValue pv = engine.get("simple.parameter", ctx);
Integer pos = pv.getInteger("ranking");

Invoking parameter via Higson Engine returns instances of ParamValue classes. It contains evaluated values as sub-matrix from given parameter based on its input levels.

Calling function

Imagine you would like to calculate the cost for booking a room given the cost per day and the duration of stay (in days). The formula is pretty simple.

1
total cost = cost per day * duration in days

Write function in Higson

Function in Higson are written in Groovy (JVM language).

FUNCTION CODE: simple.parameter

1
2
3
4
5
6
def costPerDay = ctx.getNumber('booking.costPerDay')
def dateFrom = ctx.getDate('booking.startDate')
def dateTo = ctx.getDate('booking.endDate')
def durationDays = date.getDayDiff(dateFrom,dateTo) + 1

return costPerDay * durationDays

ctx is an instance of ParamContext class that you can use to get any argument from context you passed to HigsonEngine. ParamContext is automatically passed to every function in Higson Engine.

date.getDayDiff is an example of a built in method in Higson.

date.getDayDiff is helpful in this scenario, because it calculates the difference in days between two dates. We add +1, because we want to include both end dates (the difference between 1st January and 3rd January is 2, so we need to add 1 to receive a duration).

Prepare context

Prepare context locally in a method you want to call the Higson function. Connect variables names the function within the constructor.

1
2
3
4
5
HigsonContext ctx = new HigsonContext(  
  "booking.costPerDay", "200",
  "booking.startDate","2020-01-01",
  "booking.endDate","2020-01-03"  // 3 days duration
);

Execute call method

Finally execute call method and calculate total cost of vacation

1
BigDecimal vacationCost = (BigDecimal) engine.call("simple.function", ctx);

Accessing domain

Domain is one of the most powerful Higson features. However it’s very Higson specific, so if you’re new to Higson you might be thrown away by too much abstraction. That’s why we highly recommend to start by getting familiar with the domain concept.

Defining domain in Higson

The goal of Higson domain is to map real life into the system. Let’s imagine you develop an application for selling insurance. Your domain focuses on pricing plans and its excerpt could look like this:

Higson runtime rest architecture

Let’s say we would like to receive BI position on screen - POS.

Attributes values can be constant or parameter or function.

Constant: No context needed.

Parameter: The same as in getting parameter example. Prepare context locally in a method you want to get domain value to. Connect value source from parameter definition within the method.

1
2
3
HigsonContext ctx = new HigsonContext(
   "coverage.source", "BI"
);

Function: The same as in calling function example.

Getting value from domain

Execute following code:

1
2
3
4
5
6
7
HigsonDomainObject domainObject = engine.getDomain(
  /** Profile code **/ "DEMO",
  /** Domain path **/ "/PLANS[FULL]/COVERAGES[BI]/");

ParamValue pv = domainObject.getAttribute(
  /** Attribute code **/ "POSITION").getValue(ctx);
);

We received position for BI coverage.

Let’s modify the scenario a bit and imagine we would like to list all coverages attached to full plan. We could execute the following code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
HigsonDomainObject domainObject = engine.getDomain(
  /** Profile code **/ "DEMO",
  /** Domain element path **/ "/PLANS[FULL]/");

List<HigsonDomainObject> coverages = domainObject.getChildren(
  /** Collection code **/ "COVERAGES");

for(HigsonDomainObject coverage : coverages) {
    logger.info("Coverage : {}", coverage.getCode());
}

Higson util methods

To start coding with Higson Studio, user first need to declare a programming language. Currently, there are two available languages: Groovy and Rhino. Functions can be constructed using only Groovy commands, but there are some Higson-specific methods essential to making a fast and efficient algorithm. These additional methods are called util functions and have been added to the basic Java and Groovy methods. Util functions in Higson allow users to fetch results from all Higson-specific elements: context, domain, functions, and parameters. The full documentation about all the methods is displayed in the function editor when a command is recognized.

How to get data from context

Once the context is created, we use paths to navigate through it and pull data into functions and parameters. In Higson DEMO you will find this function demo.motor.util.drivingLicenceYears. Let’s take a look at a simple example:

1
2
3
4
5
6
7
// driver's current age
def driverAge = ctx.getInteger( 'quote.driver.age')
// driver's age when obtaining licence
def obtainLicenceAge = ctx.getInteger( 'quote.driver.licenceObtainedAtAge')

// diff
return driverAge - obtainLicenceAge

This function, like every other function in Higson, requires context - it will always be passed as an argument to a function. This is necessary to make all the util functions available in the function editor.

There are two elements pulled from the Higson context: driverAge and obtainLicenceAge. The construction here is simple:

  • ctx.get<datatype>(‘contextPath’) is designed for simple elements like strings, integers, data, booleans, etc., for example: ctx.getInteger(‘contextPath’)
  • ctx.get(‘contextPath’) is used when you want to pull an object

An object like ‘driver’ is pulled using the following command:

1
def  driver = ctx.get('quote.driver')

Next, get selected drivers’ age by simply using:

1
driver.getInteger('age')

Also you can get the same result using just one command:

1
def driverAge = ctx.getInteger( 'quote.driver.age')

How to get data from attributes

The next step is to iterate through context values. In the DEMO context, we have a root attribute: quote that includes many objects type like ‘Option’. We need to use a path to get those values:

1
def options = ctx.get('quote.options')

and then we can iterate through them to perform any necessary operation. Here the attribute ‘code’ of each option is pulled:

1
2
3
4
options.each{ it ->                 
	def optionCode = it.code                
	log.info('option code {}', optionCode)            
}

How to call another function

The basic command is:

1
def functionResult = Higson.call('functionCode', ctx)

This command will perform a singular execution of the function and will pull its results to defined in the main function variable functionResult. The ‘higson’ command is one of many available in the functions’ util methods. Typing the phrase ‘Higson.’ in the function editor will display a popup with information about all available matching util methods. Functions require additional arguments when called. Their values have to be declared in the functions invocation command like:

1
def functionResult = Higson.call('functionCode', ctx, arg1-value, arg2-value)

For example, in the function pl.decerto.demo.telco.package.activation.price.calculator:

The variable overallActivationPrice is defined by a function call:

1
Higson.call("pl.decerto.demo.telco.package.activation.price.sum", ctx, packageCode)

in the 4th line of the function body. The packageCode is a variable given as an argument to pl.decerto.demo.telco.package.activation.price.sum function. Why do we need to pass an argument? That specific function requires an argument, as you can see in the function settings:

It’s not always required to pass arguments to a called function. However, just note that an argument that’s not passed to a function will need to have its value assigned in a function. Arguments have to be passed in the correct order. When a function requires five arguments, you can skip passing only the last listed arguments.

For example, we have a function named ’exampleFunction’:

1
2
C = C ? C : 1   
return A * B * C * D

That function requires arguments A, B, C and D (all integers), the call can look like this:

1
Higson.call('exampleFunction', ctx, value-A, value-B, value-C, value-D)

or

1
Higson.call('exampleFunction', ctx, value-A, value-B, null, value-D)

but when typed like this:

1
Higson.call('exampleFunction', ctx, value-A, value-B, value-D)

value-D will be assigned as variable C within the function ’exampleFunction’ and variable D will be considered null.

How to call a parameter

When a parameter has only one OUT level and only one result is expected, then we use a simpler command to declare the result value type: Higson.getString(‘parameterCode’, ctx), Higson.getInteger(‘parameterCode’, ctx), Higson.getBoolean(‘parameterCode’, ctx) etc.

Every parameter can be called using:

1
Higson.getParamValue('parameterCode', ctx)

We then receive a table of values as a result. Keep in mind that you can select OUT level values and iterate through rows of the result.

For example, in function pl.decerto.demo.telco.invoice.discount.price.calculator, parameter pl.decerto.demo.telco.package.invoice.discount is called.

It includes one IN level and two OUT levels:

  • IN - InvoiceEntryNumber,
  • OUT - discounts,
  • OUT - CrossSellPromotion

Firstly, the parameter is invoked:

1
def pv = Higson.getParamValue('pl.decerto.demo.telco.package.invoice.discount', ctx)

Then, each result column is assigned to a variable. And only the first row of the result is considered:

1
2
def discountCodes = pv.row().getStringArray('discounts')
def includeCrossSellPromotion = pv.row().getBoolean('cross-sell promotion')

For the discounts column, an array of string values is pulled because each returned result is a list of string values.
Then, boolean values are pulled for the ‘cross-sell promotion’ column. The type of pulled values declared in the function complies with the parameter level definition.
However, the example above has one main flaw - it doesn’t consider all the possible results.

Let’s see what happens when we make a small alteration to it:

  • add UNION to the invoiceEntryNumber - for more info about level properties go here,
  • add a row to the matrix with values: 1-12;EMAIL, HBO;false

As a result of these minor changes, the same parameter will always return two results.

To include all pulled result rows, we have to make the following iteration:

1
2
3
4
5
def pv = Higson.getParamValue('pl.decerto.demo.telco.package.invoice.discount', ctx)
pv.each{ it ->    
	def discountCodes = it.getStringArray('discounts')    
	def includeCrossSellPromotion = it.getBoolean('cross-sell promotion')
}

How to fetch elements from the domain

The last Higson-specific command is ‘domain.get’. To learn more about this command we have to use domain structure. In our example, the domain is from the TELCO demo profile.

If our goal is to extract value from the ‘Available’ attribute in the HBO discount, then the function should include ‘domain’ util method with selected profile code domain.get(“TELCO”).
In order to get the COMFORT collection in the Packages branch use .get("/Packages[COMFORT]").

Next, we have to run .get("/DISCOUNTS[HBO]") to navigate to the HBO element in the DISCOUNTS collection.
And lastly, we run the .getAttrBoolean(“Available”, ctx) command to pull values from the ‘Available’ attribute. The final function should look like this:

1
2
def comfortDiscountHbo = domain.get("TELCO").get("/Packages[COMFORT]/DISCOUNTS[HBO]")
def isDiscountAvailable = comfortDiscountHbo.getAttrBoolean("Available", ctx)

Another way of getting into the DISCOUNT collection and fetching all the elements is by running .getAll(“DISCOUNTS”). Then, we navigate into the DISCOUNT collection and run the .getAttrBoolean(“Available”, ctx) command to pull values from the selected attribute in the domain.

1
2
3
4
def comfortPackage = domain.get("TELCO").get("/Packages[COMFORT]")
for (def discount : comfortPackage.getAll("DISCOUNTS")) {     
	discount.getAttrBoolean("Available", ctx)    
}

Tags

Tags are helpful tools to search for parameters and functions. They work as label, which can be assigned to different elements in the system.
Selected elements may be searched by listing tags in field of our interest. Tags have no influence on work of Higson system, they are there only for our convenience.

List of tags

To see list of tags go to Domain in main toolbar and select Tags.

Creating new tag

If you want to create new tag select Add button and set tag properties.

Tag details

When detail information are needed click on selected tag to learn more about it.

Operations from toolbar:

  • Edit – make changes in tag,
  • To functions – shows all functions with this tag,
  • To parameters – shows all parameters with that tag,
  • Remove - delete tag

Exporting tags

‘Export Tag’ creates a XLSx file. When file is created you may download it on your computer.

Importing tags

To import tag it is recommended to Export empty tag file. Fill Columns and then import tag to Higson system.

Context

When application uses parameter or function, its value depends on context. In other words - context is an object model containing all data that may affect parameters’ or functions’ values. Once we design context model, we can make our parameterization depends on any data from the context.

Context designed inside Higson Studio is kind of interface which can be used by all Higson components. It should be abstracted from application’s or database model.

Context design should focus on business needs. Such context will be conceptual bridge between development team and business analysts.

Following image shows sample context defined in Higson Studio.

Context designed in abstraction from application makes it possible to test business logic directly in Higson Studio, even if application is not ready yet. Read Using tester to see how you can verify parameter’s or function’s behaviour with built-in simulator. When the application gets connected to Higson, it becomes application’s responsibility to implement context.

Plugin

A plugin is an instance of Java object added to the Higson context.

Adding plugins

HigsonEngineFactory has a method setCustomPlugins that takes map, where key is a plugin code and value is an instance of the plugin.

This method allows developers to inject custom plugins or even override behaviour of Higson default plugins. Plugins will be added, when method is called.

Higson default plugins codes:

key description
ctx Higson Context
mpp Higson operation methods
Higson alias for mpp
domain Domain operation methods
log Logger operation methods
util Utility methods
str String operation methods
math Math operation methods
date RhinoDate operation methods
type Type operation methods

Example

Let’s assume you need RSA256 cypher to encrypt data in application, to achieve that HigsonEngineFactory we will provide instance of com.auth0.jwt.algorithms.Algorithm.RSA256 to setCustomPlugins(Map<String, Object> customPlugins) method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
@Configuration
public class CustomHigsonConfiguration {
    /**
     * Cipher algorithm as custom plugins.
     */
    private final static Map<String, Object> CUSTOM_PLUGINS = Map.of(
            "rsa256", Algorithm.RSA256(publicKey, privateKey)
    );

    @Bean
    public HigsonEngine higsonEngine() {
        final var factory = new HigsonEngineFactory();
        factory.setCustomPlugins(CUSTOM_PLUGINS);
        return factory.create();
    }
}

and after tact we can use Algorithm.RSA256 methods inside Higson Studio function creator:

Domain

The domain allows to define types and create objects representing business model. Each object can have a set of attributes, which take parameters, functions or literals as values.

The purpose of the domain is twofold:

  • allows to organize parameters and functions into business objects, creating an easy way to navigate configuration
  • creates a transparent way to access these parameters and functions from the app without binding it to specific parameter/function names.

The domain answers the question of what you would like to parameterize.

  • Using Menu-Model-Domain definition we can design domain types, their relationships and attributes,
  • Using Menu-Model-Domain configuration we can create instances of domain types and configure their attributes with use of parameters or functions.

For example, if we want to configure life insurance products:

  • Each life insurance product consists of covers and funds,
  • Each cover has different maximum insurance sum, availability logic, premium logic, etc.,
  • Each fund has different transfer fee, etc.

Application connected to Higson can use any defined logic solely through domain layer. These are sample scenarios:

  • getting all products from domain,
  • getting all covers from product “PT3”,
  • getting all covers (from given product) with attribute is_available equal to true,
  • calculate premium for given cover - just by getting value from base_premium attribute. We recommend not to use parameters and functions directly in application’s code. Instead we advise to use parameterization only through domain layer. Such approach, which we call polymorphic configurations, makes application even better separated from business logic.

Following image shows an example of domain configuration:

Domain definition

Before you start defining your domain definition, you will need to create a profile. Domain definitions are linked to a specific profile, and this allows you to create multiple definitions to represent different aspects of your business.

To start creating domain definitions, go to Domain > Domain definition.

Creating domain types

Domain types represent the different types of business objects that exist in your business model.

At the top of the Domain definition screen you can see a list of domain types that have been defined for the selected profile.

To add a new domain type, click the Add button It will allow you to create a new domain type, providing it’s code and name, and optionally selecting one of the predefined business roles for the object for easier recognition. The code of the type will be used when you access your domain through programming interfaces, so it’s important to use clear codes that are intuitive in your business environment. Names are only normally used as labels inside the Higson Studio.

The types section will also allow you to edit and delete existing domain types. To maintain coherence, it’s not possible to delete a domain type if there are active objects of that type in your domain.

For this example used throughout this tutorial, we’ve created 3 domain types:

  • PRODUCT, representing a Life Insurance products
  • COVERAGE, representing coverages of specific risks within the product
  • DISCOUNT, representing reductions in premium

Additionally, we’ve created a ROOT type. To act as the main element of this domain.

Assigning components

Once you’ve created and selected a domain type, you can configure it’s components. Components represent the relations between your types.

When you create a component, you need to set a code and name. Those have roles similar to those of types: the code will be used by programming interfaces to access a component, and name is displayed throughout the Higson Studio.

Each component has to have a type specified. You can select one from the combobox in the type code column. This allows you to choose a domain type for the relation.

To determine if the relation is a collection of components, check the multiple box. Leaving it unchecked designates the relation as single-component.

You can control if the particular component is displayed in the domain tree inside the Higson Studio - if you want it to, check the in tree box. All relations of an object can be accessed from it’s details screen, but in some cases it’s good to create an easier way to navigate to them.

For our example, we’ve created some relations in the PRODUCT type. A product has a collection of COVERAGES that represents the different risks that can be covered by the product, and a collection od DISCOUNTS - allowing us to configure discounts that can be applied to a specific PRODUCT.

In addition, we’ve created a single-component relation to a COVERAGE that designates the main risk covered. In case of Life Insurance, this will be the clause that covers the risk of death of the insured, and it will require some special handling inside the application, so a direct reference to it will be useful.

Setting the main type

As the domain is a tree-like model, it needs to have a designated root. To mark a type as root, select the type from the list and click the set as main button.

Root objects have some special behaviours:

  • when a type is set as main, Higson will automatically create an instance of this type directly under the profile.
  • this instance doesn’t have its code or name, and its components are accessed directly without specifying an object in programming interfaces.
  • if the in tree box is unchecked on a component of the root type, the objects assigned to that relation are still displayed in tree, but without the grouping label.
  • any ATTRIBUTES created for the root type will not be accessible.

Creating Atributes

In addition to COMPONENTS, domain types can each have a set of ATTRIBUTES. Attributes hold the detailed information about the objects, and are used both as a navigation tool and a programming interface.

ATTRIBUTES have values that can be either functions, parameters or literals. This is decided not on the type level, but on the object level. It means that for a particular attribute, some objects can have it’s value given literally, while others have a parameter or a function assigned to calculate value based on context.

To create an attribute, select a type on the domain definition screen, and click the Add button.

Similar to types and components, you will have to provide a code and a name for the attribute, code being used in programming interfaces and name - to be displayed throughout the Higson Studio.

In addition, you are able to set a group for an attribute. Groups allow your attributes to be displayed together based on common topics they relate to.

You can also change the order in which ATTRIBUTES and groups will be displayed inside the Higson Studio. To do that, click the reorder button and drag your groups in the order you want. After selecting a group, you can also reorder the ATTRIBUTES contained in that group.

For our example, we’ve created some attributes for the PRODUCT type:

  • DISPLAYED NAME - represents the full name of the product, displayed on documents.
  • SHORT NAME - represents the shortened version of the product name, to be used on small UI components like buttons.
  • IS AVAILABLE - is an attribute that will provide a boolean answer to the question “is this product available for the given context”.
  • TOTAL PREMIUM - is an attribute that will provide the total premium for the product, which in our business case it the sum of discounted premiums for each coverage.
  • TOTALBASEPREMIUM - is an attribute that will provide the total premium before discounts are applied. In our business case, this is the sum of base premiums of each coverage.

Default values

You can assign default values to each ATTRIBUTE. The default value can be either a parameter, a function or a literal. Every object of a particular type that is created will automatically have the default values set for each of it’s ATTRIBUTES.

In addition, whenever you create a new ATTRIBUTE with a default value, or set a default value for one, you will get a popup asking you how to apply this value to existing domain objects of the given type.

Below you can see the popup with possible options for editing an existing default value. The options differ based on the operation.

For all changes:

  • no change - the values of the attribute will not be changed for existing objects. If you ad a new attribute, the existing objects will have it’s value empty, despite a default value being provided

When creating a new attribute:

  • set new value - all existing objects will have the new attribute’s value set to the default

When setting a default value (there was no default value before), or changing the default value:

  • set new value only if current is empty - all existing objects that did not have a value for the attribute will have the value set to the new default
  • force setting new value, all previous individual values will be replaced - ALL existing objects will have their values for the attribute replaced to the new default value

When changing the default value:

  • set new value only if current is equal to previous - all existing objects, that had a value for this attribute equal to the previous default value will have it’s the attribute’s value changed to the new default
  • set new value if current is empty or equal to previous - all existing objects, that had no value for the given attribute, or had a value equal to the previous default value, will have the attribute’s value replaced by the new default
  • force setting new value if current value not equal to previous, individual value will be replaced - all existing objects, that had a value NOT EQUAL to the previous default value will have their values set to the new default

Setting the right default values will speed up your work with the domain significantly. It’s important to set a general policy for it to maintain consistency.

Some ATTRIBUTES will almost uniformly share the same value. In the example we use in this tutorial, PREMIUMTOTAL and BASEPREMIUMTOTAL attributes of the PRODUCT type will use the same function as implementation for every single object created - so we’re setting the default value to that function. We’ve also set the default function for PREMIUM attribute of COVERAGES, as in our business model, this is uniformly the BASEPREMIUM reduced by the values of applicable discounts.

For ATTRIBUTES that return non-text values, it’s good to set a default so that an object can be used and function in your application without the need of detailed configuration. In our example, we’ve set the default of all ISAVAILABLE attributes to true - this means that immediately after creation, the new object will appear and function properly within the application - the specific configuration of availability can be provided later. We’ve also set the BASEPREMIUM attribute of COVERAGES to 0 - this ensures that for a newly created object, the attribute will return a value, so other aspects can be configured and tested before approaching the premium configuration.

To maintain clarity, provide descriptions of the expected values in the fields where no other default value makes sense, using a specific markup for easy recognition of fields that need to be configured before the new object is functional. In our example, we’ve used the markup to describe those fields, for example is the default value for _DISPLAYED NAME attribute on PRODUCT.

Domain configuration

To create elements, navigate to Menu -> Domain -> Domain configuration.

Creating main elements

Every element in a domain, with the exception of the root element, is a component of another element. The elements that are components of the root element are refferred to as main throughout this tutorial.

When you enter the Domain configuration screen, you will see the domain tree on the left, the components of your ROOT element on the right.
To add new elements, click Add button. You will be prompted for a code and a name of the new element.

  • code is the identifier of the element used by programming interfaces. Please note that it’s not possible to change the code once an element has been created. The code has to be unique within any given component collection, but does not have to be unique for all elements of a given type.
  • name is the descriptive name of your element. While it’s possible to access the name of an element through programming interfaces, it’s generally not advised - it’s generally better to create an attribute like DISPLAYED NAME to store the name used by client applications, and use the element’s name for easier recognition within the Higson Studio.

In our example, we created a single PRODUCT element. Once the element is created, you can navigate to it by clicking on it, or by selecting it from the left-side tree.

You can always return to the main element screen by clicking the Home button in the upper-right part of the screen.

Creating non-main components

Non-main components are created in much the same way as main elements, but we have to navigate to a specific component first.

You can navigate to a component screen of an element, from the element screen. In the lowest section of the screen, you will see labels representing all components of a given element type, along with the number of elements currently assigned to the component. Clicking on the label will take you to the component screen, where you can add new elements in the same way as main elements on the root element.

In our example, we’ve created 3 COVERAGES and 2 DISCOUNTS for our PRODUCT.

If a given component is marked as in tree in the type definition, you can also navigate to the component screen, and to any elements assigned to that component by clicking on the label on the left-side tree.

Creating references

In addition to creating new elements as components, you can also create references to existing elements. This comes in useful if some components have specific roles and are often accessed directly, or if they are shared between many parent objects.

You can create a reference in much the same way as you create a new element by navigating to the component screen and clicking the +Add reference button. This will bring up a popup screen with a list of all created elements of the required type. You can filter those elements by code, name or path (you can read more about paths in the next section of this tutorial), and select the ones you want to add as references to your component.

In our example, we’re setting the MAIN COVERAGE component to a reference to the P1MAIN coverage from the COVERAGES collection of the product. This is because while most operations we have in our application operate on all coverages, there are specific cases when the main coverage needs to be accessed directly.

A reference is a pointer to an element that is created in another branch of the domain tree. It’s important to remember that this is not a copy - navigating to a reference of an element will bring you to the actual element screen of that element, and anych changes made in it’s configuration will affect the actual element and all references to it.

While you have the freedom of choosing where you want your actual elements to be, and where the references are, it’s important to keep it consistent throughout your configuration. If you have additional components that point to elements that need to be accessed directly or treated in a special way, it’s generally better to have them as references to elements that are created in the component representing the whole collection.

Likewise, it’s better to have separate “storage” components for elements that are used throughout many main element components - if you decided, for example, that multiple products can share the same coverages, it’s better to create a main component holding all the possible coverages, and reference them inside products, then to reference coverages from one product onto another. This way, it’s more readable to the users that the given element is shared, and that changes to it will affect multiple products.

References are marked with a link icon on the domain tree and on component lists.

The element path

Any element and component in the domain has a specific path. This is very important when using the domain in programming interfaces, but it also allows for quicker navigation in certain UI components of the Higson Studio.

A path to an element is a list of elements and components that need to be navigated from the root element to access the element. This path is a set of separated component names, with element codes specifying specific object inside a component collection given in square bracers after the component name. If a given component is not a collection (it’s not designated as multiple in the type definition), the element code can be ommited.

For example, the path to the Example product 1 we’ve created for our example is PRODUCTS PROD1, and the main coverage in the product can be accessed through PRODUCTS[PROD1]/COVERAGES[P1MAIN](path to the actual element in the COVERAGES component collection, or through PRODUCTS[PROD1]/MAIN_COVERAGE

While paths are mostly used by programming interfaces, some UI elements inside the Higson Studio will allow you to filter elements by path - understanding how they are created will help you quickly limit your results to the elements you are interested in.

If, for example, we hand many more products and coverages created in our domain, selecting the MAIN_COVERAGE reference might take some time - but you can filter it by providing a partial path, for example /PRODUCTS[PROD1]/COVERAGES - this will limit the displayed elements to those defined inside our product.

Removing elements and references

You can remove an element by selecting the Remove action from the utility action bar in the upper right corner of the element screen. Please note, this will remove the element, even if you navigated to it through a reference.

Alternatively, elements can be removed from the component screen by pressing the x button next to an element. This will remove elements that were created for this component, and it will remove the reference. The referenced element will not be removed.

When you delete an element, all elements created as components of that element are also removed, along with any references that point to the elements being removed.

Parameters and functions used as values for ATTRIBUTES of removed elements are not removed.

Profiles

Option Profiles opens a list of profiles available on your Higson.

If you wish to know more about selected profile click on its name on the list. Then detail information window will appear.

Profiles are available for edition.

How to create profiles in Higson

In the main toolbar, go to ‘TOOLS/Profiles’ and click ADDSet the name to the new profile, click a ‘SAVE’ button.That is how the profile is created but it is not everything that can be configurated in this screen… In addition, we can choose a tag that will be associated with our profile and it will be set automatically for elements created in that profile. If you want to find out what tags are read more [here](../User Guide/user-configuration.md#tags).

Select a default profile TAG

The view of the created profile with default tag set. On the right settings for the default tag are available. If we select one of the first two options:

  • add tag automatically to new parameter in this profile
  • add tag automatically to new function in this profile we can set tag TRL automatically for each new parameters and/or functioncreated within given profile.

The other two flags:

  • use this tag to filter parameters in this profile
  • use this tag to filter functions in this profile are used to filter the view of the list of the parameters or function respectively. Then the default TAG (‘TRL’) will be set as a filter to selected view.

For example We choose and save check box ‘use this tag to filter functions in this profile’Because the second checkbox was selected each created function while viewing TRAVEL profile will be tagged with ‘TRL’Since the fourth chceckbox was selected, when the list of functions is viewed all the functions will be filtered, by default, by ‘TRL’ tag.

Snapshot

Snapshot is one of the global export tools available in the Higson.

This functionality allows you to export selected parts of the configuration to the ZIP file. Exported file may be imported into another environment. The contents of the ZIP file are a directory structure with plain text files. Higson allows the user to export and import snapshot.

Snapshot export

The snapshot export allows user to export selected data configuration elements from environment. Exported data may be imported to another environment. The result of the export will be a package of files in ZIP format available to download.

Selecting data configuration items for snapshot export

Higson allows user to choose the elements to export. Elements available for export are visible on screenshot below. Elements can be selected freely.

Domain

The snapshot exports published changes and the current user’s session by default. If user choose the checkbox ‘from session’, the data in the snapshot will come only from the current session. Checkbox ‘remove elements not included in snapshot’ will remove every element on the new environment, which is not included in a snapshot export.
The snapshot export file can include only data marked by a specific tag when user select ‘filter by tags’.

Functions

Exported data to snapshot may contain functions, which will be filtered by name. If user choose the checkbox ‘from session’, the data in the snapshot will come only from the current session. Checkbox ‘remove elements not included in snapshot’ will remove every element on the new environment which is not included in a snapshot export. ‘Force delete’ allows to ignore the warnings, which Higson sends that the data user have marked for deletion is used in the structure. Such data will be deleted. The snapshot export file can include only data marked by a specific tag when user select ‘filter by tags’.

Parameters

Exported data to snapshot may contain parameters, which will be filtered by name. If user choose the checkbox ‘from session’, the data in the snapshot will come only from the current session. Checkbox ‘remove elements not included in snapshot’ will remove every element on the new environment which is not included in a snapshot export. ‘Force delete’ allows to ignore the warnings, which Higson sends that the data user have marked for deletion is used in the structure. Such data will be deleted. The snapshot export file can include only data marked by a specific tag when user select ‘filter by tags’.

Profile

If user choose Profile, the snapshot export will contain the configuration of the profile. If ‘with context’ is checked, then data contained in the snapshot may contain elements from the context. Context definition can only be exported together with the profile definition.

Source profile

The snapshot export will contain functions and parameters, which are versioned inside the source profile. User can choose more than one source profile. In this case, the snapshot export will contain functions and parameters from all chosen profiles.

Tags

Exported data to snapshot will contain tags.

Snapshot import

The snapshot import allows user to import data from a ZIP file to the environment.

When user choose a file and use the Import button, the Import results will appear in a table form.

The first column, named „Status” can contain different symbols:

Global export & import

As described in previous chapters there are exports for parts of the configuration, like Domain definition or selected Parameters. Global exports allow to transfer entire configuration at once between environments or save a copy of the current configuration. There are two types of export available: Superpack and Snapshot.

Snapshot is a file containing full parametrization from application or only parts of parametrization accordingly to set requirements. What is important, Snapshot export is less complicated than building a Superpack. User decides from which profiles he would like to make an export. The next step is to choose what elements from profiles will be exported. Furthermore SNAPSHOT will generate zip file, in which all domain configuration elements are reflected in folders and each element attributes in a separate file. Users can simply check what is within every region and version by going through the folders.

In order to check XML file from snapshot open downloaded snapshot.zip and go to @domains, file with selected profile name and subfolder @def there you should find xml file named after profile name.

Superpack export

Superpack export allows to:

  • Save XML - saves configuration of Superpack export
  • Load XML - loads XML file from given path with definition of Superpack export
  • Show XML - displays XML file with configuration of Superpack export
  • Export pack - creates pack with XML file and all exported data and allows to download zip file
  • Send pack - exports Superpack to another environment.

Superpack export - rules

There are few rules user should follow while creating Superpack:

Check export environment and target environment:

  • to what profile user want to import data?
  • to what region and version user want to import data?
  • does user need to create profile, region or version?
  • are all data selected for export assigned to one version of every region or are they distributed between different versions of one region

Every step available while creating Superpack might be used multiple times.

Order of steps defined for export, will be kept during import process.

Import of Superpack overwrites configuration in target environment

  • if there are no changes - step is skipped
  • if any element is in superpack zip and not in target environment - then such element is created.

User must close current session before creating or importing Superpack. User can close session by Publishing or Disregarding changes made in current session. It is also possible to publish or reject a session while importing a Superpack, by adding the step: CommitSession or RollBarckSession.

Superpack export - steps

Every step might produce Business Error or System error. Business errors are caused by invalid configuration within Higson while import on target environment - examples of those errors are listed in every step description. System Error are unexpected exceptions in application code.

There are to attributes that allow to control how import reacts when such error occur. These attributes are:

  • OnSystemError
  • OnBusinessError

Depending on settings import might stop or continue when such problem occurs. Higson on report sheet will display information about errors during import, even if import continued when error occured.

Superpack export is build step by step. User have to design export process and import process, that includes:

  • preparation of source environment for export
  • specifying data for export
  • specifying data to delete
  • preparation of target environment for import Those are superpack capabilities which might be used when appropriate steps are added. Nevertheless, not always full potential of Superpack is needed.

Steps are settings of export. Since the is no scheme of export, every Superpack is customised plan of data export.

Superpack steps have attributes. Attributes describe in detail how each step should be executed.

Attributes with visible asterisk symbol are obligatory. Greyed out field means that value for attribute will be set automatically. There are also attributes with default value that are not marked with asterisk or grayed out. User can change this default value. Question mark icons offer additional information for selected attributes.

Property

It is intended to characterise value, which will be declared during import. Property provides validation while value is given. When step Property is added to Superpack, it also needs to be linked in other steps.

Attributes:

  • code - name of Property which will be used every time to execute set property
  • label - will be displayed, when pack import is started
  • type - value type expected in validation process, available are string, number, date
  • format - regex expression which control if entered value is correct
  • formatValidationMsg - displayed message when value in field ‘format’ is incorrect
  • min - minimal value, only for date and number type
  • max - maximal value, only for date and number type
  • propertyValue - default value displayed as suggested value. It is displayed for every step where property is in use
SetVersion

It sets version on target environment.

Attributes:

  • region - region from which version will be selected
  • version - must be set before executing other steps
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • Region does not exist in set Profile on target environment
  • Version does not exist in set Profile on target environment
SetProfile

It sets profile on target environment.

Attributes:

  • profile - profile name, obligatory. Changes will be uploaded to selected profile.
  • onBusinessError
  • onSystemError
SetOnSystemErrorOnPack

It sets new default value on OnSystemError attribute for all steps added to Superpack.

Attributes:

  • defaultValue - default value to set for all following steps of Superpack import. It describes what action should be taken, if any system error occurs.
  • onSystemError
SetOnBusinessErrorOnPack

It sets new default value on OnBusinessError attribute for all steps added to Superpack.

Attributes:

  • defaultValue - default value to set for all following steps of Superpack import. It describes what action should be taken, if any business error occurs.
  • onSystemError
ScheduleVersion

It adds selected version to Timeline

Attributes:

  • region - region from which version should be added to timeline (schedule)
  • version - version which should be added to timeline
  • fromDate - start date from which selected version will be set as system version
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • Region does not exist in set Profile on target environment
  • Version does not exist in set Profile on target environment
RollBackSession

Discards opened session on current user account. All changes from session are reverted to last published state. The user must close current session before creating or importing Superpack, that being said, step ‘RollBackSession’ might be used to close open session at the beginning of the import.

Attributes:

  • onBusinessError
  • onSystemError
  • description - added while rejecting all changes in current session. It is visible to all users on sessions list.
ResetVersions

It sets system versions as visible versions and resets versions on whole target environment for all profiles. It will not effect profiles with no regions or versions.

Attributes:

  • onSystemError
MultiLoadParams

It allows to transfer parameter between versions. Parameter must be assigned to region.

This step is divided into three sections: basic attributes, filter settings and multiload configuration table.

Attributes:

  • files - name of .zip file including list of filtered elements. If no filter is defined all elements fitting to criterions are exported
  • region - to which region filtered parameters will be imported
  • versions - filled automatically if table in the bottom of attribute section is filled
  • onBusinessError
  • onSystemError
  • Name - simple filter, allows to search through parameters by name or part of it. Full filter allows to create additional conditions for search. For more info go to Full filter
  • Region - choose region from which export will be made
  • Add Versions - available when Region is chosen. Pressing button opens pop-up window with list of versions from selected region. User can choose multiple versions. All selected versions will be visible in table under Version from column. By default Version to column has the same codes as Version from column. User can edit codes in Version to column.

Possible Business Errors:

  • Profile does not exist on target environment
  • Region does not exist in set Profile on target environment
  • Version does not exist in set Profile on target environment
MultiLoadFunctions

It allows to transfer function between versions. Function must be assigned to region.

This step is divided into three sections: basic attributes, filter settings and multiload configuration table.

Attributes:

  • files - name of .zip file including list of filtered elements. If no filter is defined all elements fitting to criterions are exported
  • region - to which region, filtered functions will be imported
  • versions - filled automatically when table in the bottom of attribute section is filled
  • onBusinessError
  • onSystemError
  • Name - simple filter, allows to search through functions by name or part of it. Full filter allows to create additional conditions for search. For more info go to Full filter
  • Region - choose region from which export will be made
  • Add Versions - available when Region is chosen. Pressing button opens pop-up window with list of versions from selected region. User can choose multiple versions. All selected versions will be visible in table under Version from column. By default Version to column has the same codes as Version from column. User can edit codes in Version to column.

Possible Business Errors:

  • Profile does not exist on target environment
  • Region does not exist in set Profile on target environment
  • Version does not exist in set Profile on target environment
MultiLoadDomain

It allows to transfer domain elements between versions. Domain element must be assigned to region and its role must be set as product.

This step is divided in two sections: basic attributes and multiload configuration table.

Attributes:

  • removeNotInFile - by default: false
    • If ‘false’ all changes from source version are added to target version.
    • If ’true’ then every element assigned to selected version on source environment is exported to target environment. All elements on target environment which are assigned to ‘version to’ and where not included in batch from source version will be deleted.
  • files - name of .zip file including list of filtered elements. If no filter is defined all elements fitting to criterions are exported
  • region - to which region domain elements will be imported
  • versions - to which version domain elements will be imported
  • onBusinessError
  • onSystemError
  • Region - choose region from which export will be made
  • Add Versions - available when Region is chosen. Pressing button opens pop-up window with list of versions from selected region. User can choose multiple versions. All selected versions will be visible in table under Version from column. By default Version to column has the same codes as Version from column. User can edit codes in Version to column.

Possible Business Errors:

  • Profile does not exist on target environment
  • Region does not exist in set Profile on target environment
  • Version does not exist in set Profile on target environment
  • incorrect data type defined in domain
  • incorrect value type, not consistent with defined data type for attribute
LoadUsers

It loads list of users from export environment. The list contains all user information: login, password and assigned roles. This step include only information about names of assigned roles. To export roles and grants assigned to users select step LoadRolesAndRights.

Attributes:

  • file - name of .zip file including list of users
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • user role does not exist on target environment
  • incorrect user status
LoadTags

It loads all tags from export environment. It does not contain list of parameters or functions with exported tags. To export parameters and functions information use LoadParams / LoadFunctions.

Attributes:

  • file - name of .zip file including list of tags
  • onBusinessError
  • onSystemError
LoadSandbox / LoadContext

It creates xml file with full configuration of context from selected Profile.

Attributes:

  • file - name of .zip file including list of tags
  • removeNotInFile - by default: false.
    • if ‘false’ all elements from file are added to current state on target environment
    • if ’true’ removes all Context elements not included in file
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • incorrect type
  • incorrect GMO Persistent value
LoadRolesAndRights / LoadRolesAndGrants

It loads all roles and grants from export environment.

Attributes:

  • file - name of .zip file including list of roles and grants
  • onBusinessError
  • onSystemError
LoadRegions

It loads all regions from export environment only for selected profile.

Attributes:

  • file - name of .zip file including list of regions, versions and schedule
  • dontOverrideRegions - by default: false.
    • If ‘false’ all regions from .zip file will be added to those already existing on target environment
    • If ’true’ all regions on target environment will be overwritten by regions from .zip file
  • dontOverrideVersions - by default: false.
    • If ‘false’ all versions from .zip file will be added to those already existing on target environment
    • If ’true’ all versions on target environment will be overwritten by regions from .zip file
  • onBusinessError
  • onSystemError
  • sourceProfile - profile on export environment from which all regions will be packed to .zip file
LoadParams

It loads parameters. Only parameters set as visible will be loaded.

  • assigned to version of region set as visible, in My View, in moment of export
  • all global parameters - not assigned to any region

Attributes:

  • file - name of .zip file including .xlsx file with parameters
  • onBusinessError
  • onSystemError
  • Name - simple filter, allows to search through parameters by name or part of it. Full filter allows to create additional conditions for search. For more info go to Full filter.

Possible Business Errors:

  • non existing tag assigned
  • assigned to non existing region
  • assigned to non existing version
  • parent does not exist on target environment (only if parameter is an alias)
LoadFunctions

It loads functions. Only functions set as visible will be loaded.

Attributes:

  • file - name of .zip file including .xlsx file and .js files with functions
  • onBusinessError
  • onSystemError
  • Name - simple filter, allows to search through functions by name or part of it. Full filter allows to create additional conditions for search. For more info go to Full filter.

Possible Business Errors:

  • non existing tag assigned
  • assigned to non existing region
  • assigned to non existing version
LoadDomain

It loads domain elements. Only elements set as visible will be loaded.

Attributes:

  • file - name of .zip file including list of domain elements from current view
  • removeNotInFile - everything not included in .zip file will be deleted
  • onBusinessError
  • onSystemError
  • sourceProfile - profile on source environment from which export will be made

Possible Business Errors:

  • assigned to non existing region
  • assigned to non existing version
DeleteParams

Allows to delete parameters from current view. Creates list of parameter codes and exports it to .txt file. That list is used to search through target environment.
This step is vulnerable to versioning. Before executing this step make sure both export environment and target environment are set on the right view.

Attributes:

  • file - name of .zip file including list of filtered parameters from current view
  • leftSelected - by defalut ‘false’
    • if ’true’ parameters not included in the list will be deleted. Parameters included in the list will not be deleted.
    • if ‘false’ only parameters included in the list will be deleted.
  • onBusinessError
  • onSystemError
  • Name - simple filter, allows to search through parameters by code or part of it. Full filter allows to create additional conditions for search. For more info go to Full filter.
DeleteFunctions

It allows to delete functions from current view. Creates list of function codes and exports it to .txt file. That list is used to search through target environment.
This step is vulnerable to versioning. Before executing this step make sure both export environment and target environment are set on the right view.

Attributes:

  • file - name of .zip file including list of filtered functions from current view
  • leftSelected - by default ‘false’
    • if ’true’ functions not included in the list will be deleted. Functions included in the list will not be deleted.
    • if ‘false’ only functions included in the list will be deleted.
  • onBusinessError
  • onSystemError
  • Name - simple filter, allows to search through functions by name or part of it. Full filter allows to create additional conditions for search. For more info go to Full filter.
CreateVersion

It creates a new version on target environment based on existing version from export environment. Creating new version does not influence ‘visible version’ settings but may change ‘system version’ settings in My View.

Attributes:

  • region - name of new region in which new version will be created on target environment in current profile
  • srcVersion - code of version on source environmen) which will be cloned as foundation of new version
  • dstVersion - name of new version on target environment
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • Region with given code does not exist in set Profile on source environment
  • Version with given code does not exist in set Profile on source environment (relates to srcVersion)
  • Version with given code already exist in set Profile on target environment (relates to dstVersion)
CreateRegion

It creates a new region on Profile set on target environment and first version in that region. Creating version is necessary while creating region. If exported elements are assigned to region named the same as new region, then Higson will interpret it as the same region.

Attributes:

  • code - name of new region which will be created on target environment on current profile
  • initialVersionCode - code of first version
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • region with given code already exist in set Profile on target environment
CreateProfile

It creates a new profile on target environment. Created profile will not be set as visible profile on target environment.

Attributes:

  • code - name of new profile which will be created on target environment
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • Profile with given name already exist on target environment
CommitSession

It causes publication of active session. That step may be used at the begging or at the end of export. Commit session may cause Business Error. If during publishing conflict with another user’s session will appear. If that happens, Cohesion analysis will be necessary.

Attributes:

  • onBusinessError
  • onSystemError
  • description - short information about changes included in published session

Possible Business Errors:

  • conflict during publishing - user needs to execute cohesion analysis
CheckNoActiveSession

It checks if on target environment, on current user profile is open session. Returns set description if open session is found.

Attributes:

  • message - information displayed on report sheet when open session is found on target environment
  • onBusinessError
  • onSystemError

Possible Business Errors:

  • Active session found

Full Filter

Basic filter allows to select functions or parameters by name. Full Filter allows the user to create additional conditions for his search.

  • Levels - only for parameters - names/codes of parameter levels, add as many as needed. Every level must be selected from dropdown list and add to filters by pressing ‘+’ or ‘-’ button.
  • If filter is added by ‘+’ button, then filter includes every element with added phrase.
  • If filter is added by ‘-’ button, then filter excludes every element with added phrase.
  • Type - only for functions, might be groovy or rhino - depending in which language functions where defined
  • Tags - add as many as needed. Every tag must be selected from dropdown list and added to filters by pressing ‘+’ button
  • Region - add as many as needed. Every region must be selected from dropdown list and added to filters by pressing ‘+’ button
  • Modified by - login of user who last made changes. You can add as many as you need

Additionally you may add time frame for last made and published modifications of the element:

  • Modify from
  • Modify to

Remember that search goes with logical conjunction. Which means that all filters must apply at once.

Batch export - order of steps

Suggested order:

The first two steps are not necessary if you know that there is no active session (on current user account) in the moment of import

  • CheckNoActiveSession
  • CommitSession or RollBackSession - depending on the expected result
  • SetOnSystemErrorOnPack - worth adding if you want default value be different than ‘stop’ (which is set by default even without this step)
  • SetOnBusinessErrorOnPack - worth adding if you want default value be different than ‘stop’ (which is set by default even without this step)
  • Property - should be added to export before the step relating to it
  • CreateProfile
  • SetProfile
  • LoadSandbox / LoadContext
  • LoadRegions
  • CreateRegion
  • CreateVersion
  • SetVersion or ResetVersions* - depending on the expected result
  • LoadTags*
  • LoadRolesAndRights / LoadRolesAndGrants*
  • LoadUsers*
  • DeleteParams
  • DeleteFunctions
  • LoadParams or MultiLoadParams - depending on the expected result
  • LoadFunctions or MultiLoadFunctions - depending on the expected result
  • LoadDomain or MultiLoadDomain - depending on the expected result
  • ScheduleVersion
  • CommitSession - if you want autocommit changes

Following steps don’t need any settings on target environment:

  • LoadRolesAndRights / LoadRolesAndGrants*
  • LoadTags*
  • LoadUsers*
  • CommitSession*
  • CheckNoActiveSession*
  • RollBackSession*
  • SetOnSystemErrorOnPack
  • SetOnBusinessErrorOnPack
  • Property
  • ResetVersions*

* - steps global for the environment

Superpack import

Batch/Superpack import loads all changes based on provided zip batch file. This functionality allows users move Higson configuration from one environment to another.

Simulations

Tester

To check if parameter works, go to main toolbar Simulations and Tester. Then screen will show.

Tester screen is divided on two sections Tested elements and Test input data and above that operations useful in adding elements process.
In ‘Available elements’ type or choose from the list which function/parameter would like to test. Then click ‘Add to test’ button. If you want to add many elements at once click on the list icon [Add from domain].

Check the checkboxes of the elements you wish to add to test and click on ‘Choose’ button in right down corner.
Then all your choices will be added to tester and will appear on ‘Tested elements’ section. When functions and parameters that need to be tested are already on the Tested elements list then may click run and see how your parameter works. Usually there are few additional information to be filled for tester to simulate properly, those information appear in section ‘Test input data’. For example let’s test parameter: demo.motor.coverage.bi.tariff and click RUN test.

In section ‘Test input data’ tester shows us what is needed to simulate how parameter works. This parameter needs to know ‘driver gender’ and ‘driver age’ then it may run again. When IN values are filled (example Gender: F, Age: 31) then OUT Value should occur.

Now in section ‘Tested elements’, column ‘Result value’ will see parameter level OUT value. Results may be compared with parameter matrix data Parameterization ->Parameters and go to our example parameter detail:

Tester gave us value 0,582 as it is shown in the matrix (on OUT level).

Test results can go through verification according to set verification rules, for this field ‘Result verification’ must be set as ‘Yes’, all verification rules possible to configure are: No - choose if no comparison is needed Yes – ‘without tolerance’ if result value must be exactly the same as expected value Yes – ‘max. absolute error’ if result value may be different from expected value by inputted factor Yes – ‘max. percent error’ if result value may be different from expected value by inputted percent of expected value. For the comparison to be possible field ’expected result’ must also be filled.

Any test case, with provided test data and result verification settings, can be exported to excel file. For export purpose column delimeter might be changed to ‘,’ from default : ‘|’, but we do not recomment changing the delimeter to ‘,’ if any of the tested emements returns list of values or any value with ‘,’ withinit.

Batch tester

Batch tester allows you to test more than one element at the time. You may create a list of parameters/functions and run test simultaneously to check all of them. To run batch test go to Simulations then Batch tester.

In Batch tester toolbar will find operations like:

  • Import/Export XLS file
  • Remove all / selected – deleting elements from test
  • Add test case – Add selected function to the mass test
  • Save package – save full test settings and results
  • Open package – open previously saved package First are basic information about test subject like:
  • Package name
  • Result verification -if test result should be compared with some expected value and with what tolerance.
  • No - choose if no comparison is needed
  • Yes – ‘without tolerance’ if result value must be exactly the same as expected value
  • Yes – ‘max. absolute error’ if result value may be different from expected value by inputted factor
  • Yes – ‘max. percent error’ if result value may be different from expected value by inputted percent of expected value. What’s important only test cases may be added to mass tester, what means that if we want to test some function in Batch Tester first we need to test it in Tester and save project. For example, if I want to add function demo.motor.coverage.bi.calculatePremium to Batch tester first I need to go to Tester and add to test that function by typing its name in field ‘Available elements’ or choosing from the list, then clicking ‘Add to test’ button. When the function is in the test user should check if everything works properly. Then fill Test Name field (top right corner) – ex. BiCalc. Now one may ‘Save’ that test.

For Batch tester it is really important to input expected value because in most cases in Batch tester user needs to make a comparison between value expected and result to tell if function/parameter is working correctly. Then go to Simulations ->Batch tester then in batch tester toolbar choose Add test case. From tests list choose your test:

Then click ‘Accept’ button to accept your choice. When accepted ‘Choose test case’ window will disappear and your test case should show on ‘Test case list’ section. This way may add as many test cases as you think is needed to Batch tester. When all are in ‘Test cases list’ choose ‘Run’ button to start testing. When tester is done checking elements gives you information like:

  • Status - green for success (no errors detected) or red for failure (error occur) may be yellow if there is no expected value and comparison was expected
  • Time [ms] – time spend on testing the element
  • Result – Success or failure

When list of ‘Test cases’ is long may use function ‘Show failures only’ (checkbox on the right side) to show only those elements which failed the test.

May also expand your test. Lets’ assume we want to test all Male in age from 30 to 45. The easiest way to do so, is to export our element as it is and then make some changes in XLSx file and then import it back to Higson.

In exported table have to input ‘age range’ and ‘driver gender’. Example changes were limited to blue column were are typed random numbers as expected results. Of course those expected results will product errors in test and most of our test subjects will come as failures.

Sweep analysis

As mentioned Sweep analysis is the best tool to find mistakes in parameters or functions definitions.

Sweep analysis screen divides into few parts:

  • Data visualization where chart will show,
  • Data series – where functions or parameters that are about to be visualized will be listed,
  • Parameters Check window – where needed information has to be added to run simulation,
  • Horizontal axis (categories) where may change axis view,

There are tree available operations on the simulation: ‘Save’, ‘Open’ and ‘Chart type’ – to change linear chart into bar graph.

For example if parameters value depends on persons’ gender and age like demo.motor.coverage.pd.premium and there is a need to make sure that all values meet the standards then we use Sweep analysis. In Data series section type name of your function/parameter or find it on the list. If you want to add more than one function click on button ‘Add’, new line will appear and another function/parameter may be input to analysis.

Then go to next section, on the right: ‘Parameter’ – click Check button to find out if your function need any information to run simulation. There may be a need to declare age of client but that does not mean you can’t check selected function by age range –declaration is obligatory for simulation to start. In example needed are Clients age and Age when driver license was obtained. Lets’ assume that our client is 30 years old women.

When asked parameter were given, click Check button again to make sure that’s all what is needed to run simulation. If no new parameter was asked go to next section: Horizontal axis.

Parameter
Here may choose what type of parameter sweep will be made through -that parameter will be your functions’ argument.

Samples type:

  • List
  • Range

In example ‘Age’ range was ‘from’ 18 ’to’ 55 and ‘step’ should be 1 unit cause variable ‘Age’ may take only integer values. Then after clicking Show button, application Higson will show:

That is correct characterization of that parameter. Now if any change was made in source matrix characteristic will show it. For example:

Scale will adjust automatically. Now in a moment you can localize wrong value in parameter and correct it as needed. What’s more we may compare values for female and male of that parameter. Just Click Add button in Data series section, then in new line input the same parameter:

Click ‘pencil’ icon on the right side of selected parameter. Then enter ‘Series Name’, then ‘Add’ (overwritten parameters for series). In column ‘Parameter’ choose gender to overwrite (since we want to show on chart female and male characteristic). Then ‘Accept’. ‘Series name’ Shows in legend above chart.

First parameter is name Female (to name it click pencil icon and input name). Then click button Show. Now you will have characteristic for both genders in age range from 18 to 55.

Overwriting parameter is needed when default information are not suitable for all parameters added to analyze or when you need to make a comparison of the same parameter for two different values (for example when you want to see how parameters values distribution looks like for Male and Female) . User will be asked about every value necessary for simulation in Parameter section– think about it as a test case which has no influence for whole simulation. Everythink about distribution is declared in section Horizontal axis where user has to declare by which Parameter value sweeping will be made by.

Session

Configuration of the product in Higson is composed of:

  • Domain Configuration
  • Parameters
  • Functions

Changes in configuration are made by operators in ‘work session’. Open session (by this we understand every change made in range of configuration) is visible only to operator, which is making changes. In the moment of publication that session changes are seen by all the users and are applied to structure. There are two basic ways to publish your session, first is to go to main toolbar.

Second is to click on shortcut session button in top right corner of the application Higson screen. When button is clicked you will see screen from Sessions’ details:

When you choose to go through main toolbar: screen will show with list of all sessions. While looking for specified session may filter possible matches by:

  • Element Code - type unique element code
  • Element Type - Parameter / Function / Domain Object
  • Operation Type - Create / Update / Delete

To sort list click Apply Filter. When filtering position simply isn’t enough may also search by selected columns:

  • User
  • Start date
  • End date
  • Session ID
  • Status - OPEN / REJECTED / PUBLISHED
  • Remote session - true / false
  • Description

Your guidelines will be applied automatically. There is no need to fill all search cells or filter parameters at once. Input only those which you find necessary. When session from list is selected (by clicking on it) detail information will show. For example:

The list that is showing now presents all created elements with general information about them. Now you can decide if: Changes in session will be deleted (Reject all changes or undo to remove only one selected change)

or Published by clicking the button. Selected (by clicking) element will open in standard edition mode (more information about edition in ‘Add’ or ‘Edit’ chapters for selected type of element).

Another case is when following information occurs:

This means that another user modified the same parameter while working on it.

Its changes are not in the current version of the parameter/function (or any objects you’ve been working on). You can overwrite another user’s changes, but that means deleting their changes and applying yours. It’s worth checking what changes have been made and applying them to your project so that you don’t lose any important data.

To view another user’s changes, go to the main toolbar and select Tools, then Sessions. From the list of sessions, select the session created by another user. Then, when the session details appear, click on the change made to your object. Then you will see how this item behaves after (that user’s) changes and you can make a comparison with your current version and then apply the changes to your version by clicking on your session in the session list.

Moreover, there is a possibility of collision during publishing.

That happens when other user makes changes on the same element in the same time. When this happend, user should run cohesion analysis to check which elements are the cause. If cohesion analysis is needed then some changes must be reverted from session and then (they may be) applied again in new session on the base of updated elements.

Versioning in Higson

Versioning is a very useful option when calculation mechanism in your product is changing through time. For example: when one product have two possible parameterizations, one from the past (which still may be used for calculations) and one which is currently in use or when calculations mechanism is changing . Then option Versioning comes to the rescue.

If you know that some part of your parameterization will be changing in specific time-frame you should assign them to regions. Then inside Region you may create different versions of them and set them as active, in the right time, using Timeline.

First version is created when region is created any other has to be made by user as copy of already existing version. That concept allows you to create as many clone versions of one region as you want and when it’s needed use them in calculations. Any time you may change perspective and use another clone version in calculations. What is important that those are clones only in the beginning , since creation every clone may be changed independently from the others. That’s how Versions are being created.

Regions

In Higson may exist such instance as Region, by this we understand configuration of one product or group of products – depend on product designer decision . Examples of Regions are: OC product or group of MOTO products. Regions are linked to profile, by what we understand, that every region exist in selected profile and to it is assign. To region, as components, might be assign:

  • Chosen elements (nodes with all child nodes) from root in Domain Configuration and its attributes (Toolbar: Domain -> Domain Configuration)
  • Chosen Parameters (Toolbar: Parameterization -> Parameters)
  • Chosen Functions (Toolbar: Parameterization-> Functions)

One component may be assigned only to one region.

Example of usage

First go to Versioning -> Regions then click ‘Add’. Then insert unique code and description.

MOTOR region

When fields are properly filled click ‘SAVE’. Then ‘Region Detail’ window will show

In here you may create other versions but more about that later on. For now just go to Main Toolbar then go to Parameterization -> Parameters. In our MOTOR region we would like to have all parameters with word ‘motor’ inside and without word ‘dict’, cause that phrase will qualify selected parameters to region DICT, which will be created later. To make that kind of search conditions, in field search, column parameter name, insert ‘motor -dict’. To approve inputsearch directions click enter.

Next check main checkbox (on the picture in blue square) to choose all elements from the list. Then all selected set as region, using roll down menu in the right corner:

Then window will show:

Click on region from the list to which you would like to assign your parameters (we created only one region so the list is pretty short) . In following window choose version you would like to assign your region to.

After that go to Function list, Parameterization ->Functions. Select all functions available and add them to region MOTOR in the same way.

It is slightly different when domain elements are to be versioned. First, domain element Type has to have role: PRODUCT. If you want to assign element GD (Good Driver) to region MOTOR/1 first you should make sure it’s type is Versionable. In domain Configuration go to Good Driver element and check it’s type:

As shown on the screen the type is: DISCOUNT. Next go to Domain Definition and find type DISCOUNT. For it set the role to: PRODUCT to make this type versionable.

When Domain Type has role PRODUCT selected (and only then) every element of the type can be assign to region.

Go back to Domain Configuration view, element GD details, select ‘MORE’ and ‘Assign region’ from here all the steps are the same as for parameters and functions.

Create region DICT

Follow the same steps as in defining region MOTOR. Field code: ‘DICT’ and description : ‘Dictionary’ (suggested). In parameter search by name type ‘dict’ and then add all matching parameters to region. None function will be assign to that region. When all those steps were followed correctly, on the parameters list assign regions will be visible. Now in Region column you can see regions’ names to which parameters were assign. What’s important is that number after region name, like: ‘MOTOR/1’ means that those parameters are assign to first version of MOTOR region.

Region Versioning

Every region subjects under versioning. There is a possibility to create any number of regions versions but only one of them may be active. However there is an option to perform changes to any of those versions (by publishing session) doesn’t matter which one is active at the time. Which version is active in what time period is regulated by Timeline

(main Toolbar: Tools ->Timeline).

Example of usage

Lets’ assume that we need two similar but not the same Versions of MOTOR region. To create new version go to Main Toolbar ->Versioning ->Regions and from regions list click on that one in which you would like to create new version ( in this example MOTOR region). As you saw there were two section in Detail information about Region: Base section and Versioning. Now we dive into Versioning part.

There are four action buttons to use, from the left:

  • Version details (eye icon),
  • Edit description (pencil icon),
  • Create new version (duplicate icon),
  • Delete (trash icon).

What is very important that created version will be based on current state of version that it is created from. So in the beginning it will be a clone version of the original, but every moment after that both versions exist separately and may be edit independently. Cloning is only possible when there is no open session. When action ‘Clone version’ was selected, window to input version number and description opens. Remember that version numbers of one region cannot repeat. After accepting that your new version is ready.

Bring your attention to Active column. Here is shown which version is currently in use. Since we didn’t get to Timeline part yet first version is active – that is a default setting.

Timeline

Section Timeline is a place, where you can specify when which version will be used. For example if you have two versions of calculations (parameter) – in Health Insurance product, one standard and one which is promotion for vacation time. Application should calculate insurance costs by standard template (Version 1) every month beside June, July and August 2018 when Version 2 applies. In timeline you may declare that and your calculation will be made accordingly. Here will have to declare in what time period (by date) which version will be active. Remember that only one version may be active at the time.

Example of usage

Well if you want (for example) Version 2 to be active from 06/2018 to 08/2018 and every other time apply logic from Version 1 the only way is to set a timeline. Go to main toolbar and choose Versioning -> Timeline. As you can see below timeline is divided in two parts left – which includes list of available regions (doesn’t matter how many versions which region has all should be there) and right sections - where established timeline will show.

From left side select region from which version you want to add to Timeline. In our example: MOTOR. When clicked will light up on green. Then click Add button in top right corner. Window will show:

Click on one from available versions and then on calendar icon below to set date from which version will be active – what means it will be used in calculation. As you see there is only start date no end date – that is set automatically if any version will be use after that one, end date will be set before start of next version.

Right now active is Version 1 – because it is default setting. On June 1 2018 Version 2 will be activated and will apply till September 1st 2018 when Version 1 will be in use for calculation until other version will be scheduled.

My view

Path to My view: main Toolbar ->Versioning ->My view. It allows you to view any version even those not active in the system at the time. My view is perspective from which you look at selected element. By that we understand from which Version perspective are you looking at the situation. If your view is set on Version 1 you will be doing all calculation by settings from Version 1.

Example of usage

As previously said My view sets your perspective. Always version 1 is set as default and active until timeline defines otherwise. Which version is set as My view that one is currently submitted under edition. If you want to change Version go to Main toolbar ->Versioning ->My view

In here can see what is default version – system version and visible version – current view in every region. System version is set by timeline and that is in current use in calculations. To change visible version click on region (in which selected version is).

In this window will see all available versions and which one is active (in use). Click on Version which you want to edit. Automatically system will set it as your view, now you may edit it but that version will not be active until it time comes (accordingly to timeline). In this example change is from MOTOR region Version 1 to MOTOR region Version 2. As shown now visible is version 2 but that didn’t change that system still makes all calculation by Version 1 calculation logic (System Version column).

What’s more now button Set system versions is active . That operation sets your view at the same version as system version in every region. If you wish to double check which version is active in MOTOR region go to Versioning ->Regions ->MOTOR here you can also find that information. And as you see below Version 2 is not active – what means it is not currently used in calculations. Nevertheless it is set as your view so any changes you make are set only for version 2. Version 1 is now independent.

Changes may be made only to non-active versions.

Profilers

Higson Runtime gives you built-in profilers, which you can use to figure out hot spots or verify your assumptions. You are able to use four types of profiles:

  • SQL profiler
  • Parameter usage profiler
  • Function usage profiler
  • Domain attribute usage profiler

Checking statistics

Higson Runtime

SQL profiler

JdbcProfiler is responsible for collecting SQL query statistics. It provides the following details:

  • totalTime = total time in milliseconds
  • count = number of times given SQL was invoked
  • sql = SQL query that was invoked

JDBC query statistics in Higson Runtime can be fetched by using the pl.decerto.higson.runtime.profiler.jdbc.JdbcProfiler class. To get statistics just invoke getQueryStats() method, as shown below:

1
2
3
JdbcProfiler profiler = JdbcProfiler.getSingleton();
List<QueryStat> queryStats = profiler.getQueryStats();
//do something with fetched stats

To reset load stats, invoke clear() method as shown below:

1
JdbcProfiler.getSingleton().clear()
Parameter usage profiler

Parameter profiler provides invoke and load statistics:

  • totalTime = total invoke time in milliseconds
  • minTime = minimal invoke time in milliseconds
  • maxTime = maximal invoke time in milliseconds
  • count = number of times given parameter was invoked
  • key = parameter’s code

Remember that the first invocation of a parameter performs two heavy operations:

  • fetching a whole matrix,
  • building an in-memory index for fast searches.

All subsequent invocations are fast, as no I/O is needed - just in-memory index look up.

Parameter profiler in Higson Runtime can be fetched by using the pl.decerto.higson.runtime.profiler.engine.EngineProfiler.PARAMETER enum.

To reset invoke stats, invoke clear() method.

To get load statistics just invoke getLoadStats() method.

To reset load stats, invoke clear() method.

Function usage profiler

Function profiler provides invoke and load statistics:

  • totalTime = total invoke time in milliseconds
  • minTime = minimal invoke time in milliseconds
  • maxTime = maximal invoke time in milliseconds
  • count = number of times given function was invoked
  • key = function’s code

Remember that the first invocation of function performs function compiling that might take some time. All subsequent invocations are fast, as no compilation is needed.

Function profiler in Higson Runtime can be fetched by using the pl.decerto.higson.runtime.profiler.engine.EngineProfiler.FUNCTION enum. To get invoke statistics just invoke getInvokeStats() method, as shown below:

1
2
List invokeStats = EngineProfiler.FUNCTION.getInvokeStats();
//do something with invoke stats

To reset invoke stats, invoke clear() method.

To get load statistics just invokegetLoadStats() method.

To reset load stats, invoke clear() method.

Domain attribute usage profiler

Domain attribute profiler provides invoke and load statistics:

  • totalTime = total invoke time in milliseconds
  • minTime = minimal invoke time in milliseconds
  • maxTime = maximal invoke time in milliseconds
  • count = number of times given attribute was invoked
  • key = domain attribute’s code

Domain attribute profiler in Higson Runtime can be fetched by using the pl.decerto.higson.runtime.profiler.engine.AttributeEngineProfiler.DOMAIN enum. To get invoke statistics just invoke getInvokeStats() method, as shown below:

1
2
List<ProfilerStat> invokeStats = AttributeEngineProfiler.DOMAIN.getInvokeStats();
//do something with invoke stats

To reset invoke stats, invoke clear() method.

To get load statistics just invoke getLoadStats() method.

To reset load stats, invoke clear() method.

Higson Runtime-REST

For Higson Runtime-Rest profilers are available under respective REST endpoints.

SQL profiler http://{host}:{port}/api/profiler/jdbc

Parameter usage profiler http://{host}:{port}/api/profiler/parameter

Function usage profiler http://{host}:{port}/api/profiler/function

Domain attribute usage profiler http://{host}:{port}/api/profiler/domain/attr

Higson Studio

All profilers for Higson Studio are available under http://{host}:{port}/higson/profiler. In Higson Studio, profilers are providing information only about your tester executions.

Access control

Grants

Every grant allows to use one or few functions in Higson system, for example authority to read list of parameters, change parameter etc. Kinds of privileges available to users are form by designers from Higson team. Nevertheless, nothing stay on your way to set new grants. Next chapter will be about roles which are the set of selected grants. That means that role has one or more grants and if some user have this role may use all the grants included. Every user in the system may have one or more roles.

List of grants

To see list of grants go to Tools in main toolbar and select Grants. Grants are permissions for user to execute selected activities. Set of grants creates a role.

In here you may search in grants by ‘Code’, ‘Description’, ‘Creation date’ and ‘Roles’ (in search line). Enter button will apply your criteria to search action.

Creating new grant

If you want to create new grant select Add button and set grant properties.

Grant details

When detail information are needed click on selected grant to learn more about it.

If you need to edit grant select Edit button.

Roles

In this chapter you will learn about roles list and adding new roles.

List of roles

To see list of roles go to Tools in main toolbar and select Roles.

In here you may search in roles by ‘Code’, ‘Description’, ‘Creation date’ and ‘Users’ (in search line). Enter button will apply your criteria to search action.

Creating new role

There are two ways to set a new role:

  • Import from XLSx file - if you chose to do it this way, we recommend to export role table and create new line in it and fill it as you want new role to be. That way will avoid errors occurring from wrong table format.
  • Create new role inside application, by clicking Add button When Add button is clicked window will follow:

While creating ‘New role’ as usual have to type in unique ‘Code’ and optional ‘Description’. Then you may decide which ‘Assigned users’ will have that role and ‘Assign Grants’ to the role.

Role details

When detail information are needed click on selected role to learn more about it.

If you need to edit role select Edit button.

Exporting role

This option generates and downloads role table as XLSx file. There are three sheets describing roles.

  • Roles - with basic data about roles: ‘Code’ and ‘Description’
  • Rights - with basic data about rights: ‘Code’ and ‘Description’
  • Roles-rights - with information with ‘Role code’ is connected to which ‘Right code’

Users configuration

Users

Users list shows who have access to Higson.

List of users

To see list of users go to Tools in main toolbar and select Users.

In here you may search in users by ‘Login’, ‘First name’, ‘Last name’, ‘Creation date’, ‘Status’ and ‘Roles’ (in search line). Enter button will apply your criteria to search action.

Creating new user

If you want to create new user select Add button and set user properties.

User details

When detail information are needed click on selected user to learn more about him.

Here are few things you can do as administrator:

  • ‘Edit’ user profile
  • ‘History’ - check login history
  • ‘Change Password’
  • ‘Block’ - take his ability to enter Higson (might be unblocked any time)
  • ‘Close account’ – delete user

License

To see all registered licenses on your module go to Tools - main toolbar and then to Licenses. On list for every component will be shown: ‘License number’, ‘Licensee’, ‘Valid from’ and ‘Valid to’, ‘Permitted CPU cores’ and ‘Special Conditions’.

To add a new license, click on ‘New license’ button and then fill in your license code. ‘License Code’ is given to you after the purchase of a selected Higson version.

Technical Documentation

Bootstrap

Studio

Higson Studio is a Java application and can be run at JVM machine equipped with:

  • at least Java 11 JRE,
  • 4 GB of RAM,
  • 4 CPU,
  • Linux, Windows or macOS machine.

Docker

Higson Studio distribution as a docker image does not contain JDBC drivers required to connect to another database than H2 and Postgresql driver which is located here.

The full step by step description how to prepare Higson docker image you can find here.

Runtime

Prerequisites:

  • Java 11
  • Maven 3.x
  • Spring Framework
  • Higson Studio with H2 database (default for bundle distribution)

We will show how to configure Higson Engine using Spring Boot configuration

Maven configuration

Apart from standard spring boot dependencies, you need to include higson-runtime dependency, available in Maven Central.

1
2
3
4
5
<dependency>
    <groupId>pl.decerto</groupId>
    <artifactId>higson-runtime</artifactId>
    <version>${higson-runtime.version}</version>
</dependency>

Another needed dependency is the JDBC driver to the database of choice, e.g., h2, oracle, mssql, postgresql and database connection pool managing library:

1
2
3
4
5
6
7
<dependencies>
  <dependency>
     <groupId>com.h2database</groupId>
     <artifactId>h2</artifactId>
     <version>${h2-database.version}</version>
 </dependency>
</dependencies>

Properties

Add Higson Runtime data source properties to application.properties file.

1
2
3
hyperon.database.url=<jdbc\_url\to\database>
hyperon.database.username=<username>
hyperon.database.password=<password>

Spring configuration

Add required beans to your java class annotated with @Configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
  @Autowired
  private Environment env;
  
  private static final Logger log = LoggerFactory.getLogger(TestConfiguration.class);
  
  @Bean
  public DialectRegistry getDialectRegistry() {
      DialectRegistry registry = new DialectRegistry();
      registry.setDialect(env.getProperty("hyperon.database.dialect"));
      return registry;
  }
  
  @Bean
  public DialectTemplate getDialectTemplate(DialectRegistry dialectRegistry) {
          return dialectRegistry.create();
  }
  
  @Bean(destroyMethod = "close")
  public DataSource getDataSource(DialectTemplate dialectTemplate) {
      BasicDataSource dataSource = new BasicDataSource();
      dataSource.setUsername(env.getProperty("hyperon.database.username"));
      dataSource.setPassword(env.getProperty("hyperon.database.password"));
      dataSource.setUrl(env.getProperty("hyperon.database.url"));
      dataSource.setInitialSize(4);
      dataSource.setDriverClassName(dialectTemplate.getJdbcDriverClassName());
      return dataSource;
  }
  
  @Bean(destroyMethod = "destroy")
  public HyperonEngineFactory getHyperonEngineFactory(DataSource dataSource) {
      log.info("Engine factory begin creation...");
      HyperonEngineFactory hyperonEngineFactory = new HyperonEngineFactory();
      hyperonEngineFactory.setDataSource(dataSource);
      return hyperonEngineFactory;
  }
  
  @Bean
  public HyperonEngine getHyperonEngine(HyperonEngineFactory hyperonEngineFactory) {
      log.info("Engine begin creation...");
      return hyperonEngineFactory.create();
  }

The application is ready to start. After successfully starting the application, you can see similar log output:

Runtime Rest Spring Boot Starter

Prerequisites

  • Java 11
  • Maven 3.x
  • Spring Boot

Maven configuration

Apart from standard spring boot dependencies, you need to include hyperon-runtime-spring-boot-starter dependency, available in Maven Central. Add hyperon-runtime-spring-boot-starter dependency to pom.xml file:

1
2
3
4
5
<dependency>
 <groupId>pl.decerto</groupId>
 <artifactId>hyperon-runtime-spring-boot-starter</artifactId>
 <version>${hyperon-runtime.version}</version>
</dependency>

Another needed dependency is the JDBC driver to the database of choice, e.g., h2, oracle, mssql, postgresql:

1
2
3
4
5
<dependency>
 <groupId>com.h2database</groupId>
 <artifactId>h2</artifactId>
 <version>${h2-database.version}</version>
</dependency>

Properties

With the above setup, all the configuration that is needed is application.properties file with database properties:

1
2
3
4
5
higson:
 database:
  username: <username>
  password: <password>
  url: <jdbc_url>

If required properties are not available, higson-runtime-spring-boot-starter will return an adequate message.

To configure external sources, you have to set comma separated list of external sources names and connection properties for each of them. You can do it by using the properties below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
higson:
 runtime:
  external-datasource:
   sql:
    postgres:
     url: <postgres_jdbc_url>
     password: <postgres_password>
     username: <postgres_username>
    h2:
     url: <h2_jdbc_url>
     username: <h2_username>
     password: <h2_password>
    names: postgres,h2

Using auto-configured HigsonEngine

After successfully configuring properties while starting the application, spring will create HigsonEngine bean available in the spring application context, then which can be injected anywhere:

1
2
3
4
5
@Component
public class HigsonClient {
 @Autowired
 private HigsonEngine engine;
}

Overriding default configuration

To override default auto-configuration, you need to define HigsonEngine bean in the @Configuration class:

1
2
3
4
5
6
7
8
@Configuration
class CustomHigsonConfiguration {
 @Bean
 public HigsonEngine HigsonEngine() {
  var factory = new HigsonEngineFactory();
  return factory.create();
 }
}

Existing auto-configured DataSource and HigsonRuntimeProperties can be used simply by injecting them:

1
2
3
4
public class HigsonEngine(
        HigsonRuntimeProperties properties,
        @Qualifier("higsonDataSource") DataSource dataSource
) {}

Disabling Higson

If you want to disable Higson temporarily for some reason, you can do it with property hyperon.runtime.enabled set to false.

1
2
3
higson:
 runtime:
  enabled: false

Runtime Rest

Higson Runtime REST is a web application that provides REST API for parameter/function/domain access. It is a REST implementation of Java’s Higson Runtime jar. It is available in two forms:

Environment

Higson Runtime REST is a Java application and can run with any Java 8 or higher on Windows, MacOS X and Linux/Unix.

CLI

To run Runtime-Rest from cli you must pass four properties:

  • loader.path - path to jdbc driver
  • hyperon.database.url
  • hyperon.database.username
  • hyperon.database.password

Download latest version of higson runtime rest and database driver (postgresql for example)

1
2
3
4
5
6
7
8
9
wget  https://repo1.maven.org/maven2/pl/decerto/hyperon-runtime-rest/2.2.11/hyperon-runtime-rest-2.2.11.jar \ 
        -O hyperon-runtime-rest.jar
wget  https://repo1.maven.org/maven2/org/postgresql/postgresql-42.6.0/postgresql-42.6.0.jar \
        -O postgresql.jar

java -Dloader.path=./postgresql.jar -jar ./hyperon-runtime-rest.jar \
        -Dhyperon.database.url=”jdbc:postgresql://your_postgresql_database:5432/hyperon?currentSchema=public” \
        -Dhyperon.database.username=”admin” \
        -Dhyperon.database.password=”admin”

Docker

To run Higson Runtime REST as a docker image, you need to build a separate docker image based on higsonio/runtime-rest image. You need to add your database driver jar and run Higson Runtime REST jar with additional path.

Example:

1
2
3
4
FROM hyperonio/runtime-rest:2.2.11
ARG DRIVER=postgresql.jar
COPY ${DRIVER} driver.jar
ENTRYPOINT [`java`,`-Dloader.path=driver.jar`, `-jar`,`/hyperon-runtime-rest.jar`]

Additionally, you need to pass 3 properties:

  • hyperon.database.url
  • hyperon.database.username
  • hyperon.database.password

An invocation example:

1
2
3
4
docker run -p 8080:8081 -e hyperon.database.url=jdbc:postgresql://your_postgresql_database:5432/hyperon?currentSchema=public
-e hyperon.database.username=admin
-e hyperon.database.pasword=password
-t my-container

Using Higson Runtime REST

This short tutorial will guide you through the process of running Higson Runtime REST as a docker image and invoking parameter/function/domain element.

Prerequisites

In order to run examples from this article you will need:

  • running docker. See the link for details on setting Docker up for your machine.
  • a favorite REST API Client to send requests such as Postman
  • a favorite internet browser
Setting up a docker images

The tutorial will be based on our motor insurance demo. It consists of the insurance web application, Higson Studio, and Higson Runtime REST modules. There is a docker-compose.yml file that makes the whole application easy to run. Just download a project from GitHub, open terminal in that directory, and run the following command:

1
2
3
docker-compose up
//or depending which docker version is installed
docker compose up

If you look closely inside the docker-compose.yml file, you will see that Higson Runtime REST docker image needs three additional properties to be passed to run properly:

  • hyperon.database.url : JDBC url to Higson’s database
  • hyperon.database.username : Higson’s database username
  • hyperon.database.password : Higson’s database password

If you want to connect to other database types such as Oracle, Postgres, MsSQL or MySQL, then you must build your own docker image and provide your database driver. Here’s a Docker file example that copies custom database driver and runs Runtime REST application:

1
2
3
4
FROM hyperonio/runtime-rest:latest
ARG DRIVER\_JAR=dbDriver.jar
COPY ${DRIVER\_JAR} driver.jar
ENTRYPOINT\["java","-Dloader.path=driver.jar","-jar","/hyperon-runtime-rest.jar"\]
  • Demo app should be available at localhost:48080/demo
  • Higson Studio should be available at localhost:38080/higson/app
  • Higson Runtime REST should be available at localhost:8081

To access higson services use followed credentials: User: admin Password: admin

Getting parameter value

We will be using parameter examples from this article. Let’s get the value of a demo.motor.coverage.position parameter for the “BI” coverage code. Here’s the request we’re going to use:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{  
 "ctx": {  
  "properties": [  
    {    
     "key":"coverage.code",    
     "value":"BI"  
    }  
   ]  
 },  
 "elements": [  
  {  
   "code":"demo.motor.coverage.position",  
   "type":"PARAMETER"  
  }  
 ]
}

It consists of 2 main parts: ctx and elements. The former represents the input values we want to pass to Higson. We can pass there simple as well as complex objects. The latter is a list of Higson elements to invoke.

When we send this request to the localhost:8081/api/execution/invoke url, we should receive the following response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
[  
  {  
   "element": {  
    "code":"demo.motor.coverage.position",  
    "type":"PARAMETER",  
    "attributeCode":null,  
    "profileCode":null  
    },  
   "resultValue": [  
    {    
     "fields": [      
      {       
       "key": "position",       
       "value": 1      
      }    
     ]  
    }  
   ]  
  }
]

We receive a list of executed Higson elements with corresponding values.

Let’s see how the response will look like if more than one row will be returned from the parameter. In this example, we are going to use the demo.motor.dict.vehicle.available Makes parameter. Here’s the request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{  
 "ctx": {  
  "properties": [  
   {    
    "key":"quote.vehicle.productionYear",    
    "value":1972  
   },
   {    
    "key":"coverage.code",    
    "value": "BI"  
   }   
  ]  
 },  
 "elements": [  
  {  
   "code":"demo.motor.dict.vehicle.availableMakes",  
   "type":"PARAMETER"  
  },   
  {  
   "code": "demo.motor.coverage.position",  
   "type":"PARAMETER"  
  }  
 ]
}

Besides a new parameter code and context property, you can see how to invoke more than one Higson element in a single JSON request. Let’s see the response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
[  
 {   
  "element": {   
   "code": "demo.motor.coverage.position",   
   "type": "PARAMETER",  
   "attributeCode": null,   
   "profileCode": null  
  },   
  "resultValue": [  
   {   
    "fields": [      
     {       
      "key": "position",       
      "value": 1      
     }    
    ]  
   }  
  ]  
 },{   
  "element": {   
  "code": "demo.motor.dict.vehicle.availableMakes",   
  "type": "PARAMETER",   
  "attributeCode": null,   
  "profileCode": null  
 },   
 "resultValue": [  
  {   
   "fields": [      
    {       
     "key": "make",       
     "value": "STAR"      
    },{       
     "key": "make_id",       
     "value": 722      
    }    
   ]  
  },{   
   "fields": [      
    {       
     "key": "make",       
     "value": "TRABANT"      
    },{       
     "key": "make_id",       
     "value": 221      
    }    
   ]  
  },{   
   "fields": [      
    {       
     "key": "make",       
     "value": "UAZ"      
    },{       
     "key": "make_id",       
     "value": 315      
    }    
   ]  
  },{   
   "fields": [      
    {       
     "key": "make",       
     "value": "WARTBURG"      
    },{       
     "key": "make_id",       
     "value": 230      
    }    
   ]  
  }  
 ]  
]

As we see, each element has its own JSON section in returned array. What’s more, each row in the parameter’s matrix corresponds to one complex element in the resultValue array.

Calling function

Let’s get the computed value of the demo.insurance.calc.premium function. Here’s the request we’re going to use:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{  
 "ctx": {  
  "properties": [    
   {      
    "key":"policy.premiumPerDay",      
    "value":200    
   },{      
    "key":"policy.startDate",      
    "value": "2017-01-01"    
   },{      
    "key":"policy.endDate",      
    "value":"2017-01-03"    
   }  
  ]  
 },  
 "elements": [  
  {    
   "code":"demo.insurance.calcpremium",    
   "type":"FUNCTION"  
  }  
 ]
}

It’s basically the same request as the one used in the parameter section. However, we pass here three context key-value pairs instead of one. Here’s the response we should get by calling the localhost:8081/api/execution/invoke endpoint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[  
 {  
  "element": {    
    "code":"demo.insurance.calcpremium",    
    "type":"FUNCTION",    
    "attributeCode":null,    
    "profileCode":null  
  },  
  "resultValue": 600.0  
 }
]

Again, the same response format as in the parameter’s.

Accessing domain attributes

Last but not least, let’s see how to access domain attributes through invoke API. We’ll be using examples from this article. Let’s see how to evaluate a position attribute of a coverage BI domain element:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{  
 "ctx": {  
  "properties": [  
   {    
    "key":"coverage.code",   
    "value":"COLL"  
   }  
  ]  
 },  
 "elements": [  
  {  
   "profileCode":"DEMO",  
   "code":"/PLANS[FULL]/COVERAGES[BI]/",  
   "attributeCode":"POSITION",  
   "type":"DOMAIN_OBJECT"  
  }  
 ]
}

The main difference between domain element and parameter/function is the presence of 2 additional attributes: profileCode and attributeCode, which names are self-describing. Let’s look at the response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
[  
 {  
  "element": {  
   "code":"/PLANS[FULL]/COVERAGES[BI]/",  
   "type":"DOMAIN_OBJECT",  
   "attributeCode":"POSITION",  
   "profileCode":"DEMO"  
  },  
  "resultValue": [  
   {    
    "fields": [      
     {       
      "key": "position",       
      "value": 8      
     }    
    ]  
   }  
  ]  
 }
]

As we see, the response format is the same as in the parameter/function section.

If you want to learn more or discover other available endpoints, there is a Runtime REST swagger online documentation available at: http://localhost:8081/swagger-ui.html.

AWS

Launch the AMI

The latest Higson versions are available as AMI (Amazon Machine Images) at Amazon Marketplace.

Higson Studio

Visit the Higson Studio Amazon Marketplace. You can read basic information about Higson Studio. Click Continue to subscribe and read Terms and Conditions. After getting yourself familiar with the license, click Continue to configuration. On the next screen, you can choose the Higson Studio version and region you want to launch your instance in. Next, click Continue to launch. Select Launch through EC2 in the Choose Action section. At the Advanced details menu you can pass user-data script to configure environment variables.

Higson Runtime

Visit the Higson Runtime Amazon Marketplace. You can read basic information about Higson Runtime. Click Continue to subscribe and read Terms and Conditions. After getting yourself familiar with the license, click Continue to configuration. On the next screen, you can choose the Higson Runtime version and region you want to launch your instance in. Next, click Continue to launch. Select Launch through EC2 in the Choose Action section. At the Advanced details menu you can pass user-data script to configure environment variables.

Configure

This step is required to be able to specify the user-data script, which allows passing environment variables to the application without the need to log in to the instance.

AWS Systems Manager Parameter Store

By default, Higson Studio uses AWS Systems Manager Parameter Store to fetch properties at the start of the application. You need to specify AWS_ACCESS_KEY_ID and AWS_SECRET_KEY in the user-data script to connect to the AWS Systems Manager Parameter Store. If you do not define those properties, Studio will not launch.

Default configuration:
  • key: /config/higson-studio/Higson.database.url
    description: JDBC address of dedicated postgresql database
    value: jdbc:postgresql://address_to_your_postgressql_server:port/postgres?currentSchema=public
  • key: /config/higson-studio/Higson.database.username
    description: username for application’s connection to the dedicated database
    value: admin
  • key: /config/higson-studio/Higson.database.password
    description: password for application’s connection to the dedicated database
    value: admin

If you prefer to connect to H2 database in order not to setting up a standalone database - you can set up following properties:

  • key: /config/higson-studio/Higson.database.url
    description: JDBC address of dedicated postgresql database
    value: jdbc:h2:/home/ec2-user/Higson.test.db;AUTO_SERVER=TRUE;NON_KEYWORDS=VALUE

  • key: /config/higson-studio/Higson.database.username
    description: username for application’s connection to the dedicated database
    value: sa

  • key: /config/higson-studio/Higson.database.password
    description: password for application’s connection to the dedicated database
    value: sa

Environment variables

To set up environment variables for containers you can manually create a /home/ec2-user/environment.conf file or prepare user-data-script like in the example below. Both are available and its main aim is to configure instance system environments.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
Content-Type: multipart/mixed; boundary="//" 
MIME-Version: 1.0 

--// 
Content-Type: text/x-shellscript; charset="us-ascii" 
MIME-Version: 1.0 
Content-Transfer-Encoding: 7bit 
Content-Disposition: attachment; filename="userdata.txt" 

#!/bin/bash 
/bin/echo "AWS_ACCESS_KEY_ID=PUT_YOUR_AWS_KEY_ID ">/home/ec2-user/environment.conf 
/bin/echo "AWS_SECRET_KEY=PUT_YOUR_SECRET" >> /home/ec2-user/environment.conf 
--//-- 

AWS_ACCESS_KEY_ID and AWS_SECRET_KEY you will be able to generate from your IAM page. Both are needed if you want to use your AWS Parameter Store to pass your configuration. You can inject this script directly into your container in EC2 console using: Actions -> Instance settings -> Edit user data button. Following script add 2 environment variables to your container.

You can learn more about bootstrapping AWS EC2 instance here.

Configure without AWS Parameter Store

If you don’t want to use AWS Parameter Store simply turn this off with AWS_PARAMSTORE_ENABLED=FALSE Now you have to pass HIGSON_DATABASE_URL, HIGSON_DATABASE_USERNAME, HIGSON_DATABASE_PASSWORD properties in your user-data script

Properties customization precedence

Higson Studio allows you to define properties in several locations. The properties are processed in the order as defined below. This implies that the last one overwrites other overlapping properties if you define the same property in two different locations.

  • /home/ec2-user/conf/application.properties
  • /home/ec2-user/higson-studio/conf/mpp-sensitive.properties
  • /home/ec2-user/higson-studio/conf/application.properties
  • /home/ec2-user/application.properties
  • /home/ec2-user/higson-studio/conf/Higson.properties
  • “HIGSON_CONFIG_PATH” environment variable (can be defined in user-data script)
  • environment variables (from/home/ec2-user/environment.conf)
  • AWS Systems Manager Parameter Store

Instance Launch Options

Below, you can find a few instance launch options:

  • version - by default you should launch the latest version available on Amazon Marketplace.
  • region - select the region you would like to launch your instance in. The image is available in all of Amazon’s publicly available regions.
  • EC2 Instance Type - select the instance type you would like to use for your launched Higson Studio.
  • Security Groups - Expose ports to access EC2 instances and Higson Studio:
    • TCP/22 – SSH - used to administrate your instance remotely.
    • TCP/38080 – default port for Higson Studio, this is the port on which you can access Higson Studio
  • Key Value pair settings - generate or use an existing one key and secret pair that will be needed later to access the EC2 instance.

Connect the instance

In order to log in, you can use the following command: ssh-i PATH_TO_PEM_FILE ec2-user@IP_HERE You need to use a PEM file with a public key downloaded while creating the EC2 Instance. Type the ssh command in a terminal. Application is deployed at /home/ec2-user/higson-studio-X.X.X where X.X.X is the version of deployed Studio.

Systemd service is configured to manage the Higson Tomcat instance. You can use standard systemctl commands to disable or check status such as sudo systemctl status higson-studio

All logs can be found under the following path /home/ec2-user/higson-studio-x.x.x/logs/

Log in to running Higson Studio

Studio stores temporary password at Higson.log file. Login to your EC2 instance and grep a string ‘Copy password’ in the log file using:

1
grep “Copy password” /home/ec2-user/higson-studio-X.X.X/logs/higson.log

as a result, you will find a string similar to: Copy password from file ‘gifzWEZl’ in home directory, where the filename is different every time Higson is bootstrapped. This file contains an admin user password. Copy the password. Now go to a browser and open a page: http://IP_HERE:38080/higson/app . At login page please fill form with credentials: pass username: admin and password: copied string here. You will be asked to change your temporary password. After that, you can login to Higson as an admin with a new set password

Supported Databases

Higson supports various SQL databases, including PostgreSQL, Oracle, MySQL, Microsoft SQL and H2. By default, we have built the AMI with PostgreSQL and H2 support. This means that the PostgreSQL and H2 JDBC drivers are present in the Tomcat lib directory, and we only need you to provide the URL and credentials for the database. If you want to connect to another database, then add a proper JDBC driver to the Tomcat lib directory, which is located under the path: /home/ec2-user/higson-studio/lib

Properties

Properties in Higson

Higson gives user a possibility to configure and overwrite internal application properties. They are stored in dedicated file, named application.yaml . File should be placed in one of the listed locations:

  • Higson Studio / Runtime app / Runtime Rest classpath
  • ${user.home}/conf/application.properties
  • ${catalina.base}/conf/application.properties
  • ~/application.yaml
  • ${catalina.base}/conf/higson.properties
  • ${higson.config.path}

The most important properties to configure are:

  • hyperon.database.dialect
  • hyperon.database.url
  • hyperon.database.username
  • hyperon.database.password

without configuring above properties nor runtime nether studio will start.

Configurable properties

Property Description Default value
Database
hyperon.database.dialect Database dialect to use. Predefined dialects available in Higson: oracle,hsqldb, h2, mssql2012, postgresql, mysql oracle
hyperon.database.hbm2ddl-mode proxy for hibernate property hibernate.hbm2ddl.auto validate
hyperon.database.autoddl-action Action to be taken during Higson Studio startup with respect to database schema update:check - verify whether schema is correctupdate - chcek database schema and update, if neededskip - do nothing update
hyperon.database.url JDBC connection url
hyperon.database.username Username that Higson will use to connect to database defined in mpp.database.url
hyperon.database.password Password that Higson will use to connect to database defined in mpp.database.url
hyperon.database.schema Database schema wherein Higson tables exist
Environment
hyperon.studio.instance-name Id identifying specific Higson Studio Instance. It is visible in Higson Studio below menu toolbar 1.5.0
hyperon.studio.url Higson Studio url used in few places, for example to create url for authentication token reset, CAS authentication etc. http://localhost:8080/higson/app
hyperon.studio.ui.header-color CSS style (e.g. rgb(27, 140, 204)) defining Studio header color. If not set, default color is used
hyperon.studio.ui.text-color CSS color (e.g. #7f8c8d) used on text existing in start pages.
hyperon.studio.ui.chart-colors Collection of rgb colors separated by semicolon used in Higson Studio Simulation View to differentiate datasets 190,210,250;110,150,240;20,80,220; 170,230,250;70,200,240;15,150,190; 190,250,205;60,240,110;10,150,50
hyperon.studio.region.updater.task-cron CRON expression used to schedule job updating system region versions in Higson Studio 0 1 0 * * *
hyperon.studio.ui.show-stacktrace Flag determining whether full stacktrace should be shown when GUI error happened false
hyperon.studio.session.require-message Flag determining whether session message is required when publishing session false
Persistent action executor
mpp.persistentExecutor.pool.size Number of threads in thread pool used by persistent action executor 1
Session publication notifications
mpp.session.notify.onPublish.betweenMillis Time period between successive attempts to send notification, in milliseconds 10000
mpp.session.notify.onPublish.timeoutMillis Timeout for single POST request with notification of session publication 1000
mpp.session.notify.onPublish.tryForMillis Time period in milliseconds, starting from last session publication, during which attempts to send notification of session publication are made. If notification is not sent successfully during this period, further attempts are cancelled and information about session changes is cleared. However, if new session is published during this period, information about session changes is updated and the time countdown from the beginning. 1200000
mpp.session.notify.onPublish.urlsWithPassword Comma-separated list of urls, which receive POST requests with notifications of session poblication. Each address can contain user name and password in standard form, e.g. https://username:password@url.com. Password is optional, only user name can be provided (e.g. https://username@url.com) or no user info at all (e.g. https://url.com). "" (empty list, no notifications)
hyperon.studio.global-search.history-limit limit of history searches to keep in Higson Studio memory 60
hyperon.studio.external-environments.codes Name for the connected environment, to SEND snapshots and Superpacks to prod
hyperon.studio.external-environments.%s.url Url to the connected environment API
hyperon.studio.external-environments.%s.username Username to data source. %s is env code from property above. admin
hyperon.studio.external-environments.%s.password Password to data source. %s is env code from property above. admin
hyperon.studio.snapshot.param.matrix.writer.order-by-all-level Should sort by all levels during export parameter to file. Available: true/false true
hyperon.studio.setup.password-force-change.enabled Enforce password change during first launch: Available: true/false true
Authentication
hyperon.studio.security.login.auto-login Flag determining whether try to auto login user without password false
hyperon.studio.security.password.send-reset-tokens Flag determining whether emails with reset password tokens should be sent automatically false
hyperon.studio.security.login.attempts-limit Number of login attempts after which cool down specified in property mpp.login.attempts.cooldown happens 3
hyperon.studio.security.login.attempts-cooldown Cool down in seconds after specified number of unsuccessful login attempts controlled by property mpp.login.attempts.limit 20
hyperon.runtime-rest.security.user-cache-enabled flag determining whether optional user cache should be working or not false
hyperon.security.basic.bcrypt.complexity change bcrypt complexity 5
hyperon.setup.password-generator.enabled set to generate if random password for admin user should be generated
hyperon.security.basic.password-encoder set a password encoder (bcrypt/Pbkdf2) bcrypt
hyperon.studio.security.type Authorization type configuration in studio
hyperon.runtime-rest.security.type Authorization type configuration in runtime-rest
CAS Authentication
hyperon.studio.security.cas.server-url CAS ticket validation url
hyperon.studio.security.cas.login-url CAS login url
hyperon.studio.security.cas.logout-url CAS logout url
hyperon.studio.security.cas.logged-out-url CAS url to go after successful logout action
Active Directory Authentication
hyperon.security.active-directory.domain Active Directory main root (usually server domain, for example: domain.local)
hyperon.security.active-directory.url Active Directory server url, for example: ldap://192.168.0.156:389/
hyperon.security.active-directory.root-dn Optional DN root
Azure Active Directory Authentication
hyperon.studio.security.azure-active-directory.client-id Azure client Id
hyperon.studio.security.azure-active-directory.tenant-id Azure tenant Id
hyperon.studio.security.azure-active-directory.client-secret Azure client Secret
hyperon.studio.security.azure-active-directory.base-url Azure base Url
hyperon.studio.security.azure-active-directory.username-attribute-name Azure username’s Attribute name
hyperon.studio.security.azure-active-directory.roles-origin Azure roles origin
SAML
hyperon.studio.security.saml.base-url
hyperon.studio.security.saml.entity-id
hyperon.studio.security.saml.idp-metadata-file-path Path to identity provider metadata file
hyperon.studio.security.saml.response-skew Determines maximum difference between clocks of the identity provider and Studio machines 60
hyperon.studio.security.saml.key-store.path
hyperon.studio.security.saml.key-store.pass
hyperon.studio.security.saml.key-store.alias
hyperon.studio.security.saml.key-store.keyPass
hyperon.studio.security.saml.roles-origin internal / saml
hyperon.studio.security.saml.inactive-interval-in-seconds Seconds for setting session timeout after idle time for saml authorization 3600
JWT Authentication for runtime rest
hyperon.security.jwt.secret-key Secret key to decrypt runtime rest token

RUNTIME

Available for runtime or runtime-rest apps

Property name Description Default Value
Database
hyperon.database.dialect Database dialect to use. Available values: oracle, hsqldb, h2, mssql2012, postgresql, mysql oracle
hyperon.database.url JDBC connection url
hyperon.database.username Username that Higson will use to connect to database defined in mpp.database.url
hyperon.database.password Password that Higson will use to connect to database defined in mpp.database.url
hyperon.database.schema Database schema wherein Higson tables exist
Environement
hyperon.runtime-rest.url URL of Higson Runtime Rest
Authentication
hyperon.runtime-rest.security.type Defines security type for runtime rest. Possible values: jwt, active-directory. When not set basic authentication is enabled
hyperon.security.jwt.secret-key Secret key to decrypt runtime rest token
hyperon.security.active-directory.domain Active Directory main root
hyperon.security.active-directory.url Active Directory server url
hyperon.security.active-directory.root-dn AD root domain
Other
hyperon.runtime.function.validate-arguments flag determining whether function arguments data types should be validated before execution false
hyperon.runtime.normalization.throw-on-exception flag determining whether an exception should be thrown when matrix value can’t be normalized false
hyperon.runtime.external-datasource.sql.names Names of data sources list.
hyperon.runtime.external-datasource.sql.%s.url Url to data source. %s is name of datasource from property above.
hyperon.runtime.external-datasource.sql.%s.username Username to data source. %s is name of datasource from property above.
hyperon.runtime.external-datasource.sql.%s.password Password to data source. %s is name of datasource from property above.
hyperon.runtime.parameter.value-never-null Flag responsible for managing global support of nullable parameter’s results in Higson Engine. If true, parameters will return instance of pl.decerto.hyperon.runtime.core.EmptyParamValue when no match found. If set to false, parameters return null. true
hyperon.runtime.watchers.enabled Flag determining whether runtime watchers should start automatically true

Properties names since version 2.x

COMMON

Version 1.x Version 2.x
mpp.database.url hyperon.database.url
mpp.database.username hyperon.database.username
mpp.database.password hyperon.database.password
mpp.database.dialect hyperon.database.dialect
hyperon.security.bcrypt.complexity hyperon.security.basic.bcrypt.complexity
jwt.security.secret.key hyperon.security.jwt.secret-key
mpp.database.hbm2ddl.mode hyperon.database.hbm2ddl-mode
mpp.database.autoddl.action hyperon.database.autoddl-action
mpp.database.schema hyperon.database.schema
mpp.build.version hyperon.build.version
mpp.build.number hyperon.build.number

HIGSON STUDIO:

Version 1.x Version 2.x
mpp.url hyperon.studio.url
mpp.environement.id hyperon.studio.instance-name
mpp.gui.header.color hyperon.studio.ui.header-color
mpp.gui.text.color hyperon.studio.ui.text-color
mpp.chart.colors hyperon.studio.ui.chart-colors
authType hyperon.studio.security.type
server.cas hyperon.studio.security.cas.server-url
server.cas.login hyperon.studio.security.cas.login-url
server.cas.logout hyperon.studio.security.cas.logout-url
server.cas.loggedout hyperon.studio.security.cas.logged-out-url
hyperon.saml.baseUrl hyperon.studio.security.saml.base-url
hyperon.saml.entityId hyperon.studio.security.saml.entity-id
hyperon.saml.idpMetadataFilePath hyperon.studio.security.saml.idp-metadata-file-path
hyperon.saml.responseSkew hyperon.studio.security.saml.response-skew
hyperon.saml.keyStore.path hyperon.studio.security.saml.key-store.path
hyperon.saml.keyStore.pass hyperon.studio.security.saml.key-store.pass
hyperon.saml.keyStore.alias hyperon.studio.security.saml.key-store.alias
hyperon.saml.keyStore.keyPass hyperon.studio.security.saml.key-store.key-pass
hyperon.saml.roles.origin hyperon.studio.security.saml.roles-origin
hyperon.security.passwordEncoder hyperon.studio.security.basic.password-encoder
hyperon.ad.domain hyperon.security.active-directory.domain
hyperon.ad.url hyperon.security.active-directory.url
hyperon.ad.rootDn hyperon.security.active-directory.root-dn
hyperon.azuread.clientId hyperon.studio.security.azure-active-directory.client-id
hyperon.azuread.tenantId hyperon.studio.security.azure-active-directory.tenant-id
hyperon.azuread.clientSecret hyperon.studio.security.azure-active-directory.client-secret
hyperon.azuread.baseUrl hyperon.studio.security.azure-active-directory.base-url
hyperon.azuread.usernameAttributeName hyperon.studio.security.azure-active-directory.username-attribute-name
hyperon.azuread.rolesOrigin hyperon.studio.security.azure-active-directory.roles-origin
mpp.mail.host hyperon.studio.mail.host
mpp.mail.port hyperon.studio.mail.port
mpp.mail.username hyperon.studio.mail.username
mpp.mail.password hyperon.studio.mail.password
mpp.mail.from hyperon.studio.mail.from
hyperon.superpack.environments hyperon.studio.superpack.environments
hyperon.superpack.test.url hyperon.studio.superpack.test.url
hyperon.superpack.test.username hyperon.studio.superpack.test.username
hyperon.superpack.test.password hyperon.studio.superpack.test.password
hyperon.external.environment.codes hyperon.studio.external.environment.codes
hyperon.external.environment.test.url hyperon.studio.external.environment.test.url
hyperon.external.environment.test.username hyperon.studio.external.environment.test.username
hyperon.external.environment.test.password hyperon.studio.external.environment.test.password
mpp.global.search.global.history.limit hyperon.studio.global-search.history-limit
mpp.login.attempts.limit hyperon.studio.security.login.attempts-limit
mpp.login.attempts.cooldown hyperon.studio.security.login.attempts-cooldown
mpp.exception.dialog.showStacktrace hyperon.studio.ui.show-stacktrace
mpp.authentication.autologin hyperon.studio.security.login.auto-login
mpp.session.message.required hyperon.studio.session.require-message
mpp.authentication.sendResetPasswordTokens hyperon.studio.security.password.send-reset-tokens
mpp.updateSystemVersion.task.cron.expression hyperon.studio.region.updater.task-cron

HIGSON RUNTIME:

Version 1.x Version 2.x
authType hyperon.runtime.security.type
hyperon.validateFunctionArgumentsDataTypes hyperon.runtime.function.validate-arguments
hyperon.throwOnNormalizeInputValueException hyperon.runtime.normalization.throw-on-exception
mpp.external.datasources hyperon.runtime.external-datasource.sql.names
datasource.test.url hyperon.runtime.external-datasource.sql.test.url
datasource.test.username hyperon.runtime.external-datasource.sql.test.username
datasource.test.password hyperon.runtime.external-datasource.sql.test.password
hyperon.devMode hyperon.runtime.dev-mode-enabled
hyperon.userName hyperon.runtime.username
mpp.engine.valueNeverNull hyperon.runtime.parameter.value-never-null
hyperon.watchers.autoStart hyperon.runtime.watchers.enabled
mpp.external.datasources hyperon.runtime.external-datasource.sql.names

HIGSON RUNTIME REST:

Version 1.x Version 2.x
hyperon.security.user.cache hyperon.runtime-rest.security.user-cache-enabled

Authentication

Authentication in Studio

Standard / Basic Authentication

No extra actions needed to use it, it is available by default. You can choose from the following password encoder security algorithms: bCrypt (default) or Pbkdf2

To select a Pbkdf2 algorithm, you must set hyperon.security.basic.password-encoder=Pbkdf2 property in the application.properties You can choose the complexity of BCrypt algorithm by setting a property hyperon.security.basic.bcrypt.complexity with values between 4 and 31 are accepted, 5 is used by default. Be careful, since the bigger the value the safer algorithm is, but the performance impact is also increasing.

CAS Integration

1
2
3
4
5
6
    hyperon.studio.url=https://hyperon_server_adress/higson/app
    hyperon.studio.security.type=cas
    hyperon.studio.security.cas.server-url=https://cas_server_adress
    hyperon.studio.security.cas.login-url=${hyperon.studio.security.cas.server-url}/login
    hyperon.studio.security.cas.logout-url=${hyperon.studio.security.cas.server-url}/logout?service=${server.cas.loggedout}
    hyperon.studio.security.cas.logged-out-url=${hyperon.studio.url}/loggedOut

Active Directory

1
2
3
4
    hyperon.studio.security.type=active-directory
    hyperon.security.active-directory.domain=domain.local #Active Directory main root
    hyperon.security.active-directory.url=ldap://10.222.20.156:389/ #Active Directory server url
    hyperon.security.active-directory.root-dn=DC=domain,DC=local #AD root domain
Requirements for Access Directory user:
  • Login - not empty, min size: 1, max size: 200
  • First name - not empty, min size: 1
  • Last name - not empty, min size: 1
  • E-mail address - if empty Higson generates default e-mail consistent with schema: ’login@local.com'
  • Roles - min one role consistent with Higson role Higson supports role management. Roles defined in Active Directory must be compatible with roles in Higson structure.
Hierarchy of roles in Higson:
  • MPP_ADMIN - Higson Administrator
  • MPP_USER - Higson User
  • MPP_USER_READONLY - Readonly Higson User
  • HYPERON_SUPERPACK_IMPORT - Readonly Higson User with grant to import Superpack It is possible to create own roles in AD but remember to create same roles in Higson structure. It’s necessary to proper authentication process.

SAML

  • Configure Tomcat to use HTTPS.
  • Fill properties:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    hyperon.studio.security.type=saml
    hyperon.studio.security.saml.base-url=
    hyperon.studio.security.saml.entity-id=
    #Path to identity provider metadata file
    hyperon.studio.security.saml.idp-metadata-file-path= 
    #Determines maximum difference between clocks of the identity provider and Studio machines.
    hyperon.studio.security.saml.response-skew=60 hyperon.studio.security.saml.key-store.path=
    hyperon.studio.security.saml.key-store.pass=
    hyperon.studio.security.saml.key-store.alias=
    hyperon.studio.security.saml.key-store.keyPass=
    hyperon.studio.security.saml.roles-origin=  ##internal or saml
  • Generate metadata from Studio https://localhost:8080/hyperon/saml/metadata
  • Import generated metadata into Identity Provider.
  • Configure Identity Provider to send attributes with assertion response.
6. Available attributes:
  • NAME_ID (this is used as user login)
  • firstname
  • surname
  • mail
1
2
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] 
=> issue(store = "Active Directory", types = ("mail", "firstname", "surname"), query = ";mail,givenName,sn;{0}", param = c.Value);
  • roles (optional, if hyperon.saml.roles-origin=saml is specified roles are taken from assertion response therefore identity provider must be configured to send it with response). internal means Studio will take roles from database instead of saml assertion response to authorize user.
1
2
3
4
5
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-1861533720-3376411538-4102833532-1113", Issuer == "AD AUTHORITY"] 
=> issue(Type = "roles", Value = "MPP_USER", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-1861533720-3376411538-4102833532-1114", Issuer == "AD AUTHORITY"] 
=> issue(Type = "roles", Value = "MPP_ADMIN", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

Azure Active Directory

  1. Go to Azure Active Directory tab in Azure console
  2. Register Higson app under “App registrations”.
  3. Select registered app
  4. Add redirect url under “Higson” → “Authentication”:
    • Choose “Add a platform” → “Web”,
    • Paste url http://{hyperon_context_url}/login/oauth2/code/ for example; http://localhost:8080/hyperon/login/oauth2/code/,
    • no need to check any checkbox related to auth tokens
  5. Add Higson role (e.g. MPP_ADMIN) under “Higson” → “App roles” (User & Groups).
  6. Generate secret for the app under “Higson” → “Certificates & Secrets”.
  7. Go back to Active Directory tab
  8. Go to “Enterprise applications” and choose the newly added app.
  9. From “Enterprise applications” go to “Users and groups” and add a user. Select previously created role while adding a new user.
  10. Go back to Active Directory tab
  11. Go to “App registration” → “Higson” → “Token Configuration” and add an optional claim. “Token Type” → “ID” and choose email. Check “Turn on the Microsoft Graph profile permission (required for claims to appear in token).” from the popup.
1
2
3
4
5
6
7
    hyperon.studio.security.type=azured
    hyperon.studio.security.azure-active-directory.client-id=
    hyperon.studio.security.azure-active-directory.tenant-id=
    hyperon.studio.security.azure-active-directory.client-secret=
    hyperon.studio.security.azure-active-directory.base-url=http://localhost:8080/hyperon
    hyperon.studio.security.azure-active-directory.username-attribute-name=preferred_username
    hyperon.studio.security.azure-active-directory.roles-origin=azuread

Authentication in Runtime REST

Standard / Basic Authentication

No extra actions needed to use it, it is available by default. You can choose from the following password encoder security algorithms: bCrypt (default) or Pbkdf2

To select a Pbkdf2 algorithm, you must set hyperon.security.basic.password-encoder=Pbkdf2 property in the application.properties You can choose the complexity of BCrypt algorithm by setting a property hyperon.security.basic.bcrypt.complexity with values between 4 and 31 are accepted, 5 is used by default. Be careful, since the bigger the value the safer algorithm is, but the performance impact is also increasing.

Active Directory

1
2
3
4
    hyperon.studio.security.type=active-directory
    hyperon.security.active-directory.domain=domain.local #Active Directory main root
    hyperon.security.active-directory.url=ldap://10.222.20.156:389/ #Active Directory server url
    hyperon.security.active-directory.root-dn=DC=domain,DC=local #AD root domain

JWT Based authentication Token

1
2
hyperon.studio.security.type=jwt
hyperon.security.jwt.secret-key=you_secret_key

The property hyperon.security.jwt.secret-key must be set in both Studio’s and client’s side Runtime Rest application with same string sequence

You can generate a new token in Studio. A view to see all existing tokens and to generate a new one can be found in Menu’s Tools tab. When creating a new token, you can specify the expiry date. Admin users may also specify a user that a newly generated token will be assigned to. To use generated token in REST API calls, you need to add an Authorization Header with the standard bearer format, such as Authorization: Bearer your_jwt_token

Upgrade

Higson applications upgrade

This is wise to upgrade Higson applications (the Studio and Runtime) for a newer version as we are repairing bugs and adding new features, so let’s check how to do it in a few short steps.

IMPORTANT:

  • As far higson-studio and higson-runtime are separate applications we truly recommend running them the same version.
  • Higson Studio MUST BE STARTED FIRST! Higson Studio is managing the Database Schema!
  • If your current version starts with 1.x and you want to bump version do 2.x line later go to this article.

Bump the Studio application first

Download new Studio

The first step you should do is to head for new applications here. After filling the form, you will get mail with a link to your download page. Depending on your needs, download the file/files (probably you use a war file with your tomcat).

Shut down old Studio.

Turn off the Studio App. You probably want to stop all running applications which are using higson-runtime, because we need to modify its database schema.

Remember to create a database backup!

Due to the fact, there might occur database updates, it would be very helpful if you prepare a Higson’s database backup.

Switch .war files at your tomcat /webapps directory
Start the Studio Application first

You should be able to see a standard login page (by default: https://{serverUrl}/higson/app)

Bump the Runtime in your applications

Since Runtime is available at Maven Central repositories, you should only bump its version at your building script, ie: build.gradle, pom.xml etc.

Migrate between versions

IMPORTANT

  • If you are lower than 1.20.x version we recommend to upgrade to the latest version in 1.x line (for instance: 1.21.21). This will ensure all minor changes that can have impact on your current configuration has been considered. You can do this following this section. *Higson Studio **MUST BE STARTED FIRST!**Higson Studio is managing the Database Schema!

MAJOR CHANGES

  • Java 11 as the minimal runtime environment
  • property names has changed so please check your property source whether it needs a change or not

Bump the Studio application

Download new Studio

The first step you should do is to head for new applications here. Search for version of 2.x

Shut down the Studio

Turn off the Studio App. You probably want to stop all running applications which are using higson-runtime, because we need to modify its database schema.

Remember to create a database backup!

Due to the fact, there might occur database updates, it would be very helpful if you prepare a Higson’s database backup.

Upgrade java to 11 version

Higson Studio 2.x is using Java 11 to run at least . You should upgrade the java runtime version of your application container

Check out new properties

In a Higson Studio 2.x there were a lot of changes with properties.

Take a look at your property source (by default: {your_tomcat_dir}/conf/application.properties) and change them regarding the table followed the link

Switch war files at your tomcat /webapps directory

Start the Studio App

You should be able to see a standard login page (by default: https://{serverUrl}/higson/app)

Bump the Runtime in your applications

Since Runtime is available at Maven Central repositories, you should only bump its version at your building script, ie: build.gradle, pom.xml etc. Check out the new properties for Runtime App since there were a lot of changes.

Enabling developer mode (devmode)

Enabling a developer mode feature allows seeing all unpublished changes of a defined user by the Runtime application, which leads to faster development. Developer mode is disabled by default.

Enabling devmode programmatically

1
2
3
4
5
6
7
8
@Bean
public HigsonEngine higsonEngine() {
	HigsonEngineFactory factory = new HigsonEngineFactory();
	...
	factory.setDeveloperMode(true);
	factory.setUsername("username"); //login of user which changes you want to see at devmode
	...
	return factory.create();

Enabling devmode using property file

Configuration that is needed in application.yml to enable developer mode:

1
2
3
4
higson:
  runtime:
    dev-mode-enabled: true
    username: <username> #login of user which changes you want to see at devmode

Using HigsonEngineFactory excludes a possibility to use application.yml.

Disabling cache for a bundle

Caching bundle saved or read by Higson Persistence may be configured in three different ways.

1. Automatically generated EhCache

If cache is not configured on sight then Higson Persistence creates its own EhCache with the name : gmo and idleTime=10 minutes

2. Use selected EhCache region

You may configure it to use selected EhCache region

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
@Profile("!nocache") //turn off nocache profile
@Bean(destroyMethod = "destroy")
public HigsonPersistenceFactory cacheableHigsonPersistenceFactory() {
	HigsonPersistenceFactory factory=new HigsonPersistenceFactory();
	factory.setDataSource(gmoDataSource);
	factory.setHigsonDataSource(runtimeDataSource);
	factory.setDefaultProfile(env.getProperty("hyperon.profile"));
	factory.setAutoStartWatchers(true);
	factory.setHiloSequenceName("hp_seq");
	factory.setHiloAllocationSize(100);
	factory.setBundleTable("hp_bundle");
	factory.setBundleColumn("bundle_id");
	factory.setOwnerColumn("owner_id");
	factory.setOwnerPropertyColumn("owner_prop");

	factory.setCacheName("abc") // execute it during Higson Persistence configuration

	return factory;
}
  • if it is defined ehcache “abc” then it uses that
  • if it is not defined ehcache, then it will create ehcache with name “abc” in default configuration

3. Add your own implementation

On HigsonPersistanceFactory may add your own implementation of cache (based on map or other cache) using HigsonPersistanceFactory.setCache(BundleCache) method

If you want to turn the cache off (for example for testing purposes) you need to give your cache implementation like follow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
public class NoBundleCache implements BundleCache {

	@Override
	public Bundle get(long id) {
		return null;
	}

	@Override
	public void put(Bundle bundle) {}

	@Override
	public void remove(long id) {}

	@Override
	public void clear() {}
}

@Profile("nocache") //turn on nocache profile
@Bean(destroyMethod = "destroy")
public HigsonPersistenceFactory noCacheHigsonPersistenceFactory() {
	HigsonPersistenceFactory factory = new HigsonPersistenceFactory();
	factory.setDataSource(gmoDataSource);
	factory.setHigsonDataSource(runtimeDataSource);
	factory.setDefaultProfile(env.getProperty("hyperon.profile"));
	factory.setAutoStartWatchers(true);
	factory.setHiloSequenceName("hp_seq");
	factory.setHiloAllocationSize(100);
	factory.setBundleTable("hp_bundle");
	factory.setBundleColumn("bundle_id");
	factory.setOwnerColumn("owner_id");
	factory.setOwnerPropertyColumn("owner_prop");

	factory.setCacheName("abc");
	factory.setCache(new NoBundleCache()); //setting custom cache implementation

	return factory;
}

Changelog

2.3.6 June 28, 2024

CHANGES:

ADDED :

  • Ability to filter exported in snapshot parameters and functions by “without tags” option
  • Java 11 support

CHANGED :

  • Disabled liquibase execution on Runtime REST startup

FIXED :

  • Import users error if import modify existing user with roles
  • Change password is no longer required when external authorization provider is set
  • The Save button after parameter change is no longer required to be clicked twice
  • Improving the header of the user import and fault info details
  • Filtering functions by type
  • Check write permission (PROD_W_) when editing domain type

BUMP :

  • rhino to 1.7.15
  • jackson to 2.17.1

2.3.5 April 24, 2024

CHANGES:

ADDED :

  • fk index on table with imported snapshot history
  • Last update date indexes in domain tables that domain watcher searches

CHANGED :

  • domain collection search change to “contains” instead of “startsWith”
  • add domain type button availability depends on profile write rights
  • available profile list depends on profile read rights

2.3.4 February 26, 2024

CHANGES:

FIXED :

  • Show import configuration report if only elements were removed
  • Date formatting error in groovy functions
  • Stopped showing of Access denied message before the SAML login
  • NPE during calling function with: .call(“func”, null)

2.3.3 January 29, 2024

CHANGES:

FIXED :

  • Add missing labels in global search
  • Rename the first column in the global search results table filter
  • Hide jdbc password appended to jdbc url

2.3.2 January 08, 2024

CHANGES:

ADDED :

  • Added higson build version in exported snapshot config.json file
  • Added a login to the activation mail
  • Studio REST API - endpoint to retrieve metadata for all parameters

FIXED :

  • Search in eighth or higher column of matrix
  • Runtime - improved function logging performance
  • Calling alias with ‘in-memory index’ set to false results in PARAM_VALUE_NOT_FOUND
  • Delete domain arguments which not exist in the file while importing a snapshot
  • Prevent automatic session publishing when imported snapshot contains errors
  • Restore the ability to change the header color on the screen after login

2.3.1 September 27, 2023

CHANGES:

CHANGED :

  • Runtime: param watcher forces cache sync at fixed intervals

FIXED :

  • Prevent to import second domain rootMaster parameter is not cached if it is not used by the application
  • Runtime - improved groovy function performance when groovy
  • Secured is set to true
  • Batch tester - faster evaluation of all test cases