Short update about current development status

Recently I have made some important changes to the NGinn engine and feel that it's getting close to what I'd like to achieve. Here's the list of most important changes made:

1. ProcessInstance class makeover. Most important change is that tokens no longer have an identity. At the beginning it was assumed that each token is an independent object and tracking the relation between tasks and tokens has been quite complicated. However, all tokens are the same, they don't convey information - so it was sensible to get rid of their identity. Now only numbers count - all we need to know about tokens is how many of them sit in each place. Results: 50% of code thrown away while retaining the same functionality. Performance and clarity improved.
2. Custom process state serialization. I have decided to use custom XML serialization instead of binary serialization used previously. Main reason is that binary serialization doesn't support versioning and upgrading the library breaks old version of processes. It adds some work to task implementation, but we have complete control of persistence.
3. Introduced distributed transactions (each step of process is run in a separate transaction).
   
4. Basic infractructure is working. Now I need to concentrate on details and providing complete functionality. Especially, task implementation is quite behind.
   
5. Number of examples was added to NGinn.XmlFormsWWW project. It demonstrates how to start and cancel process instances and how to handle worklist functionality (manual tasks). Simple TODO List web application is working (sort of).
   

Summing up, NGinn API is maturing and there are no heavy public interface modifications. It's time to start documenting it. I hope to use the engine in some commercial project, so this should speed things up and improve the quality. Sounds nice.

Tasks in NGinn

Tasks are what the workflow is 'really' made of - they provide the functionality. The rest of workflow definition - places and arrows - just defines how the tasks are interconnected and what are run-time dependencies between them.
So let's try to describe what are the most common types of tasks and what can they do. NGinn is not complete yet, so this will rather be a wish list than a typical technical documentation.

1. Manual task
   
   Manual tasks are tasks that are assigned to people (application users). Usually application will provide some kind of 'TODO' list where each user can see tasks currently assigned to him and from where he/she can pick up next task to be done. NGinn provides 'Manual task' building block, but it does not contain actual TODO list or GUI implementation - this is application specific and NGinn does not restrict the implementation.
   Manual tasks have the following configurable parameters:
   
   • Assignee - id of person responsible for the task
   • Assignee group - id of group responsible for the task (either Assignee or Assignee group must be specified)
   • Task title (short summary)
   • Description (textual description of the task)
   Much more can be said about manual tasks, for example we haven't touched at all the subject of resource management (people database) and organizational structure (groups). I'm going to give you more details on this in next posts.
   
   
2. Timer task
   
   Timer tasks are used to introduce configurable delays into the process. In runtime, timer task 'starts' when it is enabled (that is, when it gets all required input tokens) and then waits specified amount of time before completing. Task has two parameters:
   
   • Delay amount (for example: 00:00:30, meaning 30 seconds) or
   • Due date (fixed moment in time when the task will complete). Exactly one of these parameters needs to be specified, depending on situation.
     
     
   
   
3. Subprocess task
   
   As the name suggests, it's a task for starting a sub-process. When this task is enabled it initiates an instance of sub-process and waits until the sub-process completes. Then the task will also complete.
   To start a sub-process we need to know it's name (definition ID) and we need to have input data in correct structure (as defined by process input variables). In this case subprocess task's input data becomes the input data for the newly created process, and when the sub-process completes it's output data becomes Subprocess task's output data. Therefore we need to make sure the subprocess task has the same input/output data structure as the sub-process.
   
   
4. Notification task
   
   Notification task is used for sending email / sms / other notifications to users.
   
   
5. 'Receive Message' task
   
   The 'receive message' task waits for a message. It is used in scenarios where communication with external systems is necessary and when our process needs to wait for some information sent by external party. Each external message that can be received contains some data and must contain a special ID, called Message Correlation ID (MCID). The MCID is a runtime parameter of the Receive Message task, that is we need to specify what is the MCID for each Receive Message task. We are free to choose any MCID, but it must uniquely identify the task waiting for the message. By default (when not specified), MCID is assumed to have the following structure: [process instance id].[task id], for example e3bc903829badca321.wait_task.
   The structure of message is defined by Receive Message task's output variables - the message should simply contain values of these variables. When message is received its contents are retrieved and put in Receive Message task's output variables. Then the task completes.
   The most important fact here is that the MCID must be known to the external party when it sends us the message. So either the MCID is mutually agreed on, or our process needs to send the MCID to the external system before it can receive the message from it.
   
   
   
6. Script task
   
   Script tasks are used for adding custom logic to the process. Currently they can be programmed in 'Script.NET' language. Script tasks are synchronous, they cannot be 'put to sleep' and reactivated by NGinn execution engine. Script code can access and modify task's variables, but it can also communicate with other objects in application's runtime. They can be used for communication between business processes and the rest of the application.
   
   
7. Empty task
   
   Empty task does nothing - completes just after being started. But all variable bindings do their work and they can be used for synchronization without side effects - and this is the main purpose of empty tasks.
   
   
8. REST/WS call task
   
   Synchronous communication with external systems, using XML/HTTP or SOAP. The task sends a HTTP request containing it's input data and expects to receive XML with the output data (XML structure is defined by task's output data structure). Currently there's no implementation of web service calls - I'm waiting for the right idea.
   
   
9. Custom tasks
   
   Custom tasks can be used to introduce some custom or application-specific components into NGinn process description language. Custom tasks can be implemented in any CLR language, they just have to implement few interfaces and conform to some rules. This is a good topic for separate post.
   

And this is it, I consider the list to be complete and broad enough at the same time. Almost all real-time task examples can be implemented using one (or more) of NGinn tasks, and what can't be implemented or is difficult to stuff into built-in task type can be done as a custom task.

Great resource on workflow patterns

Here's a link to 'Workflow Patterns' website - a great source of information about workflow definition patterns. Please take a look at animated examples of how each pattern works - this is very much like it is implemented in NGinn. No wonder, however, as the website was created by YAWL guys.

First presentation of NGinn

Today I had a short presentation of the NGinn project at 'Zine day' - Warsaw based meeting of .Net geeks from around the Poland . My presentation was a part of open source project contest (and has even won a second prize, thanks guys!). What really pleased me was that many people got interested in the project and were asking lots of questions about how they could use the nginn engine in their projects. That gives me some clue on what features should be implemented in nearest future and how important it is to release the first version. The presentation was in polish, here's the file - sorry, no english version for now.
I enjoyed the meeting very much and would like to give my thanks to organisers, attendees - especially those who gave their votes to nginn.

Data handling in workflows

In order for workflows to be usable, they must convey some information and process it. NGinn provides a simple to understand data model that allows for easy integration with external applications.

Each instance of NGinn process contains some data. It is called process instance data. This data consists of variables, each variable having a name and holding value of some type. These variables are global to process instance. There is also 'task data', that is a set of variables containing data for a task instance.

More on variables

Variables are the base of NGinn data handling concept. Each variable has a name, type specification, 'requiredness' and direction. Here's an example of process variable definition:

<variable name="requestorName" type="string" required="true" isArray="false" dir="In" />

This line defines a 'requestorName' variable holding a string value, which is required. The variable is single instance (isArray="false") and it is an input variable.
Let's explain this a bit:

• direction (dir="In"). In NGinn, variables can be input (dir="In"), output (dir="Out"), both ways (dir="InOut") and local (dir="Local"). Think of them as procedure arguments. Input variables are used for passing data to process or task instance. Output variables can return execution results from a process or task instance. Local variables are local to process or task, that is they are internal only and invisible to the outside world.
• type (type="string"). Variables can be of some type. NGinn supports basic types, such as string, int, date, bool and complex types (like 'structs' in C or C#), explained later.
• array (isArray="false"). Variables can be single instance, holding only one value, or multiple instance, holding an array of values of the same type.
• required. Variables can be required or optional. Required variables must be passed to process or task. Optional variables can be ommitted, and there is an option for providing default value for optional variables. Default value will be used when the variable is not specified.
  

Process data consists of a set of process variables - each process has its own set of variables. The names and types of variables are defined in process definition. Each task executing in the process instance has its own data, held in task variables and completely separated from the process data. It means that a task can operate only on its own variables and cannot access parent process' or other task's data.
So, there is a question - if there is a complete isolation between task and process data, how do they exchange the information?
The answer is: through data bindings.

Data bindings

Data bindings define how process data is mapped to task input data, or how task output data is mapped back to process data.
Each task has a set of input bindings and output bindings. Input bindings define what information from process instance data will be put in task's input variables. Output bindings define what will happen with task output data - what process variables will receive the values of task output variables.
Input bindings are executed before the task is started. Output bindings are executed after the task completes.

<input-bindings>
<binding variable="requestor" bindingType="CopyVar" sourceVariable="requestedById" />
<binding variable="requestorName" bindingType="CopyVar" sourceVariable="requestedByName" />
</input-bindings>
<output-bindings>
<binding variable="managerApprovalDecision" bindingType="Expr">
   <expression>decision</expression>
</binding>
</output-bindings>

This is an example of task's input and output bindings.

Each binding defines variable that receives the data ('variable' attribute). In case of input bindings it is a task input variable and in case of output bindings it is a process instance variable. In this example, first input binding defines that 'requestor' task input variable will receive the value of 'requestedByName' process variable. 'CopyVar' binding type means that the binding is a simple value copy - from sourceVariable to variable.
The output binding above is more interesting. It is a binding for managerApprovalDecision process variable and this is expression-based binding (type="Expr"). It means that in order to get the value for managerApprovalDecision, expression will be evaluated. Here the expression is 'decision' - so it returns a value of 'decision' task variable. Of course, expressions can be more complex.

Data types

NGinn has built-in support for several basic data types, but the list of types can be extended by custom type definitions.
Supported basic types are:

• string
• int
• double
• date
• datetime (time stamp)
• future releases may add more simple types

Complex data structures can be built out of simple types, in a recursive way. Each process definition contains 'processDataTypes' section, where custom data types can be defined.
There are two kinds of custom data types that can be defined in NGinn - records (structs, similar to C/C# structs) and enums (enumeration of possible values).
Here's an example of a struct:

<processDataTypes>
  <struct name="OrderItem">
      <member name="code" type="string" required="true" />
      <member name="name" type="string" required="true" />
      <member name="quantity" type="int" required="true" />
  </struct>
</processDataTypes>

This is a definition of 'OrderItem' type, which is a struct with three fields: 'code', 'name' and 'quantity'. Each field si required and is single value (not an array).

And here's an enum type with two possible values: YES and NO:

<enum name="YesNo">
    <value>NO</value>
   <value>YES</value>
</enum>

Process data and XML

Data structures in NGinn are designed so that they can be easily converted to XML and back, so data exchange with external applications is simplified. Process or task data definition can be converted to XML schema, so by defining process or task data structure we also get XML data schemas for data exchange.
For example, let's take some process data definition:

<processDataTypes>
<enum name="YesNo">
 <value>NO</value>
 <value>YES</value>
</enum>

<enum name="WeekDay">
 <value>Sun</value>
 <value>Mon</value>
 <value>Tue</value>
 <value>Wed</value>
 <value>Thu</value>
 <value>Fri</value>
 <value>Sat</value>
</enum>

<struct name="DeStrukt">
 <member name="Decision" type="YesNo" required="true" isArray="false" />
 <member name="Day" type="WeekDay" required="true" isArray="false" />
</struct>


</processDataTypes>
<variables>
<variable name="value" type="DeStrukt" required="true" dir="In" />
</variables>

This definition contains two enumeration types and one struct type. And here's how it converts to XML schema:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="YesNo">
<xs:restriction base="xs:string">
<xs:enumeration value="NO" />
<xs:enumeration value="YES" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="WeekDay">
<xs:restriction base="xs:string">
<xs:enumeration value="Sun" />
<xs:enumeration value="Mon" />
<xs:enumeration value="Tue" />
<xs:enumeration value="Wed" />
<xs:enumeration value="Thu" />
<xs:enumeration value="Fri" />
<xs:enumeration value="Sat" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="DeStrukt">
<xs:sequence>
<xs:element name="Decision" type="YesNo" minOccurs="1" maxOccurs="1" />
<xs:element name="Day" type="WeekDay" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
<xs:element name="DataStructs">
<xs:complexType>
<xs:sequence>
  <xs:element name="value" type="DeStrukt" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

Why is it important? Because it defines the structure of XML message with process input data, so we can start new process instance by sending xml similar to this:

<DataStructs>
<value>
    <Decision>YES</Decision>
    <Day>Fri</Day>
</value>
</DataStructs>

With the XML schema auto-generated from process definition it's much easier to integrate NGinn with external tools. For example - we can take this schema and feed it into Microsoft InfoPath form designer. Then we can design an InfoPath form that can be used to start new process instance, and the InfoPath designer will know the resulting XML data structure from the schema.
Not only process input data can be defined in XML, this applies also to process output data and to task input/output data. This way, XML can be used to integrate NGinn with external applications without introducing custom protocols.

A simple process definition example

NGinn is under development and almost every part of it keeps changing. It also happens to the language itself. Currently NGinn is based on XML description of process structure and there is no graphical representation. It is important to have graphical design tools for process graphs, but I think it is too early to develop them -XML form is enough for now. Graphical NGinn representation will be developed after the language becomes stable enough.

OK, so how does NGinn process definition look like?

First of all, NGinn process is a Petri-net, so the definition contains the net structure. Petri net consists of places, transitions and connections between them. Then process-specific extensions are added, such as specialized tasks and process data specification. Let's see an example:

1. Here's a simple process

2. And here's the XML description of this process:

<?xml version="1.0" encoding="utf-8"?>
<process version="2" name="TimerTask" xmlns="http://www.nginn.org/WorkflowDefinition.1_0.xsd">
 <places>
   <place id="start" type="StartPlace"></place>
   <place id="end" type="EndPlace"></place>
 </places>
 <tasks>
   <task id="init" type="EmptyTask" splitType="AND">
   </task>
   <task id="timeout" type="TimerTask" joinType="AND" splitType="AND">
     <timerTask>
       <delayTime>00:01:00</delayTime>
     </timerTask>
   </task>
   <task id="timeout2" type="TimerTask" joinType="AND" splitType="AND">
     <timerTask>
       <delayTime>00:01:00</delayTime>
     </timerTask>
   </task>
 </tasks>

 <flows>
   <flow from="start" to="init" />
   <flow from="init" to="timeout" />
   <flow from="init" to="timeout2" />
   <flow from="timeout" to="end" />
   <flow from="timeout2" to="end" />
 </flows>
 <processDataTypes>
 </processDataTypes>
 <variables>
   <variable name="delayAmount" type="string" required="true" dir="In" />
 </variables>
</process>

OK, so let's see what we have here:

• the main process element is the root of process definition file. Contains process identification attributes, such as name and version number
• The 'places' section - contains list of places in the process definition. Here we have only starting and ending place (note the 'type' attribute identifying the start and end place)
• The 'tasks' section - contains a list of tasks, that is transitions in Petri-net terminology. Tasks can be of several types, offering different functionalities. Here we used empty task (init), which does nothing but is present for synchronization purposes, and two timer tasks which wait for specified period of time. Each type of task is defined in 'task' element, however internal structure of 'task' element depends on the task type.
  Note the 'joinType' and 'splitType' attributes of tasks. These are very important attributes - they specify the synchronization logic between tasks. There are three types of split and join: AND, OR and XOR, we will discuss each type in later posts.

• The 'flows' section, connecting places and tasks. Each 'flow' has its starting node (from) and ending node (to).

That's the Petri-net structure description. However, there is an inconsistency with Petri-net specification. Note that the 'init' task is connected directly to 'timeout1' and 'timeout2' tasks, without intermediate places. Petri nets forbid that - there can be flow only from place to a transition and from transition to a place, place-place and transition-transition connections are not allowed. In NGinn two tasks can be connected. In such case and implicit place is inserted between these two tasks. In our example, there would be an implicit place between init and timeout1 and second implicit place between init and timeout2. The purpose of such construct is only to simplify process definition, however in some cases we will need to specify places explicitly.

There are two more sections in the process definition XML:

• 'processDataTypes' section - contains definitions of data structures used for representing process data. Here it is empty, and data structures will be discussed in later posts
• 'variables' section, containing definitions of process variables. Process variables are like arguments of a function - there can be input variables (input arguments), output variables (return values) and local variables. Also, input-output variables are possible. Here we have only one  variable - 'delayAmount' string.

OK, done with process definition. But what does this process do?

1. Init task is executed. It does nothing, but then the execution is split in two parallel flows(remember the 'AND' split). So the 'init' task consumes one token from the 'start' place and produces two tokens in the implicit places for timeout1 and timeout2 tasks.
2. Timeout1 and Timeout2 execute simultaneously - each of them waits exactly 1 minute and then completes, consuming token from the implicit place between 'init' and itself and producing token in the 'end' place. 
3. There are no tokens except for the 'end' place, so the process is completed.

Process definition

NGinn process model is based on Petri nets extended with process-specific information. Picture below shows a basic Petri net. It consists of places (circles) and transitions (rectangles), connected with arrows.

 

I will not explain here how Petri net works - it can be found in many sources, for example here. Most important principle is that tokens (black dots) represent current process status. Each transition consumes tokens from its input places and produces tokens in output places, so effectively tokens move across the Petri net. In NGinn, we add two special places to the picture - a start place and an end place. Start place is the process starting point - process starts when a token is placed in the start place. End place is the finish point - process finishes when all tokens reach the end place. In the picture above, we could say P1 is the start place and P4 is the end place. 

Transitions in NGinn are called tasks. Tasks are the basic building block of a process and they represent various actions that are needed to complete the process. There are many types of tasks in NGinn, they will be described later. When a task completes, it consumes one or more tokens from its input places (which tokens are consumed depends of task 'join' type - described later) and produces one or more tokens in output places (how many tokens are produced depends on task 'split' type - also described later).

Places in NGinn have 'original' Petri-net meaning. They are just a places where tokens are held during periods of inactivity (when nothing happens in a process or when we are waiting for a task to complete).

NGinn idea is based on the YAWL language -process building blocks are generally the same, so you can read about YAWL to get the idea on how the process definition looks like. However, NGinn provides completely different implementation of the engine and process tasks.