Changes between Initial Version and Version 1 of DeveloperGuidelines/s3workflow

Timestamp:

09/21/13 13:28:06 (12 years ago)

Author:

hardik juneja

Comment:

--

DeveloperGuidelines/s3workflow

@@ +1 @@
+= S3Workflow Tutorial =
+[[TOC]]
+
+This tutorial is on S3Workflow and will briefly explain how workflows works and created in Sahana Eden.
+
+== Starting a workflow ==
+
+Starting a workflow in Sahana Eden is very easy.[[br]]
+To start a workflow just append {{{?wf_id=workflowname}}} where workflowname will be name of the workflow.[[br]]
+Each workflow has a unique name.[[br]]
+When you start a workflow a special uid get appended to the URL this uid is used to identify the current workflow.
+
+Eg -
+
+{{{
+eden/req/req?wf_id=reqmanagement:a123b-asd23
+}}}
+
+
+here ‘a123b-asdc23’ is a special uid that identify current workflow.
+
+'''Note - ''' When we start workflow it enters the workflow hook in s3rest.py and then everything is handed over to S3Workflow class and then the request get processed normally.
+
+
+== Defining Workflow ==
+
+All the workflows are defined in -
+
+{{{
+private/templates/current_temp/workflow.py
+}}}
+
+(where current_temp is the current template.)[[br]]
+
+This file contains all the workflow under a class 
+S3WorkflowConfig. [[br]]
+
+An small workflow example defnation can be-
+
+{{{
+N = S3Workflow
+Exit = S3WorkflowExitNode
+
+def reqmanagement(self):
+    return N(“first node”).handle(next_status = “create request”
+                                  controller = “req”,
+                                  function = “req”,
+                                  args = “create”) & \
+           N(“first node”).handle(next_status = “add items to req 1”
+                                  controller = "req",
+                                  function = "req",
+                                  args = [1,"req_items"],) & \
+           N(“first node”).handle(next_status = “view reqs”
+                                  controller = "req",
+                                  function = "req",
+                                  )
+
+}}}
+
+This will create a basic three steps workflow with name reqmanagement and having three steps as follows -
+
+ * Create request
+ * Add item to a particular req
+ * view requests
+
+Next section will try to explain how to make complex workflows with more configuration options.
+
+== Options to Configure Workflows ==
+
+Each node is defined using a S3WorkflowNode class.[[br]]
+We provide different option to configure each node. [[br]]
+for making things simple let us take [[br]]
+
+{{{ 
+N = S3WorkflowNode
+}}}
+
+=== Defining nodes ===
+
+{{{
+N(“first node”)
+}}}
+
+This defines a node with status “first node”
+
+{{{
+N(“first node”).handle(next_status = “second node”)
+}}}
+
+handle is used to add configuration options to each node.[[br]]
+above code snippet defines a node with status “first node”[[br]]
+and state that one possible next status that can be achived will be “first node”.[[br]]
+
+But Now the question is how to achieve this next status? [[br]]
+
+For that we can define actions in handle.[[br]]
+
+{{{
+N(“first node”).handle(next_status = “create request”,
+     controller = “req”,
+     function = “req”,
+     args = “create”)
+}}}
+
+This code snippet defines a node with status “first node” and whose next status is “second node” [[br]]
+which can be achieved by clicking on eden/req/req/create action.
+
+These actions are defined the same way we define our a url using URL() function.
+
+'''All arguments that handle accepts are -'''
+
+ * Controller - used to define controller.
+ * Function - used to define function.
+ * args - used to define args.
+ * next_status - used to define next status.
+ * http - used to define the http for the action. eg. get / post
+ * action_text - text to display  on the action button (Default next_status)
+
+'''All arguments that S3WorkflowNode class accepts are- '''
+
+ * status - current status of the node.
+ * postp - used to define postp for the node.
+ * prep - used to define prep for the node.
+ * display_text - used to define some information text in the middle of the node.
+
+You can define multiple handle to each node.
+
+=== Connecting Nodes ===
+
+Now let us point above node to a new node. [[br]]
+In the above example while defining first node we defined next_status as “create request”. [[br]]
+Now we will create a node with status “create node” which will create request for us.
+And then we will connect them.
+
+{{{
+N(“first node”).handle(next_status = “create request”,
+     controller = “req”,
+     function = “req”,
+     args = “create”) & \
+N(“create request”).handle(next_status = “add items”,
+     controller = “req”,
+     function = “req”,
+     args = [1, “req_item”])
+}}}
+
+when we will start this workflow, the status will be "first node" [[br]]
+So to achieve “create request” node  from “first node” user will have to click on “req/req/create” [[br]]
+and then to achieve “add items” from “create request” node user will have to click on “req/req/1/req_items” and so on.
+
+(Action button to navigate from one node to another get generated on the page using actions defined in handle.)
+
+
+=== Branching ===
+
+In above example we connected nodes together.[[br]]
+Now let’s see how to create branches or choice nodes.[[br]]
+
+This can be achieved by using multiple handles for each node.
+
+{{{
+
+N(“create req”).handle(next_status = “add item”,
+                       controller = “req”,
+                       function = “req”,
+                        args = [1, “req_item”]) \
+               .handle(next_status = “manage commitment”,
+                       controller = “req”,
+                       function = “req”,
+                       args = [1, “commit”] )
+
+}}}
+
+
+
+The above code snippet say when at “create req” user can click on “req/req/1/req_items” to change the status to “add item” [[br]]
+'''OR''' user can click on “req/req/1/commit” to change the workflow status to “manage commitments” [[br]]
+
+=== Receiving branched Nodes ===
+
+Now lets receive these branched nodes.
+
+To merge the branches and point them to one node do this.
+
+{{{
+N(“create req”).handle(next_status = “add item”,
+                       controller = “req”,
+                       function = “req”,
+                       args = [1, “req_item”]) \
+               .handle(next_status = “manage commitment”,
+                       controller = “req”,
+                       function = “req”,
+                       args = [1, “commit”] ) & \
+( N(“add items”).handle(next_status = “view req ”)  |  
+  N(“manage commitments”).handle(next_status = “view req”) )
+}}}
+
+Here “|” is the “or” operator and “&” is “and operator”
+
+=== Loop node ===
+
+We can make loop nodes which will keep on looping until special actions is pressed.
+
+Eg-
+
+{{{
+N(“add items”).handle(next_status = “add items”,
+                      controller = “req”,
+                      function = “req”,
+                      args = [1,“req_items”]) \
+              .handle(next_node = “view req”,
+                      controller = “req”,
+                      function = “req”)
+
+}}}
+
+=== Adding Prep and Postp to Node ===
+
+Just like we define Prep and  Postp for controller we can define one for each node too.
+
+{{{
+def postp(r, output):
+    …
+    …
+    return output
+}}}
+
+now add this postp to node.
+
+{{{
+N(“create request”,   postp = postp).handle(next_status = “view req”,
+                                            controller = “req”,
+                                            function = “req”)
+}}}
+
+== Customising Workflow header ==
+
+Workflow Header is used to inject special buttons and progress bar during the workflow.
+Developers have full permission to customise these.
+Customising the workflow header can be done by adding wheader in controllers, like we add rheader.
+So there can be different wheader for different nodes
+
+We have Default wheader defined in modules/s3/s3workflow.py
+
+=== Limitations ===
+
+ * When we specify action like org/index they redirect to URL(f = organization) and don’t catch the workflow id. so we have to be careful with this till this issue is not solved
+
+