Wizard4j Home

Flowcharts

Introduction

This page provides information on the origin of wizard4j flowcharts, the relation between diagrams, trees and xml. This is background information, but it helps to understand why things are done like they are done. It also includes a simple and instructive example.

During the 'research phase' of this project we were looking for formal definitions of flowcharts and existing flowchart languages, but as far as we could figure out there was no single flowchart definition or language. A 'flowchart' stands for a collection of "charts that represents an algorithm or process, showing the steps as boxes of various kinds, and their order by connecting these with arrows". Soon it became clear that none of the existing flowchart dialects was a perfect match: either they had unneeded features (e.g. tapedrive symbol) or they did not meet the wizard4j requirements:

most flowchart dialects contain binary choices, while wizard4j required more flexible choices:

more than 2 choices
select more than 1 possibility

various loop types
need for fragments (cfr. subroutine)
2-step approach: 1) collecting inputs & decisions and 2) generating output (most flowchart dialects generate their output while traversing the flowchart)
...

So we decided to create our own wizard4j flowchart dialect, which consists of a flowchart diagram presentation and a formal flowchart xml language.

Wizard4j Flowchart Diagram

The next table gives an overview of the symbols used in wizard4j flowchart diagrams

Name	Symbol	Description
root		This symbol is used to indicate the start of the flowchart.
end		This symbol indicates the end of the flowchart (or a fragment).
info		This symbol allows to present an 'informational' screen to the user. The user is not asked for any input.
input		This symbol will prompt the user for input.
switch		This symbol will also prompt the user for input, but the difference with the input element is that the provided input will determine the branch that will be followed in the flowchart. This element is also more flexible than the binary decisions in traditional flowcharts. It is possible to select one out of multiple branches or even to select a subset of branches. In the latter case the branches will be executed from left to right.
branch		This symbol is introduced to explicitly define a branch of a switch element. In traditional flowcharts the various choices are typically indicated along the exit points of the switch symbol. We prefer to use an explicit branch symbol to indicate these switch values: it allows a more intuitive mapping to the xml description and it also facilitates code generation.
loop		This symbol allows to execute a 'flowchart section' multiple times. The number of iterations can be fixed or the user can be queried to specify the (number of) iterations.
merge		The merge symbol is used to indicate the end of a loop or a switch. The merge symbol can be omitted when the switch allows only one branch to be selected and the various branches do not want to share common flowchart code after the branch-specific flowchart code, in this case each branch will be terminated by the end element.
fragment		This symbol is introduced to avoid duplicate code in several parts of the flowchart. The code that occurs several times in a flowchart can be extracted into a fragment (can be considered as some type of function or subroutine). Note the difference with the root symbol: the root symbol contains the '/' (root) sign, while the fragment will have a name.
fragmentPointer		This symbol points to a fragment.

If one looks for flowchart examples on the Web, the one that is encountered most often is the picture at the left side. On the right side the corresponding wizard4j flowchart is shown. Note that they differ slightly: in the wizard4j version you are only declared 'a poor bastard' after you have confirmed that 'you can not blame someone else'. This was done because it is more logical, but also - and more important - to illustrate the use of fragments.

For the impatient: what does it mean to run a flowchart.

When you were impatient and ran the flowchart you noticed that at the end you were presented a link named 'apply template' (beside some built-in result presentations), by clicking this one you were given one of the two final states of the above flowchart: 'No problem' or 'You poor bastard'. This output was generated by applying the result of the flowchart to this simple velocity template:

#if(${root.doesItWork.no.didYouMess.yes.doesAnyoneKnow.yes.canYouBlame.no} || ${root.doesItWork.no.didYouMess.no.willYouGetScrewed.yes.canYouBlame.no})
You poor Bastard
#else
No problem
#end

This is a simple illustration of the separation of flowchart execution and output generation in wizard4j.

Converting the Diagram into a Tree and into XML

The input for wizard4j is not a flowchart diagram, but an xml description of the flowchart. The above diagram does NOT have a tree structure, so the first step of moving from the diagram to xml is moving from the diagram to a tree, which we do by applying following algorithm:

1. root/fragment diagramNode is the 'root' of the tree (mapped on root/fragment treeNode)
2. the next diagramNode is the first child of the root of the tree
3.1. for info, input and fragmentPointer diagramNode: its child diagramNode will become a sibling treeNode
3.2. for switch, loop and branch diagramNode: its child diagramNode(s) will become its child treeNode(s)
3.3. for merge diagramNode: its child diagramNode becomes a sibling of the first ancestor treeNode of type LOOP or SWITCH (only once)
4. for each child diagramNode, go to 3.
5. remove all treeNodes of type merge

If this tree is visited in a preorder tree traversal the tree elements are visited in the same sequence as walking through the flowchart diagram (if one skips the non-selected branches). Applied to the above example we obtain:

Keeping the same tree structure, this tree can then be mapped onto an xml document. On this page we showed a simple example, to discover the full flowchart xml language, you should read the Xml Language section.