Exchange format
The information in this document is confidential and proprietary to SAP and may not be disclosed without the permission of SAP. Except for your obligation to protect confidential information, this
document is not subject to your license agreement or any other service or subscription agreement with SAP. SAP has no obligation to pursue any course of business outlined in this document or any related document, or to develop or release any functionality mentioned therein. This document, or any related document and SAP's strategy and possible future developments, products and or platforms directions and functionality are all subject to change and may be changed by SAP at any time for any reason without notice. The information in this document is not a commitment, promise or legal obligation to deliver any material, code or functionality. This document is provided without a warranty of any kind, either express or implied, including but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. This document is for informational purposes and may not be incorporated into a contract. SAP assumes no responsibility for errors or omissions in this document, except if such damages were caused by SAP’s intentional or gross negligence.
Please be aware that the exchange format will change and that you may have to re-develop your code.
Basic Structure
On the top level the exchange format contains an object with two pairs:
{ "smud-data-version": "0.1", "sections": […] }
The value of sections is an array of section objects. Each section object contains a unique section identifier and a string which contains the section content. The sections array is not fixed in its current scope but can be extended with new sections. Here is an example how the sections array could look like:
{ "smud-data-version": "0.1", "sections": [ { "section-id": "NODES", "section-content": "…" }, { "section-id": "NODES-STRUCTURE", "section-content": "…" }, { "section-id": "ELEMENT-NAMES", "section-content": "…" }, { "section-id": "Graphic", "section-content": "…" }, … ] }
The value of sections is an array of section objects. Each section object contains a unique section identifier and a string which contains the section content. The sections array is not fixed in its current scope but can be extended with new sections. Here is an example how the sections array could look like:
The most basic sections are the nodes, element-names, and nodes-structure section.
Nodes
We will now have a deeper look into the single sections. First we take a look at the "NODES"-Section. The content of this section is an JSON array of node objects that is structured as follows:
Property Name | Type | Description | ||||||||||||
occ_id | Char (22) | Identifier of the element | ||||||||||||
obj_type | Char (26) | Identifier of the element type | ||||||||||||
reference | Char (22) | Identifier of the referenced original element | ||||||||||||
deleted | Boolean | TRUE if the element is flagged as deleted. | ||||||||||||
attributes | Array
| List of attribute objects |
We use 22 character long GUIDs. These GUIDs may be generated with different algorithms. There is no standard algorithm for the generation or conversion. Therefore you must not do any calculations or conversions to other GUID formats with these GUIDs.
Here is an example of a "NODES" content array:
[ { "occ_id": "051MZiix7jMTW8LkOgN470", "obj_type": "PROCSTEPGRP", "reference": "", "deleted": "", "attributes": [] }, { "occ_id": "051MZiix7jMTW8LkOgOa70", "obj_type": "REF_PROCSTEP", "reference": "051MZiix7jMTW8LkOgM470", "deleted": "", "attributes": [ { "attr_type": "TCTYPE", "lang": "", "values": [ "N" ] }, { "attr_type": "DESCRIPTION", "lang": "E", "values": [ "Process Step 1" ] } ] } ]
Element-Names
In Solution Documentation it is possible to model which element attribute should be used as name in the UI. To encapsulate the determination logic an additional section "ELEMENT-NAMES" contains the element names. This section is optional. Names are also transferred in the nodes section e.g. with attr_type DESCRIPTION. It might just be more convenient for reading and writing.
Property Name | Type | Description |
occ_id | Char (22) | Identifier of the element |
Title | String | UI title of the element in Solution Documentation |
[ { "occ_id": "051MZiix7jMTW82CyoA45G", "name": "Process Step 2" }, { "occ_id": "051MZiix7jMTW82CyoBa5G", "name": "Process Steps" } ]
Nodes-Structure
The section content of "NODES-STRUCTURE" contains an adjacency list representing the tree structure of the underlying nodes.
Note
The root element of the tree-structure is the Node that has 'ROOT' as its obj_attribute.
Property Name | Type | Description | ||||||
parent_occ | Char (22) | Identifier of the element | ||||||
children | Array
| List of children. |
[ { "parent_occ": "051MWq{r7jIkx6yZmrHPGW", "children": ["051MWq{r7jIkx6yZmrHvGW"] }, { "parent_occ": "051MWq{r7jIkx6yZmrHvGW\", "children": ["051MWq{r7jIkx6yZmrIPGW","051MWq{r7jIkx6yZmrIvGW"] }, { "parent_occ": "051MWq{r7jIkx6yZmrIPGW ", "children": [...] }, ... ]
Graphics
The GRAPHIC section contains the data of a diagram element in the hierarchy. The section is composed of:
- The MODELVERSION specifying the version of the diagram JSON representation. The value is of 1.0:
- a DIAGRAMS section holding the Set of all Diagram elements,
- a DATAOBJECTS section holding the Set of Data Objects,
- a DATASTORES section holding the Set of Data Stores,
- a ROLES section holding the Set of Roles,
- a FREECOMPONENTS section holding the Set of Free Components.
Each Diagram in section DIAGRAMS is formed of:
- an ATTRIBUTES section describing the attributes of the diagram,
- an ENTITIES section containing the set of Entities belonging to a given diagram,
- a LINKS section containing the set of Links belonging to a given diagram,
- a COLLECTIONS section containing the set of Collections belonging to a diagram.
Each entity in the ENTITIES section contains a LAYOUT section.
ENTITIES section
All BPMN objects drawn on a diagram are included in the ENTITIES section. This comprise the following BPMN entities:
- Pool,
- Lane,
- Activity,
- Artifact,
- Event,
- SubProcess,
- Gateway,
- SequenceFlow,
- Association,
- Dataobject,
- DataStore,
Additionally, for a diagram, References and Diagrams can be assigned to:
- Start and End Events:
Multiple Processes can be assigned to an Event, and for each assigned Process, it is possible to assign one of its Diagrams. - SubProcess:
A single Process can be assigned to a SubProcess, and it is possible to assign one of its Diagrams. - Intermediate Events:
Multiple Interfaces (Interface and Complex Interface) can be assigned to an Event, and for each assigned Complex Interface, it is possible to assign one of its Diagrams.
Entity Assigned References and Diagrams are included using the special REFERENCE entity. The REFERENCE entity is also included in the COLLECTIONS section. REFERENCE entities are special entities that are not displayed but used for the assignments.
Each Entity has a LAYOUT section describing the entity specificities.
LINKS section
All Links (SequenceFlow and Association) are included in section LINKS with “SOURCE_ID" and "TARGET_ID" pointing respectively to the source and target object of the link.
COLLECTIONS section
All REFERENCE Entities, specifying the assigned objects to one entity, are included in the COLLECTIONS section.
JSON description
Please check here.
Update Policy
We tried to keep the update policy as simple as possible. It is not necessary to re-upload the whole data-structure or sections-array but just the changes you made(deltas). For example you only want to change the name of two nodes, you simply upload the list of these two nodes with changed name. Or if you want to reassign a Node in the tree-structure, just upload the adjacency entry of the old and the new parent. If you want to make bigger changes and it would be easier to just upload the whole structure with changes included instead of filtering out all the deltas, you can do just that. But keep in mind to take care of your data consistency if uploading the whole structure.