# Protocol Interoperability

There are different types of APIs with different scopes, benefits and intended audiences, which makes each of them uniquely suited for their unique purposes.
The Knowledge Model 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 to build a dedicated connector.

## OData (BETA program) [1]

[OData](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html) is one of the most popular industry API protocol standards in in recent years, adopted by many commercial platforms (such as Microsoft, SAP, Salesforce, etc.) as well as most of the analytics and business intelligence platforms (including Tableau, PowerBI, and SAP Analytics cloud).
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.
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 Knowledge Model API

#### Dynamic Services per Knowledge Model (KM)

The OData service definition is **the mechanism used to define what data is exposed with OData, how, and to whom**. Data is exposed as OData collections. Refer to OData doc: [3 Service Root URL](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#_Toc31360927).
Every Celonis Knowledge Model (KM) dynamically generates an OData service including collections of KM records, thus making the KM queryable. The path to access the KM OData service is `GET {{base-path}}/odata/{{km-id}}.svc`
By sending the request `GET https:://{{team}}{{realm}}.celonis.cloud/intelligence/api/odata/{{km-id}}.svc`, one gets:

- Either an ***xml*** response if `Accept=application/xml` , `$format=application/xml` or `$format=xml`
![OData Service: XML](/assets/odata-service-result-xml.3136b1cccb6f712faa9f30dcf5dc415d4a770ef6dfcf532b99755723d2950a38.3c53a942.png)
- Or a ***json*** response if `Accept=application/json` , `$format=application/json` or `$format=json`
![OData Service: JSON](/assets/odata-service-result-json.81dc3deef332154fc652abf9ea0817efa80995e2e8694dc48fc0855f20dde0e3.3c53a942.png)


#### 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](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_AddressingtheModelforaService).
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`
By sending the request `GET https:://{{team}}{{realm}}.celonis.cloud/intelligence/api/odata/{{km-id}}.svc/$metadata`, one gets:

- Either an ***xml*** response if `Accept=application/xml` , `$format=application/xml` or `$format=xml`
![OData Metadata: XML](/assets/odata-metadata-xml.a0a324a9265dc35bc182d29ccfa807beb95933101224511fea5955f3b442a30d.3c53a942.png)
- Or a ***json*** response if `Accept=application/json` , `$format=application/json` or `$format=json`
![OData Metadata: JSON](/assets/odata-metadata-json.b16cc9d6b00210692af060657bd8340db55113be2cb2ef2add6efbcefc9eaf0a.3c53a942.png)


#### 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 field selection, 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) record allows consumer to query them via OData query syntax described at Odata doc: [5 Query Options](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_QueryOptions).
The path to query the KM record via OData protocol  is `GET {{base-path}}/odata/{{km-id}}.svc/{{record-id}}`
By sending the request `GET https:://{{team}}{{realm}}.celonis.cloud/intelligence/api/odata/{{km-id}}.svc/{{record-id}}`, one gets:

- Either an ***xml*** response if `Accept=application/xml` , `$format=application/xml` or `$format=xml`
![OData Query: XML](/assets/odata-data-xml.76e3282946054261d92e1605b20c3ec79dd2bae4117921ae59867adeea00deea.3c53a942.png)
- Or a ***json*** response if `Accept=application/json` , `$format=application/json` or `$format=json`
![OData Query: JSON](/assets/odata-data-json.be26e05a243b619d9b37b9698dc5fdcf274643d76038463a7867361910c52427.3c53a942.png)
Query options that are supported:
- `$filter`: Refer to the OData doc [5.1.2  System Query Option  $filter](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionfilter)
- `$select`: Refer to the OData doc [5.1.4  System Query Option  $select](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionselect)
- `$orderby`: Refer to the OData doc [5.1.5  System Query Option  $orderby](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionorderby)
- `$top` and `$skip`: Refer to the OData doc [5.1.6  System Query Options  $top  and  $skip](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionstopandskip)
- `$format`: Refer to the OData doc [3  Requesting the JSON Format](https://docs.oasis-open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html#_Toc372793039)
- `$count=true`: Refer to the OData doc [5.1.7 System Query Option $count](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptioncount)
- `filterid`: A custom option that allows the usage of predefined KM filters
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](https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/00f68c2e08b941f081002fd3691d86a7/1c1e36eeb99e420aa20ebe6e39af2b65.html#procedure).

#### Tableau

[This example](https://help.tableau.com/current/pro/desktop/en-us/examples_odata.htm) illustrates how to connect Tableau to an OData data source.

#### Excel

After adding the [Microsoft Power Query for Excel](https://www.microsoft.com/en-us/download/details.aspx?id=39379), 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, click **From Other Sources** in the Get External Data  group, 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 it 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]:** Contact your Celonis account team if you want to join the OData Beta program.