From 207f9475a0273d6e2ea1a69efe6dca672b90512c Mon Sep 17 00:00:00 2001 From: burnettk Date: Fri, 3 Nov 2023 11:38:59 -0400 Subject: [PATCH] update the docs on data --- docs/Building_Diagrams/data.md | 9 +++++++++ docs/Building_Diagrams/data_objects.md | 6 ------ docs/Building_Diagrams/data_stores.md | 12 ++++++++++++ docs/Building_Diagrams/task_data.md | 17 +++++++++++++++++ docs/index.md | 2 +- 5 files changed, 39 insertions(+), 7 deletions(-) create mode 100644 docs/Building_Diagrams/data.md create mode 100644 docs/Building_Diagrams/data_stores.md create mode 100644 docs/Building_Diagrams/task_data.md diff --git a/docs/Building_Diagrams/data.md b/docs/Building_Diagrams/data.md new file mode 100644 index 00000000..2a715bda --- /dev/null +++ b/docs/Building_Diagrams/data.md @@ -0,0 +1,9 @@ +# Data + +```{toctree} +:maxdepth: 1 +:caption: Types of Data +task_data.md +data_objects.md +data_stores.md +``` diff --git a/docs/Building_Diagrams/data_objects.md b/docs/Building_Diagrams/data_objects.md index 10581124..4c10e358 100644 --- a/docs/Building_Diagrams/data_objects.md +++ b/docs/Building_Diagrams/data_objects.md @@ -35,12 +35,6 @@ Signifies the data or information that is generated or produced as a result of e A Data Object in BPMN typically represents a specific piece of information or a data entity that is exchanged or manipulated during the course of a business process. It can represent both physical and digital data. Examples of Data Objects include documents, forms, reports, databases, or any other data entity relevant to the process. -### Data Store - -![data_store](images/data_store.png) - -A Data Store represents a persistent storage location where data is stored and retrieved during the course of a process. It typically represents a database, file system, or any other storage mechanism. Data Stores are used to depict the long-term storage of data that can be accessed by multiple activities or tasks within the process. They provide a centralized location for data storage and retrieval. - ## Data Input Configuration | 💻 Form | ⌨ Field Input | 📝 Description | diff --git a/docs/Building_Diagrams/data_stores.md b/docs/Building_Diagrams/data_stores.md new file mode 100644 index 00000000..7ad2181c --- /dev/null +++ b/docs/Building_Diagrams/data_stores.md @@ -0,0 +1,12 @@ +# Data Stores + +![data_store](images/data_store.png) + +A Data Store is a BPMN construct that represents a storage location where data is stored and retrieved and can be accessed among multiple process instances, including for different process models. +It can represent a database, file system, or any other storage mechanism. + +## When to use + +You might use a Data Store when you it is not sufficient for data to be accessible in just a single process instance, but it needs to be shared across process instances. +If you a have a use case where you need to store data and access it from multiple different process instances, you could also consider using a Service Task to contact a database external to SpiffWorkflow, either via a database library in a connector or using a database via API. +All of these mechanisms work well in SpiffWorkflow, so the choice will depend on your storage and performance requirements. diff --git a/docs/Building_Diagrams/task_data.md b/docs/Building_Diagrams/task_data.md new file mode 100644 index 00000000..52a0fecc --- /dev/null +++ b/docs/Building_Diagrams/task_data.md @@ -0,0 +1,17 @@ +# Task Data + +Task data is copied from task to task. + +For example, consider the following sequence of tasks: + +1. Start Event +2. Set Variable (sets variable a) +3. Read Variable (reads variable a) + +In this scenario, if the "Set Variable" task sets the value of variable a to the number 1, the "Read Variable" task that follows can access that value (oh, cool, 1). + +When the flow splits, as in a set of parallel branches, each branch gets a copy of the same data. +Then, when the data is merged back together at a merging gateway, if multiple branches write to the same variable, the last branch to complete will be the data that is propagated to tasks after the merging gateway. +Therefore, if you have tasks a, b, and c that run in parallel, it might not be a good idea for both a and b to set the "desired_withdrawal_amount" variable, since, depending on how fast a and b ran (and other implementation details around the parallel processing), the expected "winner" would not be knowable in advance. + +This general branching and merging strategy is applied to all parallel constructs, including inclusive gateways. diff --git a/docs/index.md b/docs/index.md index d9a81c16..c0fe14dd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,7 @@ Building_Diagrams/signal_events.md Building_Diagrams/Displaying_Content.md Building_Diagrams/Script_Tasks.md Building_Diagrams/sub-processes_and_call_activities.md -Building_Diagrams/data_objects.md +Building_Diagrams/data.md Building_Diagrams/dmn.md Building_Diagrams/Extensions.md Building_Diagrams/pools_and_lanes.md