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:

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.

[
	{
    	"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. 

[
	{
		"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.