Main Concepts

Working with pycelonis is very simple. You first need to create a celonis instance, which can then be used to interact with all your Celonis object, like Analyses, Data Models, Data Pools etc. ::

from pycelonis import get_celonis
celonis = get_celonis()

When doing this the first time in a ML Workbench you will see a message like this:

“2020-04-16 09:39:54 - pycelonis: Login successful! Hello Application Key, this key currently has access to 0 analyses.”

This means that the connection has been established through the Application Key of the ML Workbench. By default this has very limited Permissions. For example you are not able to access any Anlayses or Datamodels. You can however associate all necessary permissions. For details on how to associate the Application Key with the right permissions to interact with Celonis objects, have a look at the video found in the help of your celonis team. This can be accessed under the folowing link: ::

Optionally you can connect to celonis using your personal API-Key. The personal API-Key has the exact same rights you have as a user. You can create a personal API-key in Celonis by first clicking on your icon on the top right and then on EDIT PROFILE. Here you find the option. Copy the created API-Key and use it like this: ::

from pycelonis import get_celonis
celonis = get_celonis(api_token="YOUR_PERSONAL_API_TOKEN")

“2020-04-16 09:53:45 - pycelonis: Login successful! Hello MaxMustermann.”

Process Analytics

Now that you have created the celonis instance, you can use it to interact with different areas and objects of your Celonis Team. To see which objects you have access to, you can simply list them, e.g. to see which anlyses you have access to, use:


“[<Analysis, id b34a1fc7-324-4b13-bded-234234, name Open Cash Discount>,
<Analysis, id a8d25417-234-4786-a1e5-234234, name Duplicate Checking Results>,
<Analysis, id 2f1c0434-c30f-4766-a734-be964ca6d8fb, name OTD Regression >,
<Analysis, id 23423-a7ab-4b0c-92de-4234, name Free Text Matching>,
<Analysis, id d6a970f4-c19c-44f5-234234-234234, name On-Time Delivery Prediction>,
…. “

If you now want to select one particular analysis you can use the name or id of the analysis. The code examples

analysis = celonis.analyses.find('b34a1fc7-324-4b13-bded-234234')

or equivalently,

analysis = celonis.analyses.find('Open Cash Discount')

lead to the same result:


“<Analysis, id b34a1fc7-c09e-4b13-bded-14f2f93bc9c2, name Open Cash Discount>”

If you now want to get the data from a particular OLAP-table (or any type of component) in your analysis into your python enviorment in form of a data frame this can be done as follows:

component = analysis.drafts.components.find('name or id of the component')
component_dataframe = component.get_data_frame()

Similarly to this you can select Workspaces and access the elements within the workspace.

Event Collection

You can also interact with the Data Pools and Data Models with a similar logic using the same celonis instance. You can access Data Pools, directly like this:

data_pool = celonis.pools.find("name or id of datapool")    

Data Models can be accessed directly as well, or from within a Data Pool

data_model = celonis.datamodels.find("name or id of datamodel")  


data_pool = celonis.pools.find("name or id of datamodel")  
data_model = data_pool.datamodels.find("name or id of datamodel")

Pulling data from Celonis first glimpse

With the objects in the Event Collection you can perform almost all actions that can be done in the UI also from within Python. For example you can directly get a column from a data pool (limited to 100 rows). This can be helpful in having a data preview in order to for example determine the data cleaning actions:

data_pool = celonis.pools.find("name or id of datapool")    
data_job = data_pool.create_data_job("my_data_job")
transformation = data_job.create_transformation("name_your_transformation", 'SELECT "table_name" from "column_name"')
transformation_df = transformation.get_data_frame()

Using the same celonis instance, you can also interact with data models and get the data into a dataframe leverging from PQL. See more on how to write PQL from Python in our PQL and Python tutorial in our Celonis API Tutorial.

from pycelonis.pql import PQL, PQLColumn, PQLFilter

data_model = celonis.datamodels.find("name or id of datamodel")
query = PQL()
query += PQLColumn("table_name.column_name", "new_name_for_df_column")
query += PQLColumn("table_name.column_name", "new_name_for_df_column")
column_df = datamodel.get_data_frame(query)

Pushing data to Celonis first glimpse

Once you are finished with all the processing and you can push the results back to your Data Pools and Data Models in order to save them together with your celonis data.

First push to a Data Pool:


Then add the results table to a your Data Model and partially load the new table:

data_model.add_table_from_pool("results_table_name", "results_table_alias", reload="PARTIAL_ON_TABLE")

More detailed examples can be found in our Celonis API Tutorial.

Next Steps

  • If you are not working inside of a Celonis ML Workbench install PyCelonis following the Installation Guide

  • Walk through the tutorials Celonis API Tutorial.

  • Looking for an overview of all the functionalities? Read the API Reference for details and advanced options.