Skip to content

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 resources like Analysis, Data Models, Data Pools, Studio etc.

from pycelonis import get_celonis
celonis = get_celonis()

>>> [2022-01-01 10:00:00] INFO: Login successful! You are using an Application Key. PyCelonis Version: 1.6.0
>>> [2022-01-01 10:00:00] INFO: Your key has following permissions:
    [
        {
            "permissions": [
                "MANAGE_PERMISSIONS",
                "EDIT_ALL_SPACES",
                "CREATE_SPACE",
                "DELETE_ALL_SPACES"
            ],
            "serviceName": "package-manager"
        },
        {
            "permissions": [],
            "serviceName": "workflows"
        },
        {
            "permissions": [],
            "serviceName": "task-mining"
        },
        {
            "permissions": [
                "MANAGE_SSO_SETTINGS",
                "MANAGE_LICENSE_SETTINGS",
                "MANAGE_MEMBERS",
                "MANAGE_UPLINK_INTEGRATIONS",
                "MANAGE_GENERAL_SETTINGS",
                "MANAGE_GROUPS",
                "MANAGE_PERMISSIONS",
                "MANAGE_APPLICATIONS",
                "MANAGE_ADMIN_NOTIFICATIONS",
                "IMPORT_MEMBERS",
                "MANAGE_MEMBER_LOCKING_POLICY"
            ],
            "serviceName": "team"
        },
        {
            "permissions": [],
            "serviceName": "action-engine"
        },
        {
            "permissions": [],
            "serviceName": "process-repository"
        },
        {
            "permissions": [],
            "serviceName": "process-analytics"
        },
        {
            "permissions": [],
            "serviceName": "transformation-center"
        },
        {
            "permissions": [],
            "serviceName": "storage-manager"
        },
        {
            "permissions": [],
            "serviceName": "event-collection"
        },
        {
            "permissions": [],
            "serviceName": "ml-workbench"
        }
    ]

Celonis provides a comprehensive permission management system that allows customers to define permissions on the member level or on the role level in a coarse or granular fashion. When running PyCelonis in a Machine Learning Workbench an Application Key (with the same name as the workbench) is already provided via the environment variable CELONIS_API_TOKEN. By default, this key has very limited permissions (see the logs above). You can change the key's permissions in the Team Settings -> Permissions.

Alternatively, you can provide a personal API Key to PyCelonis. By default, the any personal API Key has the exact same permissions you have as a user. You can create one in Edit Profile -> API-Keys.

from pycelonis import get_celonis

api_token = "<paste your personal API Key here>"
celonis = get_celonis(api_token=api_token, key_type="USER_KEY")  # key_type is optional

>>> [2022-01-01 10:00:00] INFO: Login successful! Hello bob.ross@celonis.com. PyCelonis Version: X.X.X
>>> [2022-01-01 10:00:00] INFO: Your key has following permissions: 
    ...

Info

A common issue when using PyCelonis is missing permissions for analysis, data models, data pools, studio, etc. Please make sure you check these first before proceeding. To learn how to associate the Application Key with the correct permissions to interact with Celonis, see the video available on the help page.

For a more detailed description about permission management please visit the help page.

Initial connect and permissions

The initial connect is not a login. It checks whether the API Key is valid and the correct key_type is set. This is important as the key_type determines the authorization header value:

Key Type Authorization header
APP_KEY AppKey APP_TOKEN
USER_KEY Bearer API_TOKEN

You can check if the authorization header is set correctly:

from pycelonis import get_celonis

celonis = get_celonis()
celonis._session.headers.get("authorization")
>>> 'AppKey APP_TOKEN'

If you are sure that you set the correct key_typ and the API Key you are using has all required permissions, you can disable the initial connect and permissions output:

from pycelonis import get_celonis

celonis = get_celonis(connect=False, permissions=False)

Celonis Resource Objects

The Celonis Execution Management System (EMS) API resources are based on object relational mappings. Each resource contains an ID that uniquely identifies it. If a resource is related to another, e.g. a Space and a Package, it holds the reference to the resource by its ID.
Therefore, accessing resources in Pycelonis is based on these relations, e.g.: 

package = celonis.spaces.find("341b450c-7f92-26e6-b79c-2d38a1a87d38").packages.find("b3f1149b-2aff-462a-a793-f20bec9a7af1")

Alternatively, you can also fetch resources by name:

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

Info

In order to improve performance, it is recommended to use ID instead of name.

Working with Celonis Resource Objects

PyCelonis provides an easy-to-use way to update data or fetch the latest via the Celonis EMS API. The concept is based on the data property each Celonis object has (via inheritance from CelonisApiObject). Each time you access data it will fetch the latest resource data via the Celonis EMS API. Each time you set data it will update the resource via the Celonis EMS API.

o = celonis.<api-service>.find("<name or ID")

# This will execute a POST/PUT request to '<celonis_url>/<api-service>/api/...'
o.data["name"] = "New Name"

If you don't always want to update the resource via the Celonis EMS API you can disable this behaviour by setting the resource object's static property to True: 

o = celonis.<api-service>.find("<name or ID")
o.static = True

# This will NOT execute a any request
o.data["name"] = "New Name"

Understanding the connection to the Celonis EMS API

In order to understand how PyCelonis interacts with the Celonis EMS API you can enable debugging of PyCelonis:

celonis.spaces
>>> [
    <Space, id 28572e4b-a08f-4201-9764-12bfcd1f9873, name TEST>,
    <Space, id 4daa2d6e-af72-4d19-9399-f7b1d1639f49, name PYCELONIS>,
    ...
    ]

# set the loglevel to debug
import logging
logging.getLogger("pycelonis").setLevel(logging.DEBUG)

c.spaces
>>> [2022-01-01 10:00:00] DEBUG: GET -> https://<team>.<realm>.celonis.cloud/package-manager/api/spaces, {'timeout': 300}
>>> [
    <Space, id 28572e4b-a08f-4201-9764-12bfcd1f9873, name TEST>,
    <Space, id 4daa2d6e-af72-4d19-9399-f7b1d1639f49, name PYCELONIS>,
    ...
    ]

If you need further details on HTTPConnections set:

import http.client

http.client.HTTPConnection.debuglevel = 1

Robust connections to the Celonis EMS API

PyCelonis uses Python's requests library for networking. The Celonis Base object initializes the session which is used for all interactions with the Celonis EMS API. To improve the robustness of connections you can configure the session by passing the timeout, total_retry and backoff_factor arguments to get_celonis:

from pycelonis import get_celonis

# timeout (in seconds): How long to wait for the server to send data before giving up.
# total_retry: Total number of retries 
# backoff_factor (in seconds): Factor to apply between retry attempts after the second try 
#                              based on {backoff_factor} * (2 ** ({total_retry} - 1))


# This retry strategy will wait 30 seconds before the request will fail, 
# retry the request 5 times if the request failed with error codes=[429, 500, 502, 503, 504]
# and wait {backoff_factor} * (2 ** ({total_retry} - 1)) between every retry attempt, 
# e.g. backoff_factor=1, then the process will sleep for [1.0s, 2.0s, 4.0s, 8.0s, 16.0s]  
celonis = get_celonis(timeout=30, total_retry=5, backoff_factor=1)

For more detailed examples of how to use PyCelonis check out Celonis API Tutorial.

Back to top