Interface IStructuredBpmnModelPart

All Superinterfaces:
IWorkflowBpmnAlignmentItem<Object, IStructuredBpmnModelPart>
public interface IStructuredBpmnModelPart extends IWorkflowBpmnAlignmentItem<Object, IStructuredBpmnModelPart>
Represents a part of a BPMN model for a workflow node or trigger. The workflow is based on the concept of structured programming, which does not allow arbitrary jumps in the control flow. A structured BPMN model part consists of many BPMN flow elements, with the following restrictions:
  • There is only one point of entry where the sequence flow enters the part. We call this the in port or incoming interface.
  • The structured model part then routes the sequence flow through its internal structure, which behaves like a black box.
  • At the end, the sequence flow emerges at the out port (also called outgoing interface). Each part may only have a single out port, i.e. sequence flows must be merged within the part's internal structure.

Computing positions and dimensions

Implementations can compute the layout for the BPMN elements in any way they like. However, the workflow engine provides several convenience methods to ease the layout computation.

When modelling a workflow process as BPMN, the usual approach is to first create a nested tree of alignment items, making use of the layouter. Leaf nodes in this tree are usually alignment items containing BPMN elements such as StartEvent Task, Gateway, SubProcess, or EndEvent; whereas other nodes are often used to align or pad the leaf nodes.

This tree of alignment items then gets resolved to a flat map, using flattenToMap. This resolves the positions of all nested alignment items.

Finally, the various method on IFlattenedAlignmentItemMap can be used to create the BPMN shapes, BPMN edges and sequence flows. For example, use createStartEventShape etc. to create a BPMN shape at the resolved position; or flow to create a sequence flow between two BPMN flow nodes.

Defaults

To ease the BPMN model process and prevent common issues, the workflow engine sets certain properties to sensible values automatically.

  • FlowNode normally need not be added to a container manually. All flow nodes of a structured BPMN part are added to the FlowElementsContainer of its parent part automatically. You only need to set the container when you create e.g. a SubProcess and wish to add the flow node to that sub process.
  • Artifact normally need not be added to a container manually. All artifacts of a structured BPMN part are added to the ArtifactsContainer of its parent part automatically. You only need to set the container when you create e.g. a SubProcess and wish to add the artifact to that sub process.
  • DiagramElement normally need not be added to a plane manually. All diagram elements are added to the main plane automatically. BPMN diagram elements are drawn from first to last, so elements drawn later lie on top of elements drawn earlier. The engine adds diagram elements from the children of a workflow node after the diagram elements of the parent node. You are responsible, however, for the order of BPMN elements you create for a structured BPMN part. Diagram elements of a part are added in the order they were created.

Coordinates

All flow elements within the structured model are positioned relative to the top-left corner of the part. A part can also contain other parts, which are positioned relative to the part's top-left corner as well. If this part represents a WorkflowNode, nested parts represent the node's children.

For example, a condition WorkflowNode (if-else) consist of 2 children, one child for the "if" branch and one for the "else" branch. Both children have a part with the necessary flow elements (such as a "Send email" or "Create PDF" ServiceTask). The if-else node itself also has a part, with the "if" and "else" part as its child parts; and an ExclusiveGateway as one of its ownedBpmnElements().

Children

As mentioned, each part can contain childParts(), which correspond to e.g. the children of a WorkflowNode. For each child of a part, the parts also defined the following data:

  • the position of the child, relative to the top-left corner of this part
  • the flow elements container to which FlowElement created by the child part should be added to. The container may be null when a part does not define a container for its child parts. For example, a try-catch node wraps its first child part representing the "try" block in a SubProcess container (to catch errors), but does not wrap its second child part representing the "catch" block in a container (to allow errors thrown in the catch block to propagate upwards). As such, the structured model part for a try-catch node contains two child parts, with a container set for the first child part, but no container set for the second child part.
  • the lane to which FlowNode created by the child part should be added to. The lane may be null when a part does not define a lane for its child parts. For example, each WorkflowTask creates a new lane for its children (the trigger and the root node). As another example, a SubProcess could also, in principle, define lanes for its content.

Interconnections

When converting a workflow node to a BPMN model, the tree of workflow nodes is converted to a tree of structured BPMN model parts, starting at the tree's leaf nodes (innermost nodes). SequenceFlow connect BPMN elements and often need to be drawn between different BPMN elements from different parts. For example, the BPMN diagram for an if-else node needs to draw a sequence flow from the ExclusiveGateway to the first FlowNode in the "if" and "else" branch

As we treat the each structured model part as a black box, you should not look into the part's internal structure. In general, it's also not guaranteed that a child part has a FlowNode for the sequence flow -- the FlowNode might be nested within the child part as a grandchild part, or even be in a completely different part if the child is empty.

Instead, we draw interconnections between BPMN elements and structured model parts. An interconnection represents a part (segment) of a sequence flow. Once the BPMN diagram was modeled, the workflow engine assembles all interconnection into sequence flows.

There are 3 different types of interconnections:

  1. FlowNode -> IStructuredBpmnModelPart
  2. IStructuredBpmnModelPart -> IStructuredBpmnModelPart
  3. IStructuredBpmnModelPart -> FlowNode
A BpmnEdge starts at a flow node (type 1), goes through one or more structured BPMN model parts (type 2), and ends at a flow node (type 3). Each interconnection may define addition waypoints to help in routing the edge. The in port and out port of a structured BPMN model part are added automatically as waypoints by the workflow engine, and should not be added manually.

Port and raisables

Each structured BPMN model part contains data regarding how it interacts with other parts. The SequenceFlow enters the part at the inPort(), is routed through the internal structure of the part, and emerges at the out port. The in port may be null when the part has no valid entry point, such as a StartEvent representing a WorkflowTrigger. The out port may be null when the part has no valid exit point, such as an EndEvent representing a WorkflowNode with a return statement.

A WorkflowNodemay complete abruptly by throwing an AbstractAbruptCompletionException. In the BPMN diagram, this is modeled as throw events (such as an error event for NodeThrewException). Each part also contains a list of raisable errors, escalations, and signals that can be thrown via error, escalation, and signal throw events. These include the raisables from the BPMN elements of the part itself, as well as any raisables from its child parts.

Since:
8.4.0

  • Method Details

    • boundingBox

      Rectangular2DDouble boundingBox()
      The bounding box of this part, i.e. the width and height of this part. All positions are relative to the top-left corner of this part, so no explicit x and y coordinates are needed.
      Specified by:
      boundingBox in interface IWorkflowBpmnAlignmentItem<Object, IStructuredBpmnModelPart>
      Returns:
      The bounding box of this part.

    • childAlignmentItems

      default List<Positioned<? extends IStructuredBpmnModelPart, Point2DDouble>> childAlignmentItems()
      Description copied from interface: IWorkflowBpmnAlignmentItem
      The children of this alignment item, together with their position. The position is always relative to the top-left corner of this alignment item.
      Specified by:
      childAlignmentItems in interface IWorkflowBpmnAlignmentItem<Object, IStructuredBpmnModelPart>
      Returns:
      The children of this alignment item, together with their position.

    • childParts

      List<IStructuredBpmnModelPartChild> childParts()
      Child parts of this part. Each child part has a position relative to the top-left corner of this part; as well as a FlowElementsContainer for the root elements of the child part.
      Returns:
      A list of child parts contained in this part.

    • id

      String id()
      The unique ID of this part. Must be unique only within the scope of a single BPMN diagram.
      Returns:
      The unique ID of this part.

    • inPort

      Double inPort()
      The incoming interface of this structured model part. That is, represents the in port that accepts an incoming sequence flow. The sequence flow gets routed through the internal structure of this part, and emerges at the outgoing interface (out port). Each part for a workflow node always has one (and only one) incoming interface.

      This value indicates the position of the in port of a structured BPMN model part. The meaning of this value depends on the flow direction:

      EAST
      The distance from the top edge of the part to the position to the in port. The in port is on the left edge of the part's bounding box.
      WEST
      The distance from the top edge of the part to the position to the in port. The in port is on the right edge of the part's bounding box.
      SOUTH
      The distance from the left edge of the part to the position to the in port. The in port is on the top edge of the part's bounding box.
      NORTH
      The distance from the left edge of the part to the position to the in port. The in port is on the bottom edge of the part's bounding box.

      May be null if this part represents the starts of a processing chain, e.g. a start event such as a workflow trigger or the start event inside a sub process.

      Specified by:
      inPort in interface IWorkflowBpmnAlignmentItem<Object, IStructuredBpmnModelPart>
      Returns:
      The position of the in port of this part, relative to the top or left edge.

    • interconnections

      List<IWorkflowBpmnInterconnection> interconnections()
      List of connections between elements from different parts. For these, the corresponding SequenceFlow and BpmnEdge cannot be created right now, as the source and target are not known or were not created yet. The interconnections represent the required data, so that the workflow engine can create the sequence flows and edges later. There are different types of interconnections: Each interconnection must have a source and target, as well as a list of way points. These are the points required to route the edge through this part. As such, the points are relative to the top-left corner of this part. The flow, edge and each way point must be owned by this part.
      Returns:
      A list of interconnections between elements from different parts.

    • outPort

      Double outPort()
      The outgoing interface of this structured model part. That is, represents the out port where the sequence emerges from this part again, after it entered this part at the incoming interface (in port). Other parts can connect to this part via the incoming and outgoing interfaces.

      This value indicates the position of the out port of a structured BPMN model part. The meaning of this value depends on the flow direction:

      EAST
      The distance from the top edge of the part to the position to the out port. The out port is on the right edge of the part's bounding box.
      WEST
      The distance from the top edge of the part to the position to the out port. The out port is on the left edge of the part's bounding box.
      SOUTH
      The distance from the left edge of the part to the position to the out port. The out port is on the bottom edge of the part's bounding box.
      NORTH
      The distance from the left edge of the part to the position to the out port. The out port is on the top edge of the part's bounding box.

      May be null if execution of this part never finishes successfully.

      Specified by:
      outPort in interface IWorkflowBpmnAlignmentItem<Object, IStructuredBpmnModelPart>
      Returns:
      The position of the out port of this part, relative to the top or left edge.

    • ownedBpmnElements

      List<de.xima.bpmn_model.api.behavior.BpmnElement<?>> ownedBpmnElements()
      BPMN elements that are owned by this part, including all diagram elements. Each BpmnElement is owned by exactly one structured part. As such, does NOT include nested flow elements from childParts(). All positions are relative to the top-left corner of this part.
      Returns:
      A list of flow elements contained in this part.

    • raisableErrors

      Map<String, BpmnRaisableError> raisableErrors()
      Errors that can potentially be thrown (but are not necessarily thrown) by this BPMN model part, usually via a throw event. This must include all errors of child parts.

      The set contains the error codes. The error code is the unique identifier of an error.

      Returns:
      A list of errors that can be thrown by this part.

    • raisableEscalations

      Map<String, BpmnRaisableEscalation> raisableEscalations()
      Escalations that can potentially be thrown (but are not necessarily thrown) by this BPMN model part, usually via a throw event. This must include all escalations of child parts.

      The set contains the escalation codes. The escalation code is the unique identifier of an escalation.

      Returns:
      A list of escalations that can be thrown by this part.

    • raisableSignals

      Map<String, BpmnRaisableSignal> raisableSignals()
      Signals that can potentially be thrown (but are not necessarily thrown) by this BPMN model part, usually via a throw event. This must include all signals of child parts.

      The set contains the signal names. The signal name is the unique identifier of a signal.

      Returns:
      A list of signals that can be thrown by this part.