General BPMN Serialization

This page describes the adoption of the BPMN XML files applied by the PROCEED Management System. One of the goals is to stay as standard conform as possible. Some attributes (with a prefix) extending the standard and are defined inside the PROCEED XSD definition

definitions

definitions is the top level element in any BPMN model. It contains one or more process definitions and other BPMN elements. Here is the explanation about the generated values for the attributes:

  • xmlns:proceed="https://docs.proceed-labs.org/BPMN": there is one extra namespace added for PROCEEDs extensions
  • id: Underscore plus a random UUID v4 to generate a global unique id, e.g. "_e292e6c4-4d7f-4aff-b91f-c102d5ea4ae8" (it needs to start with an underscore or letter because of the XSD type ID)
  • name: same as the (file) name of the created process, e.g. "My First PROCEED Process"
  • targetNamespace: the URL "https://docs.proceed-labs.org/" plus the id, e.g. "https://docs.proceed-labs.org/_e292e6c4-4d7f-4aff-b91f-c102d5ea4ae8"
  • xsi:schemaLocation="https://docs.proceed-labs.org/BPMN https://docs.proceed-labs.org/xsd/XSD-PROCEED.xsd http://www.omg.org/spec/BPMN/20100524/MODEL https://www.omg.org/spec/BPMN/20100501/BPMN20.xsd" for schema validation
  • expressionLanguage: "https://ecma-international.org/ecma-262/8.0/" (JavaScript Version: <, >, <=, =>, ==, ===, !=, !==)
  • typeLanguage: "https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf", (JSON has six data types: string, number, boolean, null/empty, object, array)
  • exporter: "PROCEED Management System",
  • exporterVersion contains the version number of the Management System
  • proceed:originalId: (optional) if the process was imported into PROCEED’s Management System, this contains the original definition id
  • proceed:originalExporter: (optional) if the process was imported into PROCEED’s Management System, this contains the original exporter
  • proceed:originalExporterVersion: (optional) if the process was imported into PROCEED’s Management System, this contains the original exporterVersion
  • proceed:originalTargetNamespace: (optional) if the process was imported into PROCEED’s Management System, this contains the original targetNamespace
  • proceed:creatorEnvironmentId: (optional) if given during process creation, the id of the environment the process creator belongs to. “Env”+UUIDv4
  • proceed:creatorEnvironmentName: (optional) if given during process creation, the name of the environment the process creator belongs to
  • proceed:creatorId: (optional) the id of the process creator
  • proceed:creatorName: (optional) the Name of the process creator

process

  • id: Underscore plus a random UUID v4 to generate a global unique id, e.g. "_09abb321-f819-480a-9827-66264d17b4df" (it needs to start with an underscore or letter because of the XSD type ID)
  • name: name of the pool (aka participant name), if no pool default: "PROCEED Main Process"
  • isExecutable: true
  • proceed:deploymentMethod: attribute for changing the deployment method. Can have the values static or dynamic for the respective methods

Flow Nodes inside a process

The id

The id identifies a BPMN element unambiguously and is often used to reference the specific element. It has to be unique, that’s why in PROCEED most ids have the pattern: element name plus a small random id connected with an underscore, e.g. “SequenceFlow_0mwtb46”. (This behaviour is borrowed from the bpmn.io libraries)

Hint: Since a BPMN model can import other BPMN process definitions, the ids of the elements has to be unique over multiple files. This is done with the combination of the targetNamespace and the elements id

The attributes for static deployment

For static deployment two attributes can be attached to a Flow Node (Events, Activities and Gateways). They define the Machine were this flow node must be executed. They are only valid if proceed:deploymentMethod is set to static:

  • proceed:machineId: references a specific Machine id
  • proceed:machineAddress: references a specific Machine IP address and Port (IPv4 example: 192.168.1.11:33029, IPv4 example: [1fff:0:a88:85a3::ac1f]:33029 – the port is optional)

In static deployment mode, if an execution reaches a flow node the Engine checks whether the machineId and machineAddress match the current Machine. If not, it sends the execution (the token) to the specified machine.

A flow node can contain one of the attributes or both. If both are set the machineId takes precedence because it should be a unique value.

Constraints inside extensionElements for dynamic deployment

For dynamic deployment the extensionElements on flow nodes is used. It contains constraints that restrict the deployment and execution of a flow node. For more XML serialization information, see here.

Meta Information

The <process> and every Flow Node can contain further meta data. They are embedded inside <extensionElements><proceed:meta>.... Here is a list of the possible elements:

<proceed:timePlannedOccurrence>
- specifies the scheduled date when an activity or event should start
- should only be used on Flow Node level (not directly inside <process>)
- datatype xsd:dateTime, inspired by ISO 8601, date and time required, timezone optional
- example value: 2020-08-15T15:30:00+01:00
<proceed:timePlannedDuration>
- specifies the planned duration of an activity
- should only be used inside an activity, i.e. task or subprocess (not directly inside <process>, an event or a gateway)
- datatype xsd:duration, inspired by ISO 8601, starts with a P and separates the time with a T
- example value: PT2H30M, P2M10D, P1Y2M3DT4H30M12S
<proceed:cost unit="Euro">
- specifies the planned costs of an activity
- can be used to calculate the overall process costs
- should only be used on Flow Node level (not directly inside <process>)
- datatype xsd:decimal
- unit attribute is optional and a string
<proceed:occurrenceProbability>
- specifies the assumed probability that the process flow will take a specific sequence flow after a gateway
- can be used for simulation
- should only be used inside a <sequenceFlow>
- datatype xsd:integer
<proceed:property name="xyz">
- specifies an arbitrary information
- name attribute is required and a string
- can be used on every level, i.e. on <process> or every flow node
- the value is specified inside the content of the element

Example

<?xml version="1.0" encoding="UTF-8"?>

<definitions    
    xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" 
    xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" 
    xmlns:proceed="https://docs.proceed-labs.org/BPMN" 
    xmlns:di="http://www.omg.org/spec/DD/20100524/DI" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xsi:schemaLocation="https://docs.proceed-labs.org/BPMN https://docs.proceed-labs.org/xsd/XSD-PROCEED.xsd
                        http://www.omg.org/spec/BPMN/20100524/MODEL https://www.omg.org/spec/BPMN/20100501/BPMN20.xsd"

    expressionLanguage="https://ecma-international.org/ecma-262/8.0/"
    typeLanguage="https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf"
    id="_e292e6c4-4d7f-4aff-b91f-c102d5ea4ae8" 
    name="My First PROCEED Process"
    targetNamespace="https://docs.proceed-labs.org/_e292e6c4-4d7f-4aff-b91f-c102d5ea4ae8" 
    exporter="PROCEED Management System" 
    exporterVersion="1.0"

    proceed:originalId="Definitions_0o1kcpw"
    proceed:originalExporter="Camunda Modeler"
    proceed:originalExporterVersion="4.4.0"
    proceed:originalTargetNamespace="http://bpmn.io/schema/bpmn"

    proceed:creatorEnvironmentId="Env-bbd545ad-31ac-479b-bbc3-d45155e5c212"
    proceed:creatorEnvironmentName="SNET PROCEED Environment" 
    proceed:creatorId="Anon-1234"
    proceed:creatorName="Max Mustermann"
    >
    
    <process id="_09abb321-f819-480a-9827-66264d17b4df" 
        name="PROCEED Main Process" 
        processType="Private" isExecutable="true"
        proceed:deploymentMethod="static">

        <extensionElements>
            <proceed:meta>
                <proceed:property name="lastAuthor">Max Mustermann</proceed:property>
            </proceed:meta>
        </extensionElements>
        
        <startEvent id="StartEvent_17d2o9q" proceed:machineId="6bd9c3cf-8164-453a-a039-e8aaf138f192">
            <extensionElements>
                <proceed:meta>
                    <proceed:timePlannedOccurrence>2020-07-01T00:00:00+01:00</proceed:timePlannedOccurrence>
                </proceed:meta>
            </extensionElements>
            <outgoing>SequenceFlow_0mwtb46</outgoing>
        </startEvent>

        <sequenceFlow id="SequenceFlow_0mwtb46" sourceRef="StartEvent_17d2o9q" targetRef="Task_1pdn5o1"/>

        <!-- the machineId has precedence -->
        <task id="Task_1pdn5o1"
        proceed:machineId="6bd9c3cf-8164-453a-a039-e8aaf138f192" 
        proceed:machineAddress="192.168.3.3">
        
            <extensionElements>
                <proceed:meta>
                    <proceed:timePlannedDuration>P2M10D</proceed:timePlannedDuration>
                    <proceed:cost unit="Euro">3000.50</proceed:cost>
                </proceed:meta>

                <proceed:processConstraints>
                    <proceed:hardConstraints>
                        <proceed:hardConstraint timeout="10">
                            <proceed:name>machine.mem.free</proceed:name>
                            <proceed:condition>&gt;=</proceed:condition>
                            <proceed:values conjunction="OR">
                                <proceed:value unit="GB">2</proceed:value>
                            </proceed:values>
                        </proceed:hardConstraint>
                    </proceed:hardConstraints>

                    <proceed:softConstraints>
                        <proceed:softConstraint weight="5">
                            <proceed:name>machine.cpu.free</proceed:name>
                            <proceed:condition>max</proceed:condition>
                        </proceed:softConstraint>
                    </proceed:softConstraints>
                </proceed:processConstraints>
            </extensionElements>

            <incoming>SequenceFlow_0mwtb46</incoming>
            <outgoing>SequenceFlow_0a33trv</outgoing>
        </task>

        <sequenceFlow id="SequenceFlow_0a33trv" sourceRef="Task_1pdn5o1" targetRef="EndEvent_099f60v"/>

        <endEvent id="EndEvent_099f60v" proceed:machineAddress="[1fff:0:a88:85a3::ac1f]:33029">
            <incoming>SequenceFlow_0a33trv</incoming>
        </endEvent>
    </process>
    
</definitions>