Event Processing Rules

Celonis Product Documentation

Event Processing Rules - Text Editor

Note

Instead of manually writing the event processing rules as described on this page, you can also use the visual editor provided by the configuration editor. You will find it on the Event Processing Rules tab.

Depending on the use case and legal requirements (e.g. GDPR), it is necessary to restrict data collected by Task Mining to specific events, applications, URLs, and attributes. Also, it may be required to activate or deactivate screenshots or to hash specific attributes like the user name. Furthermore, it may also be required to define different privacy rules for different applications (e.g. taking screenshots for SAP, but not for e-mail clients). In order to deal with these requirements, the Task Mining desktop application provides a simple, but powerful language to define custom rules on event processing. On this page, we describe the language and give examples for common use cases.

Language description

The language consists of an arbitrary number of Event-Condition-Action (ECA) rules and a default rule. Each ECA rule consists of three parts:

Event: The Event part defines which user interaction events should trigger the rule, e.g., a rule should only be triggered by "Left click" and "Right-click" events.
Condition: The condition part restricts the rule to events with specific properties, e.g. to events that are related to a specific application. The condition part is optional. If no condition is defined, the rule applies to all triggering events.
Action: The action part defines how the events should be processed. It is only applied to events, that match the Event and the Condition part of the rule. The Action part consists of three different parts:
1. Logging: The Logging part defines which attributes of the event should be logged and which events should be omitted. For attributes that are omitted, only a default value (usually null) is stored. Please note, that some attributes are mandatory (e.g., timestamps) and therefore cannot be omitted.
2. Hashing: The Hashing part defines which attributes should be hashed. Please note, that some attributes cannot be hashed (e.g. timestamps). The Hashing part is optional. The hash function used is SHA256.
3. Screenshots: The Screenshots part defines the screenshot mode, i.e., what to capture with the screenshot (active window, active desktop, all desktops). The Screenshots part is optional and can be omitted if no screenshots should be captured.

The ECA rules are processed in the order of their definition. This means that an event is first evaluated against the first rule. If the event matches the Event and the Condition parts of the rule, the defined action is executed for the event. Otherwise, the event is evaluated against the second rule, and so on. If none of the ECA rules matches, the default rule is applied. As the default rule is a fallback for all events that do not match any ECA rule, the default rule only consists of an Action part.

Please note that for each event only the first rule that matches is applied, even if the event might match multiple rules. Therefore, the order of rules is important. You should always start with the most specific rule and end with the most general rule. Otherwise, the more general rule would also consume the events that should match the specific rule. If you, for example, want to take screenshots only for Excel, but not for any other application, you should define the specific rule for events from Excel before the more general rule that should be applied to all other applications.

Language definition

The following table gives a descriptive overview of the rule syntax and examples.

Important

The language is case-sensitive. For example, writing 'or' will not work and lead to a syntax error but 'OR' in upper case will work.

Name	Syntax	Description	Example
Rules	<rules> ::== ( <ECA rule> )* <default rule> <ECA rule> ::== <Description>? <Event> ( <Condition> )? <Action> <default rule> ::== DEFAULT <Description>? ( <Action> \| SKIP )	The event processing rules are defined by an arbitrary number (0 to N) ECA rules and a default rule. An ECA rule consists of an optional description, an Event definition, an optional Condition, and an Action part. If no ECA rule is defined, the default rule will be applied to all events. The default rule starts with the keyword `DEFAULT` followed by n optional description, followed by an Action definition or by the keyword `SKIP`. If the Action is defined, it will be executed for all events that did not match any ECA rule. If the `SKIP` keyword is used, all events that did not match any ECA rule are omitted, i.e. not logged.	DEFAULT SKIP The most simple Event Processing Rules statement, only consisting of the default rule omitting all events. This rule effectively switches off the logging for all events.
Description	<Description> ::== RULE <string expression> DESCRIPTION <string expression>	The description consists of the keyword `RULE` followed by a string expression giving the rule's name, and the keyword `DESCRIPTION` followed by a string expression giving a detailed description of the rule. SINCE 1.2.7	RULE 'Log Chrome events' DESCRIPTION 'Logging events for Google chrome with screenshots of the active window.'
Event	<Event> ::== ON ( ALL EVENTS ) \| ( ( EXCEPT )? <string list> )	The Event definition defines which events will trigger the rule. It allows to simply trigger for all events or only for specific events which are defined in a list of event names. The optional keyword `EXCEPT` allows to invert the list of triggering events, i.e., the rule matches for each event except for the listed ones.	ON ALL EVENTS This Event definition triggers the rule for all events. ON 'Left click', 'Right click' This Event definition triggers the rule only for click events. ON EXCEPT 'Left click', 'Right click' This Event definition triggers the rule for all events, but not for click events.
Condition	<Condition> ::== IF <boolean expression THEN	The Condition defines a constraint that needs to be fulfilled for the triggering events to match the rule. The condition is defined as boolean expression.	IF ProcessName = 'chrome' THEN The rule matches only if the event was fired by the Chrome browser.
Action	<Action> ::== <Logging> ( <Hashing> )? ( <Screenshots> )?	The Action defines how an event that matches the rule should be processed. It consist of a Logging definition, an optional Hashing definition, and an optional Screenshots definition.
Logging	<Logging> ::== LOG ( ALL \| ( ( EXCEPT )? <attribute list> ) )	The Logging defines which attributes should be logged. It is possible to log all attributes or only specific attributes which are defined in a list of attribute names. The optional keyword `EXCEPT` allows to invert the list of attributes in order tp omit specific attributes. Note: For attributes that are omitted, only a default value (usually null) is stored. Some attributes are mandatory (e.g., timestamps) and therefore cannot be omitted. These attributes are automatically included, even if they are not specified in the attribute list.	LOG ALL This will log all attributes. LOG URL, KeyboardCommand Besides the mandatory attributes, this will only log the URL and KeyboardCommand attributes. LOG EXCEPT URL, KeyboardCommand This will exclude the URL and KeyboardCommand attributes from logging.
Hashing	<Hashing> ::== HASH <attribute list>	The Hashing defines which attributes should be hashed before logging. If no attribute should be hashed, the Hashing could be left out. Note: Attributes that are omitted from logging, are also implicitly excluded from hashing. Not all attributes can be hashed (e.g. timestamps). Adding attributes to the list, that are not hashable, will result in an error.	HASH URL, SystemUser This will log the attributes URL and SystemUser only as hashed values.
Screenshots	<Screenshots> ::== TAKE SCREENSHOT ( ACTIVE_WINDOW \| ACTIVE_DESKTOP \| ALL_DESKTOPS )	Screenshots defines the screenshot capturing mode to either capture the active window, the active desktop, or all desktops (in case you have multiple screens). The Screenshots can be omitted if no screenshot should be captured.	TAKE SCREENSHOT ACTIVE_WINDOW Takes a screenshot from the active window. TAKE SCREENSHOT ACTIVE_DESKTOP Takes a screenshot from the active desktop. TAKE SCREENSHOT ALL_DESKTOPS Takes a screenshot from all desktops.

Boolean expressions

Expressions are used to specify the condition of a rule. The expressions can be constructed from the following operators:

Name	Syntax	Description	Example
Comparison	<Comparison> ::== <left expression> <Comparison operator> <right expression> <Comparison operator> ::== '=' \| '!=' \| '<' \| '<=' \| '>' \| '>='	Compares two expressions with each other and evaluates it to a boolean depending on the given Comparison operator. Both input expressions need to have the same type. Available Comparison operators: equal (`=`) not equal (`!=`) less than (`<`) less equal than (`<=`) greater than (`>`) greater equal than (`>=`) The input expressions can either be an attribute or a constant value	URL = 'https://www.celonis.com/' Compares the URL attribute to a string constant for equality. ScreenshotWidth > 0 Checks if the ScreenshotWidth attribute is greater than 0.
IN	<In> ::== <expression> IN ( <value list> )	Checks if an expression evaluates to one of the given values. Note: All values of the value list must be of the same type. The value list supports `STRING`, `INT`, and `FLOAT` values.	ProcessName IN ( 'chrome', 'OUTLOOK', 'explorer') Checks if the ProcessName attribute evaluates to one of the given process names (applications).
NOT	<Not> ::== NOT <boolean expression>	Inverts a boolean expression.	NOT URL = 'https://www.celonis.com/' Checks if the URL is not https://www.celonis.com/
IS NULL	<Is null> ::== <expression> IS ( NOT )? NULL	Checks if an expression evaluates to null. Optionally, one can check if the value is not null by using the `NOT` keyword.	ActiveWindow IS NULL Checks if the ActiveWindow attribute is not set. ActiveWindow IS NOT NULL Checks if the ActiveWindow attribute is set to a value.
AND	<And> ::== <boolean expression> ( AND <boolean expression> )+	Computes the logical AND of two or more boolean expressions. Note: Currently, there is no short cut evaluation, meaning that all boolean expressions are always evaluated.	ProcessName = 'chrome' AND URL = 'https://www.celonis.com/' Checks if both comparisons evaluate to true.
OR	<Or> ::== <boolean expression> ( OR <boolean expression> )+	Computes the logical OR of two or more boolean expressions. Note: Currently, there is no short cut evaluation, meaning that all boolean expressions are always evaluated.	ProcessName = 'chrome' OR URL = 'https://www.celonis.com/' Checks if at least one of the comparisons evaluates to true.
( )	<Parenthesis> ::== '(' <boolean expression> ')'	Paranthesis allow to logically structure boolean expression, e.g. if a different evaluation order than defined by the standard logical precedence is desired.	( ProcessName = 'chrome' OR URL = 'https://www.celonis.com/' ) AND ScreenshotWidth > 0 Logically structures the statement to evaluate the `OR` statement before the `AND` statement. The following example (without parameters) evaluates the `AND` before the `OR`: ProcessName = 'chrome' OR URL = 'https://www.celonis.com/' AND ScreenshotWidth > 0
CAST	<Cast> ::== CAST '(' <Type> ',' <expression> ')' <Type> ::== STRING \| INT \| FLOAT	Converts the given expression into another data type. Casting is supported for types `STRING`, `INT`, and `FLOAT`.	CAST ( STRING, ScreenshotWidth ) Converts the value of the Screenshot attribute to type `STRING`.
LIKE	<Like> ::== <string expression> LIKE <string pattern>	Evaluates if a string expression matches the given pattern. There are two different wildcard symbols to define the patterns: Percentage sign (%): Matches an arbitrary number of characters (also 0) Underscore ( _ ): Matches exactly one character The wildcard symbols can be escaped by a preceding backslash ( \ ), e.g. `\%` or `\_` . The backslash itself needs to be escaped by a double backslash ( `\\` ). The comparison is case-insensitive, i.e. the patterns `'%celonis%'` and `'%Celonis%'` will produce the same result.	ActiveWindow LIKE '%Unread Messages%' Matches if the ActiveWindow attribute contains the string "Unread Messages" ActiveWindow LIKE 'Celonis%' Matches if the ActiveWindow attribute starts with "Celonis" ActiveWindow LIKE '%Celonis' Matches if the ActiveWindow attribute ends with "Celonis"
DOMAIN	<Domain> ::== DOMAIN '(' <string expression> ')'	Maps a URL string to its domain, i.e. removes paths, ports, and protocol of the URL.	DOMAIN ( 'https://community.celonis.com/latest' ) Trims the given URL to its domain `community.celonis.com`

Event Processing Rules Editor

To define the Event Processing Rules in the configuration file, the configuration editor provides a simple code editor on the Event Processing Rules page. The configuration editor also provides a visual editor for event processing rules. However, the visual editor does not provide the full expressiveness of the language.

Despite the text field for editing the code, the editor also provides two dropdowns to insert a valid Event name (left-side) or a valid attribute (right-side). To insert an event name (attribute) at the current cursor position, select the desired event name (attribute) from the left (right) dropdown and click on the related Insert button.

Besides that, the editor will check all changes of the code and report errors below the text area:

Example Event Processing Rules for Standard Use Cases

Rules are Case-Sensitive

Be aware that all rules are case-sensitive. For example, if you want to denylist Slack and not capture any data.

Correct: This denylists slack so no events from Slack are captured (slack is lowercase):

ON ALL EVENTS
IF ProcessName NOT IN ('slack') THEN
LOG ALL
TAKE SCREENSHOT ACTIVE_WINDOW
DEFAULT SKIP

Wrong: This would fail and still capture data from Slack, as the actual process name is lowercase and not uppercase:

ON ALL EVENTS
IF ProcessName NOT IN ('Slack') THEN
LOG ALL
TAKE SCREENSHOT ACTIVE_WINDOW
DEFAULT SKIP

Name	Example	Description
Collect all with screenshots	ON ALL EVENTS LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW DEFAULT SKIP Alternative: DEFAULT LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW	Collects all events without any restrictions with a screenshot of the active window.
Avoid duplicate events for Chrome	ON ALL EVENTS IF ProcessName = 'chrome' AND ExtensionName = 'chrome' OR ProcessName != 'chrome' THEN LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW DEFAULT SKIP	Logs all events with all attributes and takes screenshots for the active window, but filters out all events coming from chrome that were not captured by the chrome extension. This avoids duplicate events (e.g. left clicks) that are detected by the Task Mining desktop application and the Task Mining Extension for Chrome.
Only allow selected applications	ON ALL EVENTS IF ProcessName IN ('chrome', 'explorer', 'Slack') THEN LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW DEFAULT SKIP	Restricts the logging of events to a set of defined applications (Chrome, Windows Explorer, and Slack). How to retrieve the ProcessName of your application.
Deny selected applications	ON ALL EVENTS IF ProcessName NOT IN ('chrome', 'explorer', 'Slack') THEN LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW DEFAULT SKIP	Excludes the defined applications (Chrome, Windows Explorer, and Slack) from logging. How to retrieve the ProcessName of your application.
Only allow selected URLs for Chrome	ON ALL EVENTS IF DOMAIN (URL) LIKE '%.celonis.com' THEN LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW DEFAULT SKIP ON ALL EVENTS IF DOMAIN (URL) LIKE '%.celonis.com' OR ProcessName != 'chrome' THEN LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW DEFAULT SKIP	Restricts the logging of events to a set defined URLs. Here, we restrict the logging to www.celonis.com and all related subdomains (e.g. community.celonis.com) The first example omits all other events coming from other applications than Chrome because they do not provide any URL information. The second example also includes all events that are coming from other applications than Chrome.
Deny selected URLs for Chrome	ON ALL EVENTS IF ProcessName = 'chrome' AND ExtensionName = 'chrome' AND DOMAIN (URL) NOT LIKE '%.celonis.com' OR ProcessName != 'chrome' THEN LOG ALL TAKE SCREENSHOT ACTIVE_WINDOW DEFAULT SKIP	Excludes a set of defined URLs from logging. Events for chrome that are detected by the Task Mining desktop application are omitted as they do not provide URL information and would also capture one of the excluded websites.

Was this helpful?

Would you like to provide feedback? Just click here to suggest edits.