Using the extractor builder
The extractor builder allows you to use and extend pre-built extractors or create your own custom extractors to connect to your source systems to the Celonis Platform. The extractor supports GET requests to all REST and OData APIs that return a JSON or XML response, enabling you to continuously connect to a number of commonly used data sources.
Using or customizing a pre-built extractor
The Celonis Platform provides a number of pre-built on-premise and cloud extractors, enabling you to use them directly or customize and extend them where required.
To use or extend a pre-built extractor from your data pool diagram:
Click Data Connections
Click Add Data Connection - Connect to Data Source.
Either / or:
Select an existing extractor and follow the guided process.
To customize an extractor, click Custom - Build Custom Connector - Customize a Celonis Extractor.
If customizing an extractor: You can then select from the available extractor and follow the guided process from there.
Depending on your extractor, you may need or want to provide the following configuration details: Extractor configuration details.
Creating a custom extractor
If a pre-built extractor is not available for your source system, then you can create a custom extractor for it.
To create a custom extractor from your data pool diagram:
Click + Add Data Connection and select Connect to Data Source.
Click Custom - Build Custom Connector - Build a new Extractor.
Add an extractor name and an optional description and click Save and continue.
Configure your connection parameters and click Save and continue. For more information, see: Data connection parameters.
Configure your authentication methods and click Save and continue. For more information, see: Data connection authentication methods.
Define your connection endpoints. For more information, see: Endpoints / OData API.
Click Finish.
Extractor configuration details
Depending on your extractor, you may need or want to provide the following configuration details:
You can define the parameters that will be displayed in the user input fields of your data connection configuration. These parameters can then be used in your API requests, URLs, and headers, configured when defining your end points.
By default, the {Connection.API_URL} parameter will be created as a mandatory parameter and usually contains the host.
To add a new connection parameter, click Create New Connection Parameter.
 |
You can then configure the following connection parameter details:
Name: This is the label of the parameter in the connection form.
Placeholder: You will be able to access the value of this parameter by using this placeholder in your url, request parameter or header
Default value (optional): The default value of the parameter will be effective unless the value is explicitly changed in the connection form.
Confidential: When selected, the parameter will be stored as a secret and it will be displayed as a password input.
Mandatory: When selected, this parameter must be populated.
When connecting your source system to the Celonis platform, you have a number of authentication methods available to you. The method you choose should be based on your source system’s authentication options, so we recommend consulting their available API documentation before proceeding.
For each authentication method, the input required depends on whether you’re configuring the authentication method itself or creating a new data connection. The different inputs per authentication method are detailed in the following table:
Authentication Method | Description | Input (when configuring the authentication method) | Input (when creating a new data connection) | Example Request |
|---|---|---|---|---|
Basic Authentication | User inputs required in the data connection:
To authenticate with the source system, the username and password provided in the data connection is encoded with Base64. This encoded string will be prefixed with "Basic" and sent to every request's Authorization header. |
| Header: "Authorization: Basic bG9sOnNlY3VyZQ==" | |
Bearer Authentication | User inputs required in the data connection:
To authenticate with the source system, this token will be prefixed with "Bearer" and sent to every request's Authorization header. |
| Header: "Authorization: Bearer token" | |
API Key Authentication | User inputs required in the data connection:
To authenticate with the source system, this API Key will be sent in the "x-api-key" header of every request. |
|
| Header: "x-api-key: YOUR-API-TOKEN” |
OAuth2 (Authorization Code) | User inputs required in the data connection:
To authenticate with the source system, the client ID and client secret are passed to the authorization endpoint to request authorization to access the service resources in the browser (when saving the connection). If the user is authorized, an authorization grant is passed. Using this authorization grant an access token needs to be requested from the Get Token endpoint. The returned token is then used for all upcoming requests. The Grant Type authorization_code is being used. The client credentials can be sent as a Basic Auth header (default) or via the request body. |
|
| Header: "Authorization: Bearer token" For Access Token, we send a request to the Get Token Endpoint with content: “grant_type: <GRANT_TYPE>” “client_id: <CLIENT_ID>” “client_secret: <CLIENT_SECRET> → There is no test connection option, because you will get redirect to the UI of the source system for authentication. |
OAuth2 (Authorization Code + Refresh Token) | User inputs required in the data connection:
In order to authenticate with the source system, the client ID and client secret are passed to the authorization endpoint to request authorization to access the service resources in the browser (when saving the connection). If the user is authorized, an authorization grant is passed. Using this authorization grant, an access token needs to be requested from the Get Token endpoint. The returned token is then used for all upcoming requests. As the token in that connection scenario is limited to a certain period of time, a new one is automatically recreated after the old one expires using the refresh token. The Grant Types authorization_code and refresh_token are being used. The client credentials can be sent as a Basic Auth header (default) or via the request body. |
|
| Header: "Authorization: Bearer token" – To refresh the Access Token, we send a request to the Get Token Endpoint with content: “grant_type: refresh_token” “refresh_token: <REFRESH_TOKEN>“ And with Header (generated from client id and secret): "Authorization: Basic bG9sOnNlY3VyZQ==" → There is no test connection option, because you will get redirect to the UI of the source system for authentication. |
OAuth2 (Client Credentials) | User inputs required in the data connection:
To authenticate with the source system, the client ID and client secret are passed to the Get token endpoint to get an access token. The returned token is then used for all upcoming requests. The Grant Type client_credentials is being used. The client credentials are sent via the request body. |
|
| Header: "Authorization: Bearer token" – For Access Token, we send a request to the Get Token Endpoint with content: “grant_type: client_credentials” “client_id: <CLIENT_ID>” “client_secret: <CLIENT_SECRET> |
OAuth2 (Resource Owner) | User inputs required in the data connection:
The client ID, client secret, username, and password are passed to the Get token endpoint to get an access token to authenticate with the source system. The returned token is then used for all upcoming requests. The Grant Type password is being used. The client credentials are sent via the request body. |
|
| Header: "Authorization: Bearer token" – For Access Token, we send a request to the Get Token Endpoint with content: “grant_type: password” “username: <USERNAME>” “password: <PASSWORD>” “client_id: <CLIENT_ID>” “client_secret: <CLIENT_SECRET> Note: Client secret is used only if it is specified. |
OAuth2 (JWT Bearer with Private Key) | User inputs required in the data connection:
To authenticate with the source system, the Private Key, the Issuer, and Subject Label are sent to the Get token endpoint and validated based on the Audience. The returned token is then used for all upcoming requests. The respective Grant Type can be found in the API documentation of the system you want to connect to. The audience, Issuer, Subject Label, and Private Key provided in the data connection are encoded with Base64. |
|
| Header: "Authorization: Bearer token" – For Access Token, we send a request to the Get Token Endpoint with content: “grant_type: <GRANT_TYPE>” “client_assertion: <JWT_ASSERTION>” → the JWT_ASSERTION: is the assertion generated from the Private Key and the selected Signature Algorithm |
OAuth2 via Proxy | User inputs required in the data connection:
The client ID, client secret, username, and password are passed to the Get token endpoint to get an access token to authenticate with the source system. The returned token is then used for all upcoming requests. Client ID, client secret, username, and password provided in the data connection are encoded with Base64 into one string |
|
| Header: "Authorization: Bearer token" – For Access Token, we send a request to the Get Token Endpoint with headers: “content-type: <CONTENT_TYPE>” “Authorization: <AUTH_STR>” → the AUTH_STR has the value of Base64 encoded credentials. The encoded part is generated from Client ID, Client Secret, Username and Password. |
When configuring your data connection you must define the API endpoints for your source system. This includes selecting your API type, configuring your requests, responses, and headers, and optionally managing your error handling.
For more information, see: Endpoints / OData API.