Skip to content

Request JSON

The request JSON is used for the CalculateLayout endpoint of the Symbio-Graphic-Service. Layout calculation can be requested for * the calculation type cxn (connection) and * the calculation type flow (process flow).

Disclaimer: The following comparison between the request JSON and BPMN is made not because the two formats perform a similar task, but because they convey similar content: Process flows.

While the request JSON contains only the necessary information for automatic layout calculation and rendering, the BPMN also already contains all information for rendering - like position and size of shapes or the interpolation points of edges.

BPMN sample for position and size of a shape

<bpmndi:BPMNShape id="IntermediateThrowEvent_0iyvpzm_di" bpmnElement="IntermediateThrowEvent_0iyvpzm">
  <dc:Bounds x="458" y="313" width="36" height="36" />
  <bpmndi:BPMNLabel>
    <dc:Bounds x="464" y="353" width="24" height="12" />
  </bpmndi:BPMNLabel>
</bpmndi:BPMNShape>

BPMN sample for interpolation points of an edge

<bpmndi:BPMNEdge id="SequenceFlow_1vmk1br_di" bpmnElement="SequenceFlow_1vmk1br">
  <di:waypoint xsi:type="dc:Point" x="209" y="331" />
  <di:waypoint xsi:type="dc:Point" x="245" y="331" />
  <bpmndi:BPMNLabel>
    <dc:Bounds x="182" y="310" width="90" height="12" />
  </bpmndi:BPMNLabel>
</bpmndi:BPMNEdge>

General structure

The file structureCompared to BPMNComments
{
    "result": "sesvg",
    "calculation": "flow",
    "configurations": [{
    ...
    }],
    "elements": [{
    ...
    }]
}
<bpmn:definitions> 
    ...
</bpmn:definitions>
The JSON format has to support layout and rendering requests for multiple purposes (cxn and flow) as well as multiple configurations.
Thus it provides some meta-information like the requested "result", the type of "calculation" to apply and details regarding layout and rendering configurations "configurations".
Besides that, the JSON holds the data in the "elements" property just like the BPMN does it in the <bpmn:definitions/> tag.

The result property

The supported result types are: 1. sesvg (standalone enriched SVG) - used in case the resulting SVG has to be embedded into a custom HTML page and log messages are desired 2. ssvg (standalone SVG) - used in case the resulting SVG has to be embedded into a custom HTML page and log messages are not desired 3. esvg (HTML embedded enriched SVG) - used in case the resulting HTML has to be displayed directly (e. g. in a test app) and log messages are desired 4. svg (HTML embedded SVG) - used in case the resulting HTML has to be displayed directly (e. g. in a test app) and log messages are not desired 5. ejson (enriched JSON) - used in case the resulting JSON should be parsed to post-process the calculation result and log messages are desired 6. json (JSON) - used in case the resulting JSON should be parsed to post-process the calculation result and log messages are not desired

The calculation property

The supported calculation types are: * cxn (connection) - used to calculate a shape-to-shape connection * flow (process flow) - used to calculate a directed graph, that represents a process flow

The calculation type cxn supports all result types.
The calculation type flow supports the result types 1. ... 4. only.

The configurations property

To be done.

The elements property

The elements property contains all elements, that make up a diagram. This includes:

  • The diagram itself - as the container of all shapes.
  • All structure building shapes (and their edges), that are to be displayed within the diagram.
  • The items, that are the basis to the shapes.

The elements property is designed to hold an array of elements.

It is recommended that the diagram is the first element within the array and the items are the elements following the diagram in the array. The shapes are included in the diagram.

The request JSON elements propertyCompared to the BPMN <bpmn:definitions/> tagComments
[{
  "id":
    "e8b07127331a4bae8135c5c8af381b12",
  "properties": {
    "type": "subProcess"
  },
  "attributes": [{
    "key": "name",
    "values": [
        { "lcid": 1033,
          "value": "Sub process" }
    ]
  }],
  "content": [
...
<bpmndi:BPMNDiagram
 id="BPMNDiagram_1">
  ...









  <bpmndi:BPMNPlane
   id="BPMNPlane_1"
   bpmnElement=
     "Collaboration_0q51prl">
  ...
▶ The first bunch of data in the request JSON file should be the diagram. It can be recognized by the fact that its "type" is "subProcess".
The request JSON diagram typically contains also attributes while the BPMN diagram typically doesn't.

The BPMN diagram might contain a lane node as primary child node of the diagram node.


    {
      "id":
        "a6743dd3-8881-4d22-bfe7-0b7f703097c8",
      "properties": {
        "itemId":
          "9bc5994a-f64f-431f-a631-1ff405f22643",
        "type":
          "evStart",
        "poolId":
          "b0907b38-e8e4-42f3-bc0a-d3e83ae2a1a7"
      }
    },
    ...
    <bpmndi:BPMNShape
     id="StartEvent_0034tgy_di"
       bpmnElement=
         "StartEvent_0034tgy">
      <dc:Bounds
       x="178" y="635"
       width="36" height="36" />
      <bpmndi:BPMNLabel>
        <dc:Bounds
         x="196" y="675"
         width="0" height="12"
      />
      </bpmndi:BPMNLabel>
    </bpmndi:BPMNShape>
    ...
Both, the request JSON diagram within the content property and the BPMN diagram within child nodes, contain the shapes and edges that are to be displayed.

▶ The second bunch of data in the request JSON file should be the sequence of shapes within the content property of the diagram. The list of shapes should contain all structure building shapes to display.

    {
      "id":
        "a6743dd3-8881-4d22-bfe7-0b7f703097c8",
      "properties": {
        "itemId":
          "9bc5994a-f64f-431f-a631-1ff405f22643",
        "sourceId":
          "a6743dd3-8881-4d22-bfe7-0b7f703097c8",
        "targetId":
          "75397704-e829-49b3-a40c-02379fb0b393",
        "type":
          "activ1",
        "poolId":
          "b0907b38-e8e4-42f3-bc0a-d3e83ae2a1a7"
      }
    },
    ...








    ],
  },
...
    <bpmndi:BPMNEdge
     id="SequenceFlow_0pern26_di"
     bpmnElement=
       "SequenceFlow_0pern26">
      <di:waypoint
       xsi:type="dc:Point"
       x="214" y="653"
      />
      <di:waypoint
       xsi:type="dc:Point"
       x="245" y="653"
      />
      <bpmndi:BPMNLabel>
        <dc:Bounds
         x="229.5" y="632"
         width="0" height="12" />
      </bpmndi:BPMNLabel>
    </bpmndi:BPMNEdge>
    ...
  </bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
  ...
▶ The third bunch of data in the request JSON file should be the sequence of edges within the content property of the diagram. The list of edges should contain all edges to display.

The following applies to both shapes and edges:
Both, the request JSON shapes/edges and the BPMN shapes/edges, provide an identifier "id:" (for request JSON) or id (for BPMN). While the itemId: (for request JSON) refers to the underlying item id, as id: for bpmnElement, the sourceId: and targetId: hold the id of the connected shapes, as they are stated in the diagram's content section.

  {
    "id":
      "b0907b38-e8e4-42f3-bc0a-d3e83ae2a1a7",
    "properties": {
      "type": "pool",
      "kind": "OBJ",
      "servity": "source"
    },
    "attributes": [{
      "key": "name",
      "values": [
        { "lcid": 1033,
          "value": "Data source" }
      ]
    }]
  },
  ...
<bpmn:collaboration
 id="Collaboration_0q51prl">
  <bpmn:participant
   name="Data source"
   id="Participant_0zj6ka6"
   processRef="Process_0g17fhl"
  />
    ...
</bpmn:collaboration>
▶ The fourth bunch of data in the request JSON file should be the sequence of pools within the elements property of the request JSON (the diagram property has been finished already at this point). The list of pools should contain all pools that are used to hold lanes or shapes.

Both, the request JSON pools and the BPMN participants, provide an identifier "id:" (for request JSON) or id (for BPMN) and a name "key": "name" (object within the "attributes" property for request JSON) or name
(for BPMN).
  {
    "id":
      "B63F2971E571B69F49AAD5B0733302FA",
    "properties": {
      "type": "evStart",
      "kind": "OBJ",
      "evType": "throwSignal"
    },
    "attributes": [{
      "key": "name",
      "values": [
        { "lcid": 1033,
          "value": "Start" }
      ]
    }]
  },
  ...
]
<bpmn:process
 id="Process_0g17fhl"
 isExecutable="false">
  <bpmn:startEvent
   id="StartEvent_0034tgy">
    <bpmn:outgoing>
      SequenceFlow_0pern26
    </bpmn:outgoing>
  </bpmn:startEvent>
  ...
▶ The fifth bunch of data in the request JSON file should be the sequence of shape items, referenced by shapes.

Both, the request JSON items and the BPMN process child nodes, provide an identifier "id:" (for request JSON) or id (for BPMN).





  {
    "id":
      "D4B07549771B2932CFEE51B63969502F",
    "properties": {
      "type": "activ1",
      "kind": "CXN"
    },
    "attributes": [{
      "key": "cxnRole",
      "values": [
        { "lcid": 1033,
          "value": "01" }
      ]
    }]
  },
  ...
]
  <bpmn:sequenceFlow
   id="SequenceFlow_0pern26"
   sourceRef="StartEvent_0034tgy"
   targetRef="Task_1di8scb"
  />
  ...










</bpmn:process>
▶ The sixth bunch of data in the request JSON file should be the sequence of connection items, referenced by edges.

Both, the request JSON connection items and the BPMN process child nodes, provide an identifier "id:" (for request JSON) or id (for BPMN).



Shapes and shape items

The design of shape content elements is intended to be minimalistic.

{
    "id": "a6743dd3-8881-4d22-bfe7-0b7f703097c8",
    "properties": {
            "itemId": "9bc5994a-f64f-431f-a631-1ff405f22643",
            "type": "evStart",
            "poolId": "6496cb0f-8763-4e27-a8dd-77870be94fd5"
    }
}

Referencing the shape's underlying item is done with "itemId" : "9bc5994a-f64f-431f-a631-1ff405f22643".
The (optional) second reference, "poolId": "6496cb0f-8763-4e27-a8dd-77870be94fd5", defines membership of the shape in a pool.

Here is the shape underlying item:

{
  "id": "9bc5994a-f64f-431f-a631-1ff405f22643",
  "properties": {
    "type": "evStart",
    "kind": "OBJ",
    "evType": "throwSignal"
  },
  "attributes": [{
    "key": "name",
    "values": [
      { "lcid": 1033, "value": "recognize hunger" }
    ]
  }]
}

The type is provided via the "properties" property array property "type".
In addition to that the kind (which determines whether it is a shape or a edge) is provided via the "properties" property array property "kind".
In case the item (and thus the shape as well) is defined more specifically, the "properties" property array might contain a property "evType" or "funcType" ore "funcMarker".
The text to display is defined within the "attributes" property array object with the "key": "name". Since the request JSON supports multiple languages, the name value is provided by the "values" property array, that can hold distinct value objects for different cultures.

Edges and edge items

The design of edge content elements is intended to be minimalistic.
Here is an example:

{
    "id": "e5dfd46e-8720-408e-b760-171038da9f6d",
    "properties": {
        "itemId": "6496cb0f-8763-4e27-a8dd-77870be94fd5",
        "sourceId": "a6743dd3-8881-4d22-bfe7-0b7f703097c8",
        "targetId": "75397704-e829-49b3-a40c-02379fb0b393",
        "type": "activ1"
    }
}

Referencing the edge's underlying item is done with "itemId" : "6496cb0f-8763-4e27-a8dd-77870be94fd5".
The is no reference to a pool, since edges can cross lanes and pools.
The referencing of the source and target shapes is done with "sourceId": "a6743dd3-8881-4d22-bfe7-0b7f703097c8" and "targetId": "75397704-e829-49b3-a40c-02379fb0b393". An edge must always hold a source and a target shape reference.

Here is the edge underlying item:

{
    "id": "6496cb0f-8763-4e27-a8dd-77870be94fd5",
    "properties": {
        "kind": "CXN",
        "sourceId": "9bc5994a-f64f-431f-a631-1ff405f22643",
        "targetId": "b0907b38-e8e4-42f3-bc0a-d3e83ae2a1a7",
        "type": "activ1"
    },
    "attributes": [{
        "key": "cxnRole",
        "values": [
        { "lcid": 1033, "value": "yes" }
        ]
    }]
}

The type is provided via the "properties" property array property "type".
In addition to that the kind (which determines whether it is a shape or a edge) is provided via the "properties" property array property "kind".
The text to display is defined within the "attributes" property array object with the "key": "cxnRole". Since the request JSON supports multiple languages, the name value is provided by the "values" property array, that can hold distinct value objects for different cultures.

Pool items

In the case that the diagram is to be laid out and rendered with pools, the pools should be the first items and must be contained in the order in which they are expected in the final layout/rendering. This is an exoample with three pools:

{
    "id": "d5d7ce44-c18f-4119-aa18-8f9e8aa69e85",
    "properties": {
        "type": "pool",
        "kind": "OBJ",
        "servity": "source"
    },
    "attributes": [{
        "key": "name",
        "values": [
            { "lcid": 1033, "value": "Data source" }
        ]
    }]
},
{
    "id": "03c092c9-b723-4a38-befd-f6f54aef42d6",
    "properties": {
        "type": "pool",
        "kind": "OBJ"
    },
    "attributes": [{
        "key": "name",
        "values": [
            { "lcid": 1033, "value": "Processing" }
        ]
    }],
    "children": [
        "467cbfa4-ff43-49fe-ac0d-49beda2e07f6",
        "c989af38-3e9e-4693-a284-3801da7696de"
    ]
},
{
    "id": "63cf252b-ed7f-458e-97c3-3b557786eb52",
    "properties": {
        "type": "pool",
        "kind": "OBJ",
        "servity": "target"
    },
    "attributes": [{
        "key": "name",
        "values": [
            { "lcid": 1033, "value": "Data target" }
        ]
    }]
},
...

It must be designated that the pools are of item type "pool" (see "type": "pool") and of item kind "OBJ" (see "kind": "OBJ"). One pool should be designated as the default pool so that shapes can be attached to the default pool without explicitly assigning a pool to shapes. This creates a fail-safe and makes the JSON code shorter. To identify the default pool you can:

  • Mark all pools except the default pool as "source" (see "servity": "source") or "target" (see "servity": "target"). In case of multiple matches, the last one wins.
  • Mark the default pool (see "servity": "default"). In case of multiple matches, the last one wins.
  • In case no pool is designated as the default pool, the centre pool (count / 2) is used.

It is highly recommended to define names for all pools (see "attributes" with "key": "name").

In the case that a pool should contain multiple lanes and the lanes should be in a defined order, it is recommended to define the lanes as a list of children (see "children"). The ids, specified in the list of children, must refer to existing items, that are typically roles, groups, application systems or application services.

Lane items

In the case that the diagram is to be laid out and rendered with lanes, the lanes are automatically recognized by the fact, that they are related to structure building items via the configured laneRelevant relation (see "laneRelevant": "responsible" within configurations property). The lanes must not be of any of any specific item type (see "type": "..."), but they must be of item kind "OBJ" (see "kind": "OBJ") and must not be of any of the structure building item types (like "type": "func", "type": "evStart", "type": "evIntermediate", "type": "evEnd", "type": "ruleXor", "type": "ruleOr", "type": "ruleAnd" or "type": "condition").

In the case that multiple lanes should be contained in a pool and the lanes should be in a defined order, it is recommended to define the lanes as a list of children (see "children") within the pool. The ids, specified in the list of children, must refer to existing lane (items), that are typically roles, groups, application systems or application services.