Configuration Store Setup Guide

Version 1.6

Corresponding Software Version

Celonis 4.3

This document is copyright of the Celonis SE. Distribution or reproduction are only permitted
by written approval of the Celonis SE. Usage only permitted, if a valid software license is
available.
TABLE OF CONTENTS

REVISION HISTORY ............................................................................................. 3

INTRODUCTION .................................................................................................. 4
ABOUT THIS GUIDE ................................................................................................................. 4
TARGET AUDIENCE ................................................................................................................. 4

LIST OF ABBREVIATIONS ..................................................................................... 5

SUPPORTED DATABASE SYSTEMS AND PREREQUISITES ..................................... 6
SETUP CONFIGURATION STORE.......................................................................... 7
STEP 1: STOP THE CELONIS APPLICATION SERVER ................................................................. 7
STEP 2 (MIGRATION ONLY): PREPARE MIGRATION................................................................ 7
STEP 2a: BACKUP THE CONFIGURATION STORE AND CONFIGURATION FILE ................................. 7
STEP 2b: CREATE MIGRATION FOLDER AND COPY THE CONFIGURATION STORE .......................... 8
STEP 2c: COPY THE MIGRATOR TOOL INTO THE MIGRATION FOLDER ........................................... 8

STEP 3: SETUP THE EXTERNAL DATABASE SYSTEM ................................................................ 8

STEP 4: CONFIGURATE THE CONNECTION TO THE DATABASE SYSTEM................................. 9
STEP 5: START THE CELONIS SERVICE AND VALIDATE THE SETUP ......................................... 9
STEP 6 (MIGRATION ONLY): EXECUTE MIGRATION.............................................................. 10
STEP 6a: STOP THE CELONIS SERIVCE ............................................................................................ 10
STEP 6b: PERFORM THE DATA MIGRATION .................................................................................. 10
STEP 6c: RESTART THE CELONIS SERVICE AND VALIDATE THE MIGRATION ................................. 11
STEP 6d: CLEAN-UP........................................................................................................................ 11

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 2

REVISION HISTORY

VERSION NUMBER VERSION DATE SUMMARY OF REVISIONS MADE

1.6 FEB 23, 2018 Initial version

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 3

INTRODUCTION

ABOUT THIS GUIDE

Celonis is a powerful software for retrieving, visualizing and analyzing real as-is business processes
from transactional data based on event information. It provides users with the possibility to create and
share comprehensive process analyses giving them full transparency about the business processes at
hand.

This guide describes the setup of the Celonis Configuration Store. This can either be a new setup or a
migration from the internally used HyperSQL (HSQL) database to an external database system such as
PostgreSQL or Microsoft SQL Server (MSSQL). The Celonis Configuration Store is the central storage of
the application metadata, e.g. system settings, users, groups, definitions of analyses and data models
and contains all configuration done via the web frontend. The actual data to be analyzed resides in the
underlying database and is never part of the Celonis Configuration Store.

TARGET AUDIENCE

This guide is meant to be consulted by the following target audiences:

• System Administrators
• Technical Staff

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 4

LIST OF ABBREVIATIONS

ABBREVIATION EXPLANATION
DB Database

HSQL HyperSQL

JDBC Java Database Connectivity

MSSQL Microsoft SQL Server

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 5

SUPPORTED DATABASE SYSTEMS AND PREREQUISITES

Celonis supports the following database systems for the Celonis Configuration Store:

• PostgreSQL Version 9.5

• MSSQL Version 2014

The installation of these database system is out of the scope of this guide. We recommend installing
the database system locally on the Celonis application server.

It is expected that the database system is already installed on the Celonis application server. The user
that is used by the Celonis application must have the following permissions:

• PostgreSQL: superuser
• MSSQL: database owner

We recommend using the database system exclusively for the Celonis Configuration Store data.

Validate if the drivers for external database systems are present in the application data folder.

• Go to the "appfiles" (Windows) / “root” (Linux) folder of the Celonis application

“appfiles/app/WEB-INF/lib”.
• Copy the database system driver into this folder. Please download the JDBC driver from the
corresponding database system provider.
o PostgreSQL JDBC supported driver: 9.4.1211 JDBC 4
o MSSQL JDBC supported driver: Microsoft JDBC Driver 4.0 for SQL Server

Please note, when an external database system is used as Celonis Configuration Store, there are no
backups created automatically. The customer is responsible to back up the database files of the Celonis
Configuration Store.

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 6

SETUP CONFIGURATION STORE

For migrating an existing Celonis Configuration Store (powered by HSQLDB), please follow all steps
below.

For setup of a new Celonis Configuration Store (in a new installation), please only follow steps 1 and 3
to 5 as indicated below.

STEP 1: STOP THE CELONIS APPLICATION SERVER

Windows

• Open the Celonis Management Console.

• Stop the service by clicking on the “Stop” button.

Linux

• Switch to the Celonis installation directory.

• Stop the service by executing the stop script (see Table 1).

sudo sh stop.sh

Table 1: Execute stop script on Linux.

Validate if the Celonis service terminated successfully in the process explorer overview. If the service
does not terminate after several minutes, terminate the service directly.

STEP 2 (MIGRATION ONLY): PREPARE MIGRATION

STEP 2a: BACKUP THE CONFIGURATION STORE AND CONFIGURATION FILE

Backup current Celonis Configuration Store:

• The HSQL files are in "appfiles" (Windows) / “root” (Linux) folder of the Celonis installation
directory and consist of the following four files (do not select the appdata.lck file).
o appdata.lobs
o appdata.log
o appdata.properties
o appdata.script
• Zip these four files into a zip file (e.g. 7-Zip) name it properly and move the created zip-file into
your backup folder.

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 7

Backup the custom configurations file:

• Copy the file "config-custom.properties”, located in the Celonis installation directory, to your
backup folder and rename it "config-customer.properties.backup_YYYYMMDD" by replacing
the placeholder YYYYMMDD with the current date (YYYY – year, MM – month, DD – day).

STEP 2b: CREATE MIGRATION FOLDER AND COPY THE CONFIGURATION STORE

• Create the folder "migration" within the "appfiles" (Windows) / “root” (Linux) folder.
• Copy the HSQL database files into the folder "migration" excluding the “appdata.lck” file. The
files are in the "appfiles" (Windows) / “root” (Linux) folder of the Celonis installation directory
(for details see STEP 2 (MIGRATION ONLY): PREPARE MIGRATION
• STEP 2a: BACKUP THE CONFIGURATION STORE AND CONFIGURATION).
• Do not copy the appdata.lck file as it locks the HSQL database and the migrator tool cannot
establish a connection. If you copied it, delete it.

STEP 2c: COPY THE MIGRATOR TOOL INTO THE MIGRATION FOLDER

• The migration tool is the provided to you by Celonis.

• Copy the migration tool (java application) into the previously created “migration” folder.

STEP 3: SETUP THE EXTERNAL DATABASE SYSTEM

Recommended configuration of the external database system:

• Create a database user named “celonis_configuration_store_user”

o PostgreSQL: the user must be a superuser
o MSSQL: the user must be the database owner
• Create a database named “celonis_configuration_store”. The user created in the previous step
must be the database owner.

Please note, we recommend selecting the location of the database files in accordance to your backup
strategy.

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 8

STEP 4: CONFIGURATE THE CONNECTION TO THE DATABASE SYSTEM

The following fields must be activated in the “config-custom.properties” file, which is located in the
Celonis installation directory (see Table 2).

database.driverClassName=org.postgresql.Driver

database.url=jdbc:postgresql://localhost:<port>/celonis_configuration_store
PostgreSQL database.username=celonis_configuration_store_user

database.password=<password>

database.dialect=de.celonis.pm.utils.engine.CPMPostgresDialect

database.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver

database.url=
jdbc:sqlserver://localhost:<port>/databaseName=celonis_configuration_store
MSSQL
database.username=celonis_configuration_store_user

database.password=<password>

database.dialect=org.hibernate.dialect.SQLServerDialect

Table 2: Configuration settings for the connection to the external database system.

STEP 5: START THE CELONIS SERVICE AND VALIDATE THE SETUP

Please note, the restart of the application is mandatory as the application server needs to create the
required tables in the external database system. The migration tool only copies the tables from the
file-based HSQL database into the new database system.

• Start the Celonis service and login as system administrator. You should only be able to login
with system administrator account using the default password, as no application data is
available yet. The default password is stored in the “config.properties” file within the Celonis
installation directory.
• You should not see any projects or analysis.
• In any other case the configuration of the new database system was not successful.

Troubleshooting

• Check if the port of the database connection is correct

• Validate the username and password
• PostgreSQL specific: the user must be a superuser
• MSSQL specific: the user must be the database owner

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 9

STEP 6 (MIGRATION ONLY): EXECUTE MIGRATION

STEP 6a: STOP THE CELONIS SERIVCE

• Log out from the Celonis application.

• Stop the Celonis service.

STEP 6b: PERFORM THE DATA MIGRATION

• Execute the migration tool from the folder “migration” (see STEP 2B: CREATE MIGRATION
FOLDER AND COPY THE CONFIGURATION STORE) using the command in Table 3.
java -jar celonis_configuration_store_migrator_v1-6.jar "hsql-pg"
"jdbc:hsqldb:file:<HSQL_files_location>/appdata"
PostgreSQL
"jdbc:postgresql://localhost:<port>/celonis_configuration_store"
"celonis_configuration_store_user" "<password>"

java -jar celonis_configuration_store_migrator_v1-6.jar "hsql-mssql"

"jdbc:hsqldb:file:<HSQL_files_location>/appdata"
MSSQL
"jdbc:sqlserver://localhost:<port>/databaseName=celonis_configuration_store"
"celonis_configuration_store_user" "<password>"

Table 3: Command to execute the migration tool.

The following information must be updated within the command:

• Location of the HSQL files

o PostgreSQL and MSSQL: "jdbc:hsqldb:file:<HSQL_files_location>/appdata", where
<HSQL_files_location> is the folder of the Celonis application data specified in the
configuration file (“config.properties”).
• Port of the new database
o PostgreSQL: "jdbc:postgresql://localhost:<port>/celonis_configuration_store"
 Example: "jdbc:postgresql://localhost:5432/celonis_configuration_store"
o MSSQL:
"jdbc:sqlserver://localhost:<port>/databaseName=celonis_configuration_store"
 Example:
"jdbc:sqlserver://localhost:1433/databaseName=celonis_configuration_store"

Figure 1 shows a successful example output of the migration tool, where the migrated tables are listed.
If the output is different, the migration tool is configured incorrectly.

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 10

 Figure 1: Successful example output of the migrator tool.

Troubleshooting

• The location to the Celonis Configuration Store (HSQL file location) must contain the name of
the file-based database files, which is "appdata" by default.
• Check if you deleted the “appdata.lck” file, which locks the HSQL database files.
• Check if the port of the database connection is valid.
• Validate the username and password of the database system.
• Are the tables in the target database system already created? If not, go to STEP 5: START THE
CELONIS SERVICE AND VALIDATE THE SETUP.

STEP 6c: RESTART THE CELONIS SERVICE AND VALIDATE THE MIGRATION

• Start the Celonis service and login.

• Validate if the projects, analysis and your configurations have been migrated correctly.

STEP 6d: CLEAN-UP

Please note, that the clean-up steps are optional.

• Delete the configuration file backup “config-custom.properties.backup_YYYYMMDD

• Delete the backup of the Celonis Configuration Store
• Delete the “migration” folder in the "appfiles" (Windows) / “root” (Linux) folder

© 2018 Celonis SE CONFIGURATION STORE SETUP GUIDE 11