Process Flows

A process flow consists of service nodes (agents) and the edges that connect them. Edges have names (for example, success or fail_connect) that control their characteristics and use. Nodes provide services within the process flow, and although they have names, the names are not used for any purpose other than tracing the execution of the process flow.

The following image is an example of a simple process flow that contains three nodes (Start and End nodes, and one that performs a service).

The arrows that connect the nodes are the edges. In the example, the edges (relations) are the OnComplete (from Start to Service) and OnSuccess (from Service to End) edges.

Process flows are managed by the Process Flow Interpreter, which handles all aspects of process flow execution.

As the process flow begins, the XDDocument reaching it passes to the first node of the process flow. From there it passes from node to node, through the edges. Each node examines, possibly modifies and re-emits a document back into the process flow.

If the process flow is running in Local transaction mode, on completion of the process flow execution the transaction handler determines how the process flow ended (reached the end or failed during run) and calls commit() or rollback() as appropriate.

In cases in which more than one edge should be followed, the process flow is multithreaded. In the example below, both Service1 and Service2 receive the output copies of the Service node. The documents are distinct, and can be modified by either edge without affecting the document on the other edge. Programmers are reminded that documents occupy memory, and application developers are cautioned that memory may be limited.

Documents in Error

Some nodes may mark the document in error. Usually a status document detailing an error is also marked. A document that exits the process flow in an error state will be sent to the errorTo address(es) if available. Otherwise, the document is sent to the replyTo addresses. The process flow provides a node (XDDocAgent) that can set or reset the error status as required.

Emitting Information in a Process Flow

Process flows offer two methods of emitting information that differ in their use:

emitters
emit agents

An emitter adds an address to the current document that is passing through a process flow. When the document is finally emitted from the end nodes of the process flow, it eventually reaches the emit stage, as described above. At that time, the document is sent to the list of addresses associated with the document. No emit occurs as the document passes into the emit nodes. Rather, it is emitted only when the channel reaches the output stages.

An emit agent causes the current document to be emitted when the node is executed. Thus the process flow can send a message, and possibly act on the reply. Emit agents do not associate an address with the current document, but rather executes the emit operation at the time called. An emit agent does not change its behavior based on the error state of the document.

Some emit agents can operate selectively (by configuration) within or outside of a transaction boundary, For example, an MQ emit agent can be configured in this way. Doing so permits an error message to be placed on a queue (in this example) that will be committed immediately and will not roll back if the process flow is in error.

Understanding How Process Flows Handles Edges

As the service node ends and passes control back to the Process Flow Interpreter, it returns the name of one or more edges that are to receive the output document. The edge is returned as a String from the agent, using commas to delimit multiple edge names if necessary. For example, an HTTP node that cannot connect to a server might return:

fail_501,fail_5xx,fail_connect

The interpreter first examines the edges, and determines which edges are actually connected. It compares this with the list of possible edges. The document flows down all edges with names that match an offered name, under the following rules:

The String return value execute method of an agent determines the process flow edge or edges that will be followed. You can return more than one edge, using comma as a delimiter.
If the edge name starts with fail_, edges are tested until a fail_ edge is found wired. Thus the most exact edge is the one followed. In the example, if fail_501 is wired, it will receive the document. If not, then fail_5xx, and then fail_connect. A document follows only one fail edge.
If the edge name starts with fail_ and no specific edges are wired, then the process flow looks for a general fail edges (selected as failures from the relations wizard in iWay Designer).
If an OnCompletion edge is offered, any edge name from the node is considered a match, in addition to any specific wired edges.
If no edge is found to be followed, an error is thrown. Note that a node that throws an exception cannot return an edge name, and so an OnError edge is assumed to have been returned. An OnError edge will not follow an OnComplete edge. If you write agents (described later in this manual) rigorously, avoid throwing exceptions-use fail edges.
If an OnError edge is wired, the node/flow is not considered to be in error, as the application process flow has elected to handle the error.
If an OnError edge is not wired, the interpreter searches upward in the process flow looking for a catch node. If one is found, the error message document is passed down that edge, and the process flow is not considered in error (again, the application has elected to handle the error).
If the search reaches the Start node, then the process flow is considered in error. In such a case, the nodes of the transactional process flow receives a rollback() call. Otherwise, a commit() call will be received when the process flow ends.

Additional rules:

While you can use the relations wizard in iWay Designer to create edges of any name, never create one starting with a dollar character ('$'). These are reserved for the system.
A successful node should always return Success.
iWay suggests that you use an OnCompletion edge only in cases in which a node cannot fail. An example is a Move or Copy node, the edge coming from the Start node, or the edge followed by an iterator on completion of the iteration.
Be sure that the getOPEdges() method of a node returns a String[] with all edge names that the agent could return. The only exception to this is the return of one or more of a long list of possible returns, such as XOPEN SQL codes. The user can, using wizards in iWay Designer, enter a specific name for an edge not offered in the metadata of the node.