# 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; route for a single connection path from a source node to a target node) and
* the `calculation` type `flow` (process flow; directed graph with any number of nodes and edges).


From now on the description refers to the `calculation` type `flow`.

## Table of contents

* [1.0 - General structure of the Request JSON](#gen-struct)
* [2.0 - The diagram meta-information part of the Request JSON](#dgm-meta)
  * [2.1 - How it typically looks like](#dgm-meta-typic)
  * [2.2 - The requested <code>result</code> type](#dgm-meta-result)
  * [2.3 - The requested <code>calculation</code> type](#dgm-meta-calc)
  * [2.4 - The <code>configurations</code> ](#dgm-meta-conf)
* [3.0 - The context part of the Request JSON (diagram as a whole)](#context-part)
  * [3.1 - How it typically looks like](#context-part-typic)
  * [3.2 - Context informations](#context-part-info)
* [4.0 - The <code>content</code> part of the Request JSON (containing the nodes and edges collections)](#content-part)
  * [4.1 - How it typically looks like](#content-part-typic)
  * [4.2 - The <code>nodes</code> collection](#content-part-nodes)
    * [The <code>laneRelevantRelated</code> collection](#content-part-nodes-lane-relevance)
  * [4.3 - The <code>edges</code> collection](#content-part-edges)
* [5.0 - The <code>pools</code> part of the Request JSON ](#pools-part)
  * [5.1 - How it typically looks like](#pools-part-typic)
  * [5.2 - The <code>pool</code> tuning](#pools-part-tune)
* [6.0 - The <code>elements</code> part of the Request JSON](#elements-part)
  * [6.1 - How it typically looks like for events](#elements-part-typic-events)
  * [6.2 - How it typically looks like for tasks](#elements-part-typic-tasks)
  * [6.3 - How it typically looks like for roles](#elements-part-typic-roles)
  * [6.4 - How it typically looks like for data](#elements-part-typic-data) --- REWORK STOPED HERE
* [7.0 Understanding the correlation of <code>nodes</code> / <code>edges</code>  and <code>elements</code> by examples](#correlation)
  * [Sample 1 (a node/shape and the underlaying element vs. the BPMN equivalent)](#correlation-sample1)


## 1. - General structure of the Request JSON

The **Request JSON** (for `calculation` type `flow`) must provide all necessary information to calculate a layout (and optionally render a graphic, in the case the `result` type is `esvg`, `svg`, `sesvg` or `ssvg`) of a process flow (directed graph with any number of nodes and edges).

**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**.

| **The file structure** | **Compared to BPMN** | **Comments** |
|  --- | --- | --- |
| 
```javascript
  {
      "result": "json",
      "calculation": "flow",
      "configurations": [
      ...
      ],
  }
```
 | 
```javascript
  <definitions>
```
 | **Diagram meta-information**
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"** and the type of **"calculation"** as well as details regarding layout and rendering **"configurations"**.
 |
| 
```javascript
  {
      "context": {
      ...
      },
  }
```
 | 
```javascript
  <definitions>
```
 | **Diagram meta-information**
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"** and the type of **"calculation"** as well as details regarding layout and rendering **"configurations"**.
 |
| 
```javascript
  {
      "result": "json",
      "calculation": "flow",
      "configurations": [
      ...
      ],
  }
```
 | 
```javascript
  <bpmndi:BPMNDiagram>
  ...
  ...
```
 | **Diagram context**
The JSON format holds additional information about the diagram, that are not known to BPMN.
 |
| 
```javascript
  "content": {
      "nodes": [
      {
          ...
      },
      ...
      ],
      "edges": [
      {
      ...
      },
      ...
      ]
  },
```
 | 
```javascript
      <bpmndi:BPMNPlane>

          <bpmndi:BPMNShape>
          ...
          </bpmndi:BPMNShape>
          ...

          <bpmndi:BPMNEdge>
          ...
          </bpmndi:BPMNEdge>
          ...
      </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>
```
 | **Diagram - Commonalities**
Besides that, the Request JSON and BPMN hold directly comparable data:
- JSON **"nodes"** / **"edges"** and the BPMN **<bpmndi:BPMNPlain>** contain the collection of node-shapes and edge-shapes.
- JSON **"pools"** and the BPMN **<collaboration>** contain the collection of pools.
- JSON **"elements"** and the BPMN **<process>** contain the collection of node-definitions and edge-definitions.

**Diagram content - Differences**
- While JSON provides diagram information as sub-nodes (e.g.: "id": "1",), BPMN provides diagram information as attributes (e.g.: *<bpmn:process id="1">*).
- While JSON distinguishes the **"nodes"** collection and the **"edges"** collection, BPMN doesn't.

 |
| 
```javascript
  "pools": [
      ...
  ],
```
 | 
```javascript
  <collaboration>
    ...
  </collaboration>
```
 | **Pools**
The Request JSON can hold and BPMN holds a collection of pools. While the Request JSON needs the collection of pools only to add an empty pool or to determine the order of the pools, BPMN always needs the collection of pools.
 |
| 
```javascript
  "elements": [
      ...
  ]
```
 | 
```javascript
      <process>
          ...
      </process>
  </definitions>
```
 | **Elements**
The Request JSON and BPMN hold a collection elements. Each node referres to an element, multiple nodes can refer to the same element. The elements hold additional information, that can be shared across multiple nodes.
 |


## 2.0 - The diagram meta-information part of the Request JSON

### 2.1 - How it typically looks like

| **Example with request for one layout** | **Example with request for six layouts** | **Comments** |
|  --- | --- | --- |
| 
```javascript
"result": "json",
"calculation": "flow",
"configurations": [
  {
    "layoutType": "flow",
    "lcid": 1031,
    "vertical": true
  }
]
]
```
 | 
```javascript
  "result": "json",
  "calculation": "flow",
  "configurations": [
      {
      "layoutType": "flow",
      "lcid": 1031,
      "vertical": true
      },
      {
      "layoutType": "flow",
      "lcid": 1031,
      "vertical": false
      },
      {
      "layoutType": "swimlane-roles",
      "lcid": 1031,
      "vertical": true
      },
      {
      "layoutType": "swimlane-roles",
      "lcid": 1031,
      "vertical": false
      },
      {
      "layoutType": "swimlane-apps",
      "lcid": 1031,
      "vertical": true
      },
      {
      "layoutType": "swimlane-apps",
      "lcid": 1031,
      "vertical": false
   }
  ]
```
 | The the three available **"layoutTypes"**
- **"flow"** (layout without lanes or pools)
- **"swimlane-roles"** (layout with lanes and pools based on roles, alternatively based on organizational units) and
- **"swimlane-apps"** (layout with lanes and pools based on application systems, alternatively based on roles)

can be combined with the two "vertical" direction values
- **true** (vertical flow, typical for EPC) and
- **false** (horizontal flow, typical for BPMN)

and this generates six possible layouts.
In addition to that the **"lcid"** defines the language, that is used in case not only a layout but also a rendering (the **"result"** type is **"esvg"**, **"svg"**, **"sesvg"** or **"ssvg"**) is requested.
 |


### 2.2 - The requested result type

The currently suported `result` types for the `calculation` type `flow` are

* `json` (JSON, the recommended result type) - used in case the resulting JSON should be parsed to post-process the calculation result and log messages are not desired,
* `ejson` (JSON, enhanced with additional information) - used in case the resulting JSON should be parsed to post-process the calculation result and log messages are desired,
* `esvg` (HTML embedded SVG, enhanced with additional information) - used in case the resulting HTML has to be displayed directly (e. g. in a test app) and log messages are desired,
* `svg` (HTML embedded SVG, without additional information) - used in case the resulting HTML has to be displayed directly (e. g. in a test app) and log messages are not desired,
* `sesvg` (stand-alone SVG, enhanced with additional information) - used in case the resulting SVG has to be embedded into a custom HTML page and log messages are desired and
* `ssvg` (stand-alone SVG, without additional information) - used in case the resulting SVG has to be embedded into a custom HTML page and log messages are not desired


### 2.3 - The requested calculation type

The currently suported `calculation` types are

- `cxn` (route for a single connection path from a source node to a target node)- used to calculate one single shape-to-shape connection path and
- `flow` (directed graph with any number of nodes and edges)- 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.

### 2.4 - The configurations

The `configurations` collection can currently contain one or six configuration(s).
One configuration is provided, of only one of the following layouts hast to be calculated:

- The `layoutType` set to `flow` (layout without pools / lanes) and `vertical` set to `true`.
- The `layoutType` set to `flow` (layout without pools / lanes) and `vertical` set to `false`.
- The `layoutType` set to `swimlane-roles` (layout with pools / lanes, lanes are based on roles or organizational units) and `vertical` set to `true`.
- The `layoutType` set to `swimlane-roles` (wlayout ith pools / lanes, lanes are based on roles or organizational units) and `vertical` set to `false`.
- The `layoutType` set to `swimlane-apps` (layout with pools / lanes, lanes are based on application systems and fall back to roles or organizational units) and `vertical` set to `true`.
- The `layoutType` set to `swimlane-apps` (layout with pools / lanes, lanes are based on application systems and fall back to roles or organizational units) and `vertical` set to `false`.


All six configurations (three `layoutType` values multiplied with two `vertical` direction values) are provided, if all of the above listed layouts have to be calculated.

## 3.0 - The context part of the Request JSON (diagram as a whole)

The `context` represents the diagram (process) to layout as a whole. BPMN contains this data within the `<bpmndi:BPMNDiagram>` tag.

### 3.1 - How it typically looks like


```
  "context": {
    "id": "3783f2a0-99c0-4120-a639-4acfd59a8021",
    "properties": {
      "elementTypeKind": "business",
      "facetName": "processes",
      "state": "inProcess",
      "stereoType": "f5942ab4-2365-4a07-8a3f-04d10fb3b870",
      "type": "subProcess",
      "versionId": "2a536296-d3c7-47cf-8d2e-511eaf5b666d"
    },
    "attributes": [
      {
        "key": "links",
        "type": "linksValue",
        "values": [
          {
            "lcid": 127,
            "value": {
              "links": [
                {
                  "locator": "www.duckduckgo.com",
                  "title": "Find"
                }
              ]
            }
          }
        ]
      },
      {
        "key": "majorVersion",
        "type": "integer",
        "values": [
          {
            "lcid": 127,
            "value": 0
          }
        ]
      },
      {
        "key": "minorVersion",
        "type": "integer",
        "values": [
          {
            "lcid": 127,
            "value": 1
          }
        ]
      },
      {
        "key": "name",
        "type": "multiLineText",
        "values": [
          {
            "lcid": 1031,
            "value": "GRAPHIC-API"
          }
        ]
      }
    ]
  }
```

### 3.2 - Context informations

Typical information provided for the diagran (process) are:

* The `id` contains the unique identity of the diagram, it is provided for informational purposes only and is passed on to the **Result JSON**.
* The `properties` contains a collection of optional information.
* The `attributes` contains a collection of information, that are used to be displayed when the diagram is rendered. Therefore these informations are passed on to the **Result JSON**. Typically the text attributes are provided in multiple languages.


## 4.0 - The content part of the Request JSON (containing the nodes and edges collections)

The `content` contains the nodes and edges (in the meaning of nodes and edges within a directed graph) of the diagram (process). Typically the nodes and edges are displayed as soon als the layout is rendered. Therefore the nodes require the calculation of their positions and the edges require the calculation of their routes in order to be written to the **Result JSON** including the positions and routes.

### 4.1 - How it typically looks like


```
  "content": {
    "nodes": [
      {
        "shapeId": "e85e124a-86aa-4fe6-aaaf-4c5707215461",
        "elementId": "5dd9be26-b592-4e02-b4b0-e508a7844e27",
        "properties": {
          "type": "evStart"
        },
        "laneRelevantRelated": [
          {
            "elementId": "c61aaf77-5d75-4ff6-a567-d9662715c46d",
            "layoutTypes": [
              "swimlane-roles",
              "swimlane-apps"
            ]
          }
        ]
      },
      ...
    ],
    "edges": [
      {
        "shapeId": "ad711e08-3fd4-44b6-bac8-518e72a005c2",
        "elementId": "3bf7c2cf-a70e-49d3-9377-301bfebec515",
        "properties": {
          "type": "crt1",
          "source": {
            "shapeId": "542e5c76-5482-4b4d-bf56-8a6d927e6a6b"
          },
          "target": {
            "shapeId": "343b15d4-3d51-4b1b-9bef-4b3b4889a88f"
          }
        }
      },
      ...
    ],
```

(see chapter [7.0 Understanding the correlation of <code>nodes</code> / <code>edges</code>  and <code>elements</code> by examples](#correlation) below).

### 4.2 - The nodes collection

Nodes represent the shapes, comparable to BPMN `<startEvent>` or `<task>`.


```
      {
        "shapeId": "e85e124a-86aa-4fe6-aaaf-4c5707215461",
        "elementId": "5dd9be26-b592-4e02-b4b0-e508a7844e27",
        "properties": {
          "pool": {
            "poolId": "c84c7e2e-ea39-4fc8-b2dd-10df2b7c766a"
          },
	  "type": "evStart"
        },
        "laneRelevantRelated": [
          {
            "elementId": "c61aaf77-5d75-4ff6-a567-d9662715c46d",
            "layoutTypes": [
              "swimlane-roles",
              "swimlane-apps"
            ]
          }
        ]
      }
```

**Typical information provided for a node are:**

* The `shapeId` contains the unique identity of the node.
* The `elementId` contains the unique identity of the element, the node is based on, it is passed on to the **Result JSON**.
* The `properties` contains a collection of optional information, which are passed on to the **Result JSON**.
  * The optional `pool` contains the assignment of this node to a pool (this assignment is the same for all layouts).
  * The optional `type` contains the type of the node.
* The `laneRelevantRelated` contains a collection of elements, that are used to determine the lane the shape is to be assigned to.


**The pool assignment**

A node can optionally be assigned to a pool. The `poolId` must refer to an existing pool within the [The <code>pools</code> part of the Request JSON ](#pools-part).

#### The laneRelevantRelated collection

Since the **Request JSON** has to support multiple layouts at once, it is required to provide information about the lane assignment ***per layout***. Therefore the  `laneRelevantRelated` element collection includes for each lane relevant element the information which `layoutTypes` are supported by a lane relevant element. The values used for the `layoutTypes` here match the values used for the `layoutType` within the configurations.

(For details regarding the `layoutType` values see chapter [The <code>configurations</code> ](#dgm-meta-conf) above).

**Putting it all together**
For a sample, that shows the correlation between `node` and `element` in the Request JSON and in the Result JSON and also in comparison to BPMN see chapter [7.0 Understanding the correlation of <code>nodes</code> / <code>edges</code>  and <code>elements</code> by examples](#correlation) and section [Sample 1 (a node/shape and the underlaying element vs. the BPMN equivalent)](#correlation-sample1).

### 4.3 - The edges collection

Edges represent the connection between shapes, comparable to BPMN `<sequenceFlow>`.


```
    {
        "shapeId": "ad711e08-3fd4-44b6-bac8-518e72a005c2",
        "elementId": "3bf7c2cf-a70e-49d3-9377-301bfebec515",
        "properties": {
          "type": "crt1",
          "source": {
            "shapeId": "542e5c76-5482-4b4d-bf56-8a6d927e6a6b"
          },
          "target": {
            "shapeId": "343b15d4-3d51-4b1b-9bef-4b3b4889a88f"
          }
        }
      }
```

Typical information provided for an edge are:

* The `shapeId` contains the unique identity of the node.
* The `elementId` contains the unique identity of the element, the edge is based on, it is passed on to the **Result JSON**.
* The `properties` contains a collection of information, which are processed by the layouter. Every edge must contain a `source` `shapeId` and a `target` `shapeId` in order to connect two nodes.


## 5.0 - The pools part of the Request JSON

Pools can be automatically recognized from the nodes collection.

But either if empty pools are to be added or if pools shall be sorted in a distict order the automatic pool recognition is insufficient and the pools must be listed explicitly.

So we have these cases:

* The diagram is to be laid out (and optionally rendered) without pools: The pools part can be left empty.
* The diagram is to be laid out (and optionally rendered) with pools but there are no specicic requirements to the pools: The pools part can be left empty.
* The diagram is to be laid out (and optionally rendered) with pools and an empty pool hast to be added: The pools part *must* contain the pools in the desired sort order.
* The diagram is to be laid out (and optionally rendered) with pools and the order of the pool has to be distinct: The pools part *must* contain the pools in the desired sort order.


### 5.1 - How it typically looks like

This is an example with three pools:


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

The `"pools"` are of **item** type `"bpmnPool"` and of **item** kind `"object"`.

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

### 5.2 - The pool servity

One **pool** should be designated as the default **pool** so that **shapes** can be automatically (fall- back) attached to the default **pool** without explicitly assigning a **pool** to **shapes**. This creates a fail-safe behavior and makes the JSON code shorter. To identify the default **pool** you can:

- Mark all **pools** except the default **pool** as "source" ("servity": "source") or "target" ("servity": "target"). In case of multiple matches, the last one wins.
- Mark the default **pool** ("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.


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*.

Nevertheless, it is possible to provide the **pools** without any tuning at all and let the *Symbio-Graphic-Service* do all the tuning.

## 6.0 - The elements part of the Request JSON

The elements collection contains all elements, that

* underlay a node or
* are connected to nodes as related or laneRelevantRelated elements.


### 6.1 - How it typically looks like for events

| **An event sample request JSON *element*** | **Compared to the BPMN *<bpmn:process/>* tag** | **Comments** |
|  --- | --- | --- |
| 
```javascript
{
    "id":
        "B63F2971E571B69F49AAD5B0733302FA",
    "properties": {
        "type": "evStart",
        "kind": "OBJ",
        "evType": "throwSignal"
    },
    "attributes": [
        {
        "key": "name",
        "values": [
            { "lcid": 1033,
            "value": "Start" }
        ]
        },
        ...
        ]
}
```
 | 
```javascript
{ 
    <bpmn:startEvent
        id="StartEvent_0034tgy"
        name="Goods arrived">
        <bpmn:outgoing>
            SequenceFlow_0pern26
        </bpmn:outgoing>
    </bpmn:startEvent>
}
```
 | The request JSON *elements* and the BPMN *<bpmn:process/>* nodes provide very similar information:
- The type, either "evStart" or <bpmn:startEvent>, and
- the name, either "attributes"/"key": "name" or name attribute.

But there are also differences:
- While BPMN provides also the structure defining edges <bpmn:incoming> and <bpmn:outgoing>,
- the request JSON doesn't. This is because elements can be re-used within one request JSON and therefore a definition of incoming and outgoing edges can be ambiguous and is realized via the edges collection.

 |


### 6.2 - How it typically looks like for tasks

| **A task sample request JSON *element*** | **Compared to the BPMN *<bpmn:process/>* tag** | **Comments** |
|  --- | --- | --- |
| 
```
{
    "id":
        "bcf7ab71d86145919a5a0a570fa2beed",
    "properties": {
        "type": "task",
        "kind": "OBJ",
        "typeDisplayName": "Task"
    },
    "attributes": [
        {
        "key": "name",
        "values": [
            { "lcid": 1033,
            "value": "Task-01" }
        ]
        },
        ...
    ],
    "related": [
        {
        "key": "accountableRole",
        "shortKey": "A",
        "versionIds": [
        "35f4cfb5437e4f1d8fd072859648e183"
        ]
        },
        ...
    ]
}
```
 | 
```javascript
{ 
    <bpmn:task
        id="Activity_16oto7s"
        name="Process goods">
        <bpmn:incoming>
            SequenceFlow_0pern26
        </bpmn:incoming>
        <bpmn:outgoing>
            SequenceFlow_1vdst1y
        </bpmn:outgoing>
    </bpmn:task>
    ...
}
```
 | The request JSON elements and the BPMN *<bpmn:process/>* nodes provide very similar information:
- The type, either "task" or <bpmn:task>, and
- the name, either "attributes"/"key": "name" or name attribute.

But there are also differences:
- While BPMN provides also the structure defining edges <bpmn:incoming> and <bpmn:outgoing>,
- the request JSON doesn't. This is because elements can be re-used within one request JSON and therefore a definition of incoming and outgoing edges can be ambiguous and is realized via the edges collection.

On the other hand the request JSON can connect a task to all types of repository elements via "related", e. g. milestones, requirements, KPIs, documents (guidelines, directives), standards, organizational units, projects, products, objectices and so on.
 |


### 6.3 - How it typically looks like for roles

| **A role sample request JSON *element*** | **Compared to the BPMN *<bpmn:process/>* tag** | **Comments** |
|  --- | --- | --- |
| 
```
{
    "id":
        "ed6645df50804e6f9ab235121c5ea567",
    "versionId":
        "a2a8e8e8090f464fac78bec8b851c963",
    "properties": {
        "kind": "OBJ",
        "stereoType": "extern",
        "type": "role",
        "typeDisplayName": "Role"
},
    "attributes": [
        {
        "key": "name",
        "values": [
            { "lcid": 1033,
            "value": "DP officer" }
        ]
        },
    ...
]
}
```
 | 
```javascript
{ 
    <bpmn:laneSet
        id="LaneSet_1n0pzhw">
        <bpmn:lane
        id="Lane_0w5mswf"
        name="MyLane-01">
        ...
        </bpmn:lane>
    </bpmn:laneSet>
    ...
}
```
 | There is no general BPMN equivalent for the repository elements in request JSON.
While request JSON nodes can refer to various types of repository elements via related or laneRelevantRelated, BPMN can only organize elements in swimlanes (which is equivalent to request JSON's laneRelevantRelated) and connect elements to data stores and data objects.
Typically roles are used to define swimlanes - that is realizes via laneRelevantRelated in request JSON and <bpmn:laneset/>/<bpmn:lane/> in BPMN.
 |


### 6.4 - How it typically looks like for data

| **A role sample request JSON *element*** | **Compared to the BPMN *<bpmn:process/>* tag** | **Comments** |
|  --- | --- | --- |
| 
```
{
    "id":
        "480439511168499d8bc5a1fda3285542",
    "versionId":
        "1129e2af0a174064a79849002e1ceb56",
    "properties": {
        "kind": "OBJ",
        "type": "system",
        "typeDisplayName": "Application"
},
    "attributes": [
{
    "key": "name",
    "values": [
        { "lcid": 1033,
        "value": "Accounting portal" }
    ]
},
    ...
    ]
},
{
    "id":
        "9487278f25464394aff9e68bef9b2535",
    "versionId":
        "f1c69f8d04ad4e9e82f11f0465f536a6",
    "properties": {
        "kind": "OBJ",
        "type": "inOut",
        "typeDisplayName": "Input/Output"
},
"attributes": [
{
    "key": "name",
    "values": [
        { "lcid": 1033,
        "value": "Inbound quotation" }
    ]
    },
    ...
]
}
```
 | 
```javascript
    <bpmn:dataStoreReference
        id=
            "DataStoreReference_07dozvu"
        name=
            "Data-Store" />

    <bpmn:dataObjectReference
        id=
            "DataObjectReference_1unf7qz"
        name=
            "Data-Object"
        dataObjectRef=
            "DataObject_1lq9toa" />
    <bpmn:dataObject
        id=
            "DataObject_1lq9toa" />
```
 | There is no general BPMN equivalent for the repository elements in request JSON.
While request JSON nodes can refer to various types of repository elements via related or laneRelevantRelated, BPMN can only organize elements in swimlanes (which is equivalent to request JSON's laneRelevantRelated) and connect elements to data stores and data objects.
Typically data stores and data objects are connected via related in request JSON and implemented as "type": "system" respectively "type": "inOut" in request JSON and implemented as <bpmn:dataStoreReference/> respectively <bpmn:dataObjectReference/> in 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.

### 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*.

## Understanding the correlation of nodes / edges  and elements by examples

The biggest part of the necessary information is the description of the nodes and edges. In order to understand the nodes and edges within the **Request JSON**, comparing their data to **BPMN** and the expected outcome **Result JSON** could be helpful.

**Disclaimer:** The following comparison between the *Request JSON*, *BPMN* and the *Result JSON* 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), which comes closer to the *Result JSON*.

For basics about the nodes see section [The <code>nodes</code> collection](#content-part-nodes).

### Sample 1 (a node/shape and the underlaying element vs. the BPMN equivalent)

| **Request JSON sample of a shape - no position and no size** | **Request JSON sample of the underlaying element** |
|  --- | --- |
| 
```javascript
  {
      "shapeId": "fd4e1872-8742-4bfa-9c4f-b271ec81c73f",
      "elementId": "ab99ac91-be7d-43c4-955d-04324360fbdf",
      "properties": {
      "type": "evStart"
  },
  "laneRelevantRelated": [
  {
      "elementId": "c61aaf77-5d75-4ff6-a567-d9662715c46d",
      "layoutTypes": [
          "swimlane-roles",
          "swimlane-apps"
      ]
  }
  ]
  }
```
 | 
```javascript
  {
      "id": "ab99ac91-be7d-43c4-955d-04324360fbdf",
      "properties": {
          "kind": "object",
          "type": "evStart",
          "typeDisplayName": "Start"
  },
  "attributes": [
  {
      "key": "description",
      "type": "singleLineText",
      "values": [
          {
          "lcid": 1031,
          "value": "Goods arrived"
          }
      ]
  },
  {
      "key": "evStartTrigger",
      "type": "selectionValue",
      "values": [
          {
          "lcid": 127,
          "value": "evTriggerNoneIntSub"
          }
      ]
  },
  {
      "key": "evType",
      "type": "selectionValue",
      "values": [
          {
          "lcid": 127,
          "value": "evTypeMessage"
          }
      ]
  },
  {
      "key": "name",
      "type": "multiLineText",
      "values": [
          {
          "lcid": 1031,
          "value": "Start-01"
          }
      ]
  }
      ],
      "related": [
  {
      "key": "executiveRole",
      "shortKey": "R",
      "versionIds": [
          "9700e981-1c36-4536-a05b-592aa2fd6219"
    ]
  }
  ]
  },
```
 |


| BPMN sample of a shape - including position and size |
|  --- |
| 
```javascript
  <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>
```
 |


| Result SVG a shape - including position and size (and the rendering objects: rect, path and text) |
|  --- |
| 
```javascript
  <g>
  <!-- evStart(evStart) /ID:fd4e1872-8742-4bfa-9c4f-b271ec81c73f /ItemID:ab99ac91-be7d-43c4-955d-04324360fbdf -->
  <!-- evStart /W:160 /H:160 -->
  <ellipse cx="124.7244" cy="63.49606" rx="22.677164" ry="22.677164"
      style="shape-rendering:auto; stroke:#808080; stroke-width:1px; stroke-linecap:round;
      stroke-dasharray:; stroke-opacity:1; fill:#FFFFFF; fill-opacity:1;"></ellipse>
  <!-- ##ATS##_evTypeShapeCatchMessage /W:80 /H:80 -->
  <rect x="113.5" y="55.5" rx="2.2677164" ry="2.2677164" width="22" height="16"
      style="stroke:#000000; stroke-width:1px; stroke-linecap:round; stroke-dasharray:;
      stroke-opacity:1; fill:#FFFFFF; fill-opacity:1;"></rect>
  <path d="M113.224396,57.66535L122.295265,65.602356C124.56298,66.73621 124.56298,66.73621 
      126.830696,65.602356L135.90157,57.66535" style="shape-rendering:auto; stroke:#000000;
      stroke-width:1px; stroke-linecap:round; stroke-dasharray:; stroke-opacity:1;
      fill:transparent; fill-opacity:0.0;"></path>
  <text class="" x="124.5" y="99.92084" text-anchor="middle"
      style="fill:#444444;font-family:Segoe UI;font-weight:400;font-style:normal;font-size:9pt;text-decoration:none">
  <tspan class="" x="124.5" dy="0">Goods</tspan><tspan class="" x="124.5" dy="15">arrived</tspan></text>
  </g>
```
 |


| Result JSON a shape - including position and size (and the rendering objects: rect, path and text) |
|  --- |
| 
```javascript
  {
      "id": "ab99ac91-be7d-43c4-955d-04324360fbdf",
      "properties": {
          "column": 0.0,
          "evType": "evTypeCatchMessage",
          "height": 50,
          "kind": "shape",
          "row": 0.0,
          "type": "evStart",
          "typeDisplayName": "Start",
          "width": 50,
          "x": 112.5,
          "y": 45.0
  },
      "attributes": [
  {
      "key": "evStartTrigger",
      "values": [
          { "lcid": 127, "value": "evTriggerStd" }
      ]
  },
  {
      "key": "name",
      "values": [
          { "lcid": 1033, "value": "Goods arrived" }
      ]
  }
  ],
      "attributeDisplays": [
      {
      "key": "name",
      "width": 70.0,
      "height": 34.0625,
      "xOffset": -10.0,
      "yOffset": 60.0,
      "rotation": 0.0,
      "horizontalAlignment": "center",
      "verticalAlignment": "top"
      }
      ],
    "related": [
  {
      "key": "executiveRole",
      "shortKey": "R",
      "ids": [
          "4c71d84e-2084-4dc1-bda4-dd2ff664aba4"
      ]
      }
  ]
  }
```
 |


### Sample 2 (an edge)

For basics about the edges see section [The <code>edges</code> collection](#content-part-edges).

| **BPMN sample for interpolation points of an edge** |
|  --- |
| 
```javascript
  <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>
```
 |