new Data handling with global data store and local process variables

Author: iaktern

content/_meta.ts

@@ -35,8 +35,8 @@ const meta: MetaRecord = {
   'user-guide': {
     title: 'User Guide',
   },
-  'developer': {
-    title: 'Developer Information',
+  'reference': {
+    title: 'Reference',
   },
   'adv-process-deployment': {
     title: 'Advanced Process Deployment',

content/developer/_meta.ts content/reference/_meta.tscontent/developer/_meta.ts renamed to content/reference/_meta.ts

@@ -1,7 +1,7 @@
 import type { MetaRecord } from 'nextra';
 
 const meta: MetaRecord = {
-  'script-task-api': 'Script Task API',
+  "script-task-api": "Script Task API",
   'bpmn': 'BPMN Serialization',
   'ms-api': {
     title: 'MS API',

content/developer/bpmn/_meta.ts content/reference/bpmn/_meta.tscontent/developer/bpmn/_meta.ts renamed to content/reference/bpmn/_meta.ts

@@ -1,15 +1,22 @@
 import { Callout } from 'nextra/components';
 
-# Process Data
+# Data Objects and Variables
 
-Process data can be stored in _Variables_. Variables are currently created on the process level within the _Automation_ of the Property panel or directly from within the UserTask Editor.
-The specification of a Process Variable is serialized into BPMN.
+For automating processes, the transfer and storing of data is essential. 
+In an automated process, data is stored as so-called _"Data Objects"_ or _"Variables"_. 
+There are two location where data is stored: in the process instance or in the global Data Store.
+The data inside the global Data Store is independent of one process and is managed inside the Management System.
+Therefore, the definition of this data must not be serialized in the BPMN process.
+So, this page only describes the serialization of process data created within a process instance. 
 
-<Callout type='info'>
-  The serialization of Process Variables in PROCEED is not yet BPMN conform. There is no `itemDefinition`, `dataObject`
-  or `ioSpecification` created at design time and this elements are also not considered during execution of the process
-  at runtime.
-</Callout>
+# Process Data Serialization
+
+Process Data Objects can be created in the following ways:
+1. On the _process level_: within the _Automation_ tab of the Property panel there is a table to create Variables
+1. Inside a _UserTask_: for using process data, the UserTask editor offers a direct possibility to create new Variables
+1. Inside a _ScriptTask_: the `variable.XXX` library functions offers functionality to create new Variables
+
+Only for the first two options, it is possible to serialize the variable specification in the BPMN, because there definition happens at process design-time. (The creation within ScriptTask happens at runtime, so the Variables are not serialized in BPMN. But ScriptTasks can also access defined Variables from the process level or UserTask.)
 
 Variables are serializes as follows:
 
@@ -44,19 +51,31 @@ Variables are serializes as follows:
   ...
 ```
 
-A process variable is accessible within the process level and all of its sub-processes or tasks.
+<Callout type='info'>
+  The serialization of Process Variables in PROCEED is not yet BPMN conform. There is no `itemDefinition`, `dataObject`
+  or `ioSpecification` created at design time and this elements are also not considered during execution of the process
+  at runtime.
+</Callout>
+
+## Runtime behaviour
 
-During execution, _Activities/Tasks_ usually first **write** into local Task variables. After finishing the Tasks, the Engine writes the local variable states into the global variable states of the process instance.
-(_Exception:_ Script Tasks have a function to directly change the state of a global variable.)
-If two Activities/Tasks write in parallel to the same global variable, the latest executions wins and overrides the global variable value.
+During runtime, a process variable is accessible within the process level and all of its Sub-Processes, Activities, Tasks, Gateways or Events.
+Tasks usually first copy the process variables into local task variables ([the _local_ scope](../script-task-api)). 
+During execution of the Task, this local data can be modified and after finishing the tasks, the local variable states are written back into the process variable states of the process instance.
+(_Exception:_ Script Tasks have functions that can directly change the state of a process variable.)
+If two parallel Tasks write to the same process Variable after the Task finishes, the latest executions wins and overrides the process variable value.
 
+{/*
 This behaviour is a little bit different with a running _call activity_, because it is started as a
 completely separated process. Therefore, the current process variables are
 copied into the call activity execution at its start. After its execution, all
 _changed_ or _new_ variables from the call activity process are copied into the
 parent process. So, this maybe overrides a process variable at the end of the
 execution.
+*/}
 
+{/*
 _Advanced:_ Moreover, within PROCEED it can happen that parts of the process are executed on
 another Machine. When two parts are _merged_ on one Machine, newer variables
 changes override older values.
+*/}