Skip to main content

Celonis Product Documentation

Extractor Builder - OData APIs

Extractor Builder natively supports extractions from OData API based source systems. OData V2 and V4 syntax are both supported.

How can I configure requests to OData APIs in Extractor Builder?

In the ‘Configure Endpoint’ step there is a new setting to define the API Type where you can select between Default, OData V2, and OData V4. Simply select the appropriate type for your API to enable extraction filters as well as datatype handling in the background.

What is the impact of selecting an OData API Type?

When selecting OData V2 or OData V4, the behavior of Extractor Builder changes in two ways:

  • Filtering using request parameters

  • Data type handling

Filtering using request parameters

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.

When defining a filter on table level, the request parameter will be appended to the API URL that is defined for the endpoint: For example:

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

Data type handling

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 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:

What is the added value of native support for OData APIs?

You can easily connect to any source system that is based on OData APIs, or example: SuccessFactors, MS Dynamics 365, and SAP S/4HANA. Your custom OData Extractor can support filtering out-of-the-box without the need to hardcode any request parameters.