Installation¶

PyCelonis is a Python client library for the Celonis Execution Management System (EMS) API and can be used to interact with various resources of the Celonis EMS, such as data pools, tables, analyses, and knowledge models. PyCelonis can be used to develop custom Python scripts for your data science and machine learning projects and is intended to be used inside the Celonis Machine Learning (ML) Workbench.

In this tutorial, you will learn:

• How to create a new app inside the ML Workbench
• How to install PyCelonis with pip

Prerequisites:¶

To follow this tutorial, you need to have a Celonis EMS team set up.

Tutorial¶

PyCelonis is mainly used inside the ML Workbench - an integrated Python development environment based on Jupyter Notebook, which allows you to build Python scripts as apps inside the Celonis EMS. The ML Workbench already comes with PyCelonis and all dependencies pre-installed and automatically sets login configurations for the Celonis API. Further, the ML Workbench offers trigger and scheduling functionalities to automate those Python scripts. However, it is also possible to use PyCelonis outside the ML Workbench in your own IDE.

1. Create an app inside the ML Workbench¶

To get started with PyCelonis, we first need to create a new ML Workbench app. To do this, we navigate to the ML Workbench (Data -> Machine Learning), create a new app, and select Jupyter Workbench as application type.

2. Install PyCelonis¶

When using the ML Workbench, PyCelonis and all dependencies are already pre-installed, so we can simply import the package:

In [1]:

import pycelonis

import pycelonis

/opt/hostedtoolcache/Python/3.8.18/x64/lib/python3.8/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

However, if for some reason, PyCelonis is not pre-installed, we can get the package via pip:

In [ ]:

skip-execution

!pip install pycelonis

!pip install pycelonis

In case you are working outside the ML Workbench, you have to additionally specify the extra-index-url:

In [ ]:

skip-execution

!pip install --extra-index-url=https://pypi.celonis.cloud/ pycelonis

!pip install --extra-index-url=https://pypi.celonis.cloud/ pycelonis

PyCelonis uses semantic versioning. At Celonis, we are constantly working to improve the EMS. In order to keep up with all the latest features or bug fixes PyCelonis gets patched regularly. Therefore, we recommend limiting upgrades to the current major and minor version.

This will make sure that you don't accidentally upgrade to a version, which may include breaking changes that break your scripts.

To check which version is currently installed, you can execute the command:

In [2]:

print(pycelonis.__version__)

print(pycelonis.__version__)

2.11.1

Celonis periodically updates the ML Workbench with the latest version of PyCelonis. However, if for some reason, the latest version is not installed, we can upgrade PyCelonis with the command:

Additionally, we recommend creating a lockfile before upgrading via pip freeze:

pip freeze > requirements.txt

Now, the lockfile can be used for installation:

pip install -r requirements.txt

In [ ]:

skip-execution

!pip install --upgrade pycelonis pycelonis_core

!pip install --upgrade pycelonis pycelonis_core

If we want to install a particular version of PyCelonis, we can use the following command:

In [ ]:

skip-execution

!pip install pycelonis=="2.0.*"

!pip install pycelonis=="2.0.*"

Conclusion¶

Congratulations! You have learned how to setup a new Python project inside the ML Workbench and how to install PyCelonis on it. In the next tutorial Celonis Basics, you will learn how to use PyCelonis to connect to the Celonis EMS and access specific resources.