Step 1 - Installing SAP Extractor
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
The SAP Extractor is installed as part of the on-prem clients installation. See Installing on-prem clients.
Before you begin, make sure your system meets all the system requirements.
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
SAP Extractor system requirements
Important
Any references to third-party products or services do not constitute Celonis Product Documentation nor do they create any contractual obligations. This material is for informational purposes only and is subject to change without notice. Celonis does not warrant the availability, accuracy, reliability, completeness, or usefulness of any information regarding the subject of third-party services or systems.
The on-premise server will be running both Celonis SAP Extractor and Celonis on-Prem Agent. For this we recommend the following system requirements:
64-bit Operating System
Windows Server: recommended 2012 R2 (2008 R2 SP1 and later versions are also supported)
Ubuntu: recommended 18.04 LTS
Red Hat Enterprise Linux 7
SUSE Enterprise Linux (SLES) 12 and 15
Oracle Linux 6 and 7
Java (JRE) 17 64-bit (OpenJDK 18 is also supported, we recommend AdoptiumOpenJDK 18, see: Adoptium - Eclipse Temurin - Latest Releases)
On Windows (Please install both redistributable packages):
Microsoft Visual C++ 2010 Redistributable Package (x64), available for download from Microsoft Download Center.
Microsoft Visual C++ 2013 Redistributable Package (x64), available for download from Microsoft Download Center.
Administrative rights for setup
Connections for operations of the extractor
Source System | Target System | Port | Protocol | Description |
|---|---|---|---|---|
On premise extractor server | SAP ECC system | 33XX (where xx is the system number) | TCP | RFC connection from on premise extractor server to the SAP system. The system number can be retrieved from the SAP basis team. |
On premise extractor server | Celonis cloud endpoint | 443 | TCP | HTTPS connection from on premise extractor server to Celonis cloud endpoint. The IPs of the endpoint depend on the cloud realm (which can be seen in the URL) and they can be found the section below. |
Cloud IP addresses depending on the realm
The IP of the realm where the EMS team resides should be allowlisted so that the on-premise extractor can communicate with the EMS cloud endpoints.
Optional: Using proxies
Please refer to the on premise Extractor documentation on proxies topic.
Installing SAP Extractor on Windows (deprecated)
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
Use the steps below to install the SAP Extractor on Windows:
Go to Admin and Settings and then system/Uplink integrations.
Create a new uplink with the type "Connector" (independent of which Connector type you would like to connect).
Copy the keys and save them temporarily as they will be needed later in the manual process.
Download the extractor package from the EMS Download Portal.
Run yyyy-mm-dd_SAP_Extractor_Agent_Installer.zip with admin rights, and click the Install button. The installer will check that a proper Java version is installed, and also automatically install the required Microsoft Visual C++ 2010 and 2013 Redistributable Packages.
After successfully checking and installing the respective dependency libraries, the installer will prompt to install the Extractor. Click Next to proceed.
In the next steps of the workflow please enter the Uplink credentials generated in the Set up the Connection in the Celonis Cloud => Admin and Settings step above, and then define the directory where the Extractor should be installed.
After the installation is completed, the Celonis SAP Extractor service will be created in Windows Services, and the installation directory will be populated with the Extractor source files.
Download the extractor package from the EMS Download Portal.
Add the copied keys to config file application-local.yml.
Spacing in the configurationn
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.
Change the following settings:
The file name after "file:" indicates the name of the log file into which the extractor writes. The file will be automatically created.
The following options need to be configured:
url: You need to adapt the team name - it should point to the team that the data should be send to - https://{team}.{cluster}.celonis.cloud/uplink/api/public/uplink
clientId: The client ID of the uplink endpoint that you have already set-up
clientSecret: The client secret of the uplink endpoint that you have already set-up
If you would like to use a proxy (optional), please refer to the proxy configuration page.
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 use an industry-standard library - The SAP Java Connector (SAP JCo) - which is maintained and published by SAP itself. The JCo library should be downloaded and set up separately. This involves two 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 users to download software from SAP portals. Usually a customer's SAP BASIS has this access.
Copy the Library files into the dedicated folder ("Celonis SAP Shared") in the Extractor Package. The Library contains 2 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 "\Celonis SAP Shared\jco". The extractor is configured to read the Library from this directory.
Restart the Windows Service Celonis SAP Extractor for the JCo related changes to take effect.
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
Go to Admin and Settings and then system/Uplink integrations.
Create a new uplink with the type "Connector" (independent of which Connector type you would like to connect).
Copy the keys and save them temporarily as they will be needed later in the process.
Download the extractor package from the EMS Download Portal.
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.
Change the following settings:
The file name after "file:" indicates the name of the log file into which the extractor writes. The file will be automatically created.
The following options need to be configured:
url: You need to adapt the team name - it should point to the team that the data should be send to - https://{team}.{cluster}.celonis.cloud/uplink/api/public/uplink
clientId: The client ID of the uplink endpoint that you have already set-up
clientSecret: The client secret of the uplink endpoint that you have already set-up
If you would like to use a proxy (optional), please refer to the proxy configuration page.
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 use an industry standard library - The SAP Java Connector (SAP JCo) - which is maintained and published by SAP itself.
The JCo library should be downloaded and setup separately. This involves 2 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 authorises to download software from SAP portals. Usually customer's SAP BASIS has this access.
Copy the Library files into the dedicated folder in the Extractor Package
The Library contains 2 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 the to the following folder on the extractor server "Extractor path\jco". The extractor is configured to read the Library from this directory.
You can run the Extractor in of the following ways:
Start the jar file by opening the terminal/cmd, navigating to the respective folder and running it with the following command:
java -Xmx8g -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
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 startup of 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 then select "Run as administrator".
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
Load the extractor package image into docker:
docker load --input <connector_package_name>.tar.gz
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
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. Please also share this file with the Celonis Service Desk if you would like to report an issue.
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
Important
Any references to third-party products or services do not constitute Celonis Product Documentation nor do they create any contractual obligations. This material is for informational purposes only and is subject to change without notice. Celonis does not warrant the availability, accuracy, reliability, completeness, or usefulness of any information regarding the subject of third-party services or systems.
Please check that your on-premise Extractor server can reach Celonis Execution Management System. 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 Execution Management System - if it is needed, see documentation about proxies.
Please check that your Java version is 11 by typing the following in the command line:
java -version
If it is, please make sure that the environment variables PATH and JAVA_HOME are set on a system level, not on only a user level. Moreover, you need to restart your server after the environment variables have been changed so that it affects the system user as well.
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 example, -Djava.io.tmpdir="%BASE%\define\your\directory".
For Linux
The same logic applies to Linux. You need to modify the command that launches the extractor service. When running the command make sire to explicitly override the temp folder. For example:
java -Djava.io.tmpdir="/define/your/directory" -Xmx8g -jar connector-sap.jar
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
The on-premise server will be running both Celonis SAP Extractor and Celonis on-Prem Agent. For this we recommend the following system requirements:
Virtual machine or physical server
CPU: Min. Intel Xeon processor with 4 cores
RAM: min. 20 GB
Disk space: minimum 110 GBon the tmp directory (the directory can be overridden as described here)
Location of the server needs to be in the same network as the source system(s) that should be connected
64-bit Operating System
Windows Server: recommended 2012 R2 (2008 R2 SP1 and later versions are also supported)
Ubuntu: recommended 18.04 LTS
Red Hat Enterprise Linux 7
SUSE Enterprise Linux (SLES) 12 and 15
Oracle Linux 6 and 7
Java (JRE) 17 64-bit (OpenJDK 18 is also supported, we recommend AdoptiumOpenJDK 18, see: Adoptium - Eclipse Temurin - Latest Releases)
On Windows (Please install both redistributable packages):
Microsoft Visual C++ 2010 Redistributable Package (x64), available for download from Microsoft Download Center.
Microsoft Visual C++ 2013 Redistributable Package (x64), available for download from Microsoft Download Center.
Administrative rights for setup
Connections for operations of the extractor
Source System | Target System | Port | Protocol | Description |
|---|---|---|---|---|
On premise extractor server | SAP ECC system | 33XX (where xx is the system number) | TCP | RFC connection from on premise extractor server to the SAP system. The system number can be retrieved from the SAP basis team. |
On premise extractor server | Celonis cloud endpoint | 443 | TCP | HTTPS connection from on premise extractor server to Celonis cloud endpoint. The IPs of the endpoint depend on the cloud realm (which can be seen in the URL) and they can be found the section below. |
Cloud IP addresses depending on the realm
The IP of the realm where the EMS team resides should be allowlisted so that the on-premise extractor can communicate with the EMS cloud endpoints.
Optional: Using proxies
Please refer to the on premise Extractor documentation on proxies topic.
Consider the requirements for sizing the Network Shared File, Z_CELONIS_TARGET.
Installing SAP Extractor on Windows (deprecated)
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
Use the steps below to install the SAP Extractor on Windows:
Go to Admin and Settings and then system/Uplink integrations.
Create a new uplink with the type "Connector" (independent of which Connector type you would like to connect).
Copy the keys and save them temporarily as they will be needed later in the manual process.
Download the extractor package from the EMS Download Portal.
Run yyyy-mm-dd_SAP_Extractor_Agent_Installer.zip with admin rights, and click the Install button. The installer will check that a proper Java version is installed, and also automatically install the required Microsoft Visual C++ 2010 and 2013 Redistributable Packages.
After successfully checking and installing the respective dependency libraries, the installer will prompt to install the Extractor. Click Next to proceed.
In the next steps of the workflow please enter the Uplink credentials generated in the Set up the Connection in the Celonis Cloud => Admin and Settings step above, and then define the directory where the Extractor should be installed.
After the installation is completed, the Celonis SAP Extractor service will be created in Windows Services, and the installation directory will be populated with the Extractor source files.
Download the extractor package from the EMS Download Portal.
Add the copied keys to config file application-local.yml.
Spacing in the configurationn
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.
Change the following settings:
The file name after "file:" indicates the name of the log file into which the extractor writes. The file will be automatically created.
The following options need to be configured:
url: You need to adapt the team name - it should point to the team that the data should be send to - https://{team}.{cluster}.celonis.cloud/uplink/api/public/uplink
clientId: The client ID of the uplink endpoint that you have already set-up
clientSecret: The client secret of the uplink endpoint that you have already set-up
If you would like to use a proxy (optional), please refer to the proxy configuration page.
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 use an industry-standard library - The SAP Java Connector (SAP JCo) - which is maintained and published by SAP itself. The JCo library should be downloaded and set up separately. This involves two 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 users to download software from SAP portals. Usually a customer's SAP BASIS has this access.
Copy the Library files into the dedicated folder ("Celonis SAP Shared") in the Extractor Package. The Library contains 2 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 "\Celonis SAP Shared\jco". The extractor is configured to read the Library from this directory.
Restart the Windows Service Celonis SAP Extractor for the JCo related changes to take effect.
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
Go to Admin and Settings and then system/Uplink integrations.
Create a new uplink with the type "Connector" (independent of which Connector type you would like to connect).
Copy the keys and save them temporarily as they will be needed later in the process.
Download the extractor package from the EMS Download Portal.
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.
Change the following settings:
The file name after "file:" indicates the name of the log file into which the extractor writes. The file will be automatically created.
The following options need to be configured:
url: You need to adapt the team name - it should point to the team that the data should be send to - https://{team}.{cluster}.celonis.cloud/uplink/api/public/uplink
clientId: The client ID of the uplink endpoint that you have already set-up
clientSecret: The client secret of the uplink endpoint that you have already set-up
If you would like to use a proxy (optional), please refer to the proxy configuration page.
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 use an industry standard library - The SAP Java Connector (SAP JCo) - which is maintained and published by SAP itself.
The JCo library should be downloaded and setup separately. This involves 2 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 authorises to download software from SAP portals. Usually customer's SAP BASIS has this access.
Copy the Library files into the dedicated folder in the Extractor Package
The Library contains 2 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 the to the following folder on the extractor server "Extractor path\jco". The extractor is configured to read the Library from this directory.
You can run the Extractor in of the following ways:
Start the jar file by opening the terminal/cmd, navigating to the respective folder and running it with the following command:
java -Xmx8g -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
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 startup of 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 then select "Run as administrator".
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
Load the extractor package image into docker:
docker load --input <connector_package_name>.tar.gz
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
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. Please also share this file with the Celonis Service Desk if you would like to report an issue.
The new on-prem client
We are deprecating the uplink-based on-premise extractor and replacing it with the on-prem clients. For more information, see On-prem client replacing Extractor.
Important
Any references to third-party products or services do not constitute Celonis Product Documentation nor do they create any contractual obligations. This material is for informational purposes only and is subject to change without notice. Celonis does not warrant the availability, accuracy, reliability, completeness, or usefulness of any information regarding the subject of third-party services or systems.
Please check that your on-premise Extractor server can reach Celonis Execution Management System. 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 Execution Management System - if it is needed, see documentation about proxies.
Please check that your Java version is 11 by typing the following in the command line:
java -version
If it is, please make sure that the environment variables PATH and JAVA_HOME are set on a system level, not on only a user level. Moreover, you need to restart your server after the environment variables have been changed so that it affects the system user as well.
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 example, -Djava.io.tmpdir="%BASE%\define\your\directory".
For Linux
The same logic applies to Linux. You need to modify the command that launches the extractor service. When running the command make sire to explicitly override the temp folder. For example:
java -Djava.io.tmpdir="/define/your/directory" -Xmx8g -jar connector-sap.jar