Connecting to Generic Database (extractor)

The Celonis Generic Database extractor allows you to add a new JDBC source system connection and start extracting data with a quicker turnaround time when that JDBC source system is not available natively on the Celonis Platform.

The Celonis Generic Database extractor supports the following basic features:

The Generic Database extractor only natively supports direct connections, which means you do not have to upload a JDBC driver.
For uplink connections, you must use a custom JDBC driver in combination with a JDBC connection string in the extractor configuration. For more information, see Supported database types. Additionally, review the JDBC string guidelines.
Important
The Celonis Generic Database extractor only supports connections via a JDBC connection string. For more information, see JDBC string guidelines.

Prerequisites

This section details important prerequisites or prerequisite knowledge for using this extractor.

Verify your data source is supported by Generic Database for direct connections

The Generic Database natively supports multiple JDBC drivers for direct (cloud-based) extractions. To identify if your JDBC data source is supported, you can check the list of supported driver classes in the Generic Database configuration. To verify this before starting:

If the driver class for your database driver is not in the dropdown list, you must request it be added via a support request. These requests are normally completed much quicker than developing a full database extractor.

Extraction configuration requirement

The Generic Database extractor only supports extraction configurations using the Extractions Editor. For more information on Extractions Editor, see Creating extraction tasks using the Extractions Editor and AI Assistant.

Choosing the connection type

Before creating a connection between your database and the Celonis Platform you must decide which connection type you want to use. Except where stated in Supported database types, all databases have two basic connection types: Direct connections and Uplink connections via an on-premise extractor, as described below:

Direct connections: Use direct connections when you want to allow the Celonis Platform direct access to your database without additional infrastructure. Meaning, you do not need to install, patch, or maintain on-premises extractors, which speeds up implementation, reduces complexity, and simplifies operations.
Note
By default, all cloud-based extractors are direct connections.
Uplink connections via an on-premise extractor: Use uplink connections when you don't want to or can't allow the Celonis Platform to directly access your on-premise or private cloud database. The connection between the database and Celonis is then established using an on-premise extractor that's installed within your network ideally on a dedicated server.
The role of the JDBC Extractor is to poll and fetch job requests from the Celonis Platform, before then submitting the execution information to the database via SQL queries. Once the data is retrieved from the database, the extractor fetches it and sends it back to the Celonis Platform. As such, the connection between the database and the Celonis Platform is always made by the extractor, with it continuously querying the Celonis Platform
Note
To use an uplink connection, you must install an on-premise JDBC extractor in your environment. To do so, see JDBC Extractor. Additionally, if you want to use a proxy (optional), see Configuring.

Running the JDBC extractor (Uplink connections only)

When using an uplink connection:

Download the latest JDBC package from the Celonis Download Portal: Updating JDBC extractors.

Place all jar files in a folder, and then run:

java -Dloader.path=<insert_name_of_folder_of_jars> -jar connector-jdbc.jar serve

Modifying your network settings

The next step is to modify your network settings to allow the database extractor to communicate with your target system and the Celonis Platform.

The settings here are based on the connection type you are using:

Network settings for direct connections

Source system	Target system	Port	Protocol	Description
Celonis Platform	Your database	443	TCP	JDBC connection from the Celonis Platform to the database. The port is the one you normally use to connect to the database. The IPs of the Celonis Platform depending on the cloud cluster (which can be seen in the URL).

Network settings for uplinked connections

The following network settings apply for uplinked connections (via the on-premise extractor):

Source system	Target system	Port	Protocol	Description
On-premise extractor server	Your database	443	TCP	JDBC connection from on-premise extractor server to the database. The port is the one you normally use to connect to the database.
On-premise extractor server	Celonis Platform	443	TCP	HTTPS connection from on-premise extractor server to Celonis cloud endpoint. The IPs of the Celonis Platform depending on the cloud cluster (which can be seen in the URL).

JDBC string guidelines

This section describes the guidelines for using custom JDBC strings in extractor configurations:

Authentication: The Generic Database extractor natively supports authentication via a database username and password. However, if your driver supports an alternate authentication method, you can embed your credentials directly in your JDBC string.
Encryption: For standard (unencrypted) extractors (examples: SAP HANA, PostgreSQL), you can enable encryption by adding encrypt=true to the JDBC string. For encrypted extractors (examples: SAP HANA encrypted, PostgreSQL encrypted), connections are established with encryption enabled (encrypt=true) by default. You do not need to include this parameter in your JDBC string.
Certificate validation: Do not include validateCertificate=true in your JDBC strings. Instead, use Advanced Settings > Validate Certificate > Enabled.
Additional properties: You can include additional properties in either the JDBC string or the Additional Properties field. Do not specify the same properties in both places.

Authentication method – username and password

The Generic Database extractor can connect to the database using a database user account. Provide the username and password for this account to authenticate the connection. Ensure this database user has sufficient permissions to access the data to be extracted.

Note

For the Generic Database extractor, it is also possible to provide credientials or an alternate authentication method using the JDBC string.

Configuring the Generic Database extractor

This section describes the basic setup of configuring the Generic Database. To configure the extractor:

In the Celonis Platform left navigation, select Data > Data Integration.
On the Data Pools screen, select the data pool you want to use for the extraction.
Note
If you do not have a data pool to use for this extraction, see Creating and managing data pools for instructions on how to create one.
In the Data Integration section, select Connect to Data Source.
Note
If this is not the data pool's first connection, the Data Connections window opens below. Select + Add Data Connection to add a new connection.
In the Add Data Connection window, select Connect to Data Source.
In the Connect to Data Source window, depending on your use case, select either Database – On Premise or Database – Cloud.
Note
Select Database – On Premise to connect to on-premise or private cloud databases.
1. If you selected Database – On Premise, follow the on-screen instructions.
In the New Database Data Connection window, fill in the following information:
1. For Name, provide a name for this configuration.
2. For Database Type, select Generic Database.
3. For JDBC Connection String, provide your JDBC string.
  Important
  When using JDBC strings, there are specific guidelines to follow. For more information, see JDBC string_guildelines.
4. For Driver class:
  - If you are connecting to a cloud-based database, select your corresponding driver class from the list.
    Important
    If your driver class is not present in the dropdown menu, you must create a support request for the new JDBC driver to be added. For more information, see
  - If your are connecting to an on-premises or private cloud database, provide the driver class of the JDBC driver you uploaded for the uplink connection.
5. (Optional) For Additional Properties, provide any additional properties as a semicolon-separated list of key-value pairs.
6. For Credentials, provide the username and password of the database user for this connection.
  Note
  Ensure this database user has sufficient permissions to access the data to be extracted.
7. If desired, select Advanced Settings, and update these parameters as needed.
  Note
  The Advanced Setting > Validate Certificate parameter (Default: DISABLED) controls whether the extractor validates the server’s SSL/TLS certificate:
  - Disabled: Disables certificate validation (validateCertificate=false).
  - Enabled: Enforces certificate validation (validateCertificate=true).
  - Removed: Uses the driver’s default behavior. Check the driver documentation to confirm the default.
Select the Test Connection button to confirm the extractor can connect to the host system. If the test fails, adjust the data in the configuration fields as needed.
Once the test connection passes, select the Save button to continue. This returns you to the Data Integration window.

You have now connected the Generic Database extractor to your host system. To create and execute data jobs, see Creating extraction tasks using the Extractions Editor and AI Assistant.