Permalink
Browse files

Update README, docs, and diagram states

  • Loading branch information...
1 parent 6cb935b commit c777401a4c2cee0171ac6e73542b052679f1e5e1 @ziadsawalha committed Apr 6, 2012
Showing with 149 additions and 87 deletions.
  1. +0 −87 README
  2. +146 −0 README.md
  3. BIN doc/figures/state-diagram.png
  4. +3 −0 doc/figures/state-diagram.svg
View
87 README
@@ -1,87 +0,0 @@
-Spiff Workflow
----------------
-Spiff Workflow is a library implementing a framework for workflows.
-It is based on http://www.workflowpatterns.com and implemented in pure Python.
-
-
-Supported Workflow Patterns
-----------------------------
-Hint: The examples are located in tests/data/spiff/.
-
- Control-Flow Patterns:
-
- 1. Sequence [control-flow/sequence.xml]
- 2. Parallel Split [control-flow/parallel_split.xml]
- 3. Synchronization [control-flow/synchronization.xml]
- 4. Exclusive Choice [control-flow/exclusive_choice.xml]
- 5. Simple Merge [control-flow/simple_merge.xml]
- 6. Multi-Choice [control-flow/multi_choice.xml]
- 7. Structured Synchronizing Merge [control-flow/structured_synchronizing_merge.xml]
- 8. Multi-Merge [control-flow/multi_merge.xml]
- 9. Structured Discriminator [control-flow/structured_discriminator.xml]
- 10. Arbitrary Cycles [control-flow/arbitrary_cycles.xml]
- 11. Implicit Termination [control-flow/implicit_termination.xml]
- 12. Multiple Instances without Synchronization [control-flow/multi_instance_without_synch.xml]
- 13. Multiple Instances with a Priori Design-Time Knowledge [control-flow/multi_instance_with_a_priori_design_time_knowledge.xml]
- 14. Multiple Instances with a Priori Run-Time Knowledge [control-flow/multi_instance_with_a_priori_run_time_knowledge.xml]
- 15. Multiple Instances without a Priori Run-Time Knowledge [control-flow/multi_instance_without_a_priori.xml]
- 16. Deferred Choice [control-flow/deferred_choice.xml]
- 17. Interleaved Parallel Routing [control-flow/interleaved_parallel_routing.xml]
- 18. Milestone [control-flow/milestone.xml]
- 19. Cancel Task [control-flow/cancel_task.xml]
- 20. Cancel Case [control-flow/cancel_case.xml]
-
- 22. Recursion [control-flow/recursion.xml]
- 23. Transient Trigger [control-flow/transient_trigger.xml]
- 24. Persistent Trigger [control-flow/persistent_trigger.xml]
- 25. Cancel Region [control-flow/cancel_region.xml]
- 26. Cancel Multiple Instance Task [control-flow/cancel_multi_instance_task.xml]
- 27. Complete Multiple Instance Task [control-flow/complete_multiple_instance_activity.xml]
- 28. Blocking Discriminator [control-flow/blocking_discriminator.xml]
- 29. Cancelling Discriminator [control-flow/cancelling_discriminator.xml]
- 30. Structured Partial Join [control-flow/structured_partial_join.xml]
- 31. Blocking Partial Join [control-flow/blocking_partial_join.xml]
- 32. Cancelling Partial Join [control-flow/cancelling_partial_join.xml]
- 33. Generalized AND-Join [control-flow/generalized_and_join.xml]
- 34. Static Partial Join for Multiple Instances [control-flow/static_partial_join_for_multi_instance.xml]
- 35. Cancelling Partial Join for Multiple Instances [control-flow/cancelling_partial_join_for_multi_instance.xml]
- 36. Dynamic Partial Join for Multiple Instances [control-flow/dynamic_partial_join_for_multi_instance.xml]
- 37. Acyclic Synchronizing Merge [control-flow/acyclic_synchronizing_merge.xml]
- 38. General Synchronizing Merge [control-flow/general_synchronizing_merge.xml]
- 39. Critical Section [control-flow/critical_section.xml]
- 40. Interleaved Routing [control-flow/interleaved_routing.xml]
- 41. Thread Merge [control-flow/thread_merge.xml]
- 42. Thread Split [control-flow/thread_split.xml]
- 43. Explicit Termination [control-flow/explicit_termination.xml]
-
- Workflow Data Patterns:
-
- 1. Task Data [data/task_data.xml]
- 2. Block Data [data/block_data.xml]
- 9. Task to Task [data/task_to_task.xml]
- 10. Block Task to Sub-Workflow Decomposition [data/block_to_subworkflow.xml]
- 11. Sub-Workflow Decomposition to Block Task [data/subworkflow_to_block.xml]
-
-
-Contact
---------
-Mailing List: http://groups.google.com/group/spiff-devel/
-
-
-Usage
-------
-API documentation is embedded into the Spiff Workflow source code and
-currently not yet available elsewhere. Other developer documentation has not
-yet been written.
-
-If you need more help, please drop by our mailing list. You might actually
-make someone write the missing pieces of documentation.
-
-##############################
-from SpiffWorkflow.specs import *
-from SpiffWorkflow import Workflow
-
-spec = WorkflowSpec()
-wf = Workflow(spec)
-...
-##############################
View
146 README.md
@@ -0,0 +1,146 @@
+Spiff Workflow
+==============
+Spiff Workflow is a library implementing a framework for workflows.
+It is based on http://www.workflowpatterns.com and implemented in pure Python.
+
+
+Supported Workflow Patterns
+----------------------------
+Hint: The examples are located in tests/data/spiff/.
+
+ Control-Flow Patterns:
+
+ 1. Sequence [control-flow/sequence.xml]
+ 2. Parallel Split [control-flow/parallel_split.xml]
+ 3. Synchronization [control-flow/synchronization.xml]
+ 4. Exclusive Choice [control-flow/exclusive_choice.xml]
+ 5. Simple Merge [control-flow/simple_merge.xml]
+ 6. Multi-Choice [control-flow/multi_choice.xml]
+ 7. Structured Synchronizing Merge [control-flow/structured_synchronizing_merge.xml]
+ 8. Multi-Merge [control-flow/multi_merge.xml]
+ 9. Structured Discriminator [control-flow/structured_discriminator.xml]
+ 10. Arbitrary Cycles [control-flow/arbitrary_cycles.xml]
+ 11. Implicit Termination [control-flow/implicit_termination.xml]
+ 12. Multiple Instances without Synchronization [control-flow/multi_instance_without_synch.xml]
+ 13. Multiple Instances with a Priori Design-Time Knowledge [control-flow/multi_instance_with_a_priori_design_time_knowledge.xml]
+ 14. Multiple Instances with a Priori Run-Time Knowledge [control-flow/multi_instance_with_a_priori_run_time_knowledge.xml]
+ 15. Multiple Instances without a Priori Run-Time Knowledge [control-flow/multi_instance_without_a_priori.xml]
+ 16. Deferred Choice [control-flow/deferred_choice.xml]
+ 17. Interleaved Parallel Routing [control-flow/interleaved_parallel_routing.xml]
+ 18. Milestone [control-flow/milestone.xml]
+ 19. Cancel Task [control-flow/cancel_task.xml]
+ 20. Cancel Case [control-flow/cancel_case.xml]
+
+ 22. Recursion [control-flow/recursion.xml]
+ 23. Transient Trigger [control-flow/transient_trigger.xml]
+ 24. Persistent Trigger [control-flow/persistent_trigger.xml]
+ 25. Cancel Region [control-flow/cancel_region.xml]
+ 26. Cancel Multiple Instance Task [control-flow/cancel_multi_instance_task.xml]
+ 27. Complete Multiple Instance Task [control-flow/complete_multiple_instance_activity.xml]
+ 28. Blocking Discriminator [control-flow/blocking_discriminator.xml]
+ 29. Cancelling Discriminator [control-flow/cancelling_discriminator.xml]
+ 30. Structured Partial Join [control-flow/structured_partial_join.xml]
+ 31. Blocking Partial Join [control-flow/blocking_partial_join.xml]
+ 32. Cancelling Partial Join [control-flow/cancelling_partial_join.xml]
+ 33. Generalized AND-Join [control-flow/generalized_and_join.xml]
+ 34. Static Partial Join for Multiple Instances [control-flow/static_partial_join_for_multi_instance.xml]
+ 35. Cancelling Partial Join for Multiple Instances [control-flow/cancelling_partial_join_for_multi_instance.xml]
+ 36. Dynamic Partial Join for Multiple Instances [control-flow/dynamic_partial_join_for_multi_instance.xml]
+ 37. Acyclic Synchronizing Merge [control-flow/acyclic_synchronizing_merge.xml]
+ 38. General Synchronizing Merge [control-flow/general_synchronizing_merge.xml]
+ 39. Critical Section [control-flow/critical_section.xml]
+ 40. Interleaved Routing [control-flow/interleaved_routing.xml]
+ 41. Thread Merge [control-flow/thread_merge.xml]
+ 42. Thread Split [control-flow/thread_split.xml]
+ 43. Explicit Termination [control-flow/explicit_termination.xml]
+
+ Workflow Data Patterns:
+
+ 1. Task Data [data/task_data.xml]
+ 2. Block Data [data/block_data.xml]
+ 9. Task to Task [data/task_to_task.xml]
+ 10. Block Task to Sub-Workflow Decomposition [data/block_to_subworkflow.xml]
+ 11. Sub-Workflow Decomposition to Block Task [data/subworkflow_to_block.xml]
+
+
+Contact
+--------
+Mailing List: http://groups.google.com/group/spiff-devel/
+
+
+Usage
+------
+API documentation is embedded into the Spiff Workflow source code and
+currently not yet available elsewhere. Other developer documentation has not
+yet been written.
+
+If you need more help, please drop by our mailing list. You might actually
+make someone write the missing pieces of documentation.
+
+```
+from SpiffWorkflow.specs import *
+from SpiffWorkflow import Workflow
+
+spec = WorkflowSpec()
+wf = Workflow(spec)
+...
+```
+
+
+How it works
+------------
+
+### Functionality
+
+One critical concept to know about SpiffWorkflow that helps with understanding
+the code is the difference between a `TaskSpec `and `Task` and the difference between a `WorkflowSpec` and `Workflow`.
+
+A WorkflowSpec and TaskSpec are used to define your workflow. All types of
+tasks (Join, Split, Execute, Wait, etcÉ) are derived from TaskSpec. The Specs can be
+deserialized from known formats like OpenWFE. You build your WorkflowSpec by chaining TaskSpecs together in a tree.
+
+When you want to actually run the process, you create a Workflow instance from the WorkflowSpec (pass the spec to the Workflow initializer).
+
+How this works from there is based on the principles of computer programming (remember, this
+project comes from the academic world). A `derivation tree` is created based off of the spec using a hierarchy of Task objects (not TaskSpecs - but each Task points to the TaskSpec that generated it). Think of a derivation tree as tree of execution paths (some, but not all, of which will end up executing). Each Task object is basically a node in the derivation tree. Each task in the tree links back to its parent (there are no connection objects). The processing is done by walking down the derivation tree one Task at a time and moving the task (and it's children) through the sequence of states towards completion. The states are documented in [Task.py](https://github.com/knipknap/SpiffWorkflow/blob/master/SpiffWorkflow/Task.py|the code).
+
+
+The Workflow and Task classes are in the root of the project. All the specs (TaskSpec, WorkflowSpec, and all derived classes) are in the specs subdirectory.
+
+You can serialize/deserialize specs and open standards like OpenWFE are supported (and others can be coded in easily). You can also serialize/deserialize a running workflow (it will pull in its spec as well).
+
+Another important distinction is between properties and attributes. Properties belong to TaskSpecs. They are static at run-time and belong to the design of the workflow. Attributes are dynamic and assigned to Tasks (nodes in the execution path).
+
+There's a decent eventing model that allows you to tie in to and receive events (for each task, you can get event notifications from its TaskSpec). The events correspond with how the processing is going in the derivation tree, not necessarily how the workflow as a whole is moving. See [TaskSpec.py](https://github.com/knipknap/SpiffWorkflow/blob/master/SpiffWorkflow/specs/TaskSpec.py) for docs on events.
+
+
+### Understanding FUTURE, WAITING, READY, and COMPLETE states
+
+ * FUTURE means the processor has predicted that this this path will be taken and this task will definitely run.
+ * If a task is waiting on predecessors to run then it is in FUTURE state (not WAITING).
+ * READY means "preconditions are met for marking this task as complete".
+ * You can try to complete a task at any point. If it is in FUTURE state and does not complete, it can fall back to READY state.
+
+
+*Waiting* can be confusing:
+
+ * WAITING means "I am in the process of doing my work and have not finished. When the work is finished, then I will be READY for completion and will go to READY state."
+ * WAITING always comes after FUTURE and before READY.
+ * WAITING is an optional state.
+
+
+'REACHED' may also be confusing unless you remember that it means that the processor has now _reached_ this task in the execution path:
+
+ * REACHED means processing has reached this task in the derivation tree. This is not a state, but an event.
+ * A task is always reached before it becomes READY.
+
+You can nest workflows (using the SubWorkflowSpec).
+
+The serialization code is done well which makes it easy to add new formats if we need to support them.
+
+To understand better how a TaskSpec pattern works, look at [the workflow patterns](http://www.workflowpatterns.com) web site; especially the flash animations showing how each type of task works.
+
+The tasks labelled "ThreadXXXX" create logical threads based on the model in http://www.workflowpatterns.com. There is no python threading implemented. However, there is some locking and mutex code in place.
+
+### State Transitions
+![state-diagram.png](https://github.com/ziadsawalha/SpiffWorkflow/raw/docs/doc/figures/state-diagram.png)
View
BIN doc/figures/state-diagram.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
3 doc/figures/state-diagram.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="4 110 611 579" width="611pt" height="579pt"><metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:date>2012-04-06 20:40Z</dc:date><!-- Produced by OmniGraffle Professional 5.3.6 --></metadata><defs><font-face font-family="Chalkboard" font-size="36" panose-1="3 5 6 2 4 2 2 2 2 5" units-per-em="1000" underline-position="-146.96132" underline-thickness="22.099447" slope="0" x-height="501.65744" cap-height="689.50275" ascent="980.11774" descent="-282.86743" font-weight="500"><font-face-src><font-face-name name="Chalkboard"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="StickArrow_Marker" viewBox="-1 -3 6 6" markerWidth="6" markerHeight="6" color="#e9e5e2"><g><path d="M 3.8400002 0 L 0 0 M 0 -1.4400001 L 3.8400002 0 L 0 1.4400001" fill="none" stroke="currentColor" stroke-width="1"/></g></marker><font-face font-family="Chalkboard" font-size="18" panose-1="3 5 6 2 4 2 2 2 2 5" units-per-em="1000" underline-position="-146.96132" underline-thickness="22.099447" slope="0" x-height="501.65744" cap-height="689.50275" ascent="980.11774" descent="-282.86743" font-weight="500"><font-face-src><font-face-name name="Chalkboard"/></font-face-src></font-face></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1</title><rect fill="white" width="757.2514" height="752"/><g><title>Layer 1</title><text transform="translate(146.004 300.508)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="36" font-weight="500" fill="#e9e5e2" x="4.9995804" y="35" textLength="128.008835">FUTURE</tspan></text><text transform="translate(60.320526 120.036835)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="36" font-weight="500" fill="#e9e5e2" x="9.591751" y="35" textLength="114.36464">MAYBE</tspan></text><text transform="translate(211.48181 195.30894)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="36" font-weight="500" fill="#e9e5e2" x="16.939796" y="35" textLength="115.12044">LIKELY</tspan></text><line x1="138.54269" y1="166.03683" x2="194.16516" y2="280.21545" marker-end="url(#StickArrow_Marker)" stroke="#e9e5e2" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><text transform="translate(246.30612 451.52713)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="36" font-weight="500" fill="#e9e5e2" x="14.287975" y="35" textLength="109.432045">READY</tspan></text><text transform="translate(36.815826 383.59827)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="36" font-weight="500" fill="#e9e5e2" x="3.3908844" y="35" textLength="158.71823">WAITING</tspan></text><line x1="230.62349" y1="346.508" x2="287.86615" y2="432.65338" marker-end="url(#StickArrow_Marker)" stroke="#e9e5e2" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><line x1="188.08636" y1="346.508" x2="162.90839" y2="368.48596" marker-end="url(#StickArrow_Marker)" stroke="#e9e5e2" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><line x1="270.12863" y1="241.30893" x2="242.86877" y2="281.71762" marker-end="url(#StickArrow_Marker)" stroke="#e9e5e2" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><line x1="187.44226" y1="429.59827" x2="227.61331" y2="443.5062" marker-end="url(#StickArrow_Marker)" stroke="#e9e5e2" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><line x1="176.67624" y1="166.03683" x2="216.93423" y2="185.11775" marker-end="url(#StickArrow_Marker)" stroke="#e9e5e2" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><text transform="translate(129.70116 545.52588)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="36" font-weight="500" fill="#e9e5e2" x="25.169678" y="35" textLength="176.41989">COMPLETE</tspan></text><line x1="297.3074" y1="497.5271" x2="274.35342" y2="527.49023" marker-end="url(#StickArrow_Marker)" stroke="#e9e5e2" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><text transform="translate(160.2821 135.57367)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="26.597275" y="18" textLength="80.35359">Might run</tspan></text><text transform="translate(317.12842 213.61789)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="26.597275" y="18" textLength="87.23536">Might run </tspan><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="9.432636" y="41" textLength="114.68287">(default path)</tspan></text><text transform="translate(272.82446 315.05676)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="9.0149574" y="18" textLength="69.07624">Will defi</tspan><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="78.0912" y="18" textLength="53.323757">nitely </tspan><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="53.487885" y="41" textLength="26.572376">run</tspan></text><text transform="translate(18.583511 429.59827)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="35.62711" y="18" textLength="62.293922">Running</tspan><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="26.22932" y="41" textLength="81.0895">(not done)</tspan></text><text transform="translate(329.52124 466.63504)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="45.034843" y="18" textLength="43.478455">Done!</tspan></text><text transform="translate(133.71811 586.9975)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="81.631073" y="18" textLength="38.88398">Done</tspan><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="12.972511" y="41" textLength="183.08287">(and acknowledged as </tspan><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="6.4288635" y="64" textLength="189.28839">done - we've moved on)</tspan></text><text transform="translate(373.97256 587.9975)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="36" font-weight="500" fill="#e9e5e2" x="19.023827" y="35" textLength="188.71159">CANCELLED</tspan></text><text transform="translate(386.27911 633.9975)" fill="#e9e5e2"><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="14.255379" y="18" textLength="180.51712">Can be cancelled any </tspan><tspan font-family="Chalkboard" font-size="18" font-weight="500" fill="#e9e5e2" x="83.34157" y="41" textLength="35.462982">time</tspan></text></g></g></svg>

0 comments on commit c777401

Please sign in to comment.