Merge branch 'enhancement/improve-subprocess-handling' of github.com:…

…sartography/SpiffWorkflow into enhancement/improve-subprocess-handling

SpiffWorkflow/bpmn/serializer/version_migration.py

@@ -2,7 +2,7 @@
 
 def version_1_0_to_1_1(old):
     """
-    Upgrade v1.0 serializations to v1.0.
+    Upgrade v1.0 serializations to v1.1.
 
     Starting with Spiff 1.1.8, subworkflows are no longer integrated in main task tree.  When
     a subworkflow (a subprocess, transaction, or call activity) is reached, a subprocss is

SpiffWorkflow/exceptions.py

@@ -93,7 +93,6 @@ def get_task_trace(task):
             caller = workflow.name
             workflow = workflow.outer_workflow
             task_trace.append(f"{workflow.spec.task_specs[caller].description} ({workflow.spec.file})")
-            pass
         return task_trace
 
 

doc/bpmn/advanced.rst

@@ -232,7 +232,7 @@ Serialization
 
 .. warning::
 
-   Serialization Changed in Version 1.2
+   Serialization Changed in Version 1.1.7
    The old serialization method still works but it is deprecated.
    To migrate your system to the new version, see "Migrating between
    serialization versions" below.
@@ -340,30 +340,44 @@ latter should recreate your data from the serialization.
 
 Migrating Between Serialization Versions
 ----------------------------------------
-Because the serializer is highly customizable, you will need to manage your
-own versions of the serialization.  You can do this by passing a version number
-into the serializer, which will be embedded in the json of all workflows.
+
+Old (Non-Versioned) Serializer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prior to Spiff 1.1.7, the serialized output did not contain a version number.
 
 .. code:: python
 
     old_serializer = BpmnSerializer() # the deprecated serializer.
     # new serializer, which can be customized as described above.
     serializer = BpmnWorkflowSerializer(version="MY_APP_V_1.0")
 
-The new serializer has a "get_version" method that will read the version
+The new serializer has a :code:`get_version` method that will read the version
 back out of the serialized json.  If the version isn't found, it will return
-None, and you can then assume it is using the old style serializer.
+:code:`None`, and you can then assume it is using the old style serializer.
 
 .. code:: python
 
    version = serializer.get_version(some_json)
-   if(version == "MY_APP_V_1.0"):
+   if version == "MY_APP_V_1.0":
         workflow = serializer.deserialize_json(some_json)
    else:
         workflow = old_serializer.deserialize_workflow(some_json, workflow_spec=spec)
 
-This should help you migrate your old workflows to the new serialization
-method.  It should also allow you to modify the serialization and customize
-it over time, and still manage the different forms as you make adjustments
-without leaving people behind.
 
+Because the serializer is highly customizable, we've made it possible for you to manage your own versions of the
+serialization.  You can do this by passing a version number into the serializer, which will be embedded in the 
+json of all workflows.  This allow you to modify the serialization and customize it over time, and still manage
+the different forms as you make adjustments without leaving people behind.
+
+Versioned Serializer
+^^^^^^^^^^^^^^^^^^^^
+
+As we make changes to Spiff, we may change the serialization format.  For example, in 1.1.8, we changed
+how subprocesses were handled interally in BPMN workflows and updated how they are serialized.   If you have
+not overridden our version number with one of your own, the serializer will transform the 1.0 format to the 
+new 1.1 format.
+
+If you've overridden the serializer version, you may need to incorporate our serialization changes with
+your own.  You can find our conversions in 
+`version_migrations.py <https://github.com/sartography/SpiffWorkflow/blob/enhancement/improve-subprocess-handling/SpiffWorkflow/bpmn/serializer/version_migration.py>`_

doc/bpmn/synthesis.rst

@@ -47,18 +47,28 @@ BPMN parsers in SpiffWorkflow.
         parser.add_bpmn_files(bpmn_files)
         if dmn_files:
             parser.add_dmn_files(dmn_files)
-        return BpmnWorkflow(parser.get_spec(process), script_engine=CustomScriptEngine)
+        top_level = parser.get_spec(process)
+        subprocesses = parser.get_process_specs()
+        return BpmnWorkflow(top_level, subprocesses, script_engine=CustomScriptEngine)
 
 We create an instance of our previously defined parser, add the BPMN files to it, and
 optionally add any DMN files, if they were supplied.
 
 We'll obtain the workflow specification from the parser for the top level process
-using :code:`parser.get_spec()` and return a :code:`BpmnWorkflow` based on the spec.
+using :code:`parser.get_spec()`.
+
+We'll get the specs of all the processes that were parsed with :code:`parser.get_process_specs()`
+and provide these to the workflow as well.  If your entire workflow is contained in your
+top-level process, you can omit this argument, but if your workflow contains call activities,
+you'll need to include it.
 
 We also provide an enhanced script engine to our workflow.  More information about how and
 why you might want to do this is covered in :doc:`advanced`.  The :code:`script_engine`
 argument is optional and the default will be used if none is supplied.
 
+We return a :code:`BpmnWorkflow` based on the specs that uses the our custom script engine
+to execute script tasks and evaluate expressions.
+
 Running a Workflow
 ------------------