Skip to main content
Version: 2.5

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 import and export process models, making it possible to collaborate across compatible modeling and analysis environments.

Runtime Compatibility Extensions​

The tSM Process Engine preserves a set of established XML extension identifiers used by existing process definitions. They provide executable runtime settings for assignment, listeners, asynchronous boundaries, retry behavior, job priority, input/output mappings, and other process semantics.

The literal camunda:* prefix and namespace are compatibility identifiers in the supported BPMN format. Keep them unchanged when editing XML. They do not mean that a separately operated external engine is required. Runtime lineage and maintenance are documented only in Process Engine Internals.

Example:

<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, compatibility attributes such as camunda:assignee and camunda:taskListener control task assignment and execution. Use the tSM Process Designer and this reference as the product contract for supported behavior.

tSM-Specific Extensions​

In addition to BPMN and runtime compatibility extensions, tSM introduces custom attributes for task specifications, skills, statuses, transitions, privileges, forms, material management, and other product capabilities.

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 integration with compatible analysis and process-modeling tools. You can export a tSM-defined model for analysis or design and import an existing BPMN model into tSM. Validate imported models before deployment because executable extensions and referenced tSM configuration must exist in the target environment.

AI-assisted modeling can produce a draft BPMN model from a textual description. Treat the result as a draft: validate it, inspect the diff, and deploy it through the normal versioned lifecycle.

Conclusion​

By combining BPMN's standard XML structure, supported runtime compatibility extensions, and tSM's task and process extensions, you can build executable workflows tailored to your needs. Models can be exported and imported, while tSM Scripting based on SpEL adds controlled dynamic logic.