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.

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.

DEMO
Login credentials:
Login: admin
Password: admin

All documentation about Studio REST API can be found here

Instruction

Batch Tester

Testing modules allows to test parts or the whole algorithm design in Higson Studio. Using batch tester gives the ability to perform test for series of data, not just a singular set. Create and save mass tests to control how changes it the algorithm influence the results. Each batch test is created from unit test (design in singular tester). To learn more about the Unit tests read the Tester chapter.

To go to batch tester, select Tools/Batch Tester in Main Toolbar.

You will see all saved batch tests

Each batch test is listed in the center of the screen, every single one is described by four information’s:

No. Column name Description
1. Test Name Batch test name. Each batch test should have unique name.
2. User Login of the user who created the batch test.
3. Last Modified Date of the last modification of the batch test.
4. Actions List of quick access actions. Currently only Remove action (bin icon) is available here.Remove action deletes desired batch test.

Additionally you can use available actions:

No. Action Description
1. + Add test package Opens a batch test creator.
2. Upload test package Allows to upload batch test from XLSx file
3. Hide/Show filters Hides or reveals Filters bar accordingly.
If Filter bar:
- is visible, then action Hide filters is available.
- is hidden, then action Show filters is available.

Use filters to search for preferred batch test:

No. Filter name Description
1. Search text field Filter by any string provided by user.
2. Date range Filter by last change date in format YYYY/MM/DD-YYYY/MM/DD .
3. Modified by Filter by user who last modified the batch test.

Batch tester creator

To create new batch test unit test must already exist. You can create unit test using the Tester. When this condition is met you can start creating batch tests based on existing unit tests.

The Batch Test creator:

For each unit test, which creates batch test, six information is given:

No. Column name Description
1. Test Name Full test name. Test name is loaded from selected unit test. Test name can be changed (or added) through import of the XLSx file.
2. Status Test case status provided by comparison of the evaluated value with expected value.
3. Failures Number of failures within unit test case. Where evaluated value differs from expected value.
4. Errors Number of errors which occurred during the unit test.
5. Time (ms) Time taken to perform the unit test.
6. Actions List of quick access actions. Currently only Remove action (bin icon) is available here. Remove action deletes desired unit test.

By those the list of unit test can be sorted if needed.

No. Action Description
1. Checkboxes Select the top checkbox to select all unit tests in the view, or select individual checkboxes to select unit tests
2. + Add test Opens a batch test creator.
3. Upload package Allows to upload batch test from XLSx file
4. Download package Allows to download batch test from XLSx file
5. Remove selected tests Deletes all unit test with marked checkboxes. Available only if at least: one unit test was added, and one checkbox is selected
6. Save package Saves batch test for further use.
7. Run test Runs batch test, performs all unit test cases added to viewed batch test. Every batch test can be run (even not saved)

Batch tester - creating a batch test

To create new batch test, follow these steps:

  1. Go to Main Toolbar

    a. Select Tools

    b. in Tools select Batch Tester

  2. Click “Add test package”

  3. Your first action should be filling the Name for the Batch Test. Name can contain only characters from collection a-z; A-Z; 0-9; “-”; “_”.

  4. Next click +Add test

    a. Select unit test you wish to base the batch test on

    b. If test loaded correctly to batch tester it will show on the list of the unit tests

  5. Click on Run test to get the results

  6. Now, when the template has been provided you can Download the batch test to your computer as XLSx file. Click on Download package

  7. Open the XLSx file

    a. The template should look similar to this

    b. add data series according to your needs

    c. save the edited file

  8. Upload the batch test:

    a. Click on Upload package

    b. Load the updated file from your computer

    c. Click Upload

  9. When the file is loaded correctly and you will click Run test again the result of all loaded test cases should show

  10. Lastly, to be able to get back to created batch test case you must save it by clicking : Save package:

a. add the name for the batch test, if you have not added it yet. For Batch test name allowed characters are a-z, A-Z and symbols: -_

b. click on Save package

Batch tester - Upload a batch test

You can upload test package in two ways. First from the Batch Tester Panel:

  1. Click on Upload test package:

  2. Load the file from your computer

  3. Click Upload button to accept the selected file for upload

  4. The uploaded batch test should show on the list

The other way is to create new batch test:

  1. In the Batch Tester Panel click on Add test package (in actions panel)

  2. On batch test creator view, in action panel click on Upload package

  3. Select the XLSx file with the definition of the batch test

    a. Load file

    b. Click upload

  4. After successful download remember to save the batch test

Batch tester - Download a batch test

When working on selected batch test:

  1. Click on Download package

  2. The XLSx file will be generated with definition of the batch test, save the file.

Batch tester - Reading & Editing the XLSx file

Each XLSx from batch test is created according to the rules:

  • There are always three sections with data
  • Each sections may have multiple columns
  • Data sections are separated by empty column, with header # or ##

First sections:

  • starts with column including test case name
  • each next column contains one input value

Second section:

  • for each tested element one column is created
  • each column contains result expected value for one of the tested elements

Third section:

  • for each tested element two columns are created
  • first column contains evaluated value for the tested element
  • second column contains value of the difference between calculated result and expected result
First section:

Column headers are indicators of what kind of variable is needed. Usually in the context header is a context path which is used in tested elements.

Second section:

In each header two informations are stored:

  • Type of element in the test case

    • att@ for domain business attribiute
    • par@ for parameter
    • fun@ for function
  • Code of that element

    • in case of attr@ after element type domain path is given
    • in case of par@ or fun@ after element type element code is given
Third section:

In each header three informations are stored:

  • Value Type :
    • Evaluated - for columns holding values evaluated by the algorithm
    • Diff - for the value of the difference between what was calculated and what was expected
  • Type of element in the test case
    • att@ for domain business attribute
    • par@ for parameter
    • fun@ for function
  • Code of that element
    • in case of attr@ after element type domain path is given
    • in case of par@ or fun@ after element type element code is given

Run Batch Test

To Run an existing batch test follow these steps:

  1. Go to Main Toolbar

    a. Select Tools

    b. in Tools select Batch Tester

  2. You will see Batch Tester Panel, filled with all existing batch tests

  3. Click on selected batch test, to view it’s details

  4. Batch test view, in our example:

  5. When you click on selected test

  6. Here you are able to view test details and if needed change:

    a. Input values

    b. Expected values

    c. Or even change tested elements in selected unit test case (full description on how to create and edit Unit Test Cases can be found in the User Guide Tester chapter)

  7. When all the changes are made

    a. If you want to save this Unit test and be able to view it in singular Tester just click Save test

    b. It’s not obligatory to Save test as you would in Unit Tester. Just get back to the batch test by clicking the Package button

  8. On the batch test view click Run package to perform your tests

  9. For each unit test a result status will show:

    All possible statuses are described here:

    No. Status Description
    1. Success When unit test performs without problems and result value is equal to expected value.
    2. Failure Can occur in two situations:
    - The result value is not equal to expected value
    - The Error occur during performing the unit test
  10. Beside Status there are other information given by batch tester

No. Column name Description
1. Status Test case status (Success/Failure) depending on whether test was performed with positive result
2. Failures Number of failures within unit test case. Where evaluated value differs from expected value.
3. Errors Number of errors which occurred during the unit test.
4. Time (ms) Time taken to perform the unit test.

Context

Context is an object model containing all data that may affect Decision tables’ or Functions’ values. Once we design a context model, we can make our parameterization depends on any data from the context. In order to see Context, select Context in Main Toolbar.

After you enter Context you will see screen of all Types:

No. Column/Action name Description
1. Name Full type name. You can filter this column by providing any string.
2. GMO Table name Full GMO Table name. You can filter this column by providing any string.
3. Description Full description of type. You can filter this column by providing any string.
4. Last update The last modification date of the type.
5. Actions List of quick access actions. Currently only Remove action (bin icon) is available here. Remove action deletes the desired type. To learn more about removing a specific Context Type, go here.
6. Download Types Downloads a TXT file that contains all Types and Attributes of Types. To learn more about downloading Types, go here.
7. Upload Types Allows uploading Types from a TXT file. To learn more about uploading Types, go here.
8. + New type Allows creating new Types. To learn more about adding Types, go here [go here.
9. Delete all types Deletes all Context Types.

Context - Add new type

If you want to add a new context type, follow these steps:

  1. Choose Context in Main toolbar.

  2. Choose + New type.

    a. Choosing + New type opens a step-by-step Context Type wizard.

  3. In step 1. Name you need to provide unique Type name. Name can contain only characters from collection a-z; 0-9; “.”; “-”; “_” and it can’t start with “-”.

    a. If you enter illegal characters, then borders will be highlighted with red color. Hover on the field to see tooltip with more information.

  4. Choose Next.

  5. In step 2. Description you may add Type’s description. Description can contain only characters from collection a-z; A-Z; 0-9; “.”; “-”; “,”; “_” and white-space characters. This data is not

    a. If you choose Previous you will go back to step 1. Name.

    b. If you enter illegal characters, then borders will be highlighted with red color. Hover on the field to see tooltip with more information.

  6. Choose Next.

  7. In step 3. Attributes you may add/remove attributes. This data is not necessary to save a type.

    a. If you decide to add attributes, you:

    i. must** provide unique name. Name can contain only characters from collection a-z; 0-9; “-”; “_”; and it can’t start with “-”;

    ii. must select a type from a drop-down list.

    iii. can check/uncheck multi value.

    iv. can provide Attribute description. Description can contain only characters from collection a-z; A-Z; 0-9; “.”; “-”; “,”; “_” and white-space characters.

    b. You can sort attributes by left-clicking on arrows next to each Column name.

    c. If you enter illegal characters in name field for any attribute, then borders will be highlighted with red color, and you will not be able to save a type.

    d. If you enter illegal characters in the description field for any attribute, then borders will be highlighted with red color, and you will not be able to save a type.

  8. Choose Save.

    a. Type with data you provided is created.

    b. If in step 3. Attributes you entered the same name in at least two attributes, then validation error will appear.

Context - Remove Context Type

If you want to remove a specific context type, follow these steps:

  1. Choose Context in Main toolbar.

  2. Choose Remove action (bin icon) for type you want to delete.

    a. Action is greyed out for ROOT type.

    b. After choosing Remove action, confirmation pop-up will appear.

  3. Choose Delete.

    a. Specific Type is being removed from the environment. This action is irreversible.

Context - Download Context

If you want to download context, follow these steps:

  1. Choose Context in Main toolbar.

  2. Choose Download.

    a. Choosing Download a TXT file that contains the whole Context.

Context - Upload Context

If you want to upload context, follow these steps:

  1. Choose Context in Main toolbar.

  2. Choose Upload.

    a. Choosing Upload brings up Import context screen.

  3. Drag&drop desired file or Click to upload a file and choose file in File explorer.

    a. If you choose a file with extension other than TXT, then validation error will pop up.

    b. If there is something wrong with data in TXT file, then validation error will appear.

  4. Choose Upload

  5. When the progress bar reaches 100%, it means that context was uploaded correctly

    a. If a validation error occurs (see above), then an upload process is being aborted.

Context - Delete all types

If you want to delete all types in context, follow these steps:

  1. Choose Context in Main toolbar.

  2. Choose Delete all types.

    a. After choosing Delete all types button, confirmation pop-up will appear.

  3. Choose Delete.

    a. The Entire Context excluding ROOT is deleted from the environment.

Context Type details screen

You can access Context Type details by left-clicking on the specific type in the screen of all Types.

An important difference in Context is that changes made in Types are instant, without session mechanism.

No. Name Description
1. Type details section Contains information such as: Type’s name, GMO Table Name, and Type’s description.
2. Attributes section Contains information about all attributes created in Type.
3. Name Full attribute name.
4. Type Data type used in the attribute.
5. Multi value If multi-value is checked, then it allows providing a list of elements. If unchecked, then only single elements can be provided.
6. GMO Persistent Informs about the used GMO type.
7. GMO Column name Name of the GMO column in the database.
8. Description Full description of the type.
9. Edit - Type Enables Edit mode for Type details section. To learn more about editing type details, go here.
10. Edit - Attributes Enables Edit mode for Attributes section. To learn more about editing attributes, go here.

Context Type details - Edit Type details

If you want to edit data in a Type details section, follow these steps:

  1. Choose Context in Main toolbar.

  2. Left-click on a type you wish to edit.

    a. Left-clicking on type opens Context Type details screen.

  3. Choose Edit in Types details section.

    a. Highlighted borders indicate that edit mode is active.

  4. Edit any data you need.

    a. If you enter illegal characters in type’s name, then validation error will appear.

  5. Choose Save changes to save all changes made in context type.

    a. Cancel reverts all changes made in context type.

    b. If you change type’s name to name that is already used by another type, then validation error will appear.

Context Type details - Edit Attributes

If you want to edit data in the Attributes section, follow these steps:

  1. Choose Context in Main toolbar.

  2. Left-click on a type you wish to edit.

    a. Left-clicking on type opens Context Type details screen.

  3. Choose Edit in Attributes section.

    a. Highlighted borders indicate that edit mode is active.

  4. Edit any data you need.

  5. Choose Save changes to save all changes made in context type.

    a. Cancel reverts all changes made in the context type.

Domain Configuration

In Domain configuration we can create instances of domain types and configure their attributes with use of Decision tables or Functions.

In order to see Domain Configuration, select Domain in Main Toolbar.

After you enter Versions you will see screen of configuration from ROOT perspective:

No. Name Description
1. Tree search field Filter by any string provided by user. Configuration tree navigates to all Elements matching the provided criteria.
2. Download Domain Downloads a XML file that contains entire Domain Configuration. To learn more about downloading Configuration go here
3. Upload Domain Allows to upload Domain Configuration from a XML file. To learn more about uploading Configuration go here
4. Configuration tree Tree structure of your product.
5. Delete tree Deletes all Configuration Elements. To learn more about delete all Configuration elements go here
6. Collection Collections with all created elements.
6a. Add new element to tree Allows to create new Configuration Elements. To learn more about adding Configuration Elements go here

User can Expand/Collapse a tree by clicking on the arrows.

Configuration Collection:

Domain configuration - Add new collection elements

If you want to add a new collection elements, follow these steps:

  1. Choose Domain in Main toolbar.

  2. Navigate to Collection you want to add new elements to.

  3. Choose Add new elements to tree in desired Collection.

    a. Choosing Add new elements to tree brings up Add to tree screen.

  4. Choose Add elements radiobutton.

  5. On this screen, you:

    a. need to provide unique Element code. Code can contain only characters from collection a-z; 0-9; “-”; “_” and it can’t start with “-”.

    i. If the code you provided is not unique, then borders will be highlighted with red color and warning message will appear.

    ii. If you enter illegal characters, then borders will be highlighted with red color. Hover on the field to see tooltip with more information.

    b. need to provide Element name. Name can contain only characters from collection a-z; A-Z; 0-9; “-”; “_” and white-space characters.

    i. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

    c. can provide Element description. Description can contain only characters from collection a-z; A-Z; 0-9; “:”; “.”; “,”; “-”; “_” and white-space characters.

    i. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

    d. can add additional Elements by clicking + NEW ELEMENT.

  6. Choose Add.

    a. Elements with data you provided are created.

Domain Configuration - Add reference

If you want to add a reference, follow these steps:

  1. Choose Domain in Main toolbar.

  2. Navigate to the Collection for which you want to create reference.

  3. Choose Add new elements to tree in desired Collection.

    a. Choosing Add new elements to tree brings up Add to tree screen.

  4. Choose Add a reference radiobutton.

    a. If the Add button is greyed out, it means that you have not chosen any Collection Element to refer to yet.

  5. Choose Collection Element you want to create a reference to.

    a. If there are no Elements to refer to, then an information message will be placed instead of the configuration tree.

  6. Choose Add.

    a. Reference to chosen Element is created.

Domain Configuration - Add a copy

If you want to copy Collection or Collection Element, follow these steps:

  1. Choose Domain in Main toolbar.

  2. Navigate to the Collection for which you want to copy Elements.

  3. Choose Add new elements to tree in desired Collection.

    a. Choosing Add new elements to tree brings up Add to tree screen.

  4. Choose Add a copy radiobutton.

  5. In step 1. Description, you:

    a. need to provide unique Element code. Code can contain only characters from collection a-z; 0-9; “-”; “_” and it can’t start with “-”.

    i. If the code you provided is not unique, then borders will be highlighted with red color and warning message will appear.

    ii. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

    b. need to provide unique Element name. Name can contain only characters a-z; A-Z; 0-9; “-”; “_” and white-space characters.

    i. If the name you provided is not unique, then borders will be highlighted with red color and warning message will appear.

    ii. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

  6. Choose Next.

  7. In step 2. Element to copy you need to choose which Collection Element you want to copy.

    a. If the Add button is greyed out, it means that you have not chosen any Collection Element to copy.

  8. Choose Add.

    a. Copy of chosen Collection Element is created.

Domain Configuration - Download Domain Configuration

If you want to download Domain Configuration, follow these steps:

  1. Choose Domain in Main toolbar.

  2. Choose Download Domain Configuration in Configuration tree.

    a. Choosing Download Domain Configuration downloads an XML file that contains all configuration Collections, Collection Elements, Definition Types and all dependencies between them.

Domain Configuration - Upload Domain Configuration

If you want to upload Domain Configuration, follow these steps:

  1. Choose Domain in Main toolbar.

  2. Choose Upload Domain Configuration in Configuration tree.

    a. Choosing Upload Domain Configuration brings up Import from XML screen.

    b. If you select checkbox Remove elements not included in file, then warning will appear.

  3. Drag&drop desired file or Click to upload a file and choose file in File explorer.

    a. If you choose a file with extension other than XML, then validation error will pop up

    b. If there is something wrong with data in XML file, then validation error will appear.

  4. Choose Upload

  5. When the progress bar reaches 100%, it means that domain definition was uploaded correctly.

    a. If a validation error occurs (see above), then an upload process is being aborted.

    b. If you checked checkbox Remove elements not included in file in step 2, then adequate information about changes will appear after uploading a file.

Domain Configuration - Delete tree configuration

If you want to delete the entire Domain Configuration, follow these steps:

  1. Choose Domain in Main toolbar

  2. Choose Delete tree configuration.

    a. After choosing Delete tree configuration button, confirmation pop up will appear.

  3. Choose Confirm.

    a. The Entire Domain Configuration is deleted from the environment.

  4. Choose Session.

    a. After choosing Session button, Session preview screen will appear.

  5. Choose Publish changes.

Collection Element details screen

You can access Collection Element details by left-clicking on the specific Element in the Domain Configuration tree.

No. Name Description
1 Collection Element details Collection Element details include information about assigned Region, assigned Tags and description of Collection Element.
1a Definition Type code Type code from Domain Definition.
1b Assigned Tags List of all Tags assigned to the Element.
1c Collection Element Description of Collection Element.
2 Collection Element attributes List of all Global and Local Attributes created in Collection Element.
2a Attributes Group name Name of Attributes Group.
2b Global Attributes Global Attributes are defined by Types in Domain Definition.
2c Local Attributes Local Attributes are created in Collection Element by User.
3 Edit Enables Collection Element edit mode. To learn more about editing collection element go here
4 Clone Allows to clone Collection Element. To learn more about cloning collection elements go here
5 Delete element Deletes Collection Element. To learn more about deleting collection element go here
6 Attach/Detach region Allows you to add/remove a region to/from the Collection Element.
- Attach region is available if there are no regions added to Collection Element
- Detach region is available if there is a region added to Collection Element
If User has opened session, then button is greyed out.

Collection Element details - Edit

If you want to edit data in specific Collection Element, follow these steps:

  1. Choose Domain in Main toolbar.

  2. In the Configuration tree, left-click on Collection Element you wish to edit.

  3. Choose Edit.

    a. Highlighted borders indicate that edit mode is active.

  4. Edit any data you need.

  5. Choose Save changes to save all changes made in Collection Element.

    a. Cancel reverts all changes made in the Collection Element.

Collection Element details - Add local attribute

  1. Choose Domain in Main toolbar.

  2. In the Configuration tree, left-click on Collection Element you wish to add local attribute.

  3. Choose Edit.

  4. Choose Add local attribute and you:

    a. need to provide unique Attribute code. Code can contain only characters from collection “a-z”; “A-Z”; “-”; “_”.

    i. If you entered the same code in at least two attributes, then borders will be highlighted with red color, and you will not be able to save changes.

    ii. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

    b. need to provide Attribute name. Name can contain only characters from collection “a-z”; “A-Z”; “0-9”; “-”; “_” and white-space characters.

    i. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

    c. need to provide Attribute value. Value can contain any characters.

  5. Choose Save changes.

Collection Element details - Reset to default value

  1. Choose Domain in Main toolbar.

  2. In the Configuration tree, left-click on Collection Element you wish to add local attribute.

  3. Choose Edit.

  4. Choose Reset to default value for specific Global Attribute.

    a. Attribute’s value is changed to the value defined in the appropriate Definition Type.

  5. Choose Save changes.

Collection Element details - Clone

If you want to clone specific Collection Element, follow these steps:

  1. Choose Domain in Main toolbar.

  2. In the Configuration tree, left-click on Collection Element you wish to clone.

  3. Choose Clone.

    a. Choosing Clone brings up the Clone element screen.

  4. You need to provide:

    a. unique code. Code can contain only characters from collection “a-z”; “A-Z”; “-”; “_”.

    i. If the code you entered is not unique, then borders will be highlighted with red color and warning message will appear.

    ii. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

    b. unique name. Name can contain only characters from collection"a-z"; “A-Z”; “0-9”; “-”; “_” and white-space characters.

    i. If the code you entered is not unique, then borders will be highlighted with red color and warning message will appear.

    ii. If you enter illegal characters, then borders will be highlighted with red color. Hover on field to see tooltip with more information.

  5. Choose Clone.

    a. Collection Elements are being cloned.

Collection Element details - Delete element

If you want to delete specific Collection Element, follow these steps:

  1. Choose Domain in Main toolbar.

  2. In the Configuration tree, left-click on Collection Element you wish to delete.

  3. Choose Delete element.

    a. After choosing Delete element action, confirmation pop up will appear.

  4. Choose Confirm.

    a. Collection Element is deleted from the environment.

Collection Element details - Attach region

If you want to attach a region to Collection Element, follow these steps:

  1. Choose Domain in Main toolbar.

  2. In the Configuration tree, left-click on Collection Element with no region assigned you want to attach a region.

  3. Choose Attach region

    a. If Attach region action is greyed out, it means that user has active open session.

    b. If Detach region action is available, it means that Collection Element has assigned reason already. You need to Detach region before you will be able to attach a new region.

    c. Choosing Attach region brings up Manage versioning screen.

  4. Select Region and one or more Version.

  5. Choose Change.

    a. Region is being assigned to the Collection Element.

Collection Element details - Detach region

If you want to detach a region from Collection Element, follow these steps:

  1. Choose Domain in Main toolbar.

  2. In the Configuration tree, left-click on Collection Element with a region assigned you want to detach a region.

  3. Choose Detach region.

    a. If Detach region action is greyed out, it means that user has active open session.

    b. If Attach region action is available, it means that Collection Element has no region assigned.

    c. After choosing Detach region action, confirmation pop up will appear.

  4. Choose Confirm.

    a. The Region is being detached from Collection Element.

License

Licenses

Licenses are a screen that allows you to manage licenses. You can add new licenses and remove old ones. To access the license screen, please select Tools in Main Toolbar and select Licenses

After you enter Licenses you will see screen of all licenses:

No. Column name Description
1. License number Unique license identification number. You can sort table by License number pressing arrow icon.
2. Status This column indicates the current status of the license. It can have several possible labels such as active, expired. The status provides a quick way to determine if the license is currently valid and its scope. You can sort table by Status pressing arrow icon.
3. Licensee Title of the License. You can sort table by Licensee pressing arrow icon.
4. Valid from Date of the license validity. You can sort table by Valid from date pressing arrow icon.
5. Valid to Date of the license expire. You can sort table by Valid to date pressing arrow icon.
6. Permitted CPU Information about the maximum number of CPU cores cores which the software or service covered by the license can be used. You can sort table by Permitted CPU cores pressing arrow icon.
7. special Additional license conditions. You can sort table conditions by Special conditions pressing arrow icon.
8. actions List of quick access actions. Currently only Remove action is available here. Remove action delete desired license
No. Filter name Description
1. Search text field Filter by any string provided by the user.
2. Status Filter by selected license status

Action - Add license

If you want to add a new license follow these steps:

  1. Select Tools in Main Toolbar and select Licensee

  2. Choose + Add license

  3. Enter your license code and press Add button

    a. If a valid license code is entered, information about the license will appear.

    No. Column name Description
    1. License number Unique license identification number.
    2. License Title of the License
    3. Valid from Date of the license validity.
    4. Valid to Date of the license expire

    b. If an invalid license code is entered, an error message about the incorrect license code will appear.

Action - Remove license

If you want to remove license choose Delete icon and confirm it pressing Confirm button

Logging in

Logging in is necessary to use Higson features and functionalities. Once Higson Studio is opened, you will be directed to the login page automatically.

Before logging in, ensure that you have the following:

  • A registered account: You must have a valid account created within Higson. If you have not signed up yet, please contact your system administrator.
  • Username and password: Make sure you have your unique username and password associated with your account. If you do not remember your credentials, there is a Forgot Password option available on the login page. Utilize this option to reset your password.

Logging in steps

  1. Launch Higson Studio
  2. In Username field, enter your unique username.
  3. In Password field, enter the password associated with your account.
  4. Click on Log in button

Resetting password

If you have forgotten your password or need to change it for any other reason, you can utilize the password reset option. The password reset process involves the following steps:

  1. Click Reset your password.

  2. Enter email linked to your Higson account. Check your email inbox, including the spam or junk folder, for the password reset email.

  3. Upon clicking the hyperlink provided in the email, you will be directed to a page where you can set a new password for your account. Enter a new password. Retype it in the confirmation field.

  4. Once you have entered and confirmed your new password, click Reset password button to save your new password.

Profiles

Profiles in our environment are entire data modules. The domain and context are directly assigned to the profile and cannot exist without it. All the profiles existing in the environment are listed above the toolbar.

Selecting profile

  1. Open the dropdown menu on the right side of the toolbar.

  2. Choose a profile from the list.

Profiles screen

In order to access profiles screen open Tools in Main Toolbar and select profiles.

After you enter Profiles you will see screen of all profiles:

No. Column name Description
1. Name Full profile name
2. Description Optional profile description
3. Default tag Tag assigned to the profile. To learn more about assigning Tags go here [Hyperlink do przypisywania tagów]
4. Add tag to decision table Flag adding selected tag automatically for each new decision table within the given profile
5. Add tag to functions Flag adding selected tag automatically for each function within the given profile
6. Filter decision tables Flag filtering the view of the list of the decision tables to show ones containing the selected tag
7. Filter functions Flag filtering the view of the list of the functions to show ones containing the selected tag
8. Actions List of quick access actions. Edit action (pencil) allows changing other columns within a profile. After it’s selected, two buttons will emerge in its place: click Save to save changes or Cancel to reject them. Remove action (bin icon) deletes the desired profile.
9. Add profile Adds a new profile. Enter its name and optionally other data to save it. You can click Cancel to remove it.

Adding new profile

In order to add a new profile, you need to:

  1. Choose + Add profile

  2. Provide unique Profile name. Name can contain only characters from collection a-z; 0-9; “.”; “-”; “_” and it can’t start with “-”.

    a. If you enter illegal characters in name field, then borders will be highlighted with red color, and you will not be able to save tag.

  3. Optional: add description and the rest of profile properties

  4. Choose Save

    a. Profile with entered data is created.

    b. If you enter the same name as one of the Profiles already created, then validation error will appear.

Sessions

Configuration of the product in Higson is composed of:

  • Domain configuration
  • Decision tables
  • Functions

Operators make changes in configuration in work session. Open session (by this we understand every change made in range of configuration) is visible only to operator, who 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: by Main toolbar > Tools > Sessions or shortcut session button in the top right corner of the application Higson.

  1. When a user chooses to go through the main toolbar (A):

    the screen will show with a list of all sessions:

    While looking for specified session may filter possible matches by:

    • All sessions, Open, Published, Rejected (A)

    • Session id, Start date, End date, User (B)

    Your guidelines will be applied automatically. There is no need to fill all search cells or filter decision tables at once. Input only those which you find necessary. Sessions view is in the form of a table with columns (C):

    Id. Column name Description
    1. Status Status of session: Published, Open, Rejected
    2. User The user who owns the session
    3. Start date Date of creation of session
    4. End date Date of publishing or rejecting session
    5. Remote Flag informing if the session created by higson runtime rest
    6. Description Description of a session after publishing or rejecting

    When a session from the list is selected (by clicking on it) detail information will show:

    In this view, we can see a summary of the selected session: elements number, the start date of the session, and user owner (A).We can publish or reject changes in (B) (only if the Session in (A) is marked as Open). This view also contains three sections: Decision table, Domain, and Function with assigned table containing columns (C):

    Id. Column name Description
    1. Operation Operation on the element: Create, Update, or Delete
    2. ID ID number of element
    3. Element Element name
    4. Created/Modified Date of operation executed at the element
    5. Actions Column for reverting changes on one separate element on this session
  2. When the user chooses to go through the shortcut session button (B) in the top right corner of the application Higson**:**

    very similar session details to the previous one view will appear:

    After clicking on (A) Reject or Publish changes view will pop up:

    After confirmation, changes will be PUBLISH or REJECT with no message or a message in the description field filled.

    Sometimes after publishing a session, there is information about overriding changes. That means another user modified the same decision table while you were working on it. That means his changes probably are not in your current version of the decision table/function (or any objects you were working on). Then you may overwrite another user’s changes - which mean delete his changes and apply yours - or check what changes were made and apply them to your project - to not lose any important data. To check another user’s changes, go to the main toolbar and Main toolbar > Tools > Sessions (like in 1.). From the list of sessions, choose the one whose author is the other user. Then when detailed information about the session occurs, click on the change made on your object. Then you will see how that element looks after (that user) changes and may make a comparison with your current version, then apply any changes in your version by clicking on your session on the session list.

    What’s more, there is a possibility of occurring collision during publishing. That happens when another user makes changes to the same element at the same time. When this kind of situation takes place, the user should run a cohesion analysis to check which elements are the cause. If cohesion analysis is needed, then some changes must be reverted from the session and then (they may be) applied again in a new session on the base of updated elements.

Tags

Tags are helpful tools to search for decision tables and functions. They work as label, which can be assign to different elements in the system. Tags have no influence on work of Higson system, they are there only for our convenience.

In order to see Tags, select Tools → Tags in Main Toolbar.

After you enter Tags you will see screen of all Tags:

No. Column/Action name Description
1. Name Full tag name. You can sort this column by left-clicking on the arrows visible next to the label.
2. Description Full tag description. You can sort this column by left-clicking on the arrows visible next to the label.
3. Access control Shows which tags have restricted access. You can sort this column by left-clicking on the arrows visible next to the label.
4. Actions List of quick access actions available for each user. Available actions are:
- Find usages
- Edit
- Delete
5. Add tag Allows to create new Tags. To learn more about adding Tags go here.
6. Upload tags Allows to upload Tags from a XLSX file. To learn more about uploading Tags go here.
7. Download tags Downloads a XLSX file that contains data of all Tags currently on the environment. To learn more about downloading Tags go here

You can see all Filters available in Tags below:

No. Filter name Description
1. Search text field Filter by any string provided by user. Filtered by Name column.
2. Access control checkbox Filter by Access control column.

All actions visible in quick access action list are listed below:

No. Name Description
4. Actions List of quick access actions available for each tag.
4a. Find usages Redirects to Global search with the correct filters applied. To learn more about finding usages go here
4b. Edit Allows to edit tag’s data. To learn more about editing tag’s data go here.
4c. Delete Deletes tag. To learn more about deleting tag go here.

Tags - Add tag

If you want to add a new tag, follow these steps:

  1. Choose Tools → Tags in Main toolbar.

  2. Choose + Add tag.

    a. Choosing + Add tag adds new empty record to the List of all Tags.

  3. You:

    a. need to provide unique Tag name. Name can contain only characters from collection a-z; 0-9; “.”; “-”; “_” and it can’t start with “-”. i. If you entered illegal characters in name field, then borders will be highlighted with red color and you will not be able to save tag. b. can provide Tag description. Description can contain any characters. c. can select Access control checkbox to determine if Tag should have restricted access.

  4. Choose Save. a. Tag with entered data is created. b. If you entered the same name as one of Tags already created, then validation error will appear.

Tags - Upload tags

If you want to upload tags, follow these steps:

  1. Choose Tools → Tags in Main toolbar.

  2. Choose Upload. a. Choosing Upload brings up Upload tags screen.

  3. Drag&drop desired file or Click to upload a file and choose file in File explorer. a. If you will choose a file with extension other than XLSX, then validation error will pop-up.

  4. Choose Upload.

  5. When progress bar reach 100%, it mean that file was uploaded correctly.

    a. If validation error will occur (see above), then upload process is being aborted.

Tags - Download tags

If you want to download all tags currently on the environment, follow these steps:

  1. Choose Tools → Tags in Main toolbar.

  2. Choose Download.

    a. Choosing Download downloads a XLSX file, that contains data of all tags currently on the environment.

Tags - Find usages

If you want to know which elements use certain tags, follow these steps:

  1. Choose Tools → Tags in Main toolbar.
  2. Choose Find usages actions for desired Tag. a. Choosing Find usages redirects to Global search with the correct filters applied.

Tags - Edit

If you want to edit data in specific tag, follow these steps:

  1. Choose Tools → Tags in Main toolbar

  2. Choose Edit action for desired tag.

    a. If Tag is being used by any Elemetn, then Edit action is greyed out. b. Highlighted borders indicate, that edit mode is active.

  3. Edit any data you need.

    a. Name can contain only characters from collection a-z; 0-9; “.”; “-”; “_” and it can’t start with „-’’. If you entered illegal characters in name field, then borders will be highlighted with red color and you will not be able to save tag.

  4. Choose Save.

    a. Tag is being updated. b. If you entered the same name as one of Tags already created, then validation error will appear.

Tags - Delete tag

If you want to delete specific tag, follow these steps:

  1. Choose Tools → Tags in Main toolbar.

  2. Choose Delete action for desired tag. a. If Tag is being used by any Element, then Delete action is greyed out. b. After choosing Delete action, confirmation pop-up will appear

  3. Choose Delete.

    a. Specific Tag is being deleted from the environment. This action is irreversible.

Technical Documentation

Bootstrap

Studio

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

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

Docker

Higson Studio distribution does not contain JDBC drivers other than H2 database. Every image contains description how to configure JDBC driver.

Full docker repository is available here.

Runtime

Prerequisites:

  • Java 17
  • Maven 3.x
  • Spring Framework
  • Higson Studio

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>io.higson</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
higson.database.url=<jdbc\_url\to\database>
higson.database.username=<username>
higson.database.password=<password>

Properties are available here

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("higson.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("higson.database.username"));
      dataSource.setPassword(env.getProperty("higson.database.password"));
      dataSource.setUrl(env.getProperty("higson.database.url"));
      dataSource.setInitialSize(4);
      dataSource.setDriverClassName(dialectTemplate.getJdbcDriverClassName());
      return dataSource;
  }
  
  @Bean(destroyMethod = "destroy")
  public HigsonEngineFactory getHigsonEngineFactory(DataSource dataSource) {
      log.info("Engine factory begin creation...");
      HigsonEngineFactory higsonEngineFactory = new HigsonEngineFactory();
      higsonEngineFactory.setDataSource(dataSource);
      return higsonEngineFactory;
  }
  
  @Bean
  public HigsonEngine getHigsonEngine(HigsonEngineFactory higsonEngineFactory) {
      log.info("Engine begin creation...");
      return higsonEngineFactory.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 higson-runtime-spring-boot-starter dependency, available in Maven Central. Add higson-runtime-spring-boot-starter dependency to pom.xml file:

1
2
3
4
5
<dependency>
 <groupId>io.higson</groupId>
 <artifactId>higson-runtime-spring-boot-starter</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:

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 higson.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
  • higson.database.url
  • higson.database.username
  • higson.database.password

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

1
2
3
4
5
6
7
wget  https://repo1.maven.org/maven2/pl/decerto/higson-runtime-rest/4.0.0/higson-runtime-rest-4.0.0.jar -O higson-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 ./higson-runtime-rest.jar \
        -Dhigson.database.url=”jdbc:postgresql://your_postgresql_database:5432/higson?currentSchema=public” \
        -Dhigson.database.username=”admin” \
        -Dhigson.database.password=”admin”

Docker

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

Example:

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

Additionally, you need to pass 3 properties:

  • higson.database.url
  • higson.database.username
  • higson.database.password

An invocation example:

1
2
3
4
docker run -p 8080:8081 -e higson.database.url=jdbc:postgresql://your_postgresql_database:5432/higson?currentSchema=public
-e higson.database.username=admin
-e higson.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:

Setting up a docker images

The tutorial will be based on our motor insurance. 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
4
5
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:

  • higson.database.url : JDBC url to Higson’s database
  • higson.database.username : Higson’s database username
  • higson.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 decerto/higson-runtime-rest:latest
ARG DRIVER\_JAR=dbDriver.jar
COPY ${DRIVER\_JAR} driver.jar
ENTRYPOINT\["java","-Dloader.path=driver.jar","-jar","/higson-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.

Properties

Properties in Higson

Higson gives user a possibility to configure and overwrite internal application properties. They are stored in dedicated file, named application.yml . File should be placed in container or may be pass using environment properties

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
  studio-api:
    image: decerto/higson:4.0.0
    container_name: higson-studio-api
    ports:
      - "48282:8282"
    volumes:
      - ./application.yml:/application.yml  # << here properties are passed from host in yaml file
    environment: 
      - "HIGSON_DATABASE_URL=jdbc:postgresql..." # << this section let us define environment properties which has precedence over the yaml file.
      - "HIGSON_DATABASE_USERNAME=higson"
      - "HIGSON_DATABASE_PASSWORD=higson"
      - "HIGSON_DATABASE_DIALECT=postgresql" 

Configurable properties

Property Description Default value
Database
higson.database.dialect Database dialect to use. Predefined dialects available in Higson: oracle,hsqldb, h2, mssql2012, postgresql, mysql oracle
higson.database.hbm2ddl-mode proxy for hibernate property hibernate.hbm2ddl.auto validate
higson.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
higson.database.url JDBC connection url
higson.database.username Username that Higson will use to connect to database defined in mpp.database.url
higson.database.password Password that Higson will use to connect to database defined in mpp.database.url
higson.database.schema Database schema wherein Higson tables exist
Environment
higson.studio.instance-name Id identifying specific Higson Studio Instance. It is visible in Higson Studio below menu toolbar 1.5.0
higson.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
higson.studio.ui.header-color CSS style (e.g. rgb(27, 140, 204)) defining Studio header color. If not set, default color is used
higson.studio.ui.text-color CSS color (e.g. #7f8c8d) used on text existing in start pages.
higson.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
higson.studio.region.updater.task-cron CRON expression used to schedule job updating system region versions in Higson Studio 0 1 0 * * *
higson.studio.ui.show-stacktrace Flag determining whether full stacktrace should be shown when GUI error happened false
higson.studio.session.require-message Flag determining whether session message is required when publishing session false
Security
higson.security.password-encoder.name Name of using password encoder bcrypt
higson.security.password-encoder.complexity Password encoder complexity 5
higson.security.jwt.authentication-server Determines if studio server works as authentication provider true
higson.security.jwt.secret-key Secret to sign and decode JWT token (up to 256-bytes chars). To communicate with UI and Runtime Rest client.
higson.security.jwt.algorithm Determines JWT token sign algorithm (only HMAC256 supported) HMAC256
higson.security.jwt.access-token-lifetime.value Access token lifetime value 5
higson.security.jwt.access-token-lifetime.unit Access token lifetime unit Minutes
higson.security.jwt.refresh-token-lifetime.value Refresh token lifetime value 7
higson.security.jwt.refresh-token-lifetime.unit Refresh token lifetime unit Minutes
higson.security.jwt.persist-refresh-token Should persist refresh token to database (session idempotent) true
Features
higson.studio.function.support.rhino.enabled Should use Rhino as additional function’s language false
higson.studio.mail.host Mailer server host. If host and port are not set - mailer is not loaded ""
higson.studio.mail.port Mailer server port. If host and port are not set - mailer is not loaded ""
higson.studio.mail.username Mailer server username ""
higson.studio.mail.password Mailer server username’s password ""
higson.studio.mail.from Mailer from metadata ""
higson.studio.global-search.history-limit limit of history searches to keep in Higson Studio memory 60
higson.studio.external-environments.codes Name for the connected environment, to SEND snapshots and Superpacks to prod
higson.studio.external-environments.%s.url Url to the connected environment API
higson.studio.external-environments.%s.username Username to data source. %s is env code from property above. admin
higson.studio.external-environments.%s.password Password to data source. %s is env code from property above. admin
higson.studio.snapshot.param.matrix.writer.order-by-all-level Should sort by all levels during export parameter to file. Available: true/false true

RUNTIME

Available for runtime or runtime-rest apps

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

Properties names since version 4.x

COMMON

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

HIGSON STUDIO:

Version 2.3 Version 4.x default value
hyperon.studio.url higson.studio.url
hyperon.studio.instance-name higson.studio.instance-name
hyperon.studio.ui.header-color higson.studio.ui.header-color
hyperon.studio.ui.text-color higson.studio.ui.text-color
hyperon.studio.ui.chart-colors higson.studio.ui.chart-colors
hyperon.studio.security.type higson.studio.security.type
hyperon.studio.security.cas.server-url higson.studio.security.cas.server-url
hyperon.studio.security.cas.login-url higson.studio.security.cas.login-url
hyperon.studio.security.cas.logout-url higson.studio.security.cas.logout-url
hyperon.studio.security.cas.logged-out-url higson.studio.security.cas.logged-out-url
hyperon.studio.security.saml.base-url higson.studio.security.saml.base-url
hyperon.studio.security.saml.entity-id higson.studio.security.saml.entity-id
hyperon.studio.security.saml.idp-metadata-file-path higson.studio.security.saml.idp-metadata-file-path
hyperon.studio.security.saml.response-skew higson.studio.security.saml.response-skew
hyperon.studio.security.saml.key-store.path higson.studio.security.saml.key-store.path
hyperon.studio.security.saml.key-store.pass higson.studio.security.saml.key-store.pass
hyperon.studio.security.saml.key-store.alias higson.studio.security.saml.key-store.alias
hyperon.studio.security.saml.key-store.key-pass higson.studio.security.saml.key-store.key-pass
hyperon.studio.security.saml.roles-origin higson.studio.security.saml.roles-origin
hyperon.studio.security.basic.password-encoder higson.studio.security.basic.password-encoder
hyperon.security.active-directory.domain higson.security.active-directory.domain
hyperon.security.active-directory.url higson.security.active-directory.url
hyperon.security.active-directory.root-dn higson.security.active-directory.root-dn
hyperon.studio.security.azure-active-directory.client-id higson.studio.security.azure-active-directory.client-id
hyperon.studio.security.azure-active-directory.tenant-id higson.studio.security.azure-active-directory.tenant-id
hyperon.studio.security.azure-active-directory.client-secret higson.studio.security.azure-active-directory.client-secret
hyperon.studio.security.azure-active-directory.base-url higson.studio.security.azure-active-directory.base-url
hyperon.studio.security.azure-active-directory.username-attribute-name higson.studio.security.azure-active-directory.username-attribute-name
hyperon.studio.security.azure-active-directory.roles-origin higson.studio.security.azure-active-directory.roles-origin
hyperon.studio.mail.host higson.studio.mail.host
hyperon.studio.mail.port higson.studio.mail.port
hyperon.studio.mail.username higson.studio.mail.username
hyperon.studio.mail.password higson.studio.mail.password
hyperon.studio.mail.from higson.studio.mail.from
hyperon.studio.superpack.environments higson.studio.superpack.environments test, prod
hyperon.studio.superpack.test.url higson.studio.superpack.test.url
hyperon.studio.superpack.test.username higson.studio.superpack.test.username
hyperon.studio.superpack.test.password higson.studio.superpack.test.password
hyperon.studio.external.environment.codes higson.studio.external.environment.codes test, prod
hyperon.studio.external.environment.test.url higson.studio.external.environment.test.url
hyperon.studio.external.environment.test.username higson.studio.external.environment.test.username
hyperon.studio.external.environment.test.password higson.studio.external.environment.test.password
hyperon.studio.global-search.history-limit higson.studio.global-search.history-limit
hyperon.studio.security.login.attempts-limit higson.studio.security.login.attempts-limit
hyperon.studio.security.login.attempts-cooldown higson.studio.security.login.attempts-cooldown
hyperon.studio.ui.show-stacktrace higson.studio.ui.show-stacktrace true or false
hyperon.studio.security.login.auto-login higson.studio.security.login.auto-login true or false
hyperon.studio.session.require-message higson.studio.session.require-message
hyperon.studio.security.password.send-reset-tokens higson.studio.security.password.send-reset-tokens true or false
hyperon.studio.region.updater.task-cron higson.studio.region.updater.task-cron

HIGSON RUNTIME:

Version 2.3 Version 4.x default value
hyperon.runtime.security.type higson.runtime.security.type
hyperon.runtime.function.validate-arguments higson.runtime.function.validate-arguments true
hyperon.runtime.normalization.throw-on-exception higson.runtime.normalization.throw-on-exception
hyperon.runtime.external-datasource.sql.names higson.runtime.external-datasource.sql.names
hyperon.runtime.external-datasource.sql.test.url higson.runtime.external-datasource.sql.test.url
hyperon.runtime.external-datasource.sql.test.username higson.runtime.external-datasource.sql.test.username
hyperon.runtime.external-datasource.sql.test.password higson.runtime.external-datasource.sql.test.password
hyperon.runtime.dev-mode-enabled higson.runtime.dev-mode-enabled
hyperon.runtime.username higson.runtime.username
hyperon.runtime.parameter.value-never-null higson.runtime.parameter.value-never-null
hyperon.runtime.watchers.enabled higson.runtime.watchers.enabled true
hyperon.runtime.external-datasource.sql.names higson.runtime.external-datasource.sql.names

HIGSON RUNTIME REST:

Version 2.3 Version 4.x
hyperon.runtime-rest.security.user-cache-enabled higson.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 higson.security.basic.password-encoder=Pbkdf2 property in the application.properties You can choose the complexity of BCrypt algorithm by setting a property higson.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
    higson.studio.url=https://higson_server_adress/higson/app
    higson.studio.security.type=cas
    higson.studio.security.cas.server-url=https://cas_server_adress
    higson.studio.security.cas.login-url=${higson.studio.security.cas.server-url}/login
    higson.studio.security.cas.logout-url=${higson.studio.security.cas.server-url}/logout?service=${server.cas.loggedout}
    higson.studio.security.cas.logged-out-url=${higson.studio.url}/loggedOut

Active Directory

1
2
3
4
    higson.studio.security.type=active-directory
    higson.security.active-directory.domain=domain.local #Active Directory main root
    higson.security.active-directory.url=ldap://10.222.20.156:389/ #Active Directory server url
    higson.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
  • HIGSON_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

1. Configure Tomcat to use HTTPS.
2. Fill properties:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    higson.studio.security.type=saml
    higson.studio.security.saml.base-url=
    higson.studio.security.saml.entity-id=
    higson.studio.security.saml.idp-metadata-file-path= #Path to identity provider metadata file
    higson.studio.security.saml.response-skew=60 #Determines maximum difference between clocks of the identity provider and Studio machines.
    higson.studio.security.saml.key-store.path=
    higson.studio.security.saml.key-store.pass=
    higson.studio.security.saml.key-store.alias=
    higson.studio.security.saml.key-store.keyPass=
    higson.studio.security.saml.roles-origin=  ##internal or saml
3. Generate metadata from Studio https://localhost:8080/higson/saml/metadata
4. Import generated metadata into Identity Provider.
5. 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 higson.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://{higson_context_url}/login/oauth2/code/ for example; http://localhost:8080/higson/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
    higson.studio.security.type=azured
    higson.studio.security.azure-active-directory.client-id=
    higson.studio.security.azure-active-directory.tenant-id=
    higson.studio.security.azure-active-directory.client-secret=
    higson.studio.security.azure-active-directory.base-url=http://localhost:8080/higson
    higson.studio.security.azure-active-directory.username-attribute-name=preferred_username
    higson.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 higson.security.basic.password-encoder=Pbkdf2 property in the application.properties You can choose the complexity of BCrypt algorithm by setting a property higson.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
    higson.studio.security.type=active-directory
    higson.security.active-directory.domain=domain.local #Active Directory main root
    higson.security.active-directory.url=ldap://10.222.20.156:389/ #Active Directory server url
    higson.security.active-directory.root-dn=DC=domain,DC=local #AD root domain

JWT Based authentication Token

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

The property higson.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 Studio

Firstly, download application from 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

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

Bump the Studio application

Download new Studio

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

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.

Check out new properties

In a Higson Studio 4.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

Copy files to your tomcat.

  • replace file conf/server.xml,
  • copy conf/Catalina directory to your tomcat
  • remove old .war file from webapps and copy new higson#api.war and higson#app 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("higson.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("higson.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

Changelog

4.0.0 January 08, 2024

Hyperon’s business rules engine transforms into Higson!

What’s new :

  • Even More Intuitive Studio - Discover our new, user-friendly interface that simplifies both technical and business tasks.
  • Simplified Structure Configuration - Tailoring your business application structure is now more straightforward, whether you’re an IT expert or a business strategist.
  • Optimized Decision Tables Creation - Creating and editing decision tables has become simpler, and optimized for greater clarity and control.
  • New Versioning - We’ve upgraded our versioning scheme, to be more intuitive and easier to manage.
  • Changed architecture - FE and BE are released separately