BPMN raw event formats

Raw events for BPMN processes or activities are JSON objects with attributes.

Notation and example

The dot notation indicates nested fields. For example, context.trace-id means the trace-id fields within the context JSON object.

See Example of BPMN raw event attributes after the tables for a code sample.

Processes and activities

Table 1. Common attributes of raw events for BPMN process or activities
Event part Description Optional or required Type
business-events-envelope-version The event format version Required String

Example: "1.0.0"

business-events-extension-version The source of the event that defines the event format with the event format version Required A string that starts with the bpmn/ prefix

Example: "bpmn/1.0.0"

id The event identifier Required String
timestamp The timestamp of this event Required A string that contains an ISO8601 date in this format: yyyy-mm-ddThh:mm:ss.nnn+|-hh:mm
category The category of this event Required String - Typical value: bpmnx:BPD for BPMN processes
type Indicates which process or activity phase is performed. Required String - For possible values, see Example of BPMN raw event attributes.
Table 2. bpm attributes of raw events for BPMN process or activities
Event part Description Optional or required Type
bpm BPM-specific information about this event Required JSON object
bpm.sequenceId The identifier of the event sequence Required Number
bpm.createdHighResolutionTimestamp The high resolution timestamp Required Number
bpm.atRiskDate The date that was set for the process to be considered at risk Optional - Present only for at-risk process events A string containing an ISO8601 date in this format: yyyy-mm-ddThh:mm:ss.nnn+|-hh:mm
bpm.dueDate The due date of the process Optional - Present only for due date process events A string containing an ISO8601 date in this format: yyyy-mm-ddThh:mm:ss.nnn+|-hh:mm
Table 3. context attributes of raw events for BPMN process or activities
Event part Description Optional or required Type
context The correlation information Required JSON object
context.trace-id The trace identifier Required String
context.span-id The span identifier Required String
context.parent-span-id The parent span identifier Optional - Not present if the BPMN process is a top-level one. String
context.bpm BPM-specific correlation information for this event Required JSON object
context.bpm.starting-process-instance The identifier of the starting process instance which uniquely identifies the process among the systems. Required String
Table 4. data attributes of raw events for BPMN process or activities
Event part Description Optional or required Type
data The business data Optional JSON object
data.bpm BPM-specific information about business data Required JSON object
data.bpm.tracking-point The tracking point information Required JSON object
data.bpm.tracking-point.time The timestamp corresponding to the date on which the business data was retrieved. Required A string containing an ISO8601 date in this format: yyyy-mm-ddThh:mm:ss.nnn+|-hh:mm
data.bpm.tracking-point.name The tracking point name, which is one of the following:
  • Either the activity name if the tracking point refers to an activity PRE or POST.
  • Or the intermediate tracking point name if this event is an intermediate event or a process-end event
Required String
data.bpm.tracking-point.id The tracking point identifier Required String
data.bpm.tracking-point.version The identifier of the tracking point snapshot Required String
data.bpm.tracking-point.groupName The tracking group name Required String
data.bpm.tracking-point.groupId The tracking group identifier Required String
data.bpm.tracking-point.groupVersion The snpashot identifier of the group Required String
data.bpm.tracking-point.tracked-field The tracked fields associated with the tracking point Optional JSON array
Note: The parent hierarchy reported in the source.parent.* nested structure describes the (model) definition containment hierarchy for the running process, as it was created in the designer. That parent hierarchy does NOT describe the "call stack". For example, when process A calls process B, therefore links to it, the activities in process B simply report process B as their parent hierarchy and do NOT have an entry for process A in the hierarchy.
Table 5. source attributes of raw events for BPMN process or activities
Event part Description Optional or required Type
source Information about the source that generated this event Required JSON object
source.type The type of source that generated this event Required String - Typical values: "bpmn:userTask" for user tasks and "bpmn:process" for processes
source.id The identifier of the source that generated this event Required String
source.instance BPM-specific information about the current activity instance or process instance. Required JSON object
source.instance.id The identifier of the process instance if the event is for a BPMN process or the identifier of the activity instance if the event is for an activity. Required String
source.instance.bpm IBM® Business Automation Workflow-specific information about the current task or process Required JSON object
source.instance.bpm.state The state of the process. For process events only. Required String - Examples of possible values: "Active" or "Completed"
source.instance.bpm. taskInstanceId.bpm The identifier of the task instance. For activity and task events only. Optional - Present only if the enable-task-api-def option is set in the IBM Business Automation Workflow configuration. String
source.instance.bpm.taskRecord Additional information about the current task Optional - Present only if the enable-task-api-def and task-record-enabled options are set in the IBM Business Automation Workflow configuration. JSON object
source.bpm IBM Business Automation Workflow-specific information about the process or activity hierarchy. Required JSON object
source.bpm.version The process snapshot identifier if this event is for a BPMN process, or the activity snapshot identifier if this event is for an activity. Required String
source.bpm.name The name of the process if this event is for a BPMN process, or the name of the current activity if this event is for an activity. Required String
source.bpm.documentation The narrative for the current activity or process Optional String
source.bpm.snapshot-name The process snapshot name if this event is for a BPMN process, or the activity snapshot name if this event is for an activity. Optional String
source.parent Information about the process or activity parent in the hierarchy. Required JSON object
source.parent.type The parent type Required String
source.parent.id The parent identifier Required String
source.parent.instance Information about the instance of the parent in the hierarchy Required JSON object
source.parent.bpm BPM-specific information about the process or activity parent Required JSON object
source.parent.bpm.version The snapshot identifier of the parent in the hierarchy Required String
source.parent.bpm.name The name of the parent in the hierarchy Required String
source.parent.bpm.documentation The narrative of the parent in the hierarchy Optional String
source.parent.bpm.snapshot-name The snapshot name of the parent in the hierarchy Optional String
source.parent.parent The parent of the process or activity in the hierarchy. This is a recursive scheme up to the process application that is the topmost parent in the hierarchy. Each parent object can have the same attributes as those in source/parent Optional JSON object
Table 6. system attributes of raw events for BPMN process or activities
Event part Description Optional or required Type
system Information about the system that generated the event Required JSON object
system.id The identifier of the system that generated this event Required String
system.bpm IBM Business Automation Workflow-specific information about the system Required JSON object
system.bpm.bpmCellName The IBM Business Automation Workflow cell name Required String
Table 7. user attributes of raw events for BPMN process or activities
Event part Description Optional or required Type
user User information for userTask activities Optional JSON object
user.id The identifier of the user, or group of users, who can interact with a task Required String
user.bpm IBM Business Automation Workflow-specific information Optional JSON object
user.bpm.role The role for the user Optional - Present if the user.bpm attribute is set. String constant. Possible values: "PERFORMER" or "POTENTIAL_PERFORMER"
user.bpm.name The name of the group that can claim a task if the user.bpm.role attribute is set to "POTENTIAL_PERFORMER", or the name of the user who claimed the task if the user.bpm.role attribute is set to "PERFORMER". Optional - Present if the user.bpm attribute is set. String

Tracked fields

Each tracked field in the JSON array bound to attribute data.bpm.tracking-point.tracked-field is a JSON object with the following attributes.
Table 8. Attributes of tracked fields
Event part Description Optional or required Type
name The tracked field name Required String
id The tracked field identifier Required String
type The tracked field type prefixed with xs: Required String
content The tracked field value Required String or null

Example of BPMN raw event attributes

{
      "business-events-envelope-version": "1.0.0",
      "business-events-extension-version": "bpmn/1.0.0",
      "id": "i1b96c642f8ffd261792162189",
      "timestamp":"2018-04-19T17:14:16.902-05:00",
      "system":{
           "id": "7cf5b53b-6c76-487c-93e5-25361b46d01d",
           "bpm": {
                 "bpmCellName":"bpmCell01"
           }
      },
      "bpm": {
           "sequenceId":7"
           "createdHighResolutionTimestamp": 56152534230
      },
      "source":{
           "type":"bpmn:userTask",
           "id": "bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-75fb",
           "instance":{
                 "id": "5",
                 "bpm": {
                       "taskInstanceId":"854"
                 }
           },
           "bpm": {
                 "version":"2064.bbdb6a32-bcd1-44dd-bbe6-0bce233c3fb0",
                 "name":"Submit position request",
                 "snapshot-name":"Responsive Hiring Sample v8600_03"
           },
           "parent":{
                 "type":"bpmn:process",
                 "id": "c904b3b1-afc1-4698-bf5a-a20892c20275",
                 "instance":{
                       "id": "914",
                       "bpm": {
                             "state":"Active"
                       }
                 },
                 "bpm": {
                       "version":"2064.bbdb6a32-bcd1-44dd-bbe6-0bce233c3fb0",
                       "name":"Standard HR Open New Position",
                       "documentation":"This process covers a manager requesting 
                        to create a new position or fill an existing position. 
                        The process routes the position request to the Human Resources (HR) 
                        department to search for candidates.",
                       "snapshot-name":"Responsive Hiring Sample v8600_03"
                 },
                 "parent":{
                       "type":"wle:processApplication",
                       "id": "9ab0d0c6-d92c-4355-9ed5-d8a05acdc4b0",
                       "bpm": {
                             "version":"2064.bbdb6a32-bcd1-44dd-bbe6-0bce233c3fb0",
                             "name":"Hiring Sample",
                             "documentation":"Hiring Sample",
                             "snapshot-name":"Responsive Hiring Sample v8600_03"
                       }
                 }
           }
      },
      "user":{
           "id": "admin",
           "bpm": {
                 "role":"PERFORMER",
                 "name":"admin"
           }
      },
      "category":"bpmnx:BPD",
      "type":"bpmnx:ACTIVITY_RESOURCE_ASSIGNED",
      "context":{
           "trace-id":"1b944420-1143-46a4-b30f-d6a269db3a4c",
           "span-id":"bf5aa20892c20275",
           "parent-span-id":"b30fd6a269db3a4c",
           "bpm": {
                 "starting-process-instance": 
                 "c904b3b1-afc1-4698-bf5a-a20892c20275.7cf5b53b-6c76-487c-93e5-25361b46d01d.914"
           }
      },
      "data":{
           "bpm": {
                 "tracking-point":{
                       "time":"2018-04-19T17:14:16.902-05:00",
                       "name":"Submit position request",
                       "id": "4-aa5a-f4ed8784d4a8bpdid431b0753c33842e23d5457c0141a2fd3448-75fb",
                       "version":"2064.bbdb6a32-bcd1-44dd-bbe6-0bce233c3fb0",
                       "groupName":"aEmpRequisition121381434563922",
                       "groupId":"19b73424-1bdc-4ee4-aa5a-f4ed8784d4a8",
                       "groupVersion":"2064.bbdb6a32-bcd1-44dd-bbe6-0bce233c3fb0",
                       "tracked-field":[
                             {
                                  "name":"HiringManager",
                                  "id": "bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-761c",
                                  "type":"xs:string",
                                  "content":""
                             },
                             {
                                  "name":"EmploymentStatus",
                                  "id": "bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-761b",
                                  "type":"xs:string",
                                  "content":""
                             },
                             {
                                  "name":"Department",
                                  "id": "bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-761a",
                                  "type":"xs:string",
                                  "content":""
                             },
                             {
                                  "name":"Location",
                                  "id": "bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-7619",
                                  "type":"xs:string",
                                  "content":""
                             },
                             {
                                  "name":"GMApproval",
                                  "id": "bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-7618",
                                  "type":"xs:string",
                                  "content":"false"
                             }
                       ]
                 }
           }
      }
}