ACTICO Platform - Model Hub · 2020. 7. 30. · ACTICO Platform - Model Hub Operations Guide Version 9.0.0

ACTICO Platform - Model Hub

Operations Guide

Version 9.0.0

www.actico.com

Operations Guide: Version 9.0.0

Operations Guide

Copyright © ACTICO GmbH iii

Table of Contents

1. About this document ........................................................................................................ 1

1.1. Audience ........................................................................................................................... 1

1.2. Content ............................................................................................................................. 1

1.3. Conventions ...................................................................................................................... 1

2. Introduction ........................................................................................................................ 2

2.1. Feature Overview .............................................................................................................. 2

2.2. Team Server Compatibility Mode ...................................................................................... 2

3. System Overview, Links and Authentication ............................................................... 3

3.1. System Overview Diagram ................................................................................................. 3

3.2. Web User Interface ........................................................................................................... 33.2.1. Demo Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3.3. Modeler Endpoint ............................................................................................................. 3

3.4. Git Endpoint ..................................................................................................................... 4

3.5. Engine .............................................................................................................................. 4

3.6. REST Endpoint .................................................................................................................. 4

4. Installation and Configuration ....................................................................................... 5

4.1. Unpack ............................................................................................................................. 5

4.2. Java Runtime .................................................................................................................... 5

4.3. License File ...................................................................................................................... 5

4.4. Configuration ................................................................................................................... 5

4.5. Team Server Compatibility Mode ...................................................................................... 5

4.6. Users ............................................................................................................................... 64.6.1. Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.6.2. Default Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.6.3. Super Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.6.4. Internal Technical User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.7. Authentication .................................................................................................................. 74.7.1. Active Directory / LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.7.1.1. External Active Directory / LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.7.1.2. Embedded LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.7.2. Open ID Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.7.2.1. Optional Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.7.2.2. User Attribute Mapping Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.8. Authorization ................................................................................................................... 9

Operations Guide

Copyright © ACTICO GmbH iv

4.8.1. Active Directory / LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.8.2. Embedded LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.8.3. Open ID Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.9. Database ........................................................................................................................ 114.9.1. Roles and Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.9.2. Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.9.3. Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.9.4. Schema Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.9.4.1. Automatic Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.9.4.2. Manual Deployment with sqldump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.10. Server ........................................................................................................................... 124.10.1. Common Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.10.2. SSL - Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.10.3. SSL - Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.10.4. Custom HTTP Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.10.4.1. Defining a custom header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.10.4.2. Predefined Security Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.10.5. Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.11. Script Environment ........................................................................................................ 154.11.1. Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.11.2. Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.11.3. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.11.3.1. Special Configuration Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.11.4. Install as Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.11.5. Install as Unix Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.12. Maven Repository Connection ....................................................................................... 18

4.13. Clustering ..................................................................................................................... 18

5. Operations and Maintenance ....................................................................................... 19

5.1. Temporary directories ..................................................................................................... 19

5.2. Backup and Restore ........................................................................................................ 195.2.1. Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.2.2. File system folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.3. Logging ........................................................................................................................... 195.3.1. Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.3.1.1. Custom log4j2 configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.4. Monitoring ...................................................................................................................... 205.4.1. Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6. Technical Limitations ..................................................................................................... 22

7. Connecting Engines ......................................................................................................... 23

7.1. Engines ........................................................................................................................... 23

7.2. API Key Authentication .................................................................................................... 23

Operations Guide

Copyright © ACTICO GmbH v

A. Migrations ........................................................................................................................ 24

A.1. Migration from Team Server ........................................................................................... 24A.1.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24A.1.2. Migration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

A.2. Migration from Execution Core ........................................................................................ 26A.2.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26A.2.2. Background information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26A.2.3. Ec6-Export steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28A.2.4. Ec6-Migration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

B. Example Servers ............................................................................................................. 30

B.1. Using Keycloak as external OpenID Connect authentication provider ............................... 30B.1.1. Setup Keycloak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

B.2. Using LDAP as Authentication Provider ........................................................................... 30B.2.1. Prepare Password Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30B.2.2. Prepare User Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31B.2.3. Start LDAP Demo Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

B.3. Using MySQL as external database ................................................................................. 33

C. Troubleshooting .............................................................................................................. 34

C.1. Troubleshooting Active Directory / LDAP Configuration ................................................... 34C.1.1. Authentication and Basic Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34C.1.2. User Search and Attribute Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

D. Example Files ................................................................................................................... 36

D.1. Listing of Example Datasource Configuration Settings ..................................................... 36D.1.1. Oracle Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36D.1.2. Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36D.1.3. MySql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Chapter 1. About this document

Copyright © ACTICO GmbH 1

Chapter 1. About this documentThis document describes the installation and operation of ACTICO Model Hub.

1.1. Audience

This document is intended for

• System Administrators

• Database Administrators

1.2. Content

This document considers the following topics

• Installation

• Configuration

• Operation

• Maintenance

• Migration from Team Server

1.3. Conventions

The following text conventions are used in this document:

Table 1.1. Conventions

Convention Meaning

boldface Used for elements, labels and terms from the userinterface.

monospace Used for filenames or URLs.

Chapter 2. Introduction


Chapter 2. IntroductionACTICO Model Hub is the central component for the management of models throughout their entire lifecycle,from design to production. Models can be business rules, machine learning, DMN or else. All these modeltypes, including their dependencies can be versioned, released, deployed, activated and rolled back via ModelHub.

Model Hub can be run in the following modes:

• Standard mode

• Team Server compatibility mode

2.1. Feature Overview

Main features of Standard mode are:

• Versioning of model projects at design time

• Management of model projects, libraries and their dependencies

• Creation and management of releases

• Management of deployments

• Management of environments

• Statistics about executions

• Export and import functionality

• Security and access control

• Auditing of all events within the system

2.2. Team Server Compatibility Mode

Running in Team Server compatibility mode enables to use Model Hub as a replacement of Team Server, whichis compatible with ACTICO Modeler in version 6 or 8 and ACTICO Builder tools in version 6.

The Team Server compatibility mode enables only a subset of the features listed above. These features are:

• Versioning of model projects at design time

• Export and import functionality

• Security and access control

• Auditing of all events within the system

There is a separate User Guide for the Team Server Compatibility mode.

Chapter 3. System Overview, Links and Authentication



3.1. System Overview Diagram

The following diagram shows Model Hub and related systems:

3.2. Web User Interface

The Model Hub UI is available at its configured base URL, e.g. https://modelhub.example.com. By default(e.g. in a local installation with the evaluation bundle) this is http://localhost:8080.

The server port may be configured to another value. If the server is not installed locally, use thecorresponding valid server name.

3.2.1. Demo Users

If Model Hub is installed with demo data, the following users are available:

User Name User Id Password Assigned User Groups

Administrator Admin Admin Administrators &Standard Users

John John John Standard Users

Mary Mary Mary Standard Users

3.3. Modeler Endpoint

The URL to use Model Hub for model versioning is `https:/// `. By default (e.g. with the evaluationbundle), this is: `http://localhost:8080/ `.

https://modelhub.example.comhttp://localhost:8080



Use this URL in ACTICO Modeler to specify a connection to Model Hub. For authentication choose Model Huband enter user name and password for a valid user account with appropriate permissions.

3.4. Git Endpoint

Model versioning repositories in Model Hub are Git repositories and they provide the APIs to allow standard Gittooling to clone, checkout, commit and push changes. This facilitates integration into IT processes and tools.

In order to access a repository via Git use this URL: `http://:8080/git/modules/ `

Basic Authentication is used and the user needs to have the general permission 'Access Git repository'.Additionally the specific permissions 'read' and 'write' are used to secure pull and push operations for eachindividual repository.

Hints and warnings:

• It is recommended to prefer the Model Hub provided interfaces before using the Git endpoint. Use the GitEndpoint for push (write) operations at own risk, as Model Hub relies on some conventions.

• Modeler does show revision information for folders. When creating a new folder using this endpoint, a file.tsfoldermeta is required next to the folder. Best is to use the Modeler for this.

• Modeler accesses tags by a timestamp and branch information. When creating a new tag using thisendpoint, you must add a Git note with necessary information to the tag. Best is to use the Modeler for this.

• Modeler can only handle certain entries in its own order for .gitignore files. Do not edit this file yourself.

• Some files can not be merged using a textual merge, as those might get invalid. Those can only be mergedusing the Modeler. In order to prevent a textual merge, those files are marked as binary.

• Adapt the git config settings to Model Hub conventions:

• "user.name" is the "name" attribute as shown in your profile.

• "user.email" is the "username" attribute as shown in your profile, appended with @modelhub.internal.

3.5. Engine

Multiple Engines can connect to Model Hub.

3.6. REST Endpoint

REST calls require authentication using OAuth 2.0 with Access Token. The token can be generated e.g. with thePostman Application.Table 3.1. Required values for the Postman Dialog "Get new access token"

Property Value

Token Name

Grant Type Password Credentials

Access Token URL https://localhost:8080/security/oauth/token

Username

Password

Client ID actico-model-hub

Client Secret (empty)

Scope openid profile email

Client Authentication Send Basic Auth header

https://www.getpostman.com/https://localhost:8080/security/oauth/token

Chapter 4. Installation and Configuration



4.1. Unpack

Unzip the file model-hub-application.zip.

The app folder contains:

• the binary file of the application

The config folder contains:

• the application-model-hub.properties file that is used to store configuration settings

• the log4j2.xml file that is used to configure the logging

• the actico.keys properties file containing private keys (must be kept confidential!). It is created when theapplication starts the first time.

The bin folder contains preconfigured start and stop scripts.

The data, logs and work folders are created when the application starts. They contain dynamic content.

All resources in the config folder are automatically on the classpath of the application. Placeadditional files, like JDBC driver JAR files, in the config/lib directory.

4.2. Java Runtime

Model Hub requires a Java runtime to be available in the java folder of the installation. If this folder is emptyand the Model Hub installation is part of an ACTICO Platform installation, the Java runtime defined for theACTICO Platform is used. If the java folder of the installation is empty and no ACTICO Platform Java installationwas found the environment variable JAVA_HOME is used.

Make sure the Java version matches with the System Requirements

4.3. License File

Copy your obtained license file to one of the following folders:

• /.actico/license

• /config/license

In case you like to rename the license file, make sure the filename starts with license and ends with thesuffix .txt.

4.4. Configuration

The file config/application-model-hub.properties is used to configure the Model Hub. The specificconfiguration settings are described in the next chapters. All changes to this file necessitate a restart of ModelHub. Only then changes are picked up.

4.5. Team Server Compatibility Mode

Model Hub can be run in Team Server Compatibility Mode.



Set this only once at installation time. It must not be changed later once there is already datacreated.

This mode can be enabled by adding the following setting:

actico.model-hub.teamserver-compatibility-mode=true

4.6. Users

4.6.1. Users

Each user is assigned to a user group by default. This user group can be configured using the following setting:

# Default user group name assigned to users that login the first timeactico.permission-management.default-user-group=Standard Users

4.6.2. Default Administrators

In order to initially setup the Model Hub installation, at least one User with administrative privileges isnecessary. At startup Model Hub creates a default admin user group which will include all permissions.Additionally, all default admin users are assigned to this user group.

# Default administrator user group containing all permissions

actico.permission-management.default-admin-user-group=Administrators 1

# Subjects of default admin users (comma separated). Use id of created keycloak users if Open ID Connect is used.# These users are automatically assigned to the user group 'default-admin-user-group'.

actico.permission-management.default-admin-users=Admin 2

1

defines the default admin user groups name2

defines the users which are created and assigned to this group

These users and user groups will be created at each startup, if they do not yet exist! This meansif you 'lock out' your administrative users by unassigning user groups or permissions, a restart ofthe application will re-privilege your default admin users.

4.6.3. Super Administrators

Users with super administrative privilege have automatically all permissions and can access all data. Thisincludes the login permission application.login. To grant a user super administrative privilege, add it tothe following setting in config/application-model-hub.properties:

# List of users, who get super-admin privileges (comma separated)actico.security.authorization.super-admins=SuperAdmin

If the rare case arises that a user cannot access an entity and no other user can assignpermissions to this user in order to access the entity, a common solution is to temporarily add anadministrator user to the super administrator list in order to assign the privilege. Afterwards theadministrator should be removed from the list. The application needs to be restarted for thesechanges to take effect.

4.6.4. Internal Technical User

For some tasks the Model Hub uses an internal technical user with the id System. The System user is notallowed to log in and does not need to be configured in external authentication providers.



4.7. Authentication

Authentication of users can be done against a LDAP Server, Active Directory or any Open ID Connectauthentication system.

Authentication of other technical components is done with technical users and API keys.

A user is registered (and is then available e.g. to assign permissions) within Model Hub in one ofthe following cases:

• user logs in

4.7.1. Active Directory / LDAP

Steps:

• Add the following properties to config/application-model-hub.properties

• Change values specific to your environment

# The authentication provider typeactico.security.authentication.provider-type=LDAP

# configure User handling## The LDAP filter used to search for users. For example "(uid={0})" or "(sAMAccountName={0})".actico.security.authentication.ldap.user-search-filter=(uid={0})## Search base for user searches.actico.security.authentication.ldap.user-search-base=

## User Attribute Mapping (optional)## The user ID mapping. For example "uid" or "sAMAccountName".#actico.security.authentication.ldap.user-attribute-mapping.userId=uid#actico.security.authentication.ldap.user-attribute-mapping.fullName=cn#actico.security.authentication.ldap.user-attribute-mapping.familyName=sn#actico.security.authentication.ldap.user-attribute-mapping.givenName=givenName#actico.security.authentication.ldap.user-attribute-mapping.preferredUsername=displayName#actico.security.authentication.ldap.user-attribute-mapping.email=mail

# JWT Token Configurationactico.security.authentication.jwt.access-token-validity-seconds=600actico.security.authentication.jwt.refresh-token-validity-seconds=1800

Additionally, an external Active Directory / LDAP Server or an Embedded LDAP Server must be configured asdescribed in the following chapters.

4.7.1.1. External Active Directory / LDAP

See also chapter Troubleshooting Active Directory / LDAP Configuration for troubleshooting tips.

In case you want to link multiple external Active Directories with different domains to ModelHub, we recommend using Keycloak. See appendix Using Keycloak as external OpenID Connectauthentication provider and https://keycloak.org for more information.

Steps:

• Add the following properties to config/application-model-hub.properties in addition to theproperties defined in chapter Active Directory / LDAP.


https://keycloak.org



actico.security.authentication.ldap.manager-dn=cn=admin,dc=actico,dc=comactico.security.authentication.ldap.manager-password=actico.security.authentication.ldap.url=ldap://localhost:389/dc=actico,dc=com

## If set to true, a subtree scope search will be performed below the group search base. If false a single-level search is used. Default is false.actico.security.authentication.ldap.search-subtree=false

4.7.1.2. Embedded LDAP

In order to use an included embedded LDAP server follow these steps:

• Add the following properties to config/application-model-hub.properties in addition to theproperties defined in chapter Active Directory / LDAP.


actico.security.authentication.ldap.base-dn=dc=actico,dc=comactico.security.authentication.ldap.ldif=classpath:embedded-ldap-demo.ldif

• Change the embedded-ldap-demo.ldif file to your needs. It is stored in the config folder.

Be aware that passwords can only be changed by editing this file.

Be aware that these passwords are stored in clear text when using the embedded LDAP.

Be aware that advanced password policies like maximum login retries are not supported.

4.7.2. Open ID Connect

Model Hub supports OpenID Connect providers that have the Authorization Code Flow and Resource OwnerPassword Flow enabled. It also requires the client scopes openid, email, profile to be enabled. (The scopeopenid may be implicit on your server).

Steps:

• Add the following required properties to config/application-model-hub.properties


actico.security.authentication.provider-type=EXTERNAL_OIDC# URI that can either be an Open ID Connect discovery endpoint or# an OAuth 2.0 Authorization Server Metadata endpoint defined by RFC 8414spring.security.oauth2.resourceserver.jwt.issuer-uri=

4.7.2.1. Optional Properties

Client ID

The client id can be configured, if the default is not possible (actico-model-hub):

actico.security.authentication.oauth2.client-id=



Client Secret

An optional client secret can be specified (avoid enabling a client secret on your authentication server, ifpossible). It will be sent on every token request to the OIDC server (parameter client_secret):

actico.security.authentication.oauth2.client-secret=

Access token URI

The access token URI can be configured, if the default is not possible (default is${spring.security.oauth2.resourceserver.jwt.issuer-uri}/protocol/openid-connect/token):

actico.security.authentication.oauth2.access-token-uri=

4.7.2.2. User Attribute Mapping Properties

Different Open ID Connect authentication servers may have a different set of user attributes. Model Hubsupports defining the mapping between the values used in Model Hub and the values provided by theauthentication server. The following properties can be defined, copy them to your configuration properties,uncomment and change the values accordingly:

## User Attribute Mapping for provider-type=EXTERNAL_OIDC (optional)#actico.security.authentication.external-oidc.user-attribute-mapping.userId=preferred_username#actico.security.authentication.external-oidc.user-attribute-mapping.preferredUsername=preferred_username#actico.security.authentication.external-oidc.user-attribute-mapping.fullName=name#actico.security.authentication.external-oidc.user-attribute-mapping.familyName=family_name#actico.security.authentication.external-oidc.user-attribute-mapping.givenName=given_name#actico.security.authentication.external-oidc.user-attribute-mapping.email=email

4.8. Authorization

Model Hub supports externally defined user groups. When a user logs in, these external definitions are readand Model Hub will automatically create missing user groups. The user is automatically assigned to theprovided user groups. Existing user group assignments are removed if not provided any more. Model Hubdistinguishes between externally defined user groups and manually created user groups. If a manually createduser group has the same name as an externally defined, the manual created user group has precedence.Manual assigned user groups are not unassigned from a user. Automatically created user groups are neverdeleted.

In order to enable externally defined user groups the following steps must be performed:



# Synchronize externally defined user groups (LDAP: groups, OIDC: roles) as user groups# (default value: false)actico.permission-management.external-user-groups.enabled=true

# Inclusion filter regular expression applied to user group name. Only matched user group names are synchronized# Examples:# - no user group is synchronized# .* - all user groups are synchronized (this may be many user groups)# (default value: )actico.permission-management.external-user-groups.inclusion-filter=.*

Only user groups matching the inclusion filter regular expression are synchronized.



Depending on the used authentication provider additional steps are necessary:

4.8.1. Active Directory / LDAP

Groups defined by an Active Directory / LDAP server can be synchronized as user groups with Model Hub.

Steps:



# Search base for group searches.actico.security.authentication.ldap.group-search-base=ou=groups

# Finding groups based on uniqueMember attribute at group objectactico.security.authentication.ldap.group-search-filter=(&(objectClass=group)(member={0}))

# Extensible match rule: find all groups where specified user is a member of including nested groups# actico.security.authentication.ldap.group-search-filter=(member:1.2.840.113556.1.4.1941:={0})

# Attribute of group nameactico.security.authentication.ldap.group-role-attribute=sAMAccountName

## If set to true, a possibly occurring PartialResultException is ignored. This may occur if an Active Directory server is used. Default is false.actico.security.authentication.ldap.ignore-partial-result-exception=true

4.8.2. Embedded LDAP

Groups defined by the embedded LDAP server can be synchronized as user groups with Model Hub.

Steps:


# Search base for group searches.actico.security.authentication.ldap.group-search-base=ou=groups

# Finding groups based on uniqueMember attribute at group objectactico.security.authentication.ldap.group-search-filter=(&(objectclass=groupOfUniqueNames)(uniqueMember={0}))

# Attribute of group nameactico.security.authentication.ldap.group-role-attribute=cn

4.8.3. Open ID Connect

Roles defined by an Open ID Connect server can be synchronized as user groups with Model Hub.

Steps:



The following example uses the KeyCloak default: realm_access.roles

# JSON path to roles defined by OpenID Connect provider. Used to map externally defined roles to user groups.actico.security.authentication.external-oidc.external-authorities-path=realm_access.roles



4.9. Database

4.9.1. Roles and Permissions

Model Hub uses database tables, indexes, unique constraints and foreign key constraints. Technical row IDsare calculated using Identity column types.

Ensure that a database user with sufficient roles and privileges is available in order to create these databasestructures. Since Model Hub includes an automatic Schema update feature, the configured database user musthave sufficient roles and privileges to execute DDL statements.

4.9.2. Restrictions

Microsoft SQL Server needs to be configured with case insensitive collation (CI) and IsolationLevel READ_COMMITTED_SNAPSHOT.

4.9.3. Connection

Steps:

• Download JDBC database driver from vendor’s website

• Copy JDBC database driver to config/lib



spring.datasource.url=jdbc:...spring.datasource.username=spring.datasource.password=spring.datasource.driver-class-name=

In case of MySQL, also add the following property to config/application-model-hub.properties:

spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL55Dialect

Make sure the database version matches with the System Requirements

A complete listing of example configuration settings for supported databases can be found in theappendix.

4.9.4. Schema Deployment

4.9.4.1. Automatic Deployment

On startup the application will automatically install or upgrade the database schema.

Please ensure that the configured data user has sufficient roles and privileges to perform DDLoperations for used database resources.



4.9.4.2. Manual Deployment with sqldump

If it is necessary to manually initialize or upgrade a database schema, the sqldump command can be used.Running

start-app sqldump --file=

will dump the SQL statements into the specified file. Executing them will deploy a schema the same way theautomatic deployment would.

The sqldump needs to connect to the database in order to detect the changes that are necessary.

4.10. Server

Model Hub uses an embedded web server to host the web application and endpoints (e.g. REST). The settingsare already preconfigured, but may need to be adjusted.

In order to configure the embedded web server to your requirements add settings starting withserver.tomcat to the config/application-model-hub.properties file. A complete list of settings canbe found at Spring Boot Application Properties.

4.10.1. Common Settings

Common configuration settings are:

# Limits the size of http post requests to a maximum number of bytesserver.tomcat.max-http-post-size=104857600

Add these settings to config/application-model-hub.properties if necessary and configure theirvalues.

Model Hub does not support custom context roots. See also chapter ??? setup.

4.10.2. SSL - Server

This section describes the configuration of SSL for the embedded server.

HTTP is enabled by default.

In order to use HTTPS instead of HTTP a keystore with a SSL certificate is required. For a test and productionenvironment a SSL certificate issued by an official authority is recommended. For a development or demoenvironment a self signed SSL certificate may be sufficient.

The following command line uses the Java keytool and creates a keystore with filename keystore.p12 with aPKCS12 SSL certificate having a validity of 1 year. Use the server IP address or hostname as CN (Common Name)of the certificate (i.e. localhost or mycompany.com) which will be used to connect to the server. Otherwisethe SSL hostname verification will fail.

keytool -genkey -alias model-hub -storetype PKCS12 -keyalg RSA -keysize 2048 -keystore keystore.p12 -validity 365

If it is no option to use the IP address or hostname as CN, it can be defined as a Subject Alternative Name. Thefollowing command line uses Java keytool and creates a keystore with filename keystore.p12 with a PKCS12SSL certificate having a validity of 1 year. Additionally the hostname is specified as a Subject Alternative Name.An IP address can also be specified this way.

keytool -genkey -alias model-hub -storetype PKCS12 -keyalg RSA -keysize 2048 -keystore keystore.p12 -validity 365 -ext san=dns:localhost

https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html



Steps:

• Create keystore with SSL certificate

• Place keystore file in the config folder

• Add the following SSL related properties to config/application-model-hub.properties andconfigure them accordingly

Configure SSL related properties:

# SSL Connector portserver.port=8443# Allow only HTTPS requestssecurity.require-ssl=true

# Whether to enable SSL supportserver.ssl.enabled=true# Alias that identifies the key in the key storeserver.ssl.key-alias=model-hub# Password used to access the key in the key storeserver.ssl.key-password=# Path to the key store that holds the SSL certificate (typically a PKCS12 file)server.ssl.key-store=classpath:keystore.p12# Password used to access the key storeserver.ssl.key-store-password=# Type of the key store (JKS/PKCS12)server.ssl.key-store-type=PKCS12

If the above configuration is used, the HTTP connector of the embedded server is disabled.

4.10.3. SSL - Client

This section describes the configuration of SSL for embedded HTTP clients.

The platform components are using embedded HTTP clients connecting to HTTP servers of other componentsof the ACTICO Platform. If SSL is configured for an HTTP server, the connecting embedded HTTP client must alsobe configured for SSL.

In order to configure the embedded HTTP client to connect to a server that uses SSL, the certificate of theserver must be trusted by the JVM the embedded client uses.

Steps:

• Get the SSL certificate of the server

• Import the SSL certificate into the truststore of the JVM the embedded client is executed in

The following command line uses the Java keytool to export a certificate from a keystore to a file namedserver.cert.

keytool -exportcert -alias model-hub -keystore keystore.p12 >> server.cert

The following command line uses the Java keytool to import a certificate named server.cert to the JVMtruststore.

keytool -import -alias model-hub -keystore /jre/lib/security/cacerts -file server.cert

Ensure that the SSL embedded client uses the hostname or IP address that was used as CN duringSSL certificate creation. Or alternatively ensure that the hostname or IP address of the SubjectAlternative Name is used that was specified during SSL certificate creation.



4.10.4. Custom HTTP Response Headers

By default, a set of predefined HTTP headers are sent with each server response. They have been designed toprovide the best security options without limiting the usability of Model Hub.

Through the configuration, some of these headers can be customized to a specific environment and securityneeds.

Customizing the predefined headers is not recommended, unless there is a specific need to doso. Keep in mind that customizing the response headers may affect the operation and security ofModel Hub.

4.10.4.1. Defining a custom header

A custom header can be defined with the following property syntax:

actico.server.http.response-headers[Custom-Header-Name]=Custom Header Value

The Custom-Header-Name is the name of the header and the Custom Header Value the value for thatheader. (The square brackets are part of the property definition). Multiple headers can be defined: just addanother configuration entry.

4.10.4.2. Predefined Security Headers

The following security headers are predefined and can be modified.

actico.server.http.response-headers[Content-Security-Policy]=default-src 'self'; style-src 'self' 'unsafe-inline'actico.server.http.response-headers[X-Permitted-Cross-Domain-Policies]=noneactico.server.http.response-headers[Expect-CT]=max-age=86400, enforceactico.server.http.response-headers[Referrer-Policy]=no-referrer

Default headers can be disabled by setting an empty value. For example, to disablethe Expect-CT header from being returned by the server, set it to an empty value:actico.server.http.response-headers[Expect-CT]=

The Content-Security-Policy header has a different default, when using an external OIDC Provider(actico.security.authentication.provider-type=EXTERNAL_OIDC). In that case, the protocol, hostand port of the external authentication provider will be added to the header value, e.g.:

actico.server.http.response-headers[Content-Security-Policy]=default-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' http://localhost:8091

The Content-Security-Policy header requires to have the unsafe-inline modifier for thestyle-src directive to support Angular-based applications, like Model Hub. Angular usesinline style elements. See GitHub Issue 37631. Despite the 'unsafe' keyword our default Content-Security-Policy header is significantly more secure than having no header set.

You can find descriptions and more details about the default security headers on Mozilla Developer Networkweb docs.

4.10.5. Connection Pool

By default the Hikari Connection Pool is included in Model Hub and used with default settings. To configurethe Hikari Connection Pool specific to your needs add settings starting with spring.datasource.hikari tothe config/application-model-hub.properties file. A complete list of settings can be found at HikariConfiguration.

Common Hikari configuration settings are:

https://github.com/angular/angular/issues/37631https://developer.mozilla.org/en-US/docs/Web/HTTP/Headershttps://developer.mozilla.org/en-US/docs/Web/HTTP/Headershttps://github.com/brettwooldridge/HikariCP#configuration-knobs-babyhttps://github.com/brettwooldridge/HikariCP#configuration-knobs-baby



# Maximum number of milliseconds that a client will wait for a connectionspring.datasource.hikari.connectionTimeout=30000# Maximum amount of time in milliseconds that a connection is allowed to sit idle in the poolspring.datasource.hikari.idleTimeout=600000# Maximum lifetime in milliseconds of a connectionspring.datasource.hikari.maxLifetime=1800000# Minimum number of idle connectionsspring.datasource.hikari.minimumIdle=10# Maximum size of connections (idle plus in-use connections)spring.datasource.hikari.maximumPoolSize=10

4.11. Script Environment

Model Hub comes with a preconfigured set of shell scripts that can be used to configure, start, stop, install anduninstall the server.

4.11.1. Startup

On a Windows system use the start-app.bat and stop-app.bat scripts for this purpose. On a Linux systemuse the start-app.sh and stop-app.sh scripts.

In a production environment it is recommended to install the application as a system service. On a Windowssystem use the install-service.bat file to install Model Hub as a service and use start-service.bator any operating system mechanism to start the service.

4.11.2. Shutdown

Always properly shutdown Model Hub. This is important for files to be closed. If the application was startedwith start-app.bat or start-app.sh it should be stopped with stop-app.bat or stop-app.sh.

If the Model Hub was installed as a Windows service, the stop-service.bat file or any operating systemmechanism to stop a service normally can be used.

Background Information:

• Model Hub is looking for a stop file actico.jvm.stop that is created in the work folder with aconfigured filename. If the file is detected, the application will initiate the shutdown process and willterminate. The stop flag file is configured using the --actico.stopfile command line argument.The --actico.stopfile.initsleep command line argument can be used in order to specify asleep time in seconds. The application waits for this duration until it looks for a stop flag file. Usethis argument to prevent a shutdown during the startup phase of the application. Finally the --actico.stopfile.jvmshutdown command line argument can be used to simply create the stop flag file,that signals an already running JVM to terminate.

• Use the --actico.stopfile and --actico.stopfile.initsleep command line arguments for theModel Hub itself.

• Use the --actico.stopfile and --actico.stopfile.jvmshutdown command line argumentsto initiate the termination of an already running Model Hub. Note that the stop flag file handling ispreconfigured in all provided scripts.

4.11.3. Configuration

In order to temporarily pass parameters to Model Hub just specify them after the start-app.bat or start-app.sh script.

Example: start-app.bat myParameter

If a specific configuration of Model Hub is necessary or parameters should be permanently specified, create afile config.bat or config.sh in the config folder. Use this file in order to add or overwrite environmentvariables and parameters defined by the bin\windows\config.bat or bin/unix/config.sh file. It will beevaluated after the config.bat or config.sh file in the bin folder.



A created custom config.bat or config.sh file is also used during the installation as Windows Service orUnix Service.

Use the following environment variables to add or overwrite settings:

• JAVA_HOME: Defines the JAVA_HOME directory. Note: A JDK or JRE in the java folder of the platform orproduct is automatically detected. Example for Windows: set "JAVA_HOME=C:\Programme\Java"

• JVM_XMS: Defines the heap size in MBytes. Example for Windows: set "JVM_XMS=128"

• JVM_XMX: Defines the maximum heap size in MBytes. Example for Windows: set "JVM_XMX=2048"

• JVM_XSS: Defines the stack size in kBytes. Example for Windows: set "JVM_XSS=4000"

• JVM_OPTIONS: Defines the JVM options. Note: For Windows use a semicolon to separate multiple settingsand use § to enclose paths which may contain spaces. For Linux use a space to separate multiple settingsand use \" to enclose paths which may contain spaces. Example for Windows: set "JVM_OPTIONS=%JVM_OPTIONS%;-Djavax.net.ssl.trustStore=myTrustStore"

• JVM_OPTIONS_APP: Defines additional JVM options if started as application. Note: For Windows use asemicolon to separate multiple settings and use § to enclose paths which may contain spaces. For Linux usea space to separate multiple settings and use \" to enclose paths which may contain spaces. Example forWindows: set "JVM_OPTIONS_APP=-ea"

• JVM_OPTIONS_SERVICE: Defines additional JVM options if started as service (only supported for Windows).Note: For Windows use a semicolon to separate multiple settings and use § to enclose paths which maycontain spaces. Example for Windows: set "JVM_OPTIONS_SERVICE=-verbose"

• CLASSPATH: Defines the classpath of the application. Note: For Windows use a semicolon to separatemultiple settings. For Linux use a colon to separate multiple settings. It is not recommended to overridethis environment variable as auto detection and auto configuration will be disabled. Just add new resourcesif they cannot be stored in the config or config/lib folder. Example for Windows: set "CLASSPATH=%CLASSPATH%;C:\libs\myLib.jar"

• START_PARAMS: Defines parameters for the started application. Note: For Windows use asemicolon to separate multiple settings and use ^ as escape character for " characters that definepaths. For Linux use a space to separate multiple settings and use \ as escape character for "characters that define paths. Example for Windows: set "START_PARAMS=%START_PARAMS%;--spring.profiles.active=production

• STOP_PARAMS: Defines parameters for the application that initiates the stop of a application. Note: ForWindows use a semicolon to separate multiple settings and use ^ as escape character for " charactersthat define paths. For Linux use a space to separate multiple settings and use \ as escape character for "characters that define paths.

Example additional config.bat file stored in the config folder:

@echo offrem Custom configuration file defining maximum heap size,rem a custom trust store and an additional Spring Boot profile.set "JVM_XMX=4096"rem Using already set JVM options and add a new oneset "JVM_OPTIONS_APP=%JVM_OPTIONS_APP%;-Djavax.net.ssl.trustStore=§%ACTICO_COMPONENT_HOME%\config\myTrustStore§"rem Using already set start parameters and add a new oneset "START_PARAMS=%START_PARAMS%;--spring.profiles.active=production"exit /B 0

Example additional config.sh file stored in the config folder:

#!/bin/bash# Environment configuration file defining maximum heap size,# a custom trust store and an additional Spring Boot profile.JVM_XMX="4096"# Using already set JVM options and add a new oneJVM_OPTIONS_APP="$JVM_OPTIONS_APP -Djavax.net.ssl.trustStore=\"$ACTICO_COMPONENT_HOME/config/myTrustStore\""# Using already set start parameters and add a new oneSTART_PARAMS="$START_PARAMS --spring.profiles.active=production"



4.11.3.1. Special Configuration Modes

The script environment supports additional configuration modes for the application. A configuration modeadds additional settings to environment variables that were preconfigured by the config.bat or config.shscript. To add a new configuration mode create a new file with the following filename schema: config-.bat. Configure the settings inside the created file. The file will be executed automatically if youpass as a command line argument for a script file (e.g. start-app ). Note that thismechanism works for start and stop scripts of the application.

Example additional config-debug.bat file, enabling debugging and stored in the config folder:

@echo offrem Environment configuration file for mode "debug".set "JVM_OPTIONS_APP=%JVM_OPTIONS_APP%;-Xdebug;-Xrunjdwp:server=y,transport=dt_socket,address=8778,suspend=n"exit /B 0

Example additional config-debug.sh file, enabling debugging and stored in the config folder:

#!/bin/bash# Environment configuration file for mode "debug".JVM_OPTIONS_APP="$JVM_OPTIONS_APP -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8778,suspend=n"

4.11.4. Install as Windows Service

Model Hub also contains preconfigured scripts to install, start, stop and uninstall the application as a Windowsservice. Use the install-service.bat, start-service.bat, stop-service.bat and uninstall-service.bat scripts for this purposes. The Windows Service can also be started and stopped using anyoperating system mechanism.

4.11.5. Install as Unix Service

Model Hub can also be installed as a Unix service.

• Create a file /etc/systemd/system/actico-model-hub.service

• Paste the following content into that file

[Unit]Description=Model Hub

[Service]Type=simpleUser=rootEnvironment=JAVA_HOME=/usr/lib/jvm/jreExecStart=/actico/actico-model-hub/bin/unix/start-app.shExecStop=/actico/actico-model-hub/bin/unix/stop-app.sh

[Install]WantedBy=multi-user.target

• Adopt the example settings to your installation:

• User: The user id under which the application is started.

• Environment=JAVA_HOME: Points to the Java jre installation. If you are using a dedicated Javainstallation inside your Model Hub, you can remove this line. See also chapter Java Runtime.

• ExecStart: Points to the Unix start script of your Model Hub installation.

• ExecStop: Points to the Unix stop script of your Model Hub installation.

• Enable the new service (required only once):



• sudo systemctl enable actico-model-hub

From here, Model Hub will start automatically, when the system boots. You can use these commands to controlthe service:

• Manually stop, start, restart and check the service:

• sudo systemctl stop actico-model-hub

• sudo systemctl start actico-model-hub

• sudo systemctl restart actico-model-hub

• sudo systemctl status actico-model-hub

• Show the service log:

• sudo journalctl -u actico-model-hub

4.12. Maven Repository Connection

Libraries can be added to Model Hub by either uploading them via the web user interface or by retrievingthem from a maven repository. Add the following configuration to the config/application-model-hub.properties to enable the connection to a maven repository:

# Enables Model Hub to retrieve libraries from# maven repositories that are specified in the# configured maven settings fileactico.repository.maven.settings=

Example for a path on Windows: file:C:/apache-maven/settings.xml

The settings.xml is a standard maven settings file. Maven itself does not need to be installed.

4.13. Clustering

Clustering of multiple Model Hub instances is not supported.

Chapter 5. Operations and Maintenance



5.1. Temporary directories

The following temporary directories are used:

• the logs folder contains log files.

• the work folder contains the embedded web server’s temporary files.

5.2. Backup and Restore

A backup must contain both database and file system data.

Backing up and restoring the database and file system should be closely spaced in time to keep them in sync.Reason is e.g. when creating a new module, an entry is stored in the database and a git repository is createdwithin the file system.

It is recommended that backups be made either by previously shutting down the server or during a more orless inactive period. This will ensure that most file handles for the git repository are closed and that all data isincluded in the backup.

5.2.1. Database

Please refer to the database provider’s user manual.

5.2.2. File system folders

The data folder contains mainly the model versioning repositories that require to be included in a backup.

Also the config folder needs to be included in the backup as it may contain specific configuration files andspecific configuration settings.

5.3. Logging

Model Hub uses Apache Log4j 2 by default and comes with a default log4j2 configuration available in theconfig directory.

The default configuration has been designed for production usage and provides the following settings:

• Log to console AND file

• Log errors to separate error log file

• Maximum size for log files: 10MB

• Maximum number of roll-over files: 20

• Files exceeding 10MB are zipped and placed in a archive directory next to the log file

• Maximum amount of zipped files to be kept: 20

These settings result in a maximum usage of about 70MB of disk-space consumed for log files.

5.3.1. Log Levels

Log levels can be configured in config/application-model-hub.properties (restart of server required)OR in config/log4j2.xml

https://logging.apache.org/log4j/2.x/



Examples configuring log levels in config/application-model-hub.properties:

# Log level configuration# Example to enable debug logging for a part of the applicationlogging.level.com.actico.repository=DEBUG

Examples configuring log levels in config/log4j2.xml:

...

5.3.1.1. Custom log4j2 configuration

Custom log4j2 configurations should only be considered, when the default logging appenders are not sufficientor required to be changed.

If a custom log4j2 configuration is desired, for example to configure custom appenders, create your ownlogging file by copying the existing log4j2.xml and place it in the config directory. Afterwards activate theconfig in config/application-model-hub.properties:

The following config shows how to activate a custom log4j2-custom.xml for logging.

# Enable log4j2 custom configuration, if required. See operations guide for details.logging.config=${actico.component.home}/config/log4j2-custom.xml

Configuring your own log4j2 configuration can affect the standard behavior of the product andimpede maintenance and support.

5.4. Monitoring

To monitor the application, Spring Boot’s Actuator Web API is enabled. The actuator endpoints can be accessedat http://localhost:8080/actuator/.

Please check the Spring Boot Actuator Web API documentation for further information.

5.4.1. Endpoints

All actuator endpoints are enabled, here is a short list of some of them. The complete list can be seen at SpringBoot Actuator Endpoints documentation.

• info - Display application name and version

• health - Display health status of application (database, disk space)

• env - Display property environment configuration

• configprops - Display configuration settings

• threaddump - Display current thread dump

• metrics - Display application metrics

• logfile - Display the log file

• prometheus - Data source for the Prometheus monitoring solution

http://localhost:8080/actuator/https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.htmlhttps://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.htmlhttp://prometheus.io



The endpoints require authentication. Either basic authentication, or OAuth2 token based authentication. Anauthenticated user must also have the configured authority (default: application.metrics). The authoritycan be configured with the actico.security.permission.actuator-endpoints-authority property.

See Chapter "REST Endpoints" how to authenticate using token based authentication.

The endpoints actuator/info and actuator/health do not require authentication orauthorization by default and therefore are suited best to be used for monitoring.

Chapter 6. Technical Limitations


Chapter 6. Technical LimitationsThe following listing shows technical limitations of the product:

Component Limitation Comment

Model Hub Versioning Maximum allowed file size tocommit: 20MB

Prevent long-term performanceproblems with Git repositories.

Chapter 7. Connecting Engines


Chapter 7. Connecting Engines

7.1. Engines

When a Environment is created in the Model Hub user interface, automatically a technical user is created. Thistechnical user can be used by Engines to connect with Model Hub. The technical user id for an engine has thefollowing format:

Environment-

To generate the API Key for the technical user, select an Environment, go to the Settings tab and click onGenerate New API Key. After confirming with the Environment ID and clicking on Generate New API Key buttonthe API Key for the technical user is created and stored. Copy this API Key, as it cannot be displayed anymore,and configure the Engines for the choosen Environment in the properties file of the engine:

actico.execution.server.environment-identifier=actico.execution.server.environment-api-key=

The Engine will automatically add the Environment- prefix and has a built in check if theconfigured API Key matches the configured Environment ID. If not matching, the Engine will notcommunicate with Model Hub.

7.2. API Key Authentication

To connect technical components (i.e. Engines) with Model Hub, API Key authentication is used. A technicalcomponent needs a technical user which is managed by Model Hub. A technical user is stored in the configuredModel Hub database. The Model Hub user interface provides the ability to generate an API Key for a technicaluser. An API Key is used as HTTP Authorization Header:

ApiKey

The Api Key is a base 64 encoded string built from the technical user id and a randomly created key. The '~'character is used as separator.

~

Model Hub uses the BCrypt algorithm to securely encode the randomly created key. The encodedkey is stored in the configured Model Hub database. Once created, encoded and stored, ModelHub does not know the formerly created key but is able to authenticate incoming authenticationrequests.

It is not necessary to configure technical users in external authentication systems.

Always use SSL/HTTPS when using API Key authentication. Otherwise the API Key may be sniffedand reused by others.

If SSL/HTTPS is configured for an Engine ensure that the JVM that is used by Model Hub, trusts theSSL server certificate of the Engine server (e.g. execution server).

Appendix A. Migrations



A.1. Migration from Team Server

A.1.1. Introduction

Supported Team Server versions for the migration are 6.7 and 6.8.

Be aware about naming and other changes during migration. Changes are:

• Some characters in tags and branches are replaced:

• Spaces will be replaced with underscore (e.g. My Branch → My_Branch)

• German umlauts will be replaced (e.g. Ä → Ae)

• Branch HEAD will be named master

• Empty branches will not be migrated

• Empty tags will not be migrated

The migration is described for Windows. If you use Linux, please use the start-app.sh insteadof start-app.bat.

A.1.2. Migration Steps

1. Export and download the requested repository from Team Server (see Team Server documentation)

2. Generate user mapping

a. Export users from Identity Management (IM) by executing the following URLs in the browser and savethe XML file. The first link is for active users, the second to get deleted users.

http://://1/rest/users?offset=0&limit=200

and

http://://1/rest/users?offset=0&limit=200&showDeleted=true

The depends on the configuration of the Identity Management. Itcan be picked from the value of the property imServerUrl of the property file im-webui.properties located on the Identity Management server. Most likely it is im orim-server

When browsing to the URL, the browser asks for credentials. Use \for the username field. Example: DEFAULT\Admin.

The user to export the data needs to have the role IM Administrator.

http://://1/rest/users?offset=0&limit=200http://://1/rest/users?offset=0&limit=200&showDeleted=truehttp://://1/rest/users?offset=0&limit=200&showDeleted=true



Figure A.1. Identity Management screen with Admin user

The downloaded XML file contains an entry . If this number exceeds 200 (themaximum number of users to be downloaded at once), the offset needs to be increased by 200 untilall users have been downloaded. Store all downloaded files in one folder.

Examples (local installation, for active users):

i. 1st set http://localhost:8087/im/1/rest/users?offset=0&limit=200

ii. 2nd set http://localhost:8087/im/1/rest/users?offset=200&limit=200

iii. 3rd set http://localhost:8087/im/1/rest/users?offset=400&limit=200

b. Create a mapping file with users referenced in the export

Make sure there is no Model Hub application running that was started with the samestart-app.bat script. Otherwise there might be conflicts in log files and otherresources. Recommendation is to use a separate installation.

Example Call with cmd.exe.

start-app.bat ts6-usermapping --im-user-mapping-directory="C:\mymigrations\im-users" --archive-file="C:\mymigrations\.zip" --output-directory="C:\mymigrations"

The --im-user-mapping-directory is the folder containg all downloaded users XML files. Thesecond parameter --archive-file is the Team Server export file. --output-directory specifiesthe location where the user mapping file mappings.csv is created.

c. Open the generated mappings.csv and edit if required. The users full names and the E-Mailaddresses will be used in the commit history of the Model Hub Git repository. The first columncontains the ID used by Team Server. If no mapping like E-Mail or full name is given, this ID (e.g.d30cf610-ffab-11e4-9f76-0242ac1102b3) will be used.

3. Start the migration itself

Make sure there is no Model Hub application running that was started with the samestart-app.bat script. Otherwise there might be conflicts in log files and other resources.Recommendation is to use a separate installation.

Example Call with cmd.exe.

http://localhost:8087/im/1/rest/users?offset=0&limit=200http://localhost:8087/im/1/rest/users?offset=200&limit=200http://localhost:8087/im/1/rest/users?offset=400&limit=200



start-app.bat ts6-migration --user-mapping-file="C:\mymigrations\mapping.csv" --archive-file="C:\mymigrations\.zip" --output-directory="C:\mymigrations"

The --user-mapping-file is the file containing the user information, created in the previous step. Thesecond parameter --archive-file is the Team Server export file. --output-directory specifies thelocation where the migrated repository will be created.

4. Rename the folder --output-directory/.git if you wish a different name.

5. Verify the migration by switching to the directory --output-directory/.git. Execute e.g. git log (git needs to be installed locally) to check thecommit history and verify if the user mapping is as expected.

6. Once the repository migration was successful, copy the migrated repository to the directory data\model-versioning\teamserver.

7. Within your browser, navigate to Repositories and press the button New Repository. Enter the nameof the migrated repository (without suffix .git). The migrated repository is now linked and can be used.Don’t forget to assign permissions to other users if required.

A.2. Migration from Execution Core

A.2.1. Introduction

Model Hub ships with a built-in commandline tool for migrating rule models from Execution Core basedproducts to Model Hub release format.

Supported products are:

• Workplace

• Execution Server

A.2.2. Background information

The tool works in a two-step manner:

• Ec6-Export

• Export artifact meta data and aggregated data as csv files for composing rule model bundles:

• EP_ARTIFACTS.csv (complete table EP_ARTIFACTS, artifacts meta data)

• EP_ARTIFACTS_DATA.csv (complete table EP_ARTIFACTS_DATA except column "data", artifactsbinaries meta data)

• EP_DEPENDENCIES.csv (complete table EP_DEPENDENCIES, artifacts dependencies data)

• REVISION_PER_GAV.csv (count of distinct group_id-artifact_id-version-revision in EP_ARTIFACTS)

• ROOT_MODEL.csv (contains list of rule models that has no incoming dependencies in EP_ARTIFACTS)

• UNIQUE_GROUP_ID.csv (contains list of unique group_ids in EP_ARTIFACTS)

• RM_RULE_MODEL_VERSION.csv (optional, only for Workplace, complete tableRM_RULE_MODEL_VERSION)

• Export artifact binaries as jar files with checksum as their filename, stored in subfolder jars

• Ec6-Migration



• Migrate the exported artifacts in Model Hub release format.

The Ec6-Export supports the following command line arguments:

Table A.1. Execution Core Export Command Line Arguments

Command line argument Description

ec6-export this is the mark to trigger the export

--db-user the username to connect to the execution core database

--db-password the password to connect to the execution core database

--db-driver-class-name the class name of the JDBC driver used to connect to the execution coredatabase

• Oracle: oracle.jdbc.OracleDriver

• SQLServer: com.microsoft.sqlserver.jdbc.SQLServerDriver

• MySQL: com.mysql.cj.jdbc.Driver

--db-url the jdbc connection url used to connect to the execution core database

--db-table-prefix the table prefix of the execution platform (EP) tables

• Workplace: X23_

• Execution Server: EP_ if default was used, or according to used prefix

If no prefix was used omit this argument.

--output-directory the directory to store the exported csv and jar files

--property-file (OPTIONAL) the path pointing to a property file that contains all parameters abovewithout the -- prefix. Place the property file in the config folder ofModel Hub.

Example contents of the property file for different databases:

# for Oracle Workplacedb-driver-class-name=oracle.jdbc.OracleDriverdb-url=jdbc:oracle:thin:@localhost:1521:ORCLdb-user=hrdb-password=hrdb-table-prefix=X23_output-directory=C:/outputdir/

## for SQLServer Workplacedb-driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriverdb-url=jdbc:sqlserver://localhost:1433;databaseName=workplacedb-user=sadb-password=yourStrong(!)Passworddb-table-prefix=X23_output-directory=C:/outputdir/

## for MySQL Execution Serverdb-driver-class-name=com.mysql.cj.jdbc.Driverdb-url=jdbc:mysql://localhost:3306/executionserverdb-user=VR_ESdb-password=vrdb-table-prefix=EP_output-directory=C:/outputdir/

The Ec6-Migration supports the following command line arguments:



Table A.2. Execution Core Migration Command Line Arguments

Command line argument Description

ec6-migration this is the mark to trigger the migration

--artifact-dir the path to the output-directory of the Ec6-Export

--output-dir the directory to store the exported release zip files

--property-file (OPTIONAL) the path pointing to a property file that contains all parameters abovewithout the -- prefix. Place the property file in the config folder ofModel Hub.

A.2.3. Ec6-Export steps

Remind that due to policy and regulation, the Ec6-Export does not include JDBC drivers. Thereforeyou have to download JDBC drivers and save them %ACTICO_COMPONENT_HOME%/config/lib inorder to be on the classpath.


Be aware that the export overwrites existing files!

1. Export the Execution Core data by using command line arguments or the property file:

a. Export by command line arguments:

Start the Model Hub Ec6-Export and specify the command line arguments accordingly:

start-app.bat ec6-export --dbUser= --dbPassword= --dbUrl= --db-table-prefix= --db-driver-class-name= --output-directory=

b. Export by property file:

Configure the settings in the property file and store it in the config folder of Model Hub.

Start the Model Hub Ec6-Export and specify the command line arguments accordingly:

start-app.bat ec6-export --property-file=

2. The export creates a log file ec6-export.log with information about the export. The file is storedbeneath the created csv files.

A.2.4. Ec6-Migration steps


1. Migrate the exported data by using command line arguments or the property file:

a. Migration by command line arguments:



Start the Model Hub Ec6-Migration and specify the command line arguments accordingly:

start-app.bat ec6-migration --artifact-dir= --output-dir=

b. Migration by property file:

Configure the settings in the property file and store it in the config folder of Model Hub.

Start the Model Hub Ec6-Migration and specify the command line arguments accordingly:

start-app.bat ec6-migration --property-file=

Example contents of the property file:

# ec6-migration argumentsartifact-dir=C:/outputdir/output-dir=C:/releaseOutputdir/

Appendix B. Example Servers



B.1. Using Keycloak as external OpenID Connect authentication provider

These installation instructions are only for demo usage.

B.1.1. Setup Keycloak

• Start the jboss/keycloak docker container

docker run -d --name -p 8091:8080 -p 8082:8081 -p 9091:9090 -e KEYCLOAK_USER= -e KEYCLOAK_PASSWORD= jboss/keycloak

• Configure the Model Hub client

• Login as keycloak_admin_username at http://localhost:8091

• (optional) Create a new Realm and switch to that Realm

• Create a client at clients → create with name actico-model-hub and client protocol openid-connect

• Access Type: public

• Valid redirect URIs: http://localhost:8080/*

• Web Origins: +

• Create a new user at Users → Add user

• Set the user’s credentials at tab Credentials

• Navigate to Realm Settings and open the OpenId Endpoint Configuration and note the issuervalue

• In Realm Settings select the Security Defenses tab. Click on Brute Force Detection andenable it. Set the Max Login Failures to 5. Set Permanent Lockout to ON

• Configure the Model Hub

• Add the following application properties and restart the Model Hub server:

actico.security.authentication.provider-type=EXTERNAL_OIDCspring.security.oauth2.resourceserver.jwt.issuer-uri=

B.2. Using LDAP as Authentication Provider

These installation instructions are only for demo usage.

B.2.1. Prepare Password Policy

• Create a password-policy.ldif file in a directory of your choice, e.g. c:\temp\password-policy.ldif

http://localhost:8091http://localhost:8080/*




# Load policy moduledn: cn=module{0},cn=configchangetype: modifyadd: olcModuleLoadolcModuleLoad: {0}ppolicy

# Configure password policy moduledn: olcOverlay=ppolicy,olcDatabase={1}{{ LDAP_BACKEND }},cn=configchangetype: addobjectClass: olcPPolicyConfigobjectClass: olcOverlayConfigolcOverlay: ppolicyolcPPolicyDefault: cn=default,ou=pwpolicies,{{ LDAP_BASE_DN }}olcPPolicyHashCleartext: TRUEolcPPolicyUseLockout: TRUE

B.2.2. Prepare User Data

• Create a openldap-demo.ldif file in a directory of your choice, e.g. c:\temp\openldap-demo.ldif




# create the group organizational unitdn: ou=groups,dc=actico,dc=comobjectclass: topobjectclass: organizationalUnitou: groups

# create the people organizational unitdn: ou=people,dc=actico,dc=comobjectclass: topobjectclass: organizationalUnitou: people

# create the admin userdn: uid=admin,ou=people,dc=actico,dc=comobjectclass: topobjectclass: personobjectclass: organizationalPersonobjectclass: inetOrgPersoncn: AdministratordisplayName: Administratormail:[email protected]: Adminuid: AdminuserPassword: Admin

# create demo userdn: uid=davaar01,ou=people,dc=actico,dc=comobjectclass: topobjectclass: personobjectclass: organizationalPersonobjectclass: inetOrgPersoncn: David AaronsdisplayName: David Aaronsmail:[email protected]: Aaronsuid: davaar01userPassword: davaar01

# create demo groupdn: cn=users,ou=groups,dc=actico,dc=comobjectclass: topobjectclass: groupOfUniqueNamescn: usersuniqueMember: uid=davaar01,ou=people,dc=actico,dc=comuniqueMember: uid=admin,ou=people,dc=actico,dc=com

# create the password policy nodedn: ou=pwpolicies,dc=actico,dc=comobjectClass: organizationalUnitobjectClass: topou: pwpolicies

# configure the password policydn: cn=default,ou=pwpolicies,dc=actico,dc=comobjectClass: topobjectClass: deviceobjectClass: pwdPolicycn: defaultpwdAttribute: userPasswordpwdLockout: TRUEpwdLockoutDuration: 0pwdMaxFailure: 5

B.2.3. Start LDAP Demo Server

Start the LDAP server using the following docker command. Change the location of the ldif file in case you didnot use c:\temp. This example assumes you run it on Windows.



docker run -d -p 389:389 -p 636:636 --name actico-openldap --env LDAP_ORGANISATION="Actico GmbH" --env LDAP_DOMAIN="actico.com" -v C:\temp\password-policy.ldif:/container/service/slapd/assets/config/bootstrap/ldif/password-policy.ldif -v C:\temp\openldap-demo.ldif:/container/service/slapd/assets/config/bootstrap/ldif/custom/openldap-demo.ldif osixia/openldap:1.2.5 --copy-service

B.3. Using MySQL as external database

These installation instruction are only for demo usage.

docker run -p 3306:3306 --name model-hub-mysql -e MYSQL_ROOT_PASSWORD=pw123 -e MYSQL_DATABASE=modelhub81 -e MYSQL_USER=testuser -e MYSQL_PASSWORD=my-secret-pw -d mysql:5.7.26

Appendix C. Troubleshooting



C.1. Troubleshooting Active Directory / LDAP Configuration

With the help of an external tool it might get more comfortable to configure Active Directory / LDAP properties.We recommend a Java based LDAP browser like http://jxplorer.org/. The screenshots in this chapter arecaptured with that tool.

In case you use SSL, make sure the Java runtime is configured the same way as the one used tostart Model Hub. This is especially important for configured certificates.

C.1.1. Authentication and Basic Settings

The required connection parameters for the example LDAP server are:

Those fields can be mapped to Model Hub properties:

Model Hub Property Value

actico.security.authentication.provider-type Always use "LDAP"

actico.security.authentication.ldap.url The url property requires the format ://:/

The protocol is "ldap" if the field Level in JXplorer isUser + Password.

The protocol is "ldaps" if SSL + User + Password isused.

The host, port and base dn are those used inJXplorer.

In this example the url is: ldap://localhost:389/dc=actico,dc=com

actico.security.authentication.ldap.base-dn The value of Base DN used in JXplorer.

actico.security.authentication.ldap.manager-dn The value of User DN used in JXplorer.

actico.security.authentication.ldap.manager-password

The value of Password used in JXplorer.

http://jxplorer.org/



C.1.2. User Search and Attribute Mapping

Those fields can be mapped to Model Hub properties (for user handling):

Model Hub Property Value

actico.security.authentication.ldap.user-search-base Defines the starting node in the LDAP tree to searchusers recursively. The value needs to be relative tothe base dn. It is recommended to reduce the treehierarchy to improve performance. Set to an emptyvalue to indicate to search below the complete basedn.

In this example the value can either be an emptystring. It can also be "ou=people", which isrecommended as the tree hierarchy is more specificand therefore faster

actico.security.authentication

Documents

ACTICO Platform - Model Hub · 2020. 7. 30. · ACTICO Platform - Model Hub Operations Guide Version 9.0.0