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/
Email	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

1. A team in Celonis Platform.
2. A Knowledge Model available in a client's team.
3. 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:

1. Create the token in Celonis: MDg5MGVkNDktNjMwZC00ODdiLTkyNGItMjNmMzMxNjRmM2IwOkhNUVRMUis4SGh6NHhBY21Vck9GaWdkem5rYzBrb3p0N056WUM0bGlqczMM
2. 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:

1. Create the AppKey in Celonis:
   MzgyZDEzYjItNjI1MS00NTIwLTk1YTItY2ZjYzMzZTllOTNmOkE3a1dvYnpYQ0c3aUtUdTNRNC9UNzFLUXZmY0E2ZjVXUUROajFoN1R5UzIr
2. 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 Permissions from 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 PACKAGE rights.

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

Operation ID:

createSubscription

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

Operation ID:

getFilters

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

Operation ID:

getRecordDataResult

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

Operation ID:

getRecords

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

Operation ID:

getTriggers

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

Operation ID:

getKnowledgeModel

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

Operation ID:

getSubscriptions

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

Operation ID:

getKnowledgeModelDetails

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

Operation ID:

getRecordDetails

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

Operation ID:

pauseSubscription

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

Operation ID:

resumeSubscription

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

Operation ID:

resumeSubscriptionNoHistory

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

Operation ID:

nextPageFromRemainingData

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

Operation ID:

unsubscribe

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

Operation ID:

updateSubscription

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'.