diff --git a/config.yaml b/config.yaml
index c152132..c0d1354 100644
--- a/config.yaml
+++ b/config.yaml
@@ -130,10 +130,6 @@ params:
quote: You guys are rock stars. I really appreciate your passion and your expertise on this project. I’m very excited too about what we can do with it in the future.
job: VP - IT - UVA
img: ron
- - name: Anonymous CTO
- quote: Lorem ipsum dolor sit amet, elit deleniti dissentias quo eu, hinc minim appetere te usu, ea case duis scribentur has. Duo te consequat elaboraret, has quando suavitate at.
- job: CTO
- img: brian
section5: true
footer:
# Logo (from /images/logos/___)
diff --git a/content/posts/articles/get_started.md b/content/posts/articles/get_started.md
index fdd47f8..39279e2 100644
--- a/content/posts/articles/get_started.md
+++ b/content/posts/articles/get_started.md
@@ -7,7 +7,7 @@ thumbnail: /images/articles/get_started_thumbnail.png
---
In this article (and accompanying video) you will create and run your first executable SpiffWorkflow diagram. We'll be using a brand new open source application called SpiffArena that wraps the SpiffWorkflow library in an easier to use interface that provides a host of important tools. Let's get started and you can see for yourself ...
-
+
## Install and Start SpiffArena
@@ -48,22 +48,22 @@ Let’s build and run a very simple workflow to get familiar with the interface,
**Select “Processes” from the Main Menu**
-
+
**Select “Add a process group”**
-
+
**Provide the following information:**
1. Display Name: “Playground” _The identifier will automatically be set to “playground”. We will cover other fields and options at another time._
2. Description: “These are my test processes.”
3. Click “Submit”
-
+
**Select “Add a process model” (the second button)**
-
+
**Provide the following information:**
* Display Name: “Simple Example”
@@ -78,41 +78,41 @@ Let’s draw a simple functional BPMN Diagram
Every new BPMN diagram is initially populated with a Start Event, which looks like an open circle. Click on it and it will show a blue outline and a “context menu” – find the “Task” icon in the menu (the rectangle with rounded corners) and click it to “Append Task”.
-
+
Your diagram should now look like this:
-
+
-Now let’s turn the “Task” (the rectangle) into a Script Task, and we will add a bit of Python code to our diagram. Click the Task, to get the context menu up again. Click the wrench icon , and select  “Script Task” from the list of options.
+Now let’s turn the “Task” (the rectangle) into a Script Task, and we will add a bit of Python code to our diagram. Click the Task, to get the context menu up again. Click the wrench icon , and select  “Script Task” from the list of options.
At this point your cursor will be blinking inside of the Task icon, allowing you to enter the name of the Task. For this time we will use an alternative method, described in the next step
Click anywhere off the Task and your diagram should now look like this:
-
+
Select the Script Task (the rectangle should have a blue outline around it) and then take a look at the options in the Properties Panel on the right. You should see something like the image below. There are three sections. When you click on a section it will expand.
-
+
Click General so it is expanded, we can give the Task a name. Let’s call it “Set Name”. Your diagram should now look like this:
-
+
For this exercise we’ll need two Tasks, so similar to how you added the first Task after the Start Event click on the Script Task you just added, and append a second task,
-
+
so the diagram looks like this:
-
+
Take advantage of the blinking cursor in the middle of the newly added Task and name it “Display Message”. Next click on the wrench icon and select “Manual Task” . And to complete the diagram, click on the bolded circle at the top left, it should say “Append EndEvent” as shown below.
-
+
Your diagram should now look like this:
-
+
Now let’s add a bit of Python code to execute. Click in the Script Task and expand the “Script” Section and click the “Launch Editor” button – which will bring up a python editor. Paste in the following code, and click the Close Button.
{{< highlight Python "linenos=true" >}}
@@ -131,7 +131,7 @@ Welcome to SpiffWorkflow!
The right hand Property Panel should look like this (you may need to grab the bottom left of the Instruction box and drag it down to see everything you pasted in there).
-
+
Save the diagram using the save button in the upper left. When it asks for a name call it “hello_world”
@@ -141,7 +141,7 @@ Click the Start button, and you should be greeted with your “Hello World!” m
Click the Continue button to return to the Home page and then the Completed tab to see your first completed process instance!
-
+
### Shutting it all down
diff --git a/content/posts/articles/get_started/add_process.png b/content/posts/articles/get_started/add_process.png
new file mode 100644
index 0000000..f980a5f
Binary files /dev/null and b/content/posts/articles/get_started/add_process.png differ
diff --git a/content/posts/articles/get_started/add_process_model.png b/content/posts/articles/get_started/add_process_model.png
new file mode 100644
index 0000000..0f92170
Binary files /dev/null and b/content/posts/articles/get_started/add_process_model.png differ
diff --git a/content/posts/articles/get_started/append_task.png b/content/posts/articles/get_started/append_task.png
new file mode 100644
index 0000000..009a637
Binary files /dev/null and b/content/posts/articles/get_started/append_task.png differ
diff --git a/content/posts/articles/get_started/diagram_1.png b/content/posts/articles/get_started/diagram_1.png
new file mode 100644
index 0000000..d3ef3e5
Binary files /dev/null and b/content/posts/articles/get_started/diagram_1.png differ
diff --git a/content/posts/articles/get_started/diagram_2.png b/content/posts/articles/get_started/diagram_2.png
new file mode 100644
index 0000000..04df9c6
Binary files /dev/null and b/content/posts/articles/get_started/diagram_2.png differ
diff --git a/content/posts/articles/get_started/diagram_3.png b/content/posts/articles/get_started/diagram_3.png
new file mode 100644
index 0000000..ba56495
Binary files /dev/null and b/content/posts/articles/get_started/diagram_3.png differ
diff --git a/content/posts/articles/get_started/diagram_4.png b/content/posts/articles/get_started/diagram_4.png
new file mode 100644
index 0000000..6b5b2ce
Binary files /dev/null and b/content/posts/articles/get_started/diagram_4.png differ
diff --git a/content/posts/articles/get_started/diagram_5.png b/content/posts/articles/get_started/diagram_5.png
new file mode 100644
index 0000000..d248e39
Binary files /dev/null and b/content/posts/articles/get_started/diagram_5.png differ
diff --git a/content/posts/articles/get_started/diagram_6.png b/content/posts/articles/get_started/diagram_6.png
new file mode 100644
index 0000000..603da81
Binary files /dev/null and b/content/posts/articles/get_started/diagram_6.png differ
diff --git a/content/posts/articles/get_started/diagram_7.png b/content/posts/articles/get_started/diagram_7.png
new file mode 100644
index 0000000..a691c72
Binary files /dev/null and b/content/posts/articles/get_started/diagram_7.png differ
diff --git a/content/posts/articles/get_started/final_screen.png b/content/posts/articles/get_started/final_screen.png
new file mode 100644
index 0000000..c827e86
Binary files /dev/null and b/content/posts/articles/get_started/final_screen.png differ
diff --git a/content/posts/articles/get_started/process_goup_form.png b/content/posts/articles/get_started/process_goup_form.png
new file mode 100644
index 0000000..5c2a539
Binary files /dev/null and b/content/posts/articles/get_started/process_goup_form.png differ
diff --git a/content/posts/articles/get_started/prop_panel_manual.png b/content/posts/articles/get_started/prop_panel_manual.png
new file mode 100644
index 0000000..3b63031
Binary files /dev/null and b/content/posts/articles/get_started/prop_panel_manual.png differ
diff --git a/content/posts/articles/get_started/prop_panel_script.png b/content/posts/articles/get_started/prop_panel_script.png
new file mode 100644
index 0000000..6aed4f9
Binary files /dev/null and b/content/posts/articles/get_started/prop_panel_script.png differ
diff --git a/content/posts/articles/get_started/script_task.png b/content/posts/articles/get_started/script_task.png
new file mode 100644
index 0000000..a5b42dd
Binary files /dev/null and b/content/posts/articles/get_started/script_task.png differ
diff --git a/content/posts/articles/get_started/select_processes.png b/content/posts/articles/get_started/select_processes.png
new file mode 100644
index 0000000..fce0d82
Binary files /dev/null and b/content/posts/articles/get_started/select_processes.png differ
diff --git a/content/posts/articles/get_started/spiff_arena.png b/content/posts/articles/get_started/spiff_arena.png
new file mode 100644
index 0000000..649b42d
Binary files /dev/null and b/content/posts/articles/get_started/spiff_arena.png differ
diff --git a/content/posts/articles/get_started/wrench.png b/content/posts/articles/get_started/wrench.png
new file mode 100644
index 0000000..6ca0a66
Binary files /dev/null and b/content/posts/articles/get_started/wrench.png differ
diff --git a/content/posts/articles/visual_workflows.md b/content/posts/articles/visual_workflows.md
index a41d668..88c737e 100644
--- a/content/posts/articles/visual_workflows.md
+++ b/content/posts/articles/visual_workflows.md
@@ -7,7 +7,7 @@ author: Dan Funk
thumbnail: images/articles/lowcode_thumbnail.png
---
-
+
(originally posted on [Medium](https://medium.com/@danfunk/a-visual-workflow-library-for-python-d19e1387653))
@@ -26,7 +26,7 @@ Visual software development environments are key for handling many of the busine
The term “Workflow” can mean many things in software. Our focus is on Business Processes — such as the complex approval process necessary for launching a medical research study at a university (our core use case at the moment). There is a well established standard for visualizing business processes called BPMN (Business Process Modeling Notation) that looks a heck of a lot like a flow chart (see image below). Version 2.0 published in 2010 was designed to be executable. This is important.
-{{< figure src="/images/articles/lowcode_diagram.png" caption="Not to delve too deeply, but the arrows in the diagram above dictate motion from one task to the next. The boxes with people are User Tasks, and are often powered by user interfaces that allow real people to provide input. The X’s are crossroads where different paths can be taken. The script tasks (with the piece of curvy paper) are where we can inject brief bits of code to make calculations and call out to other software systems and APIs. This is a very small example of all that is possible within the enormous 538 page BPMN standard, but it is a valid example, and demonstrates that powerful diagramming tools can still be intuitive." >}}
+{{< figure src="lowcode_diagram.png" caption="Not to delve too deeply, but the arrows in the diagram above dictate motion from one task to the next. The boxes with people are User Tasks, and are often powered by user interfaces that allow real people to provide input. The X’s are crossroads where different paths can be taken. The script tasks (with the piece of curvy paper) are where we can inject brief bits of code to make calculations and call out to other software systems and APIs. This is a very small example of all that is possible within the enormous 538 page BPMN standard, but it is a valid example, and demonstrates that powerful diagramming tools can still be intuitive." >}}
What’s great about BPMN is that you can potentially create software even a CEO can understand. Imagine having a board meeting where everyone around the table actually knew what they were talking about. This is the glorious promise of BPMN. A diagram that doesn’t roughly abstract the general meaning of what we think the software does. It’s a diagram that IS the software.
diff --git a/static/images/articles/lowcode.png b/content/posts/articles/visual_workflows/lowcode.png
similarity index 100%
rename from static/images/articles/lowcode.png
rename to content/posts/articles/visual_workflows/lowcode.png
diff --git a/static/images/articles/lowcode_diagram.png b/content/posts/articles/visual_workflows/lowcode_diagram.png
similarity index 100%
rename from static/images/articles/lowcode_diagram.png
rename to content/posts/articles/visual_workflows/lowcode_diagram.png
diff --git a/content/posts/deep_dives/_index.md b/content/posts/deep_dives/_index.md
index 861545b..d02dd58 100644
--- a/content/posts/deep_dives/_index.md
+++ b/content/posts/deep_dives/_index.md
@@ -3,5 +3,4 @@ title: Deep Dive Articles
subtitle: These articles delve a little deeper into the BPMN Standard or provide technical details on complex implementations.
date: 2022-12-29T16:16:00-05:00
---
-
-# Is this really not here?
+These articles are “Deep Dives” into specific areas of SpiffWorkflow that deserve some special attention. We hope that these articles will help spawn higher level discussions that will guide SpiffWorkflow’s future development.
diff --git a/content/posts/deep_dives/data_objects.md b/content/posts/deep_dives/data_objects.md
new file mode 100644
index 0000000..dad08de
--- /dev/null
+++ b/content/posts/deep_dives/data_objects.md
@@ -0,0 +1,116 @@
+---
+title: "Data Objects in SpiffWorkflow"
+subtitle: "Or, “A diagram of Love”"
+date: 2022-09-13T10:00:00-05:00
+draft: false
+author: Dan Funk
+thumbnail: /images/articles/data_object_thumbnail.png
+---
+
+
+
+
+### A Simple Default
+One of the benefits of both BPMN and Python is they have low-sloped learning curves. Things are simple by default. As we introduce new concepts into SpiffWorkflow we want the default behavior to be equally intuitive.
+
+In SpiffWorkflow, data follows the process flow. Each task receives all data from the previously executed task.
+
+
+
+
+As such, you can expect your web form submission to be available as variables in the following service task. And the variables you create in that task will be available to the next task, and so on.
+
+We call this type of data **Task Data**, because it belongs to the task. Each task has full control over the information it receives, and can choose to pass the data on unaffected, or make any changes to it, including clearing it out completely.
+
+This is different from how many BPMN based systems work, but we feel it creates a very intuitive and easy to learn system. It has some limitations, particularly as your diagrams become larger and more complex. At this point BPMN Developers may need more control.
+
+
+### Data Objects
+Data Objects are graphical notations that allow BPMN Developers to control which tasks have access to which variables. As we will demonstrate below, this ability has some far reaching implications, and can become a critical tool as your BPMN structures grow in size and complexity.
+
+
+
+Rather than feed you a list of rules, we’ll cover the full definition of these notations in a detailed example later down in the article.
+
+But first we want to introduce you to one more common task with data: transforming it. This is important as you will often need to change the shape of information as you use it for different purposes.
+
+### Data Mapping and Transformations
+We added the ability to associate Pre-Scripts and Post-Scripts to most task types in the bpmn-js modeler extensions we’ve created. We found our diagrams were getting overloaded with Script Tasks, but they were the fastest and easiest way to munge data, i.e., convert it from one form to another. So now all tasks can execute small scripts if they need to alter the structure of information before it comes in, or as it leaves. Since these are scripts and can contain most any python code, they also open the opportunity to perform assertions — so you can “Fail Fast” (a respected software development idiom that encourages uncovering issues as soon as possible) by checking to see that data is in the right form before attempting to use it.
+
+#### An Example
+In this example, we will model a pizza delivery service that will cover placing the order, selecting the pizza, providing a credit card, and sending the pizza off to the delivery team. In the process, we will describe how SpiffWorkflow can solve the problem using its default behavior, then cover the major benefits of using Data Objects to manage specific situations.
+
+
+
+
+This diagram will work in SpiffWorkflow as is, and each task would gather more information, add it to the Task Data and then send a new copy of that data on to the next task in the flow. The benefit here is you don’t have to model the data at all. It’s clear where information is coming from, and that it will be available when you need it. The data and the flow are one in the same. The problem is that the Credit Card task would be passed in a list of all 500 available pizza toppings — information it really doesn’t likely need. Worse, the data we provided in credit card details will be passed on to the task for making pizza or sent off in the external call activity, data exposure which is unnecessary and potentially unsafe.
+
+#### Rule #1: Use Data Objects to reference information that will not change
+
+
+
+If we add a BPMN Data Object called “toppings,” and Load Pizza Toppings produces a variable called “toppings,” that variable is now treated as a Data Object in SpiffWorkflow. It is not passed along as a part of the Task Data. It is available for the next task, because we connect it with a Data Association (the dotted arrows). This saves us from holding multiple copies of this data in tasks where it is not relevant. It will make the model far more efficient to store and execute, and it will keep this data out of subsequent tasks that do not need it. Were another task later in the workflow to need to reference the list (say we wanted to display a detailed list of the ingredients in the final order summary), we could just link that task to toppings as well, and there is still only one actual list of toppings stored with the process.
+
+#### Rule #2: Use Data Stores to persist information
+
+
+
+If there is information that should persist beyond the scope of the process, you can use the Data Store to reference it. SpiffWorkflow will provide hooks for making this information available, but it will require some work on the part of the calling application, as Data Stores will be specific to both the implementation (the type of database in use) and the domain (orders here would be connected to the user account, but you might also save information relative to one of many delivery addresses).
+
+#### Rule #3: Do NOT use Data Objects to track things that are modified along the way
+
+
+
+Since almost all of the tasks here will need to deal with the order details, it is helpful NOT to make it a Data Object. It is far better to allow it to pass from task to task as we add additional information to the order. The process will do things like adding the calculated costs, showing that the payment is complete, and determining if the cheap gluttonous jerks bothered to leave any kind of tip for the driver.
+
+
+#### Rule #4: Do Use Data Objects to limit access to information
+
+
+
+Only two tasks need access to the Credit Card information, and it isn’t something we need or want to keep copying to later tasks. So we can split it off here and isolate access to it.
+
+#### Rule #5: Data composition should match the model composition
+
+
+
+The example above is a good candidate for a Call Activity. In this example, we use Data Objects to share information with the Call Activity, which defines its required parameters with a Data Input, shown below. The Data Input is used here to indicate that an Invoice is required by this Process, and SpiffWorkflow will throw an exception if data by this name is not available. The process below further promises to provide a “receipt” as output.
+
+
+
+
+## Two Types of Data
+I hope these examples were helpful. Just to reiterate, there are two different types of Data in SpiffWorkflow, and they behave slightly differently. Here is an overview of their behavior for reference:
+
+### Task Data
+Task Data is information that belongs to the TASK. It is most useful within a single process model that does not contain large amounts of information.
+
+* Task Data is thread safe by nature, as the data follows the Flow (arrows) of the BPMN diagram.
+* Task Data is transferred by default. Any variables created by forms, decision tables, and scripts are passed on in the Task Data.
+* Task Data behaves like a pipeline architecture. Each task has control over the data and may alter it in any way before passing it on.
+* Each completed task in a workflow will retain a copy of the data as it was when the task executed. “Rewinding” to a previously completed task would allow access to the Task Data as it was when the Task was first executed.
+* Task Data can be directly referenced by name in script tasks, gateways, forms in user tasks, and decision tables.
+
+### Dat Objects
+Data Objects are information that belongs to the PROCESS. It offers encapsulation as well as control over data from within the BPMN diagram. Data Objects are most useful when decomposing complex diagrams into call activities, referencing a large data set, or protecting sensitive information.
+
+* It is represented and controlled by BPMN Data Objects, Data Inputs, Data Outputs, and Data Stores, which are all visible elements in the BPMN Diagram.
+* A Data Object is scoped to the process in which it is defined.
+* A Data Object can be used to share data with a Call Activity through Data Inputs and Data Outputs.
+* A Data Object is defined by a name, and during execution, a variable by this name is guaranteed to exist for all connected tasks.
+* Parallel tasks can share a data object and see changes immediately. This is not true of Task Data.
+
+As Bruno Paré-Simard pointed out in a recent GitHub Issue, we should find ways to Type our Data Objects to assure they meet a certain data structure, or can be mapped to a specific class, and we are considering ways to make this happen while respecting the BPMN standard.
+
+## References and Further Reading
+The implementation of BPMN Data Objects, Data Inputs and Data Outputs has, at times, been hotly debated, as you can find in the comments of this article from BPMN expert Bruce Silver: https://www.trisotech.com/bpmn-decoded-data-flow/
+
+We looked at a number of existing BPMN based products to see how they handled Data, and they took widely divergent approaches. We looked closely at some other BPMN implementations as we formulated our approach.
+
+Camunda [avoids the use of BPMN’s Data Objects](https://docs.camunda.io/docs/components/best-practices/development/handling-data-in-processes/) and prefers its own proprietary method for transferring data between tasks, as they describe in their documentation.
+
+Flowable [follows this same trend](https://www.flowable.com/open-source/docs/bpmn/ch07b-BPMN-Constructs/#passing-variables), evolving away from the BPMN spec and using extension elements to handle the exchange of data.
+
+Trisotech favors using Data Objects for all data, and sticks close the the standard as described in this recent Bruce Silver article: https://methodandstyle.com/executable-bpmn-vs-method-and-style/
+
+In our opinion, these all seem to create difficult interfaces for Citizen Developers (folks from other domains that have picked up programming skills along the way) — and we are hoping that our approach makes it a little easier for people to develop BPMN diagrams without having to understand everything from the very beginning.
diff --git a/content/posts/deep_dives/data_objects/data_object.png b/content/posts/deep_dives/data_objects/data_object.png
new file mode 100644
index 0000000..00d0e71
Binary files /dev/null and b/content/posts/deep_dives/data_objects/data_object.png differ
diff --git a/content/posts/deep_dives/data_objects/default.png b/content/posts/deep_dives/data_objects/default.png
new file mode 100644
index 0000000..d4e05d0
Binary files /dev/null and b/content/posts/deep_dives/data_objects/default.png differ
diff --git a/content/posts/deep_dives/data_objects/example.png b/content/posts/deep_dives/data_objects/example.png
new file mode 100644
index 0000000..e17d304
Binary files /dev/null and b/content/posts/deep_dives/data_objects/example.png differ
diff --git a/content/posts/deep_dives/data_objects/intro.png b/content/posts/deep_dives/data_objects/intro.png
new file mode 100644
index 0000000..900d2b2
Binary files /dev/null and b/content/posts/deep_dives/data_objects/intro.png differ
diff --git a/content/posts/deep_dives/data_objects/receipt.png b/content/posts/deep_dives/data_objects/receipt.png
new file mode 100644
index 0000000..5481a3f
Binary files /dev/null and b/content/posts/deep_dives/data_objects/receipt.png differ
diff --git a/content/posts/deep_dives/data_objects/rule1.png b/content/posts/deep_dives/data_objects/rule1.png
new file mode 100644
index 0000000..e3af301
Binary files /dev/null and b/content/posts/deep_dives/data_objects/rule1.png differ
diff --git a/content/posts/deep_dives/data_objects/rule2.png b/content/posts/deep_dives/data_objects/rule2.png
new file mode 100644
index 0000000..7a7138a
Binary files /dev/null and b/content/posts/deep_dives/data_objects/rule2.png differ
diff --git a/content/posts/deep_dives/data_objects/rule3.png b/content/posts/deep_dives/data_objects/rule3.png
new file mode 100644
index 0000000..27d0eae
Binary files /dev/null and b/content/posts/deep_dives/data_objects/rule3.png differ
diff --git a/content/posts/deep_dives/data_objects/rule4.png b/content/posts/deep_dives/data_objects/rule4.png
new file mode 100644
index 0000000..6b28c0f
Binary files /dev/null and b/content/posts/deep_dives/data_objects/rule4.png differ
diff --git a/content/posts/deep_dives/data_objects/rule5.png b/content/posts/deep_dives/data_objects/rule5.png
new file mode 100644
index 0000000..479aacf
Binary files /dev/null and b/content/posts/deep_dives/data_objects/rule5.png differ
diff --git a/content/posts/deep_dives/messages.md b/content/posts/deep_dives/messages.md
index 8512d25..f55540e 100644
--- a/content/posts/deep_dives/messages.md
+++ b/content/posts/deep_dives/messages.md
@@ -1,122 +1,149 @@
---
title: "BPMN Messages in SpiffWorkflow"
subtitle: "Or, “A diagram of Love”"
-date: 2022-12-27T13:15:00-05:00
+date: 2022-09-21T10:00:00-05:00
draft: false
author: Dan Funk
-thumbnail: /images/articles/messages/messages_thumbnail.png
+thumbnail: /images/articles/messages_thumbnail.png
---
-This is a deep dive into BPMN 2.0 Messages and how we implemented them in our open source project SpiffWorkflow. If you want to get a gentle introduction to our project, please check out this article. This will be primarily of interest to people who care about the BPMN 2.0 standard or are developing larger applications with Spiffworkflow that would benefit from having their BPMN diagrams communicate with each other. This is thick material, but there is a beautiful idea here well worth understanding, and beneficial to anyone who is interested in prolonged communications between complex systems.
+
+
+This is a deep dive into BPMN 2.0 **Messages** and how we implemented them in our open source project SpiffWorkflow. This will be primarily of interest to people who care about the BPMN 2.0 standard or are developing larger applications with Spiffworkflow that would benefit from having their BPMN diagrams communicate with each other. This is thick material, but there is a beautiful idea here well worth understanding, and beneficial to anyone who is interested in prolonged communications between complex systems.
Adherence to the BPMN standard for Messages is exceedingly rare. There are few working examples that actually implement the standard or attempted to further its adoption. That isn’t surprising, as the BPMN specification’s paragraph on Message “Correlations” is one the most dense and challenging bits of technical writing you will ever be so unfortunate as to confront. But it is beautiful at its heart, and we will try to capture that here.
-The Concepts
-In this section we will cover the following major concepts: The Message itself, Collaborations, and Correlations. Understanding these concepts is critical to the following sections where we will describe their usage.
+### The Concepts
+In this section we will cover the following major concepts: The **Message** itself, **Collaborations**, and **Correlations**. Understanding these concepts is critical to the following sections where we will describe their usage.
-A Simple Message
+### A Simple Message
Messages themselves are pretty simple. They have a unique name and a payload. If you imagine two people talking in a quiet room, that’s all that is needed.
Messages always have a one-to-one relationship. One sender to one receiver.
To better explain messages, we’ll build on a simple example that doesn’t initially require one. Buddy and Peggy, deeply in love, are in a tight embrace and Buddy says: “Peggy Sue, Oh how my heart yearns for you”, and Peggy, hearing it, responds: “Buddy Holly, how you make my heart jolly!” It is a perfect moment, and can be captured in a happy little BPMN diagram.
+
But love isn’t always so simple. And neither is BPMN.
-Collaborations
+### Collaborations
Let’s move Buddy and Peggy to a room full of romantic couples and track all the romantic profferings in BPMN. To do that we will need to use more generic terms and introduce a Collaboration diagram, as shown below. Collaborations encompass multiple participants/processes with interconnected messages.
+
Imagine we have 2 “Admirer” and 2 “Beloved” instances running at the same time: Buddy and Mary Jane play the “Admirer”, “Peggy” and “Tom” are the beloved. If we get this right, it’s a romantic evening. If we get it wrong, there will be blood.
It is all about context. If Buddy is saying nice things to Peggy, then we don’t want Peggy responding to Mary Jane. The critical concept here is a “conversation”, and just like in real life, there are some very complex social rules about how conversations work.
-Some “conversations” in life are terrible. They seem to meander about from one thing to the next with no rhyme or reason, and no end in sight. That isn’t an actual conversation, it’s a nuisance — an area not covered by BPMN. We want good conversations, and that requires a subject or topic on which the conversation is grounded. All the messages back and forth should relate to the topic of the conversation. Or, to use the correct BPMN words, a Collaboration (the conversation) has a CorrelationKey (topic). THIS IS IMPORTANT
+Some “conversations” in life are terrible. They seem to meander about from one thing to the next with no rhyme or reason, and no end in sight. That isn’t an actual conversation, it’s a nuisance — an area not covered by BPMN. We want good conversations, and that requires a subject or topic on which the conversation is grounded. All the messages back and forth should relate to the topic of the conversation. Or, to use the correct BPMN words, a **Collaboration** (the conversation) has a **CorrelationKey** (topic). THIS IS IMPORTANT
-Correlations
+### Correlations
Think of a correlation as the “Subject of the Conversation”. In our example, a good subject would be the beloved’s name: “Peggy”, “Tom”. The Admirers know who they admire, and each beloved knows their own name — so we have a kind of “Key” on which to base the conversation. You don’t get the Key wrong. You don’t yell out Tom’s name in a passionate moment with Peggy.
-Collaborations, Messages, and Correlations have no visual representation in the BPMN diagrams. So I can’t draw you a picture. But they are first order concepts carefully covered in the BPMN 2.0 standard. You have to manipulate them through some sort of “Properties Panel,” which we will cover in the next section.
+**Collaborations**, **Messages**, and **Correlations** have no visual representation in the BPMN diagrams. So I can’t draw you a picture. But they are first order concepts carefully covered in the BPMN 2.0 standard. You have to manipulate them through some sort of “Properties Panel,” which we will cover in the next section.
The hardest concept for me, when I read the specification, was understanding that Correlations apply to the Collaboration as a whole. It is the subject of the conversation. It isn’t (as I struggled with for weeks) the address on an envelope. It is a sticky thing that should be used consistently across all the messages in a conversation, So as we continue, fight to keep this idea in your head: It’s all about having a good conversation about a specific subject.
+
Finally, it is worth noting that you will likely model these different processes in completely different BPMN files. So in the real world, you would describe the other process in a collapsed state as shown to the left. It will be up to the application that is executing these processes to coordinate the messages between them. We will cover that responsibility in the following section on Applications and the SpiffWorkflow Backend.
-Implementation in SpiffWorkflow
+## Implementation in SpiffWorkflow
-This section will cover the changes to 4 different SpiffWorkflow applications in order to support messages as described above, working with the standard and attempting to avoid any custom BPMN extensions. If you are wondering why we have 4 different applications and how the pieces fit together, please check out this article on our current development efforts. We’ll tackle the BPMN editor first — as this is where many of the changes are visible, then we will delve into the XML and how the backend systems will process this information.
+This section will cover the changes to 4 different SpiffWorkflow applications in order to support messages as described above, working with the standard and attempting to avoid any custom BPMN extensions. We’ll tackle the BPMN editor first — as this is where many of the changes are visible, then we will delve into the XML and how the backend systems will process this information.
-BPMN.js — Spiffworkflow
+### BPMN.js — Spiffworkflow
This section includes our additions and modifications to the excellent open source BPMN.js editor maintained by Camunda. The changes will impact the Properties Panel when specific visual elements are selected. Included here are actual screen shots from our working extensions to the BPMN.js editor. We’ll provide links lower in this article to our code repository so you can try it out!
-Collaboration
+### Collaboration
+
+
When a collaboration is selected in the editor, we will display a new section called “Correlation Keys”. We want to make it clear at a glance that this conversation is based around the “beloved_name”, and that communications back and forth should relate to this name somehow.
But this can also be a cumbersome place to go as you are working through the diagram. So we will make it possible to edit these correlation keys elsewhere within the context of Send and Receive tasks and events.
-Send Tasks, and Message Throw Events
+### Send Tasks, and Message Throw Events
+
+
When defining a message to be sent out in SpiffWorkflow, you will need to specify three things:
-The message id — a message name that should be unique among all messages in your system, but human readable. And it should match up on the receiving end.
-The Payload — the content of the message. SpiffWorkflow is all about Python, so here we define the payload as a Python Dictionary.
-Any correlations directly related to this message, if there are any.
+* The message id — a message name that should be unique among all messages in your system, but human readable. And it should match up on the receiving end.
+* The Payload — the content of the message. SpiffWorkflow is all about Python, so here we define the payload as a Python Dictionary.
+* Any correlations directly related to this message, if there are any.
+
When this message is sent out, it will contain these three parts, and the SpiffWorkflow Backend (described later) will use the ID and Correlation to match this message up with the correct process.
+
-Receive Tasks and Message Catch Tasks
+### Receive Tasks and Message Catch Tasks
When receiving a message, you can specify the message id (you can create a new id, or select it from a dropdown list). The Correlation here should match exactly the correlation defined in the other BPMN diagram if these are separate. We’ll talk about this as well in the section on SpiffWorkflow Backend, where it may be possible through API integrations to ensure these remain locked between disparate diagrams.
-Resulting XML
+### Resulting XML
The extensions we will add to BPMN.io will produce BPMN 2.0 compliant XML. We will create only one extension to the BPMN to complete this effort to make it easy to define the message payload.
-Messages and Correlations will be defined within the root element, per the specification. The SpiffWorkflow Backend will work to assure these values remain consistent across all processes, and can provide endpoints to verify the messages are correctly aligned. IMPORTANT: Don’t think about messages and correlations as belonging to a process. They do not. They belong to the system as a whole, and can be maintained across different BPMN diagrams. The resulting XML in this case is:
+Messages and Correlations will be defined within the root element, per the specification. The SpiffWorkflow Backend will work to assure these values remain consistent across all processes, and can provide endpoints to verify the messages are correctly aligned. **_IMPORTANT_**: Don’t think about messages and correlations as belonging to a process. They do not. They belong to the system as a whole, and can be maintained across different BPMN diagrams. The resulting XML in this case is:
+{{< highlight XML >}}
+
+
+
+
+
+ lover.name
+
+
+ from.name
+
+
+{{< / highlight >}}
Collaborations will contain the message flows, and will offer a correlation Key that connects the correlation properties defined as described above.
+{{< highlight XML >}}
+
+
+
+
+
+
+ Lover_first_name
+ Lover_last_name
+
+
+{{< / highlight >}}
Send Tasks and Receive Tasks can just reference the unique message id. The SendTask will include a custom SpiffWorkflow extension to define the payload in a simple and direct way, and is the only custom extension we will create as a part of this effort.
+{{< highlight XML >}}
+
+
+
+{
+'to': {'name': my_lover_var},
+'from': {'name': 'buddy'},
+'salutation': 'Dear Beloved',
+'body': 'Oh how my heart yearns for you!'
+}
+
+
+ Flow_1bl6jeh
+ Flow_0tp8uut
+
+{{< / highlight >}}
-SpiffWorkflow — Core Library
-The SpiffWorkflow BPMN interpreter, at the center of everything, will have the following modifications:
+### In Closing
+Most implementations of BPMN see messages as primarily a means of communicating with other external applications. This article is focused specifically on how multiple BPMN processes can communicate with each other in a loosely coupled way. Loosely enough, that in theory, one process could actually be an external application. Service Tasks are another way of sending and retrieving information from an external system.
-Notify the calling application of Message Send events that occur during the running of a process
-Interpret / execute the message payload and the correlation expressions
-Provide a way to accept incoming messages
-It will be the responsibility of the SpiffWorkflow Backend (or your application) to listen for these events and respond appropriately.
-
-SpiffWorkflow — Backend
-The SpiffWorkflow backend is responsible for managing multiple running instances of the SpiffWorkflow Library. It also provides API endpoints to other applications (Like SpiffWorkflow Frontend) to allow introspection and management of running processes. The following abilities will be added to the Backend:
-
-Database tables to track message definitions. For every current process model (every BPMN file) we will record what messages that process is capable of sending and receiving, and what correlation values it defines for those messages.
-Database tables to track message delivery. This will include tables that can capture a message
-API Endpoints for listing, searching, viewing, and in some cases editing these values. (Editing of Collaborations will likely be included at some future date)
-SpiffWorkflow — Frontend
-The SpiffWorkflow Frontend will add additional pages for viewing message definitions, current messages, etc, as provided by the new backend enhancements. Future releases of SpiffWorkflow’s Frontend will include documentation covering how the User Interface looks, and how it can be configured and repurposed for your specific needs.
-
-Learning More & Get Involved
-These new tools will be available in the next release of SpiffWorkflow, which are still weeks if not months off. In the meantime, if you are willing to try the bleeding edge, please check out the main branch of our repositories on GitHub:
-
-SpiffWorkflow — The main branch has support for everything described here. You can start a new project and create a dependency on our GitHub repository. In Poetry you might do something like:
-
-spiffworkflow = {git = “https://github.com/sartography/SpiffWorkflow", rev = “main”}
-SpiffWorkflow bpmn-js — Camunda’s excellent bpmn-js library can be extended to support Data Inputs and Data Outputs, as well make Data Objects a little easier to create and manage. These extensions to bpmn-js are available in the GitHub repository, which also includes a way to build and run a local BPMN editor with a simple node command.
-
-Finally, most implementations of BPMN see messages as primarily a means of communicating with other external applications. This article is focused specifically on how multiple BPMN processes can communicate with each other in a loosely coupled way. Loosely enough, that in theory, one process could actually be an external application. We will come back to external applications in a future article.
-
-References:
+### References
When tackling a new area of SpiffWorkflow we take a careful look at other BPMN based systems. Here are links to some of the resources we consulted in addition to the official BPMN 2.0 Specification.
-https://youtu.be/8SYEc3dHnM4 (great video on Camunda’s process)
-
-https://youtu.be/-UaFHzit7LA (Using Message Based Correlation in an Oracle BPM Process)
-
-https://www.trisotech.com/using-messages-in-executable-bpmn/ (Silver / Trisotech)
-
-https://community.bonitasoft.com/blog/when-use-call-activity-or-bpm-message (BonitaSoft)
+* https://youtu.be/8SYEc3dHnM4 (A great video on Camunda’s process)
+* https://youtu.be/-UaFHzit7LA (Using Message Based Correlation in an Oracle BPM Process)
+* https://www.trisotech.com/using-messages-in-executable-bpmn/ (Silver / Trisotech)
+* https://community.bonitasoft.com/blog/when-use-call-activity-or-bpm-message (BonitaSoft)
diff --git a/content/posts/deep_dives/messages/bpmn1.png b/content/posts/deep_dives/messages/bpmn1.png
new file mode 100644
index 0000000..9cd248e
Binary files /dev/null and b/content/posts/deep_dives/messages/bpmn1.png differ
diff --git a/content/posts/deep_dives/messages/bpmn2.png b/content/posts/deep_dives/messages/bpmn2.png
new file mode 100644
index 0000000..96d8c18
Binary files /dev/null and b/content/posts/deep_dives/messages/bpmn2.png differ
diff --git a/content/posts/deep_dives/messages/collaboration.png b/content/posts/deep_dives/messages/collaboration.png
new file mode 100644
index 0000000..b4c96f6
Binary files /dev/null and b/content/posts/deep_dives/messages/collaboration.png differ
diff --git a/content/posts/deep_dives/messages/event.png b/content/posts/deep_dives/messages/event.png
new file mode 100644
index 0000000..d49a0ce
Binary files /dev/null and b/content/posts/deep_dives/messages/event.png differ
diff --git a/content/posts/deep_dives/messages/happy.png b/content/posts/deep_dives/messages/happy.png
new file mode 100644
index 0000000..6e6d8a0
Binary files /dev/null and b/content/posts/deep_dives/messages/happy.png differ
diff --git a/static/images/articles/messages/intro.png b/content/posts/deep_dives/messages/intro.png
similarity index 100%
rename from static/images/articles/messages/intro.png
rename to content/posts/deep_dives/messages/intro.png
diff --git a/content/posts/deep_dives/messages/message_panel.png b/content/posts/deep_dives/messages/message_panel.png
new file mode 100644
index 0000000..39e5361
Binary files /dev/null and b/content/posts/deep_dives/messages/message_panel.png differ
diff --git a/static/css/custom.css b/static/css/custom.css
index 30690ad..42ccf33 100644
--- a/static/css/custom.css
+++ b/static/css/custom.css
@@ -3,6 +3,10 @@
max-width: 860px;
}
+.content img {
+ display: block;
+ margin: auto;
+}
.content p, .content ol, .content ul {
font-size: 1.3em;
}
diff --git a/static/images/articles/data_object_thumbnail.png b/static/images/articles/data_object_thumbnail.png
new file mode 100644
index 0000000..9374268
Binary files /dev/null and b/static/images/articles/data_object_thumbnail.png differ
diff --git a/static/images/articles/messages/messages_thumbnail.png b/static/images/articles/messages/messages_thumbnail.png
deleted file mode 100644
index 1140ad8..0000000
Binary files a/static/images/articles/messages/messages_thumbnail.png and /dev/null differ
diff --git a/static/images/articles/messages_thumbnail.png b/static/images/articles/messages_thumbnail.png
new file mode 100644
index 0000000..49c6a2c
Binary files /dev/null and b/static/images/articles/messages_thumbnail.png differ