BPMN Importer Configuration

The BPMN Importer Configuration allows you to import BPMN diagrams from other platforms (such as Signavio or Bizagi) and use them in Celonis Process Management (CPM) without loss of data integrity.

The configuration file

The configuration is an XML file composed of mapping rules. Each rule primarily consists of:

A Match section: Defines criteria to identify specific extension elements.
An Actions section: Specifies operations to perform on matched elements.

Actions range from simple data extraction and string manipulation to complex operations like foreach loops and invoking internal CPM functions.

Basic XML structure

<?xml version="1.0" encoding="UTF-8"?>
<Configuration
    xmlns="http://schemas.symbioworld.com/plugins/bpmn-import/v1"
    xmlns:ref="local:references"  xmlns:engine="local:engine">  <Variables>
    <Variable Key="MyGlobalVariable1" Value="value of MyGlobalVariable1" />
    <Variable Key="xmlns:foo" Value="urn:my_global_xml_namespace_definition" />
  </Variables>

  <Mappings>
    <Rule Attribute="ATX_CUSTOM_MY_ATTRIBUTE_1" CultureIndependent="true">
      <Match>
        </Match>

      <Variable Key="MyScopedVariable1" Value="value of MyScopedVariable1" />

      <Actions>
        </Actions>
    </Rule>
  </Mappings>
</Configuration>

This structure provides a clear framework. Let's delve into each component.

Variables

Variables store reusable values, reducing repetition and improving maintainability. They can be defined globally (under <Configuration>/<Variables ) or scoped to a specific rule (under <Rule>/<Variable> ). XML namespace prefixes (e.g. xmlns:signavio) should also be defined as variables to be usable in XPath expressions.

Declaration syntax

Simple Value (string literal):

<Variable Key="variableName" Value="my simple string value" />
<Variable Key="xmlns:custom" Value="urn:my-custom-namespace" />

Complex Value (structured data):

<Variable Key="variableName">
  </Variable>

Complex values allow for richer, structured data. They require corresponding C# type definitions registered within the application.

Built-in variables (provided by the execution engine):

$ExtensionElementsRoot – The XmlElement containing the <extensionElements /> XML element from the input BPMN file.
$MatchedElement : The first element matched in the Match phase of rule execution. Automatically passed to the first action in the Accumulator variable.
$AllMatchedElements : All elements matched in the Match phase of rule execution.
$Entity : The process designer IEntity object. May be null.
$Shape : The process designer IShape object. May be null.

Rules

Defined within the <Mappings> element, rules are the core of the configuration. Each <Rule> dictates:

Target Elements: Which XML elements within <extensionElements /> (or which BPMN elements themselves) it processes.
Conditions: Additional criteria for when the rule should execute.
Processing Logic: The sequence of actions to apply to the matched data.

Rule Attributes:

Attribute (Optional): Where the final value is stored after executing actions. If not specified, the actions are responsible to storing the value.
CultureIndependent (Optional): If true, the value is saved using the invariant culture; otherwise, the current culture is used. Defaults to false if not specified.

Example

Consider this BPMN file fragment:

<extensionElements>
  <myExtensionElement key="key1" value="[ 'value1', 'value2' ]" />
  <myExtensionElement key="key2" value="value3" />
</extensionElements>

And the following 2 rules:

<Rule>
  <Match>
    <Element XPath="myExtensionElement[@key='key1']" />
  </Match>
  <Actions>
    <XPathSelect XPath="string(@value)" />
    <ForEachJsonItem>
      <Invoke Implementation="DoSomething" />
    </ForEachJsonItem>
  </Actions>
</Rule>
<Rule>
  <Match>
    <Element XPath="*[@key='key2']" />
  </Match>
  <Actions>
    <XPathSelect XPath="string(@value)" />
    <Invoke Implementation="DoSomething" />
  </Actions>
</Rule>

In Match section, we use Element instructing to match the extension element using an XPath expression. Notice that the expression is designed to return a set of XML elements. The matched elements are then available to actions defined in Actions section.

In Actions section, we use a couple of steps to process the value:

XPathSelect is used to extract the value from the attribute value.
ForEachJsonItem is used to iterate on the value items (value1 and value2).
Invoke is used to call an internal function that does something specific with the value.

Match constraints (<Match> )

<Rule Attribute="ATX_TARGET_ATTRIBUTE">
  <Match> <Element XPath="custom:data[@type='Type1']" xmlns:custom="urn:example" />
    <Entity Type="MTX_SUB_PROCESS" />
    <Element XPath="*[@key='key1']" />
  </Match>
  <Match> 
    <Element XPath="custom:otherData[@status='Urgent']" xmlns:custom="urn:example" />
  </Match>
  <Actions>
    </Actions>
</Rule>

A Rule must have 1 or more Match sections.
A rule is considered valid, when at least 1 Match section is satisfied. By adding multiple Match sections, we can combine different rules with identical actions.
Each Match section contains one or more Match constraints.

Actions

The <Actions> element lists operations executed sequentially. The output of one action typically becomes the input for the next.

Action Parameters:

Simple String Attribute:

<Action MyParamName="My literal parameter value" />

Complex Value via <Arg> Element:

<Action>
  <Arg Name="MyParamName">
    <!-- A complex value -->
  </Arg>
</Action>

Value passed from a variable defined elsewhere:

<!-- Concise syntax (ref namespace must be defined): -->
<Action ref:MyParamName="MY_VARIABLE_NAME" />

<!-- Verbose syntax -->
<Action>
  <Arg Name="MyParamName" Ref="MY_VARIABLE_NAME" />
</Action><Action MyParamName="My literal parameter value" />

The Accumulator : Implicit Input/Output in Actions

Every action implicitly receives one parameter internally called Accumulator, and writes its result again to the Accumulator variable.

Consider the following configuration:

<Actions>
  <!-- 1: [Implicit] Initial extension element is stored in Accumulator -->
  <!-- 2: Action1 receives the element stored in Accumulator -->
  <!-- 3: Action1 is executed -->
  <Action1 />
  <!-- 4: Action1 stores its result in Accumulator -->
  <!-- 5: Action2 receives the element stored in Accumulator (i.e. the value from Action1) -->
  <!-- 6: Action2 is executed -->
  <Action2 />
  <!-- 7: Action2 stores its result in Accumulator -->
  <!-- 8: [Implicit] Value in Accumulator is saved in Celonis attribute -->
</Actions>

As we can see, a value flows through actions, is modified on its way and ultimately is saved in CPM attribute. However, sometimes this implicit value flow is not desired, and we can override it by reading/storing the value in a variable of our choice.

<Actions>
  <Action1 engine:Result="MyIntermediateVariable" />
  <Action2 engine:Input="MyIntermediateVariable" engine:Result="MyFinalVariable" />
</Actions>

As we can see, we can bypass the Accumulator variable mechanism and opt to storing to another variable. This might be useful if we need to retain value from previous steps of the execution pipeline (because Accumulator is always overwritten).

Value conversions

When passing values (via Accumulator or parameters), the runtime attempts to convert the source value to the type expected by the action. Conversion attempts include:

Any C# type to Newtonsoft JToken.
Newtonsoft JToken to any C# type.
String or integer to a C# enum.
Using source and target TypeConverters.
Convert.ChangeType() method.

Reference

List of Match Constraints

<Entity /> (EntityConstraint)

Satisfied if the currently processed entity (associated with the BPMN element) matches the specified TypeType in CPM.

Attributes

Type (Required): The CPM entity type name (e.g., MTX_SUB_PROCESS, OT_FUNC).

Example

<Match> <Entity Type="MTX_SUB_PROCESS" /> </Match>

<Element />Element (XmlElementConstraint)

Satisfied if an XML element within <extensionElements/> matches the specified XPath expression.

Attributes

XPath (Required): An XPath expression evaluated against the children of <extensionElements/>. It should select the desired element(s).
Collect (Optional): If true (default), the matched element(s) are made available via $MatchedElement and $AllMatchedElements variables. Set to false if this element constraint is purely conditional and its matched value isn't directly needed by actions.
xmlns:* (Optional): Declare any XML namespace prefixes used in the XPath expression (e.g., xmlns:custom="urn:my-custom-ns").

Behavior

The first XML element matched by this constraint (if Collect="true") becomes $MatchedElement and is typically the initial input to the actions.
All matched elements (if Collect="true") are available in $AllMatchedElements.

Example

<Match>
  <Element XPath="*[@key='my-key']" />

  <Element XPath="myPrefix:MyExtensionElement[@key='my-key']" xmlns:myPrefix="urn:example-vendor" />
</Match>

<BpmnElement /> (BpmnElementConstraint)

Satisfied if the BPMN element currently being processed is of the specified Type.

Attributes

Type (Required): BPMN element name (e.g., Lane, Task, StartEvent, Process, Collaboration, TextAnnotation).

Example

<Match>
<BpmnElement Type="Lane" />
</Match>

<Any /> (AnyConstraint)

Satisfied if at least one of its child constraints is met (OR logic).

Example

The constraint below is satisfied if the Celonis entity type is OT_FUNC OR OTX_FUNC_GLOBAL

<Match>
  <Any>
    <Entity Type="OT_FUNC" />
    <Entity Type="OTX_FUNC_GLOBAL" />
  </Any>
</Match>

List of CPM entity types

MTX_SUB_PROCESS: the sub process diagram
MTX_MAIN_PROCESS: the main process diagram
MTX_SUB_CATEGORY: the category type
OT_FUNC: the task type
OTX_FUNC_GLOBAL: the global task type
OTX_EV_START: start event type
OTX_EV_INTERMEDIATE: intermediate event type
OTX_EV_END: end event type
OT_TECH_TRM: the technical Term type

List of complex types

These types can be used within <Variable> declarations or as <Arg> values for actions.

<Dict /> (XmlDictionaryValue)

The Dict is a simple structure for providing a list of key-value pairs.

Structure

<Dict>
  <Entry Key="key1" Value="stringValue1" />
  <Entry Key="key2">
    <List> <Item Value="nestedItem" /> </List>
  </Entry>
</Dict>

<List /> (XmlListValue)

The List is a simple structure for providing a list of values.

<List>
  <Item Value="value1" />
  <Item>
    <Dict> <Entry Key="k" Value="v" /> </Dict>
  </Item>
</List>

<JSON /> (XmlJsonValue)

Contains a JSON formatted string. Internally parsed as a Newtonsoft.Json.Linq.JToken, allowing flexible data structures (objects, arrays, primitives) and broad compatibility with action parameters due to value conversions.

Structure and examples

<JSON>
{
  "key1": "value1",
  "nestedObject": { "prop": 123 }
}
</JSON>

<JSON>[ "arrayItem1", true, null, 42 ]</JSON>

<JSON>"A simple JSON string"</JSON>

<JSON>100.5</JSON>

For JSON containing characters like <, >, &, use XML entities or a CDATA section:

<JSON>
<![CDATA[
{
  "message": "Text with < & > special characters."
}
]]>
</JSON>

Note on Parsing: Uses Newtonsoft.Json. This library is lenient and may accept JSON that is technically invalid (e.g., unquoted keys, trailing commas).

List of Actions

Actions define the processing steps within a rule.

>Copy /> (CopyAction)

Copies a value from an input variable to a result variable (by reference). Useful for preserving the Accumulator or other values.

Parameters

engine:Input (Optional): Variable to copy from. Defaults to Accumulator.
engine:Result (Required): Variable to copy to.

Example

<Copy engine:Input="MyVariable1" engine:Result="MyVariable2" />
<Copy engine:Result="MyCopyOfAccumulator" />

<ForEach /> (ForEachAction)

Iterates over items in an input collection (must implement IEnumerable). Each item is passed to child actions.

Parameters

engine:Input (Optional): The enumerable variable to iterate. Defaults to Accumulator.
engine:Result (Required): Variable to store the current item in each iteration. Defaults to Accumulator. (overwriting it for child actions).

Child Actions: Executed for each item. The item is placed in the variable specified by engine:Result (or Accumulator). The final state of this variable after child actions for one item does not carry to the next iteration directly; rather the main Accumulator of the <ForEach> action itself is the collection of results from each iteration if no engine:Result is specified on the ForEach and if child actions modify their input. Typically, ForEach is used for side-effects or when child actions themselves save results elsewhere.

Example

<ForEach> <MyAction />
  <AnotherAction />
</ForEach>

<ForEach engine:Input="MyListVariable" engine:Result="currentItemVar">
  <MyAction ref:Param1="currentItemVar" />
</ForEach>

<ForEachJsonItem /> (ForEachJsonItemAction)

Similar to <ForEach />, but specifically for JSON arrays. Input is expected to be a JSON array (or convertible to JArray). Each item (a JToken) is passed to child actions.

Parameters

engine:Input (Optional): Variable containing the JSON array. Defaults to Accumulator.
engine:Result (Optional): Variable to store the current JToken item. Defaults to Accumulator.
Strict (Optional, boolean): If false (default), attempts to parse non-array JSON as a single-item array. If true, expects a strict JSON array.

Example

<ForEachJsonItem Strict="false">
  <MyAction />
  <AnotherAction />
</ForEachJsonItem>

<ForEachJsonString /> (ForEachJsonStringAction)

Similar to <ForEachJsonItem />, but each item passed to child actions is converted to its string representation.

Parameters

Same as <ForEachJsonItem />. Item type passed to children is string.

Example

<ForEachJsonString Strict="false">
  <MyAction />
  <AnotherAction />
</ForEachJsonString>

<Invoke /> (InvokeAction)

The Invoke action calls a function with name specified in the Implementation parameter. Methods exposed through this action usually provide a core functionality such as reading, writing, or creating CPM objects.

Parameters

Implementation (Required): Name of the internal function to call.
Other parameters depend on the specific implementation. Can be passed as attributes, <Arg> children, or ref: attributes.
Implicit Input/Output: Many implementations expect input from the Accumulator and write their result back to it.

Example

<Invoke Implementation="SomeInternalFunction" />
<Invoke Implementation="SomeInternalFunction" Param1="Value1" />
<Invoke Implementation="SomeInternalFunction" ref:Param1="VARIABLE1" />
<Invoke Implementation="SomeInternalFunction">
  <Arg Name="Param1">
    <!-- A complex value -->
  </Arg>
</Invoke>

<MapArray/> (MapArrayAction)

Transforms an input array by applying child actions to each item, constructing a new array from the results. same as the map method in Javascript

outputArray = inputArray.map(item => { /* child actions logic on item */ return modifiedItem; });

Parameters

engine:Input (Optional): Input array variable. Defaults to Accumulator.
engine:Result (Optional): Output array variable. Defaults to Accumulator.
engine:Item (Optional): Variable name for the current item being processed within child actions. Defaults to Accumulator.
Strict (Optional): If false (default), a non-array input is treated as a single-item array. If true, expects an array.

Example

The Accumulator (or specified engine:Input) should be an array. Each item from the input array is processed by MyAction, and the results form a new array which updates the Accumulator (or engine:Result).

<MapArray engine:Item="item" Strict="false">
  <MyAction engine:Input="item" />
</MapArray>

<Map/> (MapValueAction)

Looks up the input value in a provided mapping dictionary and outputs the corresponding mapped value.

Parameters

engine:Input (Optional): Input value to look up. Defaults to Accumulator.
engine:Result (Optional): Variable to store the mapped value. Defaults to Accumulator.
Mapping (Required): The dictionary used for lookup. Must be convertible to IDictionary<string, object>. Can be provided as a complex value (<Dict /> or <JSON />) or a variable reference.

Example

<Map ref:Mapping="MY_MAPPING_TABLE_VARIABLE" />
<Map>
  <Arg Name="Mapping">
    <Dict>
      <Entry Key="input1" Value="output1" />
      <Entry Key="input2" Value="output2" />
    </Dict>
  </Arg>
</Map>
<Map>
  <Arg Name="Mapping">
    <JSON>
    {
      "input1": "output1",
      "input2": "output2"
    }
    </JSON>
  </Arg>
</Map>

<ParseJson /> (ParseJsonAction)

The ParseJson action takes input value and converts it to Newtonsoft's JToken. The primary use case is parsing JSON strings; however, it is possible to pass any C# object, in which case JToken.FromObject(input) call is used.

Parameters

engine:Input (Optional): Input value. Defaults to Accumulator.
engine:Result (Optional): Variable to store the JToken. Defaults to Accumulator.
Strict (Optional, boolean): If false (default), uses lenient parsing.
ValidateType (Optional): Checks if the resulting JToken is of a specific JTokenType (e.g., "Array", "Object", "String"). Logs a warning if mismatched.

Example

<ParseJson ValidateType="Array" Strict="false" />

<JSONPathSelect /> (SelectJsonPathAction)

The JSONPathSelect action takes the input object, attempts to convert it to JToken JToken (either from JSON string or C# class), and applies a JSONPath expression. The result is either JArray or a singular JToken (depending on the TakeFirst parameter).

Parameters

Path: A JSONPath expression which selects JSON tokens from the input value.
TakeFirst: When provided, singular result JToken is returned; otherwise a JArray of tokens is returned.

Example

<JSONPathSelect Path="$.items[*].value" />

<JSONPathSelect Path="$.data.id" TakeFirst="true" engine:Result="FirstIdVar" />

<XPathSelect /> (SelectXPathAction)

The XPathSelect action takes the input object which must be of type XmlElement, and applies an XPath expression. The result can be a node set or a singular primitive value, depending on the expression.

Parameters

XPath (Required): The XPath expression, which is evaluated against the input XML element
mlns:* (Optional): Declare any XML namespace prefixes used in the XPath. These must be declared here or as in-scope variables (e.g. <Variable Key="xmlns:myPrefix" Value="urn:my-uri" />). Namespaces on parent XML elements in this config file (or the root) are not automatically inherited by XPathSelect.

Example

<XPathSelect XPath="string(@metaValue)" />

 <XPathSelect XPath=".//prefix:Books" xmlns:prefix="urn:bookstore-schema" />

<StringReplace /> (StringReplaceAction)

The StringReplace action can be used to manipulate string by replacing its parts. It supports start, end, and global string replacement.

Parameters

What (Required): The substring to be replaced.
Replacement: specifies the new value that is inserted in place of the old value. When not provided, substring is removed without replacement.
Location: Start, End, or unspecified. Specifies whether the string replacement occurs at the start, end, or globally respectively.

Example

<StringReplace What="/my/prefix/" Location="Start" />
<StringReplace What="/my/prefix/" Replacement="/another/prefix/" Location="Start" />

List of invoke implementations

ConnectApplicableDocument

<Invoke Implementation="ConnectApplicableDocument" />

Connects a Signavio extension applicable document.

Parameters

Implicit reference: The reference path to the applicable document.

ConnectIntermediateLinkEvent

<Invoke Implementation="ConnectIntermediateLinkEvent" />

Connects the Signavio extension intermediate link events.

Parameters

Implicit reference: The reference path to the (other) linked event.

ConnectLocation

<Invoke Implementation="ConnectLocation" />

Connects the Signavio extension location relation.

Parameters

Implicit reference: The reference path to the location.

ConnectMasterData

<Invoke Implementation="ConnectMasterData" />

Connects the Signavio extension master-data relation.

Parameters

Implicit reference: The reference path to the master data object.

ConnectOrganization

<Invoke Implementation="ConnectOrganization" />

Connects the Signavio extension organization relation.

Parameters

Implicit reference: The reference path to the organization.

ConnectRACIRoleAsAccountable

<Invoke Implementation="ConnectRACIRoleAsAccountable" />

Connects a RACI role as accountable.

Parameters

Implicit reference: The reference path to the role.

ConnectRACIRoleAsConsulted

<Invoke Implementation="ConnectRACIRoleAsConsulted" />

Connects a RACI role as consulted.

Parameters

Implicit reference: The reference path to the role.

ConnectRACIRoleAsInformed

<Invoke Implementation="ConnectRACIRoleAsInformed" />

Connects a RACI role as informed.

Parameters

Implicit reference: The reference path to the role.

ConnectRACIRoleAsResponsible

<Invoke Implementation="ConnectRACIRoleAsResponsible" />

Connects a RACI role as responsible.

Parameters

Implicit reference: The reference path to the role.

ConnectRiskControl

<Invoke Implementation="ConnectRiskControl" />

Connects the Signavio extension SOX control relation.

Parameters

Implicit reference: The reference path to the SOX control.

ConnectTransaction

<Invoke Implementation="ConnectTransaction" />

Connects the Signavio extension transaction relation.

Parameters

Implicit reference: The reference path to the transaction.

TransferProcessDocuments

<Invoke Implementation="TransferProcessDocuments" ref:StripPrefix="FILE_DICTIONARY_PREFIX" />

Parameters

Implicit rawValue: The BPMN extension raw value, containing the process document.
StripPrefix: Specifies a string that is stripped from the beginning of the input value.

TransferProcessExperts

<Invoke Implementation="TransferProcessExperts" />

Transfers the Signavio extension process experts to an attribute.

Parameters

Implicit rawValue: he BPMN extension raw value, containing the process experts.
Implicit attributeTypeName: The type name of the attribute to transfer the value to.
Implicit cultureIndependent: The flag whether the attribute to transfer the value to is culture independent.

TransferProcessItPartner

<Invoke Implementation="TransferProcessItPartner" />

Transfers the Signavio extension process IT Partner to an attribute.

Parameters

Implicit rawValue: The BPMN extension raw value, containing the process experts.
Implicit attributeTypeName: The type name of the attribute to transfer the value to.
Implicit cultureIndependent: The flag whether the attribute to transfer the value to is culture independent.

TransferProcessOwner

<Invoke Implementation="TransferProcessOwner" />

Transfers the Signavio extension process owner to a user relation.

Parameters

Implicit rawValue: The BPMN extension raw value, containing the process owner.
Implicit attributeTypeName: The type name of the attribute to transfer the value to.
Implicit cultureIndependent: The flag whether the attribute to transfer the value to is culture independent.

TransferSimpleText

<Invoke Implementation="TransferSimpleText" Append="true" />

Transfers the Signavio extension vision - as an text to append.

Parameters

Implicit rawValue: Implicit rawValue – The BPMN extension raw value, containing the process document.
Implicit attributeTypeName: The type name of the attribute to transfer the value to.
Implicit cultureIndependent: The flag whether the attribute to transfer the value to is culture independent.
Append: The flag determining whether to append or to replace the Celonis attribute value.

BPMN Importer Configuration

The configuration file

Basic XML structure

Variables

Rules

Actions

Reference

List of CPM entity types

List of complex types

List of Actions

List of invoke implementations

Search results