Protocol Interoperability

There are different types of APIs with different scopes, benefits and intended audiences, which makes each of them uniquely suited for different purposes.

Intelligence API is a generic purpose API, supporting pure REST and serving any use case. However, it turns out that industry protocol standards can speed up integration and guarantee native interoperability with numerous cloud platforms without the need of building a dedicated connector.

OData (BETA program) 1

OData is one of the most popular industry API protocol standards in the previous decades adopted by many commercial platforms (Microsoft, SAP, Salesforce, etc.) as well as most of the analytics and business intelligence platforms (incl. Tableau, PowerBI, SAP Analytics cloud etc.)

Whereas REST is an architectural style solely concerned with data transfer via web service APIs, OData builds upon REST architecture with a set of metadata that can be easily integrated into most programming and scripting languages.

So OData provides self-discoverability and standard functionality, thus helping applications to focus on business logic without worrying about the various API approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc.

Target Audience

There is no need for development skills to manage and make use of OData integration. It can be handled by personas like:

  • Data Analysts
  • Data Scientists
  • Business Intelligence Professionals

OData v4 Intelligence API

Dynamic Services per Knowledge Model (KM)

The OData service definition is the mechanism one uses to define what data to expose with OData, how, and to whom. Data exposed as an OData collection is available for analysis and display by client applications.

Refer to OData doc: 3 Service Root URL.

Every Celonis Knowledge Model (KM) dynamically generates an OData service including collections of KM records, thus making the KM self-discoverable. The path to access the KM OData service is GET {{base-path}}/odata/{{km-id}}.svc

For example, by sending the request GET https:://{{team}}{{realm}}.celonis.cloud/intelligence/api/odata/{{km-id}}.svc, depending on the Accept header, one gets:

  • Either an xml response if Accept=application/xml , $format=application/xml or $format=xml OData Service: XML
  • Or a json response if Accept=application/json , $format=application/json or $format=json OData Service: JSON

Dynamic Metadata per Knowledge Model (KM)

OData metadata documents describe the Entity Data Model (EDM) for a given service, which is the underlying abstract data model used by OData services to formalize the description of the resources it exposes.

Refer to OData doc: 4.1 Addressing the Model for a Service.

Every Celonis Knowledge Model (KM) dynamically generates their OData metadata including the schema of each KM record, thus making the KM self-discoverable. The path to access the KM OData metadata is GET {{base-path}}/odata/{{km-id}}.svc/$metadata

For example, by sending the request GET https:://{{team}}{{realm}}.celonis.cloud/intelligence/api/odata/{{km-id}}.svc/$metadata, depending on the Accept header, one gets:

  • Either an xml response if Accept=application/xml , $format=application/xml or $format=xml OData Metadata: XML
  • Or a json response if Accept=application/json , $format=application/json or $format=json OData Metadata: JSON

Dynamic Query of the records of each Knowledge Model (KM)

OData specifies a simple, yet powerful query language that allows a client to request arbitrary filtering, sorting, paging and so on. A client is able to express, via query string parameters, the amount and order of the data that an OData service returns for the resource identified by the URI.

Every Celonis Knowledge Model (KM) records allows consumer to query them via OData query syntax described at Odata doc: 5 Query Options.

The path to query the KM record via OData protocol is GET {{base-path}}/odata/{{km-id}}.svc/{{record-id}}

For example, by sending the request GET https:://{{team}}{{realm}}.celonis.cloud/intelligence/api/odata/{{km-id}}.svc/{{record-id}}, depending on the Accept header, one gets:

  • Either an xml response if Accept=application/xml , $format=application/xml or $format=xml OData Query: XML
  • Or a json response if Accept=application/json , $format=application/json or $format=json OData Query: JSON

Query options that are supported:

Example of a query URI: https://apinauts.develop.celonis.cloud/intelligence/api/odata/poc-ms-excel-1.svc/O_CELONIS_ORDER?$select=ID,CREATIONTIME&$orderby=ID desc&$filter=CREATIONTIME gt 2024-04-25&$top=1000&$skip=10&filterid=this_quarter

How Celonis OData integration looks like on 3P platforms

SAP Analytics Cloud

The procedure to create an Import Data Connection from an OData Source into SAP Analytics Cloud takes a few clicks as described at SAP Analytics Cloud Documentation.

Tableau

This example illustrates how to connect Tableau to an OData data source.

Excel

After adding the Microsoft Power Query for Excel, one can easily connect to Celonis by following the below simple steps:

  1. Open Microsoft Excel.
  2. Create a new, blank workbook.
  3. On the Power Query tab, in the Get External Data group, click From Other Sources , and then click From OData Data Feed .
  4. In the OData Feed dialog box page, in the URL box, specify the website address for the data feed as follows: {{base-path}}/odata/{{km-id}}.svc/{{record-id}}?{{parameter-value-list}}
    For example: https://apinauts.develop.celonis.cloud/intelligence/api/odata/poc-ms-excel-1.svc/O_CELONIS_ORDER?$select=ID,CREATIONTIME&$orderby=ID desc&$filter=CREATIONTIME gt 2024-04-25&$top=1000&$skip=10
  5. If you are prompted for your API key, enter them and then log on. The Query Editor opens.
  6. In the Query Editor, view the records available for the endpoint. Edit the queries as required.
  7. Click Close & Load to import the endpoint information in Excel in tabular format.

  1. Please contact your Celonis account team if you want to join the OData Beta program.