Celonis (Preview)
Celonis Platform API to work with Knowledge Model elements, like records, KPIs, filters, triggers and their related data.
This connector is available in the following products and regions:
| Service | Class | Regions |
|---|---|---|
| Logic Apps | Standard | All Logic Apps regions except the following: - Azure Government regions - Azure China regions - US Department of Defense (DoD) |
| Power Automate | Premium | All Power Automate regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
| Power Apps | Premium | All Power Apps regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
| Contact | |
|---|---|
| Name | Celonis Support |
| URL | https://developer.celonis.com/ |
| intelligence-api-feedback-sc@celonis.de |
| Connector Metadata | |
|---|---|
| Publisher | Celonis |
| Website | https://www.celonis.com |
| Privacy policy | https://www.celonis.com/privacy-policy/ |
| Categories | AI;Business Management |
Title
The Celonis Intelligence API allow Celonis customers to embed actionable process intelligence into third-party platforms where end-users may benefit from Celonis process insights. In this manner, it would bring Celonis intelligence like process KPIs or process inefficiencies closer to the end-users and benefit operational users without current access to Celonis by providing valuable insights for better decision-making while executing their day-to-day activities. Apart from the data query capability, Intelligence API also supports pushing data to third-party platforms by allowing them to subscribe to business triggers.
Publisher: Publisher's Name
Celonis
Prerequisites
- A team in Celonis Platform.
- A Knowledge Model available in a client's team.
- Process-based Celonis Subscription (contact your account team to verify).
Supported Operations
The current API methods allow consumers to interact with Knowledge Models defined in Celonis Platform by providing the following functionalities:
Knowledge Model Discovery Methods
Get a list of Knowledge Models (KM)
Get a list of KM Records
Get a KM Record Schema Details
Get a list of KM Filters
Knowledge Model Data Retrieval Methods
Get a list of KM Record data
Subscription Lifecycle Management Methods
Get a list of Subscriptions
Get a list of KM Triggers
Create a Subscription to a KM Trigger
Update a Subscription
Pause a Subscription
Resume a Subscription
Terminate a Subscription
Obtaining Credentials
Authentication
Each request to the API must be authenticated with a Celonis API key. There are two ways of doing this:
Using a User API key
You can find out how to create an user API key by following our User API Keys guide. The Celonis API uses Bearer Token Authentication for verifying consumer access. The credentials must be sent in an Authorization header in the HTTP request. Credentials sent in the URL or body of the request will be ignored. To authenticate using Bearer Token Authentication:
- Create the token in Celonis:
MDg5MGVkNDktNjMwZC00ODdiLTkyNGItMjNmMzMxNjRmM2IwOkhNUVRMUis4SGh6NHhBY21Vck9GaWdkem5rYzBrb3p0N056WUM0bGlqczMM - Include the string in the HTTP Authorization header formatted like this:
Authorization: **Bearer** MDg5MGVkNDktNjMwZC00ODdiLTkyNGItMjNmMzMxNjRmM2IwOkhNUVRMUis4SGh6NHhBY21Vck9GaWdkem5rYzBrb3p0N056WUM0bGlqczMM
Using an Application API key
You can find out how to create an AppKey by following our Application API Keys guide. To authenticate using AppKey Authentication:
- Create the AppKey in Celonis:
MzgyZDEzYjItNjI1MS00NTIwLTk1YTItY2ZjYzMzZTllOTNmOkE3a1dvYnpYQ0c3aUtUdTNRNC9UNzFLUXZmY0E2ZjVXUUROajFoN1R5UzIr - Include the string in the HTTP Authorization header formatted like this:
Authorization: **AppKey** MzgyZDEzYjItNjI1MS00NTIwLTk1YTItY2ZjYzMzZTllOTNmOkE3a1dvYnpYQ0c3aUtUdTNRNC9UNzFLUXZmY0E2ZjVXUUROajFoN1R5UzIr
Authorization
You must set the right permissions and ensure the User API Key or the Application API Key leveraged for authorization purposes has access to the Celonis Studio package containing the Knowledge Model(s) you would like to access through Intelligence APIs. You can grant access permissions by following these steps:
- Go to the Studio package.
- Click on the three dots and select
Permissionsfrom the pop-up menu. - Search for the User (in case you are using a Bearer token ) or AppKey (in case you are using an AppKey ) and grant at least
USE PACKAGErights.
Getting Started
The base URL for the Celonis API is https://<team>.<cluster>.celonis.cloud/intelligence/api
To find the team and the cluster, please check the URL you use to access the Celonis Platform and retrieve the team and cluster from it.
The Celonis Intelligence API is a JSON API and its endpoints will always return a JSON response, no matter the success of the request.
The current API methods allow consumers to interact with Knowledge Models defined in Celonis Platform by providing the following functionalities:
- List of available Knowledge Models and their details
- List of records and their details
- List of filters
- Data for a specific record. Details about the Celonis Intelligence API Features at Celonis developer portal.
Known Issues and Limitations
Rate limiting
The Intelligence API was not built to bulk export RAW data but to make the calculated results and insights from process mining available to 3rd party platforms and applications. That’s why the Celonis API enforces rate limiting. This means that only a certain number of requests are allowed per day and a certain number of records can be retrieved in each call. Celonis reserves the right to adjust the rate limits at any time to guarantee high-quality service for all clients.
In case a client repeatedly exceeds the rate limits or engages in behavior that is deemed to be suspicious, Celonis reserves the right to temporarily or permanently limit or suspend access to the API for that client.
When a client exceeds the number of requests per day, the Celonis API will return a 429 response (too many requests) including an HTTP header (x-ratelimit-reset) which indicates the time (in seconds) that the client needs to wait before a new request can be processed.
The following HTTP headers are also returned as part of each call:
x-ratelimit-limit: Represents the max number of requests that the client can perform in the current time window.x-ratelimit-remaining: Number of remaining requests in the current time window. Currently, the API has the following default limits:
Table 1. Default request rate limits
| Limit | Default Values |
|--|--|
| Max number of requests/day | 6000 requests/day |
| Max number of requests/second | 20 requests/second |
| Max number of allowed fields per request in the Knowledge Model | 200 fields/request |
| Max number of records per request returned when calling the /data endpoint | 50 records/request |
| Total maximum number of records that can be retrieved through the /data endpoint | First 5.000 records per filtered/sorted table |
Subscription to Trigger is also enforcing rate limiting. This means for a team, only a certain number of subscriptions can be created. In addition, no matter how many subscriptions are created, there is a maximum number of events that can be emitted from the API to the third parties consumers.
If a client reaches the maximum number of subscriptions, they will need to delete an existing subscription in order to create a new one.
If a client reaches the maximum number of events emitted from the API, the rest of data produced by Celonis Platform will be discarded.
If the client is approaching their daily quota, they will be informed via emails to your admin account. The first email will be sent when 80% of the quota is exceeded, letting your admin account know that you're over that percentage. The second email will be sent as soon as you exceed 100% of the quota.
Currently, the API has the following default limits:
Table 2. Default event rate limits
| Limit | Default Values |
|--|--|
| Max number of subscriptions/team | 10 |
| Max number of events/day | 100,000 |
Please consult your account team to verify your team's limits.
Frequently Asked Questions
Please refer to the Frequently Asked Questions section in Celonis Developer Portal.
Deployment Instructions
Required. Add instructions on how to deploy this connector as custom connector.
Creating a connection
The connector supports the following authentication types:
| Default | Parameters for creating connection. | All regions | Not shareable |
Default
Applicable: All regions
Parameters for creating connection.
This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.
| Name | Type | Description | Required |
|---|---|---|---|
| Team | string | Please specify the Celonis team. | True |
| Cluster | string | Please specify the Celonis cluster. | True |
| Authorization | securestring | The Authorization for this api | True |
Throttling Limits
| Name | Calls | Renewal Period |
|---|---|---|
| API calls per connection | 100 | 60 seconds |
Actions
| Creates a subscription for the trigger |
Creates a subscription for the trigger |
| Get a list of KM Filters |
List of Filters for the Knowledge Model |
| Get a list of KM Record data |
Data for a Record in the Knowledge Model |
| Get a list of KM Records schema |
List of Records schema |
| Get a list of KM Triggers |
List of Triggers for the Knowledge Model |
| Get a list of KMs |
List of Knowledge Models defined in an EMS team |
| Get a list of Subscriptions |
List of all Subscriptions created |
| Get the top-level KM details |
Knowledge Model defined in an EMS team |
| Get the top-level KM Record Schema details |
Top-level Record Schema details |
| Pauses the subscription to stop receiving events |
Pauses the subscription to stop receiving events |
| Resumes paused subscription to start receiving events again |
Resumes paused subscription to start receiving events again |
| Resumes subscription to start receiving new events, discarding history events |
Resumes paused subscription to start receiving new events again, discarding history events |
| Retrieves the next page of events weren't forwarded due to a failed subscription |
Retrieves the next page of events if they were not forwarded due to a failed subscription |
| Unsubscribe from a trigger removing all the data for the subscription |
Unsubscribe from a trigger removing all the data for the subscription |
| Updates a subscription |
Updates a subscription |
Creates a subscription for the trigger
Creates a subscription for the trigger
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Km Id
|
km_id | True | string |
The Knowledge Model Id |
|
Trigger Id
|
trigger_id | True | string |
The Trigger Id |
|
headers
|
headers | object |
Callback headers may contain authentication token, content type, etc. |
|
|
protocol
|
protocol | True | string |
Only value possible actually is HTTPS which means the callback URI must be a valid https |
|
uri
|
uri | True | string |
Uri to perform the callback from Intelligence API once the trigger is fired |
|
configurations
|
configurations | array of string |
Configuration for the Subscription |
|
|
name
|
name | True | string |
Name for the subscription |
Returns
- response
- string
Get a list of KM Filters
List of Filters for the Knowledge Model
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Page
|
page | integer |
The page number of the result, starting by 0 (first page) |
|
|
Page Size
|
pageSize | integer |
The number of items returned in a page. |
|
|
Sorting
|
sort | string |
Defines the strategy to proceed for case insensitive sorting. It must be just one field, and it should start with "+" to apply ASC order or "-" to apply DESC order. Non prefix will sort as ASC. Non existing field at the header will throw an error |
|
|
Knowledge Model ID
|
km_id | True | string |
Knowledge Model ID |
Returns
- Filter schema result page
- filterResultPage
Get a list of KM Record data
Data for a Record in the Knowledge Model
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Knowledge Model ID
|
km_id | True | string |
Knowledge Model ID |
|
Record ID
|
record_id | True | string |
Record ID |
|
Filters
|
filters | array |
A predefined filter id |
|
|
Field IDs
|
fields | True | array |
A predefined filter id |
|
Page
|
page | integer |
The page number of the result, starting by 0 (first page) |
|
|
Page Size
|
pageSize | integer |
The number of items returned in a page. |
|
|
Sorting
|
sort | array |
Defines the strategy to proceed for sorting. It must be a comma separated list of fields, and they should start with "+" to apply ASC order or "-" to apply DESC order. Fields with no prefix will be sorted as ASC. Non existing fields at the header will throw an error |
|
|
Filter Expression
|
filterExpr | array |
Dynamic filter expressions |
Returns
- Record data result page
- recordResultPageDTO
Get a list of KM Records schema
List of Records schema
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Page
|
page | integer |
The page number of the result, starting by 0 (first page) |
|
|
Page Size
|
pageSize | integer |
The number of items returned in a page. |
|
|
Sorting
|
sort | string |
Defines the strategy to proceed for case insensitive sorting. It must be just one field, and it should start with "+" to apply ASC order or "-" to apply DESC order. Non prefix will sort as ASC. Non existing field at the header will throw an error |
|
|
Knowledge Model ID
|
km_id | True | string |
Knowledge Model ID |
Returns
- Record schema result page
- recordSchemaResultPage
Get a list of KM Triggers
List of Triggers for the Knowledge Model
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Page
|
page | integer |
The page number of the result, starting by 0 (first page) |
|
|
Page Size
|
pageSize | integer |
The number of items returned in a page. |
|
|
Sort
|
sort | string |
Defines the strategy to proceed for case insensitive sorting. It must be just one field, and it should start with "+" to apply ASC order or "-" to apply DESC order. Non prefix will sort as ASC. Non existing field at the header will throw an error |
|
|
Km Id
|
km_id | True | string |
The Knowledge Model Id |
Returns
- Trigger schema result page
- triggerResultPage
Get a list of KMs
List of Knowledge Models defined in an EMS team
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Page
|
page | integer |
The page number of the result, starting by 0 (first page) |
|
|
Page Size
|
pageSize | integer |
The number of items returned in a page. |
|
|
Sorting
|
sort | string |
Defines the strategy to proceed for case insensitive sorting. It must be just one field, and it should start with "+" to apply ASC order or "-" to apply DESC order. Non prefix will sort as ASC. Non existing field at the header will throw an error |
Returns
- KnowledgeModel result page
- knowledgeModelResultPage
Get a list of Subscriptions
List of all Subscriptions created
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Page
|
page | integer |
The page number of the result, starting by 0 (first page) |
|
|
Page Size
|
pageSize | integer |
The number of items returned in a page. |
|
|
Sort
|
sort | string |
Defines the strategy to proceed for case insensitive sorting. It must be just one field, and it should start with "+" to apply ASC order or "-" to apply DESC order. Non prefix will sort as ASC. Non existing field at the header will throw an error |
Returns
- Subscription schema result page
- subscriptionResultPage
Get the top-level KM details
Knowledge Model defined in an EMS team
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Knowledge Model ID
|
km_id | True | string |
Knowledge Model ID |
Returns
Knowledge Model data's structure
- Knowledge Model
- knowledgeModelDetailedDTO
Get the top-level KM Record Schema details
Top-level Record Schema details
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Knowledge Model ID
|
km_id | True | string |
Knowledge Model ID |
|
Record ID
|
record_id | True | string |
Record ID |
Returns
Record represents a concept inside a Knowledge Model
- Record Type
- recordDTO
Pauses the subscription to stop receiving events
Pauses the subscription to stop receiving events
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Subscription Id
|
subscription_id | True | string |
The subscription Id will be paused |
Resumes paused subscription to start receiving events again
Resumes paused subscription to start receiving events again
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Subscription Id
|
subscription_id | True | string |
The subscription Id will be resumed and start to receiving event again |
Resumes subscription to start receiving new events, discarding history events
Resumes paused subscription to start receiving new events again, discarding history events
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Subscription Id
|
subscription_id | True | string |
The subscription Id will be resumed without receiving passed events |
Retrieves the next page of events weren't forwarded due to a failed subscription
Retrieves the next page of events if they were not forwarded due to a failed subscription
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Subscription Id
|
subscription_id | True | string |
The subscription Id that will retrieve failed event sent, in a maximum 50 items |
Returns
- Signal result page
- SignalResultPage
Unsubscribe from a trigger removing all the data for the subscription
Unsubscribe from a trigger removing all the data for the subscription
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Subscription Id
|
subscription_id | True | string |
The subscription Id will be deleted |
Updates a subscription
Updates a subscription
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Subscription Id
|
subscription_id | True | string |
The subscription Id that will be entirely updated |
|
headers
|
headers | object |
Callback headers may contain authentication token, content type, etc. |
|
|
protocol
|
protocol | True | string |
Only value possible actually is HTTPS which means the callback URI must be a valid https |
|
uri
|
uri | True | string |
Uri to perform the callback from Intelligence API once the trigger is fired |
|
configurations
|
configurations | array of string |
Configuration for the Subscription |
|
|
name
|
name | True | string |
Name for the subscription |
Definitions
SignalResultPage
| Name | Path | Type | Description |
|---|---|---|---|
|
content
|
content | array of signalDTO | |
|
pageSize
|
pageSize | integer |
Page size, defined by the system |
filterDTO
Filter to apply in a KM
| Name | Path | Type | Description |
|---|---|---|---|
|
description
|
description | string |
Human understandable Filter description |
|
id
|
id | string |
Filter's Unique identifier |
|
name
|
name | string |
Human understandable Filter display name |
filterResultPage
| Name | Path | Type | Description |
|---|---|---|---|
|
page
|
page | integer |
Page |
|
pageSize
|
pageSize | integer |
Page size, defined by pageSize parameter |
|
sort
|
sort | string |
Field used to apply sorting to the requested data, + or no symbol means ASC, - means DESC |
|
total
|
total | integer |
Total elements returned in the page |
|
content
|
content | array of filterDTO |
knowledgeModelDetailedDTO
Knowledge Model data's structure
| Name | Path | Type | Description |
|---|---|---|---|
|
id
|
id | string |
Unique Identifier of Knowledge Model |
|
name
|
name | string |
Human understandable text |
|
extendedKMId
|
extendedKMId | string |
Knowledge model used as reference, KM base. |
knowledgeModelResultPage
| Name | Path | Type | Description |
|---|---|---|---|
|
page
|
page | integer |
Page |
|
pageSize
|
pageSize | integer |
Page size, defined by pageSize parameter |
|
sort
|
sort | string |
Field used to apply sorting to the requested data, + or no symbol means ASC, - means DESC |
|
total
|
total | integer |
Total elements returned in the page |
|
content
|
content | array of knowledgeModelSimplifiedDTO |
knowledgeModelSimplifiedDTO
Knowledge Model data's structure
| Name | Path | Type | Description |
|---|---|---|---|
|
id
|
id | string |
Unique Identifier of Knowledge Model |
|
name
|
name | string |
Human understandable text |
|
published
|
published | string |
Latest published date |
recordDTO
Record represents a concept inside a Knowledge Model
| Name | Path | Type | Description |
|---|---|---|---|
|
description
|
description | string |
Record description |
|
id
|
id | string |
Record's Unique identifier |
|
name
|
name | string |
Record display name, a human understandable name |
|
fields
|
fields | array of recordFieldDTO |
recordFieldDTO
Fields for a Record
| Name | Path | Type | Description |
|---|---|---|---|
|
format
|
format | string |
Format to be applied |
|
id
|
id | string |
Amount pending to pay |
|
name
|
name | string |
human understandable name |
|
type
|
type | string | |
|
unit
|
unit | string |
Unit added to field value |
recordIdDTO
Record Type's id and name
| Name | Path | Type | Description |
|---|---|---|---|
|
description
|
description | string |
Record description |
|
id
|
id | string |
Record's Unique identifier |
|
name
|
name | string |
Record display name, a human understandable name |
recordItemDTO
| Name | Path | Type | Description |
|---|---|---|---|
|
data
|
data | array of |
List of record item, compound with name and value |
|
headers
|
headers | array of recordItemHeaderDTO |
recordItemHeaderDTO
| Name | Path | Type | Description |
|---|---|---|---|
|
aggregation
|
aggregation | boolean |
Indicate if a field is a aggregation/calculated information(KPI). |
|
filterable
|
filterable | boolean |
Indicate if the field could be filtered. |
|
format
|
format | string |
Format expression |
|
id
|
id | string |
Field identity to use in field list param and filterExpression param |
|
name
|
name | string |
Human understandable text |
|
sortable
|
sortable | boolean |
Indicate if the field could be sorted. |
|
type
|
type | string |
Possible data types. |
|
unit
|
unit | string |
A complementary sign for format value view |
recordResultPageDTO
| Name | Path | Type | Description |
|---|---|---|---|
|
page
|
page | integer |
Page |
|
pageSize
|
pageSize | integer |
Page size, defined by pageSize parameter |
|
sort
|
sort | array of string | |
|
total
|
total | integer |
Total elements returned in the page |
|
Record Item
|
content | recordItemDTO |
recordSchemaResultPage
| Name | Path | Type | Description |
|---|---|---|---|
|
page
|
page | integer |
Page |
|
pageSize
|
pageSize | integer |
Page size, defined by pageSize parameter |
|
sort
|
sort | string |
Field used to apply sorting to the requested data, + or no symbol means ASC, - means DESC |
|
total
|
total | integer |
Total elements returned in the page |
|
content
|
content | array of recordIdDTO |
signalDTO
Signal stored at subscription
| Name | Path | Type | Description |
|---|---|---|---|
|
signal
|
signal | string |
Raw json of a signal |
|
subscriptionId
|
subscriptionId | string |
Subscriber's Unique identifier as a SUID |
|
triggerId
|
triggerId | string |
Trigger's Unique identifier as a SUID |
|
creationDate
|
creationDate | date-time |
Date of the signal creation |
subscriptionDTO
Subscription schema
| Name | Path | Type | Description |
|---|---|---|---|
|
configurations
|
configurations | array of string |
Configuration for the Subscription |
|
id
|
id | string |
Subscriber's Unique identifier as a SUID |
|
knowledgeModelId
|
knowledgeModelId | string |
Unique Identifier of Knowledge Model |
|
latestSucceedEvent
|
latestSucceedEvent | date-time |
Date of the last succeeded event |
|
name
|
name | string |
Human understandable Subscription name |
|
status
|
status | string | |
|
triggerId
|
triggerId | string |
Trigger's Unique identifier as a SUID |
subscriptionResultPage
| Name | Path | Type | Description |
|---|---|---|---|
|
page
|
page | integer |
Page |
|
pageSize
|
pageSize | integer |
Page size, defined by pageSize parameter |
|
sort
|
sort | string |
Field used to apply sorting to the requested data, + or no symbol means ASC, - means DESC |
|
total
|
total | integer |
Total elements returned in the page |
|
content
|
content | array of subscriptionDTO |
triggerDTO
Trigger defined at KM
| Name | Path | Type | Description |
|---|---|---|---|
|
id
|
id | string |
Trigger's Unique identifier as a SUID |
|
name
|
name | string |
Human understandable Trigger name |
|
record
|
record | string |
Record's Unique identifier as a SUID |
triggerResultPage
| Name | Path | Type | Description |
|---|---|---|---|
|
page
|
page | integer |
Page |
|
pageSize
|
pageSize | integer |
Page size, defined by pageSize parameter |
|
sort
|
sort | string |
Field used to apply sorting to the requested data, + or no symbol means ASC, - means DESC |
|
total
|
total | integer |
Total elements returned in the page |
|
content
|
content | array of triggerDTO |
string
This is the basic data type 'string'.