Introduction

Using helper scripts it is possible to generate helpful documentation for the workflows in Bungeni. As a pre-requisite you need to have a working bungeni buildout - also you need to have graphviz :

sudo apt-get install graphviz

and a java runtime engine installed :

sudo apt-get install sun-java-jre

Generating the Documentation

To generate the documentation, from the buildout folder run :

./bin/diagrammer

This will generate the document in the ./docs folder within the buildout.

Internal Details

Tabular Documentation

The tabular documentation is generated using an XSLT template (located in ./templates/docgen) which is applied to the workflow XML configuration files located in src/bungeni.main/bungeni/core/workflows.

The XSLT transformer used for this is saxon9 (located in ./templates/docgen/saxon9.jar)

Graphs

The graphs are generated from .dot files created using graphviz. To generate updated dot files (the buildout does it,but if you have to run it manually do the following :

$ cd <buildout-folder>/src/bungeni.main/bungeni/core/workflows/docs
$ <bungeni-python> ../dia.py

The output of the autogenerated dot file is hard to interpret if you do not know which actors are involved. the original generated dot file:

digraph g {
ratio=auto
None [shape=doublecircle]
t1 [shape=none, label="Create"]
"None" -> t1 -> "draft"
t2 [shape=none, label="Make private"]
"draft" -> t2 -> "private"
t3 [shape=none, label="Submit to Clerk"]
"draft" -> t3 -> "submitted"
t4 [shape=none, label="Withdraw"]
"submitted" -> t4 -> "withdrawn"
t5 [shape=none, label="Receive"]
"submitted" -> t5 -> "received"
t6 [shape=none, label="Needs Clarification by MP"]
"received" -> t6 -> "requires_amend"
t7 [shape=none, label="Withdraw"]
"received" -> t7 -> "withdrawn"
t8 [shape=none, label="Reject"]
"received" -> t8 -> "inadmissible"
t9 [shape=none, label="Complete"]
"received" -> t9 -> "complete"
t10 [shape=none, label="Withdraw"]
"complete" -> t10 -> "withdrawn"
t11 [shape=none, label="Approve"]
"complete" -> t11 -> "admissible"
t12 [shape=none, label="Needs Clarification by MP"]
"complete" -> t12 -> "requires_amend"
t13 [shape=none, label="Reject"]
"complete" -> t13 -> "inadmissible"
t14 [shape=none, label="Defer"]
"admissible" -> t14 -> "deferred"
t15 [shape=none, label="Withdraw"]
"admissible" -> t15 -> "withdrawn"
t16 [shape=none, label="Send to ministry"]
"admissible" -> t16 -> "pending response"
t17 [shape=none, label="Schedule"]
"admissible" -> t17 -> "scheduled"
t18 [shape=none, label="Postpone"]
"scheduled" -> t18 -> "postponed"
t19 [shape=none, label="Withdraw"]
"scheduled" -> t19 -> "withdrawn"
t20 [shape=none, label="Respond"]
"scheduled" -> t20 -> "responded"
t21 [shape=none, label="Answer"]
"responded" -> t21 -> "answered"
t22 [shape=none, label="Schedule"]
"postponed" -> t22 -> "scheduled"
t23 [shape=none, label="Withdraw"]
"postponed" -> t23 -> "withdrawn"
t24 [shape=none, label="Respond"]
"pending response" -> t24 -> "responded"
t25 [shape=none, label="Schedule"]
"deferred" -> t25 -> "scheduled"
t26 [shape=none, label="Send to ministry"]
"deferred" -> t26 -> "pending response"
t27 [shape=none, label="Withdraw"]
"deferred" -> t27 -> "withdrawn"
t28 [shape=none, label="Resubmit to clerk"]
"requires_amend" -> t28 -> "submitted"
t29 [shape=none, label="Withdraw"]
"requires_amend" -> t29 -> "withdrawn"
t30 [shape=none, label="Re draft"]
"private" -> t30 -> "draft"
}

renders into the graphic:

For the question workflow you can cluster the states by the actor who can view/edit the states

subgraph "cluster_mp" { label="Member of parliament"; draft; private; requires_amend; }
subgraph "cluster_co" { label="Clerks office"; submitted; received; responded }
subgraph "cluster_so" { label="Speakers office"; complete; admissible; deferred; postponed; scheduled;}
subgraph "cluster_ministry" { label="Ministry"; "pending response"; }
subgraph "cluster_end" { label="End States"; answered; withdrawn; inadmissible; }

additionally you may move the transitions that occur in one office into those clusters and to 'declutter' the output divide the clerks office into two clusters. The rank indicates our start and end of the workflow.

{ rank=source; None }
subgraph "cluster_mp" { label="Member of parliament"; draft; private; requires_amend; t2; t30 }
subgraph "cluster_co" { label="Clerks office"; submitted; received;  t5; }
subgraph "cluster_so" { label="Speakers office"; complete; admissible; deferred; postponed; scheduled; t11; t14; t17; t18; t25; t22; }
subgraph "cluster_ministry" { label="Ministry"; "pending response"; }
subgraph "cluster_co2" { label="Clerks office"; responded; }
subgraph "cluster_end" { label="End States"; answered; withdrawn; inadmissible; rank=sink }

A little adjustment to the cluster_co label and we come up with the file:

digraph g {
ratio=auto
None [shape=doublecircle]
t1 [shape=none, label="Create"]
"None" -> t1 -> "draft"
t2 [shape=none, label="Make private"]
"draft" -> t2 -> "private"
t3 [shape=none, label="Submit to Clerk"]
"draft" -> t3 -> "submitted"
t4 [shape=none, label="Withdraw"]
"submitted" -> t4 -> "withdrawn"
t5 [shape=none, label="Receive"]
"submitted" -> t5 -> "received"
t6 [shape=none, label="Needs Clarification by MP"]
"received" -> t6 -> "requires_amend"
t7 [shape=none, label="Withdraw"]
"received" -> t7 -> "withdrawn"
t8 [shape=none, label="Reject"]
"received" -> t8 -> "inadmissible"
t9 [shape=none, label="Complete"]
"received" -> t9 -> "complete"
t10 [shape=none, label="Withdraw"]
"complete" -> t10 -> "withdrawn"
t11 [shape=none, label="Approve"]
"complete" -> t11 -> "admissible"
t12 [shape=none, label="Needs Clarification by MP"]
"complete" -> t12 -> "requires_amend"
t13 [shape=none, label="Reject"]
"complete" -> t13 -> "inadmissible"
t14 [shape=none, label="Defer"]
"admissible" -> t14 -> "deferred"
t15 [shape=none, label="Withdraw"]
"admissible" -> t15 -> "withdrawn"
t16 [shape=none, label="Send to ministry"]
"admissible" -> t16 -> "pending response"
t17 [shape=none, label="Schedule"]
"admissible" -> t17 -> "scheduled"
t18 [shape=none, label="Postpone"]
"scheduled" -> t18 -> "postponed"
t19 [shape=none, label="Withdraw"]
"scheduled" -> t19 -> "withdrawn"
t20 [shape=none, label="Respond"]
"scheduled" -> t20 -> "responded"
t21 [shape=none, label="Answer"]
"responded" -> t21 -> "answered"
t22 [shape=none, label="Schedule"]
"postponed" -> t22 -> "scheduled"
t23 [shape=none, label="Withdraw"]
"postponed" -> t23 -> "withdrawn"
t24 [shape=none, label="Respond"]
"pending response" -> t24 -> "responded"
t25 [shape=none, label="Schedule"]
"deferred" -> t25 -> "scheduled"
t26 [shape=none, label="Send to ministry"]
"deferred" -> t26 -> "pending response"
t27 [shape=none, label="Withdraw"]
"deferred" -> t27 -> "withdrawn"
t28 [shape=none, label="Resubmit to clerk"]
"requires_amend" -> t28 -> "submitted"
t29 [shape=none, label="Withdraw"]
"requires_amend" -> t29 -> "withdrawn"
t30 [shape=none, label="Re draft"]
"private" -> t30 -> "draft"
{ rank=source; None }
subgraph "cluster_mp" { label="Member of parliament"; draft; private; requires_amend; t2; t30 }
subgraph "cluster_co" { label="Clerks office"; submitted; received;  t5; }
subgraph "cluster_so" { label="Speakers office"; complete; admissible; deferred; postponed; scheduled; t11; t14; t17; t18; t25; t22; }
subgraph "cluster_ministry" { label="Ministry"; "pending response"; }
subgraph "cluster_co2" { label="Clerks office - final review"; responded; }
subgraph "cluster_end" { label="End States"; answered; withdrawn; inadmissible; rank=sink }
}

which renders into this graphic:

To render the dot file into a graphic use the command:

 dot -Tpng -O question.dot

to render a png, or:

 dot -Tsvg -O question.dot

to render a SVG

When you render the dot file into a SVG file you may experience that the output gets cropped and that the whole diagramm is not visible. if that is the case simply open the svg with a text editor and adjust the dimensions e.g. from:

<svg width="17.35in" height="12.90in"
 xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">

to:

<svg width="20in" height="15in"
 xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">