Skip to main content
Version: 2.4

BPMN XML Reference

Overview​

Business Process Model and Notation (BPMN) is a widely adopted industry standard for modeling business processes. It allows businesses to represent their workflows in a graphical, XML-based format, enabling automation and integration with various systems. In tSM, we use BPMN to model processes and extend its functionality through specific custom extensions.

BPMN can be directly edited in the tSM Process Designer, where it serves as the full definition of the process. You can transfer processes between environments by using copy & paste, or by utilizing the backup and restore functionality. When transferring BPMN definitions, ensure that the process ID remains unchanged and that all referenced entities (such as user groups, skills, statuses, etc.) are correctly in place to avoid errors during execution.

BPMN Standard and XML Definition​

The BPMN XML format defines the structure of a business process in an interoperable way, meaning the process can be shared between different systems and tools. The key XML namespaces ensure that the process is recognized and executable by BPMN-compliant engines.

Here is an example of a basic BPMN XML definition:

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
                  xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
                  xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
                  xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
                  id="Definitions_1gs58qx"
                  targetNamespace="http://bpmn.io/schema/bpmn">
    <!-- BPMN Process Definitions -->
</bpmn:definitions>

The BPMN standard XML format allows tools to easily import and export process models, making it possible to collaborate across different systems, including analytical tools like Camunda Modeler, Signavio, and others.

Camunda BPMN Extensions​

Camunda process engine extends the BPMN standard by introducing additional execution logic and attributes to make the models executable. These extensions allow you to define tasks, assign roles, and handle process flow with conditions. The Camunda extensions can also specify how tasks are executed, paused, or restarted, with attributes like camunda:asyncBefore or camunda:jobPriority.

Here’s an example with Camunda extensions:

<bpmn:process id="ExampleProcess" isExecutable="true" camunda:versionTag="1.0">
    <bpmn:userTask id="Task1" name="Review Task" camunda:assignee="${user}">
        <bpmn:extensionElements>
            <camunda:taskListener event="create" class="com.example.TaskListener" />
        </bpmn:extensionElements>
    </bpmn:userTask>
</bpmn:process>

In this example, Camunda-specific attributes like camunda:assignee and camunda:taskListener are used to control task assignment and execution.

More details about Camunda BPMN extensions can be found in the official Camunda documentation.

tSM-Specific Extensions​

In addition to BPMN and Camunda extensions, tSM introduces custom attributes to tailor the process definitions for telecommunication service management. These extensions offer extra capabilities like defining task specifications, skills required, material management, and more.

The tsm namespace is used to include these custom extensions:

<bpmn:definitions xmlns:tsm="http://tsm.datalite.cz/schema/1.0/bpmn">
    <bpmn:process id="TSMProcess" isExecutable="true">
        <bpmn:userTask id="Task1" tsm:taskDefinition="WFM_TASK" tsm:skills="INSTALL_CPE" tsm:defaultUserGroup="FIELD_SOUTH">
            <bpmn:extensionElements>
                <tsm:statusListener expression="${logService.info('task status', ticket.id)}" status="IN_PROGRESS"/>
            </bpmn:extensionElements>
        </bpmn:userTask>
    </bpmn:process>
</bpmn:definitions>

tSM BPMN Extensions Reference​

This reference lists the tSM BPMN attributes used to extend the standard BPMN workflow capabilities in tSM. These attributes allow for advanced task management, assignment, and process customization. All expressions use Spring Expression Language (SpEL) for dynamic evaluations.

Attribute Reference​

  • tsm:taskDefinition
    Task can be associated with a specific template, defining its behavior. Example: tsm:taskDefinition="EXAMPLE_TEMPLATE"

  • camunda:assignee
    Assigns the task to a specific user.
    Example: camunda:assignee="#{ticket.whoInserted}"

  • camunda:candidateGroups
    Specifies the user groups eligible to handle the task.
    Example: camunda:candidateGroups="group1,group2"

  • tsm:defaultUserGroup
    Assigns a default user group to the task.
    Example: tsm:defaultUserGroup="ENGENEERING"

  • tsm:status
    Defines possible status and allowed transitions.
    Example:

    <bpmn:extensionElements>
        <tsm:status status="NEW">
          <tsm:transition status="IN_PROGRESS" name="Start progress" description="Allow in progress status only for My.Category tickets" formKey="Status.Progress" condition="#{#ticket.category == 'My.Category'}" hasAuthority="Process.Edit" />
          <tsm:transition status="NEGO" />
      </tsm:status>
    </bpmn:extensionElements>

  • tsm:skills
    Lists required skills for task completion.
    Example: tsm:skills="INSTALL_KZ,RANZIR"

  • camunda:formKey
    Associates the task with a specific form for user interaction (tSM Form Designer form code)
    Example: camunda:formKey="TEST"

  • tsm:hideInInstanceGraph
    Controls visibility of the task in the instance graph. Use this to hide tasks that are not relevant for business users.
    Example: tsm:hideInInstanceGraph="true"

  • tsm:disableChangeUser
    Disables the ability to change the assigned user.
    Example: tsm:disableChangeUser="false"

  • tsm:disableChangeUserGroup
    Disables the ability to change the assigned user group.
    Example: tsm:disableChangeUserGroup="false"

  • tsm:hideDefaultDoneStatus
    Hides the default done status for the task.
    Example: tsm:hideDefaultDoneStatus="false"

  • camunda:executionListener
    Adds behavior during process execution. Use tSM Scripting for the execution Example:

    <camunda:executionListener expression="#{logService.info('exec start', ticket.id)}" event="start" />

  • tsm:statusListener Triggers an action when the task reaches a specific status. Example:

    <tsm:statusListener expression="${logService.info('task status', ticket.id)}" status="WAITING_FOR_CUSTOMER" formKey="MY_FORM"/>

Attributes of tsm:transition​

The tsm:transition element defines the transition between task statuses, along with conditions, authorities, and other properties.

  • status
    Defines the target status for the transition. Example: status="IN_PROGRESS"

  • name
    Specifies the name of the transition. Example: name="Start progress"

  • description
    Provides a description of the transition. Example: description="Allow in progress status only for My.Category tickets"

  • formKey
    Specifies the form associated with this transition, which will be displayed to the user when transitioning. Example: formKey="Status.Progress"

  • condition
    Defines a condition using SpEL that must be met for the transition to occur. Example: condition="#{#ticket.category == 'My.Category'}"

  • hasAuthority
    Specifies a required authority to allow the transition. Example: hasAuthority="Process.Edit"

  • hasAnyAuthority
    Specifies if any authority from a list is required for the transition. Example: hasAnyAuthority="Process.Admin,Process.Manager"

  • charsPropertyName
    Defines the name of a characteristic property associated with this transition (optional). Example: charsPropertyName="UrgencyLevel"

Example of tSM Extensions​

Here is an example of a BPMN process with tSM extensions:

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
                  xmlns:camunda="http://camunda.org/schema/1.0/bpmn"
                  xmlns:tsm="http://tsm.datalite.cz/schema/1.0/bpmn">
    <bpmn:process id="tsm-extension" name="TSM Extension Example" isExecutable="true" camunda:versionTag="1.0">
        <bpmn:startEvent id="StartEvent" />
        <bpmn:userTask id="Task1" name="Task Example"
                       tsm:taskDefinition="EXAMPLE_TEMPLATE"
                       tsm:skills="INSTALL_KZ,RANZIR"
                       camunda:assignee="${ticket.createdBy}"
                       tsm:defaultUserGroup="${#tsmUser(ticket.createdBy).defaultUserGroup}"
                       camunda:formKey="taskForm"
                       camunda:priority="5">
            <bpmn:extensionElements>
                <camunda:executionListener expression="${logService.info('Task started', ticket.id)}" event="start" />
                <camunda:taskListener expression="${logService.info('Task completed', ticket.id)}" event="complete" />
                <tsm:statusListener expression="${logService.info('Task status updated', ticket.id)}" status="IN_PROGRESS"/>
            </bpmn:extensionElements>
        </bpmn:userTask>
        <bpmn:endEvent id="EndEvent" />
    </bpmn:process>
</bpmn:definitions>

Import/Export Capabilities​

The BPMN XML standard enables seamless integration with various analytics and process modeling tools. You can export tSM-defined BPMN models to popular modeling tools like Enterprise Architect, Signavio, and others for further analysis or process design. Similarly, you can import existing BPMN models from those tools into tSM, allowing for a flexible and collaborative process design environment.

You can even use AI tools such as ChatGPT to generate BPMN models based on textual descriptions.

Conclusion​

By leveraging BPMN’s standard XML structure, Camunda's execution extensions, and tSM’s specific task and process management extensions, you can build comprehensive, executable workflows tailored to your needs. These processes can be exported to and imported from other tools, and you can use tSM Scripting (based on SpEL) to add dynamic logic and control to your processes.