Extractor builder endpoints
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.
Configuring endpoints
The first stage of configuring your API endpoints is to select the request methods and API types.
With the Celonis Platform, you can use two request types:
GET (default)
POST: This allows POST requests to be sent between your source system and the Celonis Platform. When selected, an additional BODY field is visible, allowing you to select between two HTTP standards:
x-www-form-urlencoded (default): This enables you to select key-value pairs.
Plain text: This provides you with a free text box to add your body in plain / raw format.
With the Celonis Platform, you can use three API types:
Default: Configure your own API.
OData V2: This allows you to apply filtering in the extraction configuration without defining request parameters. All applied filters will be natively translated into the OData V2 syntax for the request. See: Filtering using request parameters.
OData V4: This allows you to apply filtering in the Extraction configuration without defining request parameters. All applied filters will be natively translated into the OData V4 syntax for the request. Filters on datetime columns must be specified using the UTC timezone. See: Filtering using request parameters.
You can also select whether this endpoint depends of the response of another endpoint - when selected, the dependencies configuration panel is displayed. For more information, see: Configuring dependencies (optional).
 |
This endpoint will be requested for every unique "Dependency.depends-on-column" value extracted after the extraction of "DEPENDS-ON-ENDPOINT" endpoint. In order to make a request for this endpoint, the placeholder you define in your url or request parameter will be replaced with the actual value of "Dependency.depends-on-column".
You can define dependency in your request in two different ways.
Define dependency in the url: You can use the column you selected with the following syntax "/your/api/{Dependency.depends-on-column}/data"
Define dependency in a request parameter: You can define request parameter where the static value of the parameter is {Dependency.depends-on-column}
The request URL defines the API endpoint that is called and can be identified in your source system’s API documentation. It always starts with the connection parameter, configured as {Connection.API_URL}.
You then have the following options:
Request parameter: Add request parameters to apply filters to your API requests, such as the last creation or updated date filters.
Request header: This is done via defining a key-value pair. For example: define Accept as key and application/json as value for the API response to be returned as json.
Pagination method: To fetch data from all pages when extracting, you must select the pagination mechanism used by your source system's API.
For more information about configuring request parameters, see: Configuring request parameters.
 |
After configuring the API request, you can also configure the response. To define the response structure and content, you have two options:
Example JSON response: Copy and paste a JSON response example from the API documentation of your source system.
Sample a response: If you've already established a data connection with your source system, you can copy a sample response directly from that.
Based on the JSON response copied, the extractor builder automatically creates a table structure including all columns, data types and nested objects. You can configure this table in the following ways:
Multiple response roots: If your JSON response has multiple response roots, you can specify which root you want to extract via the dropdown.
Define primary keys: If you define a primary key for a parent table, the primary key will automatically be created as a foreign key column in its nested tables if they exist. The key will also be used as default primary keys in the extraction configuration.
Adjusting and deleting table elements: You can delete elements from the created table structure by deleting the respective key value pair from the JSON response. Elements you remove here will not be extracted.
Adjust Data Types: You can adjust the data type of each column via a dropdown. For Datetime values, a format based on Joda-Time standard needs to be provided. For more information, see: Joda-Time.
If you don't have any error handling rules, your extraction will fail if the response status is not 200. If there are some cases where you would prefer the extraction to continue, you can specify error handling rules. If the response matches any of the rules, that response will be ignored and extraction will continue.
 |
When adding an error handling rule, you can select from the following rule types:
Http status
Http response body
Field in the response
You can also stop the extraction task when an error rule is met, with the task marked as successfully executed. To enable this, toggle on Don't continue extraction and mark it as successful when configuring your rule:
 |
OData APIs offer various filtering options that require a specific syntax to be used. All filter conditions are expected to be combined in one parameter $filter, for example:
myAPIURL/?$filter=FiscalYear eq ‘2022’ and InvoiceNumber eq = ‘1234’
Selecting OData V2 or V4 allows you to apply filtering in the extraction configuration without defining request parameters on the endpoint. All applied filters will be natively translated into the OData syntax for the request. You do not need to define a request parameter on the endpoint itself. For the filtering, you can use all available configurations in the UI of your table: Creation Date Filter, Change Date Filter, Filter Statement, and Delta Filter Statement.
Filter in extraction configuration | How the request parameter will be generated |
|---|---|
“FiscalYear” = ‘2022’ and “InvoiceNumber” = ‘1234’ | $filter=FiscalYear eq ‘2022’ and InvoiceNumber eq = ‘1234’ |
“FiscalYear” >= ‘2012’ | $filter=FiscalYear ge ‘2012’ |
“FiscalYear” IN (‘2012’, ‘2014’, ‘2016’) | $filter=FiscalYear eq ‘2012’ or FiscalYear eq ‘2014’ or FiscalYear eq ‘2016’ |
CreationDate >= ‘2022-04-03 00:00:00 | For OData V2:$filter=DocumentDate ge datetime'2022-04-03T00:00:00' For OData V4:$filter=DocumentDate ge 2022-04-03T00:00:00Z |
OData APIs return a specific Datetime format called Edm.DateTime in the API response. Exemple values are /Date(1646956800000)/ and /Date(1655900237856+000)/.
When generating the response in the extractor builder, Datetime columns in this format are automatically detected. At the time of extraction, the timestamp will be parsed and inserted as a user-readable Datetime value (for example, 2022-05-01 10:22:12) into Celonis.
In the Configure Response step of your endpoint this will look as follows:
 |