Introduction¶

In this tutorial, you will learn how to use PyCelonis to perform basic interactions with Celonis Studio. More specifically, you will learn:

• What Celonis Studio is and how its general workflow is structured
• How to create spaces, packages, and variables in Studio
• How to add Studio assets, such as analyses or knowledge models, into the package
• How to publish packages to make them available in Celonis Apps
• How to update packages and how to specify a new version number

Prerequisites¶

To follow this tutorial, you should have PyCelonis installed and should know how to perform basic interactions with PyCelonis objects. If you don't know how to do this, please complete the Celonis Basics tutorial first. Further, it would be helpful to already have a data model inside your EMS. Please refer to the Data Push tutorial for an overview how to push data into the EMS and create a data model out of it.

Tutorial¶

Celonis Studio is a development platform, in which analysts and app creators can leverage data from the EMS to create various assets, such as analyses, knowledge models, or action flows. These assets are organized into packages, which, in turn, are organized into spaces. A space can contain multiple packages and a package can contain multiple assets. An asset can use data from different data models.

Once all desired assets are created inside a package in Celonis Studio, the package can be published with a certain version number. The assets inside the package are then available in Celonis Apps for end-users to interact with them.

Note:
Assets in Celonis Apps are read-only as its purpose is to provide Celonis assets for end-users to interact with them. If we want to create or modify assets, we have to use Celonis Studio.

1. Import PyCelonis and connect to Celonis API¶

In [3]:

from pycelonis import get_celonis
celonis = get_celonis()

from pycelonis import get_celonis celonis = get_celonis()

[2023-12-12 14:56:11,879] INFO: No `base_url` given. Using environment variable 'CELONIS_URL'
[2023-12-12 14:56:11,880] INFO: No `api_token` given. Using environment variable 'CELONIS_API_TOKEN'

[2023-12-12 14:56:11,972] WARNING: KeyType is not set. Defaulted to 'APP_KEY'.

[2023-12-12 14:56:11,974] INFO: Initial connect successful! PyCelonis Version: 2.6.0
[2023-12-12 14:56:11,977] INFO: `package-manager` permissions: ['$ACCESS_CHILD', 'MANAGE_PERMISSIONS', 'EDIT_ALL_SPACES', 'CREATE_SPACE', 'DELETE_ALL_SPACES']
[2023-12-12 14:56:11,978] INFO: `workflows` permissions: []
[2023-12-12 14:56:11,979] INFO: `task-mining` permissions: []
[2023-12-12 14:56:11,979] INFO: `action-engine` permissions: []
[2023-12-12 14:56:11,980] INFO: `team` permissions: []
[2023-12-12 14:56:11,980] INFO: `process-repository` permissions: []
[2023-12-12 14:56:11,981] INFO: `process-analytics` permissions: ['CREATE_WORKSPACE', 'MOVE_TO', 'DELETE_ALL_WORKSPACES', 'DELETE_ALL_ANALYSES', 'EDIT_ALL_ANALYSES', 'EDIT_ALL_WORKSPACES', 'USE_ALL_ANALYSES', 'CREATE_ANALYSES', 'MANAGE_PERMISSIONS', 'EXPORT_CONTENT']
[2023-12-12 14:56:11,982] INFO: `transformation-center` permissions: []
[2023-12-12 14:56:11,982] INFO: `storage-manager` permissions: ['DELETE', 'CREATE', 'GET', 'ADMIN', 'LIST']
[2023-12-12 14:56:11,983] INFO: `event-collection` permissions: ['USE_ALL_DATA_MODELS', '$ACCESS_CHILD', 'EDIT_ALL_DATA_POOLS', 'CREATE_DATA_POOL']
[2023-12-12 14:56:11,985] INFO: `user-provisioning` permissions: []
[2023-12-12 14:56:11,986] INFO: `ml-workbench` permissions: ['DELETE_SCHEDULERS', 'EDIT_SCHEDULERS', 'USE_ALL_SCHEDULERS', '$ACCESS_CHILD', 'USE_ALL_APPS', 'CREATE_SCHEDULERS', 'MANAGE_ALL_APPS', 'CREATE_WORKSPACES', 'MANAGE_SCHEDULERS_PERMISSIONS', 'VIEW_CONFIGURATION', 'CREATE_APPS', 'MANAGE_ALL_MLFLOWS', 'CREATE_MLFLOWS', 'USE_ALL_MLFLOWS', 'MANAGE_ALL_WORKSPACES']

2. Create a space¶

When we work on a new PyCelonis project and don't have any Celonis Studio assets inside our EMS, the first step will be to create a new space. Spaces are the main structural elements of the Studio service and are used to organize Studio assets. It is required to have a space in place before other Studio assets can be created.

In [4]:

space = celonis.studio.create_space("PyCelonis Tutorial Space")
space

space = celonis.studio.create_space("PyCelonis Tutorial Space") space

[2023-12-12 14:56:12,003] INFO: Successfully created space with id '4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a'

Out[4]:

Space(id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a', name='PyCelonis Tutorial Space')

3. Add package to the space¶

Packages are used to bundle various Celonis assets, such as analyses, knowledge models, or action flows, into apps which can then be published to end-users via Celonis Apps. It is required to have a package in place before other Celonis assets can be created. A new package can be created by calling the create_package() method from the parent-object space. The method takes as input arguments:

Name	Type	Description	Default
name	str	Displayable name of the package	Required
key	str	Unique key which can be used to identify the package (Is optional and defaults to name when left out)	None

In [5]:

package = space.create_package(name="PyCelonis Tutorial Package", key="pycelonis_tutorial_package")
package

package = space.create_package(name="PyCelonis Tutorial Package", key="pycelonis_tutorial_package") package

[2023-12-12 14:56:12,019] INFO: Successfully created package with id '154c2053-f380-4c60-b93a-216ed5dc48ce'

Out[5]:

Package(id='154c2053-f380-4c60-b93a-216ed5dc48ce', key='pycelonis_tutorial_package', name='PyCelonis Tutorial Package', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')

We can verify that the package exists inside our space by calling the get_packages() method:

In [6]:

space.get_packages()

space.get_packages()

Out[6]:

[
	Package(id='154c2053-f380-4c60-b93a-216ed5dc48ce', key='pycelonis_tutorial_package', name='PyCelonis Tutorial Package', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')
]

4. Add variables to the package¶

Another important point to consider when working with Celonis Studio is to define package variables. These variables are used to store information on a package-level and can be referenced by various assets inside the package. It is a best-practice to use package variables instead of hardcoding the information into the assets, since we have a single source of truth and we can easily change information across multiple assets.

A new package variable can be created by calling the create_variable() inside a package. The method takes the following input arguments:

Name	Type	Description	Default
key	str	Unique key to identify the variable	Required
value	str	Value that should be written into the variable (Content depends on the type of created variable)	Required
type_	str	Type of created variable (Supported values: DATA_MODEL, PLAIN_TEXT)	Required

4.1 Data Model Variables¶

Data model variables are used to reference a specific data model from various Celonis assets. When creating a new data model variable, type_ must be set to DATA_MODEL and value must be set to the data model ID.

In order to get the data model ID, we first navigate to the data model we want to use:

In [7]:

data_pool = celonis.data_integration.get_data_pools().find("PyCelonis Tutorial Data Pool")
data_model = data_pool.get_data_models().find("PyCelonis Tutorial Data Model")
data_model

data_pool = celonis.data_integration.get_data_pools().find("PyCelonis Tutorial Data Pool") data_model = data_pool.get_data_models().find("PyCelonis Tutorial Data Model") data_model

Out[7]:

DataModel(id='bed857a0-6bbc-40de-9d62-bd6f8b5a6b31', name='PyCelonis Tutorial Data Model', pool_id='9af14578-0fdf-4f76-ad0e-e529181f30bc')

Now, we can create the data model variable and link the data model to it:

In [8]:

data_model_variable = package.create_variable(key="pycelonis_tutorial_data_model",
                                              value=data_model.id,
                                              type_="DATA_MODEL")
data_model_variable

data_model_variable = package.create_variable(key="pycelonis_tutorial_data_model", value=data_model.id, type_="DATA_MODEL") data_model_variable

[2023-12-12 14:56:12,095] INFO: Successfully created variable with key 'pycelonis_tutorial_data_model'

Out[8]:

Variable(key='pycelonis_tutorial_data_model', type_='DATA_MODEL', value='bed857a0-6bbc-40de-9d62-bd6f8b5a6b31')

4.2 Plain Text Variables¶

Plain text variables store simple text values, which can be used by various Celonis assets. When creating a new plain text variable, type_ must be set to PLAIN_TEXT and value can be an arbitrary String value:

In [9]:

text_variable = package.create_variable(key="pycelonis_tutorial_text",
                                        value="PyCelonis Tutorial Text",
                                        type_="PLAIN_TEXT")
text_variable

text_variable = package.create_variable(key="pycelonis_tutorial_text", value="PyCelonis Tutorial Text", type_="PLAIN_TEXT") text_variable

[2023-12-12 14:56:12,110] INFO: Successfully created variable with key 'pycelonis_tutorial_text'

Out[9]:

Variable(key='pycelonis_tutorial_text', type_='PLAIN_TEXT', value='PyCelonis Tutorial Text')

4.3 Accessing package variables¶

To show all available variables inside a package, we can call the get_variables() method:

In [10]:

package.get_variables()

package.get_variables()

Out[10]:

[
	Variable(key='pycelonis_tutorial_data_model', type_='DATA_MODEL', value='bed857a0-6bbc-40de-9d62-bd6f8b5a6b31'),
	Variable(key='pycelonis_tutorial_text', type_='PLAIN_TEXT', value='PyCelonis Tutorial Text')
]

To access a specific variable, we can call the get_variable() method and pass the variable key as input argument:

In [11]:

variable = package.get_variable(key="pycelonis_tutorial_text")
variable

variable = package.get_variable(key="pycelonis_tutorial_text") variable

Out[11]:

Variable(key='pycelonis_tutorial_text', type_='PLAIN_TEXT', value='PyCelonis Tutorial Text')

Note:
Unlike other assets in Celonis Studio, variables do not have an ID but only a key, over which they can be accessed.

5. Add folder to the package¶

A new folder can be created with the create_folder() method inside a package. The method takes as input arguments:

Name	Type	Description	Default
name	str	Displayable name of the folder	Required
key	str	Unique key to identify the folder (Is optional and defaults to name when left out)	None

In [12]:

folder = package.create_folder(name="PyCelonis Tutorial Folder", key="pycelonis_tutorial_folder")
folder

folder = package.create_folder(name="PyCelonis Tutorial Folder", key="pycelonis_tutorial_folder") folder

[2023-12-12 14:56:12,152] INFO: Successfully created folder with id '709e1a9c-3a4b-449c-a1bb-1c67a93def64'

Out[12]:

Folder(id='709e1a9c-3a4b-449c-a1bb-1c67a93def64', key='pycelonis_tutorial_folder', name='PyCelonis Tutorial Folder', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')

We can display all folders inside our package by calling the get_folders() method:

In [13]:

package.get_folders()

package.get_folders()

Out[13]:

[
	Folder(id='709e1a9c-3a4b-449c-a1bb-1c67a93def64', key='pycelonis_tutorial_folder', name='PyCelonis Tutorial Folder', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')
]

6. Add Analysis to the package¶

A new analysis can be created by calling the create_analysis method inside a package. The method takes the following input arguments:

Name	Type	Description	Default
name	str	Displayable name of the analysis	Required
key	str	Unique key to identify the analysis (Is optional and defaults to name when left out)	None
data_model_id	str	ID of the data model to which the analysis is linked. A best practice is to use a data model variable instead of hard-coding the ID into the analysis. A data model variable can be referenced in the format: ${{key}}	None

In [14]:

analysis = package.create_analysis(name="PyCelonis Tutorial Analysis",
                                   key="pycelonis_tutorial_analysis",
                                   data_model_id="${{pycelonis_tutorial_data_model}}")
analysis

analysis = package.create_analysis(name="PyCelonis Tutorial Analysis", key="pycelonis_tutorial_analysis", data_model_id="${{pycelonis_tutorial_data_model}}") analysis

[2023-12-12 14:56:12,187] INFO: Successfully created analysis with id '67a0a08a-448a-4eff-944a-f98f8fe6a569'

Out[14]:

Analysis(id='67a0a08a-448a-4eff-944a-f98f8fe6a569', key='pycelonis_tutorial_analysis', name='PyCelonis Tutorial Analysis', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')

We can display all analyses inside our package by calling the get_analyses() method:

In [15]:

package.get_analyses()

package.get_analyses()

Out[15]:

[
	Analysis(id='67a0a08a-448a-4eff-944a-f98f8fe6a569', key='pycelonis_tutorial_analysis', name='PyCelonis Tutorial Analysis', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')
]

7. Add knowledge model to the package¶

A new knowledge model can be created by calling the create_knowledge_model() method inside a package and passing the content of the knowledge model as input argument. The content of the knowledge model is defined as dictionary. PyCelonis then takes this dictionary and creates a YAML file out of it, which is used by the EMS to create the knowledge model.

Here, we simply create an empty knowledge model with some metadata that references our data model variable. However, it is also possible to define additional content that should be part of the knowledge model, such as records, KPIs, and filters.

In [16]:

content = {
    "kind" : "BASE",
    "metadata" : {"key":"pycelonis_tutorial_km", "displayName":"PyCelonis Tutorial Knowledge Model"},
    "dataModelId" : "${{pycelonis_tutorial_data_model}}"
}

content = { "kind" : "BASE", "metadata" : {"key":"pycelonis_tutorial_km", "displayName":"PyCelonis Tutorial Knowledge Model"}, "dataModelId" : "${{pycelonis_tutorial_data_model}}" }

In [17]:

knowledge_model = package.create_knowledge_model(content)
knowledge_model

knowledge_model = package.create_knowledge_model(content) knowledge_model

[2023-12-12 14:56:12,227] INFO: Successfully created knowledge model with id '7870b7c3-b401-4d60-b2fc-8a0fda34aad8'

Out[17]:

KnowledgeModel(id='7870b7c3-b401-4d60-b2fc-8a0fda34aad8', key='pycelonis_tutorial_km', name='PyCelonis Tutorial Knowledge Model', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')

We can display all knowledge models inside our package by calling the get_knowledge_models() method:

In [18]:

package.get_knowledge_models()

package.get_knowledge_models()

Out[18]:

[
	KnowledgeModel(id='7870b7c3-b401-4d60-b2fc-8a0fda34aad8', key='pycelonis_tutorial_km', name='PyCelonis Tutorial Knowledge Model', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')
]

We can access the current YAML configuration of a knowledge model via its serialized_content property:

In [19]:

print(knowledge_model.serialized_content)

print(knowledge_model.serialized_content)

kind: BASE
metadata:
  key: pycelonis_tutorial_km
  displayName: PyCelonis Tutorial Knowledge Model
dataModelId: ${{pycelonis_tutorial_data_model}}

8. Publish a package¶

Once we are finished with building assets, we can publish the package to make them available to end-users via Celonis Apps. A package can be published by calling the publish() method inside a package. The method takes the following input arguments:

Name	Type	Description	Default
version	str	Version of the published app (Format: Major.Minor.Patch, Example: 1.0.4)	None
node_ids_to_exclude	List[str]	List of asset IDs, which should not be published in Celonis Apps	None

Let's publish our newly created package as version 1.0.0 and exclude the folder, since it is currently empty:

In [21]:

package.publish(version="1.0.0", node_ids_to_exclude=[folder.id])

package.publish(version="1.0.0", node_ids_to_exclude=[folder.id])

[2023-12-12 14:56:12,314] INFO: Successfully published package with id '154c2053-f380-4c60-b93a-216ed5dc48ce' with version '1.0.0'

9. Access assets in Celonis Apps¶

Once assets in a package have been published, they can be accessed via Celonis Apps by end-users. PyCelonis also supports accessing published assets in Celonis Apps. However, since Celonis Apps is read-only, PyCelonis only supports get_<asset>() methods but no create_<asset>() methods.

Let's start by accessing the space, in which our assets have been created by calling get_space() inside celonis.apps and passing the space ID as input parameter.

Note:
All IDs for assets inside Celonis Apps are exactly the same as in Celonis Studio.

In [22]:

app_space = celonis.apps.get_space(space.id)
app_space

app_space = celonis.apps.get_space(space.id) app_space

Out[22]:

PublishedSpace(id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a', name='PyCelonis Tutorial Space')

Assets inside Celonis Apps can be recognized by the prefix Published<asset>. We can now access the package, in which our assets are located by calling the get_package() method inside our Celonis Apps space and passing the package ID as argument:

In [23]:

app_package = app_space.get_package(package.id)
app_package

app_package = app_space.get_package(package.id) app_package

Out[23]:

PublishedPackage(id='154c2053-f380-4c60-b93a-216ed5dc48ce', key='pycelonis_tutorial_package', name='PyCelonis Tutorial Package', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')

From this package, we can access published Celonis assets via the get_<asset>s() method for all assets of a certain type or the get_<asset>("id") method for a specific asset:

In [24]:

app_package.get_analyses()

app_package.get_analyses()

[2023-12-12 14:56:12,354] INFO: `get_analyses` returns analyses without content. To fetch the content for a specific analysis call`analysis.sync()` or use `package.get_analysis(analysis_id)`

Out[24]:

[
	PublishedAnalysis(id='67a0a08a-448a-4eff-944a-f98f8fe6a569', key='pycelonis_tutorial_analysis', name='PyCelonis Tutorial Analysis', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')
]

In [26]:

published_analysis = app_package.get_analysis(analysis.id)

published_analysis = app_package.get_analysis(analysis.id)

10. Updating packages and versioning¶

When making changes to assets inside Celonis Studio, we have to publish the package again, as otherwise the changes will not be available in Celonis Apps. This can be easily done by calling the publish() method each time we want to publish an update and passing a new version number in the format MAJOR.MINOR.PATCH as input argument.

Note:
The version number can also be left out, in which case the version will simply increment by one PATCH number (e.g. 1.0.4 -> 1.0.5).

Let's update our app by deleting the analysis from our package:

In [27]:

analysis.delete()

analysis.delete()

[2023-12-12 14:56:12,434] INFO: Successfully deleted content node with id '67a0a08a-448a-4eff-944a-f98f8fe6a569'

By calling get_analyses() from our package, we can see that the analysis has been successfully removed:

In [28]:

package.get_analyses()

package.get_analyses()

Out[28]:

[]

However, when calling the same method from the app-package, the analysis still exists. This is because we have not published our changes yet:

In [29]:

app_package.get_analyses()

app_package.get_analyses()

[2023-12-12 14:56:12,460] INFO: `get_analyses` returns analyses without content. To fetch the content for a specific analysis call`analysis.sync()` or use `package.get_analysis(analysis_id)`

Out[29]:

[
	PublishedAnalysis(id='67a0a08a-448a-4eff-944a-f98f8fe6a569', key='pycelonis_tutorial_analysis', name='PyCelonis Tutorial Analysis', root_node_key='pycelonis_tutorial_package', space_id='4f1c47f1-c5e5-46db-93b3-a2243ed3bc4a')
]

To do this, we simply call the publish() method another time and specify a new version number for our package:

In [30]:

package.publish(version="2.0.0")

package.publish(version="2.0.0")

[2023-12-12 14:56:12,486] INFO: Successfully published package with id '154c2053-f380-4c60-b93a-216ed5dc48ce' with version '2.0.0'

By calling the get_analyses() again from the app-package, we can see that the changes have been published in Celonis Apps:

In [31]:

app_package.get_analyses()

app_package.get_analyses()

[2023-12-12 14:56:12,495] INFO: `get_analyses` returns analyses without content. To fetch the content for a specific analysis call`analysis.sync()` or use `package.get_analysis(analysis_id)`

Out[31]:

[]

Conclusion¶

Congratulations! You have learned how to perform basic interactions with Celonis Studio, such as creating new assets, publishing a package, and pushing updates into Celonis Apps. This is the end of the PyCelonis tutorials. You should now be able to write Python scripts that leverage various assets of the EMS, which can be used for performing analyses and running machine learning algorithms.