Skip to main content

Celonis Product Documentation

Setting up an on-premise extractor

The on-premise extractors need to be installed on an on-premise server. Please follow the system requirements topic for the setup.

Extractor setup on a Windows/Linux server
Step A: Set up the connection in the Celonis Cloud => Admin and Settings

  1. Go to team settings and then system/Uplink integrations.

  2. Create a new uplink with the type "Connector" (independent of which Connector type you would like to connect).

  3. Copy the keys and save them temporarily (they will be needed in Step B).

Step B: Download and configure the extractor

  1. Download the extractor package.

    Note

    Unless you're using an older version of SAP, 4.6C or earlier or you use PO/PI, we recommend that you use our newer on-prem clients. For the instructions to install this client, see On-premise clients (OPC). The on-prem clients run mostly in the Celonis Platform cloud, so you'll get these benefits compared to the uplink-based on-premise extractors. If you still wish to get the on-prem extractor, reach out to the Celonis support team at servicedesk@celonis.com.

  2. Add the copied keys to config file application-local.yml (see the example below).

Spacing in the configuration

Please make sure not to change anything regarding the white spaces in the configuration file application-local.yml. The different elements need to be spaced exactly as in the original example.

41194546.png

Most settings can be left as is. You need to adopt the following:

  1. The file name after "file:" indicates the name of the log file into which the extractor writes. The file will be automatically created.

  2. The following options need to be configured:

    1. url: You need to adapt the team name - it should point to the team that the data should be sent to: https://{team}.{cluster}.celonis.cloud/uplink/api/public/uplink

    2. clientId: The client ID of the uplink endpoint that you have already set up.

    3. clientSecret: The client secret of the uplink endpoint that you have already set up.

To use an optional proxy, please refer to the proxy configuration page.

Step C: Set up the JCo (applicable only for SAP extractor)

To communicate with the Celonis RFC module, the extractor needs to establish a connection to the SAP system and be able to make RFC calls. For this purpose, we require the SAP Java Connector (JCo) 3.1 or later to be installed.

The JCo library should be downloaded and set up separately. This involves the following steps:

  • Download the respective package from the SAP Marketplace

    This step should be performed by someone who has an SAP Service User (S User), which authorizes to download software from SAP portals. Usually, a customer's SAP BASIS has this access.

  • Copy the Library files into the dedicated folder in the Extractor Package

    The Library contains two files - a Java part “sapjco3.jar”, and an operating system-specific part, for example, sapjco3.[.dll | .so | .sl ].

    After downloading the files make sure to copy them to the following folder on the extractor server "Extractor path\jco". The extractor is configured to read the Library from this directory.

Step D: Run the extractor

There are two ways to run the extractor:

  1. in the command line

  2. as a service

1. Run the extractor in the command line

Start the jar file by opening the terminal/cmd, navigating to the respective folder, and running the following command:

 java -Xmx8g -Dspring.config.location=application-local.yml -jar connector_file_name.jar

Running multiple extractors

If you like to run multiple on-premise extractors in the same folder, you need to rename the application-default.yml files so that they are distinct. Then you need to start the respective extractor with the following command:

 java -Dspring.config.location=configuration_file_name.yml -Xmx8g -jar extractor_file_name.jar
2. Run an on-premise extractor as a service

The major benefit of running it as a service is that the extractor can be automatically started when the server is rebooted.

On Linux

If you wish to start the application on starting up the server, you can use systemd - the standard way to start a Linux service at boot.

For this you need to create a unit file and put it in the directory /etc/systemd/system/. You can use this example unit file below named celonis_extractor.service:

celonis_extractor.service

[Unit]
Description=Celonis Extractor Service.

[Service]
Type=simple
User=username
WorkingDirectory=[path to folder of installation]
ExecStart=/usr/bin/java -Xmx8g -jar connector-sap.jar
Restart=on-abort

[Install]
WantedBy=multi-user.target

To enable and start the service execute the following commands:

Start the service

sudo systemctl start celonis_extractor.service # starts the service
sudo systemctl enable celonis_extractor.service # registers the service so that it is started on boot

On Windows

The extractor package contains four files that enable you to run the extractor as a Windows service:

  • Celonis<ConnectionType>Extractor.xml: The configuration file of the service. Normally, you do not need to make any changes to this file.

  • install.bat: The batch file to install the services on the service.

  • startup.bat: The batch file to start the service manually.

  • shutdown.bat: The batch file to stop the service manually.

In order to perform an install, a startup or a shutdown, you need to run the batch file as an administrator. To do that, simply right-click on the respective file and select "Run as administrator".

JDBC extractor setup on Docker (applicable only for JDBC extractor)

  1. Load the extractor package image into Docker:

    docker load --input <connector_package_name>.tar.gz

  2. Steps to run the extractor in the command line:

    docker run \ 
-e UPLINK_ENABLED=true \ 
-e UPLINK_URL=https://{team}.{cluster}.celonis.cloud/uplink/api/public/uplink \ # insert the team url, it should point to the team that the data should be send to. 
-e UPLINK_CLIENTID=<clientID>\ # insert the client ID of the uplink endpoint that you have already set-up 
-e UPLINK_CLIENTSECRET=<clientsecret>\ # insert the client secret of the uplink endpoint that you have already set-up 
-p <port>:<port>\ # insert the port 
-v <connector_package_name> # provide the package name

Separate driver

You specify the driver in the following way when running the extractor:

Supply the driver

-v <path_to_driver_locally>:<path_to_driver_in_the_container> <connector_package_name> # insert the local and container path to the driver
Additional information
Using log files of the on-premise extractor

If you encounter an error when starting or running the extractor, it is very helpful to have a look at the log file that the extractor produces. It can be found in the same folder as the extractor and it has the name given in the configuration file (see above), by default <ConnectionType>_connector.log.

To download the on-premise extractor logs, find the relevant connection in the listing of on-premise Data Connections, and select "Extractor Logs" from the context menu for the connection. You can specify a date range to download the logs.

Frequently Asked Questions about setting up an on-premise extractor

After starting the Extractor I see the message "Connection refused: connect; nested exception is java.net.ConnectException: Connection refused: connect". How can this be fixed?

Please check that your on-premise extractor server can reach Celonis Platform. Specifically, please verify that:

  • You can reach the URL https://[team].[realm].celonis.cloud in the browser of your server. If not, please check your firewall settings.

  • No proxy is blocking the connection between the extractor and Celonis Platform. For more information, see documentation about proxies.

If I run the extractor as a Windows service, it always fails immediately and I can only see the log files ending with the wrapper. What can I do?

Please check that your Java version is 17 by entering:

java -version

in the command line. If it is the correct version, make sure that the environment variables PATH and JAVA_HOME are set on a system level and not only on a user level. In addition, you will need to restart your server after the environment variables have been changed so that it affects the system user as well.

How do I override the temp folder that is used by extractor for storing the files temporarily?

This is possible to do by overriding the command that starts the extractor service.

For Windows

Windows service is installed according to the metadata that is defined in the file CelonisSapExtractor.xml, which is located in the extractor folder. You can modify the command line arguments there and override the directory which is by default "%BASE%\temp".

For Linux

The same logic applies to Linux. You need to modify the command that launches the extractor service. When running the command make sure to explicitly override the temp folder. For example:

java -Djava.io.tmpdir="/define/your/directory" -Xmx8g -jar connector-sap.jar