Technical Documentation

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

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

Docker#

Higson Studio distribution only contains H2 and PostgreSQL drivers, the others have to be added manually. Every image contains description how to configure JDBC driver.

Full docker repository is available here.

Prerequisites:

• Java 17
• Maven 3.x
• Higson Studio

JavaDoc

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, Postgres, MsSQL or MySQL and database connection pool managing library:

1
2
3
4
5

  <dependency>
     <groupId>com.h2database</groupId>
     <artifactId>h2</artifactId>
     <version>${h2-database.version}</version>
  </dependency>

Properties#

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

1
2
3

higson.database.url=<jdbc_url>
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:

Run Higson Runtime REST in Test Mode Using Snapshot-Based Configuration#

It is possible to run the Higson Runtime in test mode using a configuration loaded directly from a snapshot. In this mode:

• The runtime does not require a database connection, as the entire configuration is sourced locally from the snapshot.
• The environment operates in read-only mode.
• Watchers are disabled, as no changes to the configuration are expected.
• Test mode is mutually exclusive with development mode and cannot be used simultaneously.
• This setup does not support tables from external data sources.

To use runtime in test mode, you need the following configuration:

private String pathToSnapshot = "C:\Users\UserName\Downloads\snapshot.zip"

@Bean(destroyMethod = "destroy")
public HigsonEngineFactory getHigsonEngineFactory() {
    log.info("Engine factory begin creation...");
    HigsonEngineFactory higsonEngineFactory = new HigsonEngineFactory();
    higsonEngineFactory.setDataSource(new HigsonSnapshotDataSource(new File(pathToSnapshot)));
    return higsonEngineFactory;
}

@Bean
public HigsonEngine getHigsonEngine(HigsonEngineFactory higsonEngineFactory) {
    log.info("Engine begin creation...");
    return higsonEngineFactory.create();
}

Prerequisites#

• Java 17
• Maven 3.x
• Spring Boot 3

Maven Configuration#

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

1
2
3
4
5
6

<dependency>
	<groupId>io.higson</groupId>
	<artifactId>spring-boot-starter-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:

1
2
3
4
5
6

<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.yml file with database properties:

1
2
3
4
5

higson:
  database:
    username: <username>
    password: <password>
    url: <jdbc_url>

If required properties are not available, spring-boot-starter-higson-runtime 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:
        names: postgres,h2
        postgres:
          url: <postgres_jdbc_url>
          password: <postgres_password>
          username: <postgres_username>
        h2:
          url: <h2_jdbc_url>
          username: <h2_username>
          password: <h2_password>

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
6
7

@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
 9
10

@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
5

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

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

• Spring boot’s executable jar, available here: https://www.higson.io/docs/d-success
• Docker image, available here: https://hub.docker.com/repository/docker/decerto/higson-runtime-rest

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.2.0/higson-runtime-rest-4.2.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.2.0
ARG DRIVER=postgresql.jar
COPY ${DRIVER} driver.jar
ENTRYPOINT [`java`,`-Dloader.path=driver.jar`, `-jar`,`/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 decision table/function/domain element.

Prerequisites#

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

• running docker. See https://docs.docker.com/installation/#installation for details on setting Docker up for your machine.
• a favorite REST API Client to send requests such as Postman
• a favorite internet browser

Setting Up 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","/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 Decision Table Value#

We will be using a decision table examples from this article. Let’s get the value of a demo.motor.coverage.position decision table 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 decision table. In this example, we are going to use the demo.motor.dict.vehicle.available decision table. 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 decision table (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
70
71
72
73
74
75
76
77
78

[
  {
    "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 decision table’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 decision tables 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 decision table’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":"BI"
      }
    ]
  }, 
  "elements": [
    {
      "profileCode":"DEMO", 
      "code":"/PLANS[FULL]/COVERAGES[BI]/", 
      "attributeCode":"POSITION", 
      "type":"DOMAIN_OBJECT"
    }
  ]
}

The main difference between domain element and decision table/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": 1
          }
        ]
      }
    ]
  }
]

As we see, the response format is the same as in the decision table/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/index.html.

Accessing Swagger UI#

The Swagger UI link is generated automatically based on the installation type (Docker or Bundle). The Swagger UI is accessible at the following address format:

http://[host]:[port]/[appname]/[apiname]/swagger-ui/index.html

For Docker-Based Deployments#

When the application is running in a Docker environment, the URL components are determined as follows:

• host: localhost (or the container’s IP address if accessed externally)
• port: retrieved from the server.port property (e.g., 8080)
• apiname: the value of server.servlet.context-path from the application’s configuration (e.g., /api)

Example: http://localhost:8080/api/swagger-ui/index.html

For Bundle Installations#

In the case of a bundle installation:

• host: localhost

• port: retrieved from the conf/server.xml configuration file by locating a line such as:

  <Connector port="38080" protocol="HTTP/1.1" ... />
  

  In this example, the port is 38080.

• appname and apiname: determined based on the directory structure within the webapps folder. For version 4.1, the typical folder name is higson#api, which translates to:

  • appname = higson
  • apiname = api

Example: http://localhost:38080/higson/api/swagger-ui/index.html

By following these rules, you can easily determine the correct Swagger UI URL regardless of the deployment method.

Generating Runtime REST JSON from Tester#

To generate a request to Runtime Rest, navigate to Tools -> Tester. Click “Add Test”, then add the elements for which you want to generate an example request. In the example below, the following elements have been selected:

• Decision Table,
• Function,
• Domain Element,

1. Click “Add element” on the left side.
2. Select the elements for which you want to generate an example request.
3. Add the selected elements to the test.

Now you can click the “Generate Runtime Rest JSON” button, which will generate an example request without context values.

 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": []
  },
  "elements": [
    {
      "code": "demo.motor.coverage.availability",
      "type": "PARAMETER",
      "profileCode": "DEMO"
    },
    {
      "code": "demo.insurance.calcpremium",
      "type": "FUNCTION",
      "profileCode": "DEMO"
    },
    {
      "code": "/PLANS[FULL]/OPTIONS[SILVER]",
      "type": "DOMAIN_OBJECT",
      "attributeCode": "ORDER",
      "profileCode": "DEMO"
    }
  ],
  "arguments": []
}

If you need to generate an example request with context values, you must first run the test by clicking “Run Test” button. This will populate the Context table with all available context values. Next, fill in the desired context values and click “Run Test” again. Then click “Generate Runtime Rest JSON”.

Now the generated example request will include the values from the context.

 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

{
  "ctx": {
    "properties": [
      {
        "key": "coverage",
        "complexValue": [
          {
            "key": "code",
            "value": "BI"
          }
        ]
      },
      {
        "key": "option",
        "complexValue": [
          {
            "key": "code",
            "value": "BRONZE"
          }
        ]
      },
      {
        "key": "policy",
        "complexValue": [
          {
            "key": "premiumPerDay",
            "value": "3"
          },
          {
            "key": "startDate",
            "value": "2025-10-10"
          },
          {
            "key": "endDate",
            "value": "2026-10-10"
          }
        ]
      }
    ]
  },
  "elements": [
    {
      "code": "demo.motor.coverage.availability",
      "type": "PARAMETER",
      "profileCode": "DEMO"
    },
    {
      "code": "demo.insurance.calcpremium",
      "type": "FUNCTION",
      "profileCode": "DEMO"
    },
    {
      "code": "/PLANS[FULL]/OPTIONS[SILVER]",
      "type": "DOMAIN_OBJECT",
      "attributeCode": "ORDER",
      "profileCode": "DEMO"
    }
  ],
  "arguments": []
}

Cache Mechanism and the Role of Watchers in Higson Runtime REST#

Higson Runtime REST uses a caching mechanism to store computation logic, which significantly contributes to its high performance. The actual computation logic (e.g., functions or decision tables) is stored in a database managed by Higson Studio.

What happens when a Higson Studio user modifies a business configuration — for example, by editing a decision table? To ensure that Higson Runtime REST always operates on up-to-date data, the system must detect these changes and refresh its cache accordingly.

This is where watchers come in — specialized components within Runtime REST responsible for monitoring the state of business configuration in Higson Studio. By default, every 3 seconds, watchers check the current state of the Higson Studio database. If they detect any change in the configuration (e.g., in decision tables, functions, etc.), they signal the need to reload the cache. In response, Higson Runtime REST refreshes the configuration, ensuring that all computations are performed using the most recent data.

Thanks to this mechanism, Higson Runtime REST:

• Always holds an up-to-date business configuration in cache,
• Eliminates delays caused by accessing the database during computation,
• Ensures consistency between Higson Studio and the runtime environment.

Types of Watchers#

Higson Runtime REST defines nine types of watchers, categorized by the type of business configuration element they monitor:

• Decision tables
• Functions
• Versions
• Profiles
• My view - in dev-mode
• Domain
• Developer mode - unpublished changes in session
• Timeline
• Refresh

Each watcher is responsible for tracking changes in a specific resource type, enabling precise and efficient synchronization. Each watcher operates independently. This means that a change in one type of element (e.g., a decision table) does not trigger unnecessary cache reloads for other unrelated areas. This design significantly improves the system’s operational efficiency.

Watcher Properties#

The table below lists the properties related to each watcher type, along with their default values (expressed in seconds).

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.2.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#

Runtime#

Available for Higson Runtime Spring Boot Starter or Higson Runtime REST apps

Security#

Standard / Username and Password#

No extra actions needed to use it, it is available by default.

SAML#

Configuration steps:

• Configure Tomcat to use HTTPS (if needed).
• Fill properties:

 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

#Required properties:
  
higson.studio.security.token.generation.authentication.type=saml
#Specifies the URL of the Studio backend application, e.g.: http://yourdomain.com:38080/higson/api
higson.studio.security.token.generation.authentication.saml.base-url=
#Specifies entity identifier, e.g.: higson
higson.studio.security.token.generation.authentication.saml.entity-id=
#Specifies the path to the IDP metadata file, e.g.: file:/home/user/metadata.xml
higson.studio.security.token.generation.authentication.saml.idp-metadata-file-path=
#Specifies maximum difference between clocks of the identity provider and Studio machines, e.g.: 60
higson.studio.security.token.generation.authentication.saml.response-skew=
#Specifies the source of the roles, possible values: saml / internal
higson.studio.security.token.generation.authentication.saml.roles-origin=
#Specifies the path to the keystore with certificate and private key used to sign and decrypt data, e.g.: file:/home/user/higson.jks
higson.studio.security.token.generation.authentication.saml.key-store.path=
#Specifies the keystore password
higson.studio.security.token.generation.authentication.saml.key-store.pass=
#Specifies an alias for the certificate in the keystore
higson.studio.security.token.generation.authentication.saml.key-store.alias=
#Specifies the private key password
higson.studio.security.token.generation.authentication.saml.key-store.key-pass=
#Specifies the URL of the Studio frontend application, e.g.: http://yourdomain.com:38080/higson/app
higson.studio.security.token.generation.authentication.saml.token-destination-url=

#Optional properties:
  
#Specifies the attribute names
higson.studio.security.token.generation.authentication.saml.attributes.firstname=firstname
higson.studio.security.token.generation.authentication.saml.attributes.lastname=lastname
higson.studio.security.token.generation.authentication.saml.attributes.mail=mail
higson.studio.security.token.generation.authentication.saml.attributes.roles=roles
#Specifies the endpoint that returns SP metadata 
higson.studio.security.token.generation.authentication.saml.sp-metadata-endpoint=/saml2/metadata
#Specifies the endpoint that accepts login response from the IDP
higson.studio.security.token.generation.authentication.saml.assertion-consumer-service-endpoint=/login/saml2/sso/higson
#Specifies the endpoint that accepts logout request
higson.studio.security.token.generation.authentication.saml.single-logout-service-endpoint=/saml2/logout

• Generate Studio metadata and import in your Identity Provider

On your IDP:

• Configure Identity Provider to send attributes with assertion response.
• Check that Identity Provider configuration for Assertion Consumer Service URL and Logout Service URL is correct.

Important! SAML Response signature must include message and assertions!

Attributes Mapping#

SAML Response must contain following attributes:

• Name ID (this is used as user login)
• firstname
• lastname
• mail
• roles

When a user logs into Higson Studio, their account is automatically created in the system with an external status.

Roles#

• if higson.studio.security.token.generation.authentication.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.

Active Directory#

• Fill properties:

1
2
3
4
5
6
7
8
9

#Required properties:

higson.studio.security.token.generation.authentication.type=active-directory
#Specifies Active Directory main root, e.g.: domain.local
higson.studio.security.token.generation.authentication.active-directory.domain=
#Specifies Active Directory server url, e.g.: ldap://10.111.22.156:389/
higson.studio.security.token.generation.authentication.active-directory.url=
#Specifies Active Directory root domain, e.g.: DC=domain,DC=local
higson.studio.security.token.generation.authentication.active-directory.root-dn=

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.

Roles defined in Active Directory must be compatible with roles in Higson structure. When a user logs into Higson Studio, their account is automatically created in the system with an external status.

Hierarchy of Roles in Higson#

MPP_ADMIN - Higson Administrator
MPP_USER - Higson User
MPP_USER_READONLY - Readonly Higson User \

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.

CAS#

Configuration steps:

• Configure Tomcat to use HTTPS.
• Fill properties:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

#Required properties:

higson.studio.security.token.generation.authentication.type=cas
#Specifies the URL of the Studio backend application, e.g.: https://yourdomain.com:38080/higson/api
higson.studio.security.token.generation.authentication.cas.base-url=
#Specifies CAS server url, e.g.: https://cas_server_adress:9443/cas/p3
higson.studio.security.token.generation.authentication.cas.server-url=
#Specifies CAS login endpoint, e.g.: https://cas_server_adress:9443/cas/login
higson.studio.security.token.generation.authentication.cas.login-url=
#Specifies CAS logout endpoint, e.g.: https://cas_server_adress:9443/cas/logout
higson.studio.security.token.generation.authentication.cas.logout-url=
#Specifies the URL of the Studio frontend application, e.g.: http://yourdomain.com:38080/higson/app
higson.studio.security.token.generation.authentication.cas.token-destination-url=

When logging in using CAS, you must configure the corresponding users on the Higson Studio side. Roles are defined and managed on the Higson Studio side.

A refresh token is a special type of access key used to automatically renew a user session without the need to log in again. It is used together with an access token. It is used to ensure user convenience, as it means that users do not have to constantly log in to the application.

The following properties define the lifetime of tokens:

higson.studio.security.token.generation.access-token-lifetime.unit=Minutes
higson.studio.security.token.generation.access-token-lifetime.value=5
higson.studio.security.token.generation.refresh-token-lifetime.unit=Minutes
higson.studio.security.token.generation.refresh-token-lifetime.value=7

The refresh token has a longer lifespan and is used to obtain a new access token. The access token is included in requests and enables authorized access to the API. Once the access token expires, the browser automatically uses the refresh token to retrieve a new access token. If the refresh token also expires, the user will be logged out of the system. Modifying the access token lifetime affects how often it needs to be refreshed — in other words, how frequently the system must generate a new access token. Meanwhile, the refresh token lifetime determines how long a user can remain logged in, that is, how long they can obtain new access tokens without having to log in again.

It’s important to remember that when an automatic logout occurs, any unsaved changes will be lost.

JWT Based Authentication (Runtime Token)#

It is set by default.

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:

1
2

higson.runtime-rest.security.type=jwt
higson.security.jwt.secret-key=your_secret_key

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

Basic Authentication#

1

higson.runtime-rest.security.type=basic

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.runtime-rest.security.type=active-directory
    higson.security.active-directory.domain=domain.local #Active Directory main root
    higson.security.active-directory.url=ldap://server-url/ #Active Directory server url
    higson.security.active-directory.root-dn=DC=domain,DC=local #AD root domain

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. This article refers to patch installation.

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!

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. Use a database client to create the backup. Do not use a snapshot (Higson Studio functionality), as snapshots do not store history.

Check out properties

Make sure that application properties are up to date.

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

Adjust ports

If necessary, modify the server.xml file (adjust ports as in previous version).

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.

Developer License Requirement (version 4.3)#

Starting from version 4.3, a developer license is required on all non-production environments. Before completing the upgrade to version 4.3, ensure that a developer license has been obtained for each non-production environment.

To obtain a developer license, contact:

• Product Manager: oktawia.jakubik@decerto.com
• Sales team: lukasz.niedospial@higson.tech

Bump the Studio Application#

Understanding dependencies between applications:

• Higson Studio and Higson Runtime are separate applications but should run on the same version.
• Higson Studio must be started first, as it manages the database schema.

Download new Studio

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

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. Use a database client to create the backup. Do not use a snapshot (Higson Studio functionality), as snapshots do not store history.

Check out new properties

Make sure that applicatio properties are set up correctly.

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

Adjust ports

If necessary, modify the server.xml file (adjust ports as in version 4.0 or 4.1).

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.