The Iterator object allows you to repeat certain portions of a complete process flow or in specified sections of an input document. The number of times a flow is repeated can be based on a count, the result of a Boolean expression, or the structure of the document itself.
When the iterator completion condition is met, execution of the flow continues with the objects after the loop. Despite the appearance of the diagram in the Process Flow Designer at completion, the flow jumps over the objects inside the loop. Otherwise, the logic inside the loop would be erroneously executed one additional time.
Some guidelines for using Iterator objects in a process flow are:
The loop must begin with an Iterator object. The flow cannot branch into an iteration loop.
Iterator loops can be nested. However, loop lines logic cannot cross.
Only Execution objects can end a loop.
Loops cannot be drawn from Control objects (Join, Junction, Choice, Decision, Set, Sync, Debug, and so on).
The Iterator object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
There are many available iterators, each performing a specific process and then passing the appropriate document into the loop and to the end of the loop. The following table lists and describes the most commonly used iterators.
Iterator
Description
Condition (iterate based on condition)
Iterates a loop while (or until) a condition is met.
Syntax: {com.ibi.agents.XDIterCond}
Chunk (iterate over chunks)
Splits the input document into chunks of equal size.
Syntax: {com.ibi.agents.XDIterChunk}
Line (iterate over each line)
Iterates a loop for each line in the input document.
Syntax: {com.ibi.agents.XDIterLine}
JSON (iterate over JSON)
Iterates a loop for each value selected from a JSON value.
Syntax: {com.ibi.agents.XDIterJsonSplit}
Sibling (iterate over sibling documents)
Iterates a loop for each sibling document.
Syntax: {com.ibi.agents.XDIterSibSplit}
XML (iterate over XML)
Iterates a loop for each portion of an XML document.
Syntax: com.ibi.agents.XDIterXMLSplit
Attachment (iterate through attachments)
Handles each attachment of the current document iteratively.
Syntax: {com.ibi.agents.XDIterAttachments}
SQL Select (iterate through JDBC result set)
Sends out rows, one at a time, to the flow.
Syntax: {com.ibi.agents.XDIterSQLSelect}
Test (iterate using a comparator)
Iterates a loop while (or until) a condition is met.
Syntax: {com.ibi.agents.XDIterTest}
Counter (iterate using a counter)
Iterates a loop a specified number of times.
Syntax: {com.ibi.agents.XDIterCount}
Delimited (iterate using delimiter)
Accepts a delimited value input from a stream or flat document, and emits an XML document representing one row at a time to the flow.
Syntax: com.ibi.agents.XDIterDelVal
Iter RVI Relay
Relays messages for external execution.
Syntax: {com.ibi.agents.XDIterRVIRelay}
FTP Emit
Emits through an FTP protocol to a specified host:port using various common FTP commands.
Syntax: {com.ibi.agents.XDIterNFTPEmitStdAgent}
The available Iterator types are:
Condition Iterator {com.ibi.agents.XDIterCond}. Iterates a loop while (or until) a specified condition is met.
When you add the Condition Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate based on condition
This action iterates a loop while (or until) a condition is met.
Determines the loop logic between Do-While {true} or Do-Until {false}.
By default, this parameter is set to true.
Expression
Expression controlling the termination of the loop.
Parameter
Description
Document
Document emitted at each iteration is the original document or the result of the previous iteration.
By default, this parameter is set to transient.
Parameter
Description
Document
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
Chunk Iterator {com.ibi.agents.XDIterChunk}. Splits the input document into chunks of equal size.
When you add the Chunk Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate over chunks
This action splits the input document into chunks of equal size.
Line Iterator {com.ibi.agents.XDIterLine}. Iterates a loop for each line in the input document. Lines are assumed to be separated by standard end-of-line delimiters.
When you add the Line Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate over each line
This action iterates a loop for each line in the input document.
Sets the number of lines to be skipped for processing. Often a delimited file has a header row, which is not desired in the process.
By default, this parameter is set to 0.
Keep Blanks
If set to true, passes empty (blank) input lines into the loop.
By default, this parameter is set to false.
Parameter
Description
Document
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
JSON Iterator {com.ibi.agents.XDIterJsonSplit}. Iterates a loop for each value selected from a JSON value.
When you add the JSON Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate over JSON
This action iterates a loop for each value selected from a JSON value.
JsonPath expression that selects the items to iterate.
Parameter
Description
Document
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
Sibling Iterator {com.ibi.agents.XDIterSibSplit}. Iterates a loop for each sibling document.
When you add the Sibling Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate over sibling documents
This action iterates a loop for each sibling document.
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
XML Iterator {com.ibi.agents.XDIterXMLSplit}. Iterates a loop for each portion of an XML document.
When you add the XML Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate over XML
This action iterates a loop for each portion of an XML document.
Determines how many top-down levels to trim off of the new XML document, starting from the top (root) node.
A value of 0 preserves all levels. A value of 1 cuts off the root. A value of 2 cuts off the root and immediate child, and so on, down to the XPath location being iterated. The default value is 0, which will return all parent tags up to the root.
Note: Cross Section data may be lost depending on the snip level setting.
Expression
Describes the XPath location of the element on which to split. When the Evaluate Expression is not set (false), type an XPath expression directly. When the Evaluate Expression is set (true), type an expression that returns an XPath expression.
Evaluate Expression
When not set, the Expression parameter contains an XPath expression directly. When set, the Expression parameter is evaluated and the returned value is the XPath expression used for splitting.
By default, this parameter is set to false.
XML Namespace Map Provider
If the XPath expression depends on namespaces, then specify the name of an XML Namespace Map Provider that contains the required namespace prefixes and URLs.
Cross Section
If set to true, the iterated portion is included with the remainder of the non-iterated portion of the document. Otherwise, only the parental path is included.
By default, this parameter is set to false.
Iterating Document State
In addition to content, a document carries state. This parameter determines how the state should be managed at the iterations.
By default, this parameter is set to transient.
End Iteration Signal
Determines whether an extra iteration is added at the end to emit the End Iteration document. If applicable, the end of iteration signal will be emitted on the end_iteration edge. The default is not to emit the End Iteration document.
By default, this parameter is set to false.
Output document
Select one of the following values from the drop-down list:
status. Status document will be the output document.
original. Original input document will be the output document.
accumin (Loop Accumulation), accumont (Iterated Accumulation). Allow gathering of partial documents, but can be memory intensive. Input is what passes from the iterator, and output is what is returned for each iteration.
By default, this parameter is set to status.
XPath Syntax
Determines which syntax level of XPath should be used. The default option selects the syntax level as set in the console global settings.
By default, this parameter is set to default.
Attachment Iterator {com.ibi.agents.XDIterAttachments}. Handles each attachment of the current document iteratively.
When you add the Attachment Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate through attachments
This action handles each attachment of the current document iteratively.
Select one of the following values from the drop-down list:
leave. Leaves the original attachments unchanged.
delete. Removes each attachment from the current document after processing.
replace. Replaces the original attachment with the modified document.
By default, this parameter is set to leave.
Start Index
Index of the first attachment to process in the mail object. The first attachment to the main document has index 0.
Keep Document Flat
Determines whether to keep the body of the document as an array of bytes.
By default, this parameter is set to false.
Parameter
Description
Header Namespace
Special register namespace where MIME headers for the current attachment will be stored. If the replace option is selected for the Handling Option parameter, then registers in this namespace will be added to the replaced attachment.
Main Body Part Header Namespace
If the current attachment is itself a Multipart, this is the special register namespace where the MIME headers for the main body part will be stored.
SQL Select Iterator {com.ibi.agents.XDIterSQLSelect}. Sends out rows, one at a time, to the flow.
When you add the SQL Select Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate through JDBC result set
This action sends out rows, one at a time, to the flow.
SQL Select statement to retrieve rows to pass into the process flow.
Isolation Level
Transaction isolation level to be set, if possible.
By default, this parameter is set to asis.
Parameter
Description
Base 64
If set to true, all fields are checked for base64. This option is resource-intensive.
By default, this parameter is set to false.
SQL Agent Format
If set to true, the generated rows are formatted according to the SQLAgent field schema.
By default, this parameter is set to false.
Inline xLOBs
If set to true, character and boolean large objects are inline in the select results. BLOBs are enclosed in base64() tags.
By default, this parameter is set to false.
Input Encoding
IANA character set to be used for the input database. Select from the standard list, or enter an encoding name.
By default, this parameter is set to leave.
Three Part Name
If set to true, the names will be presented as full three part names, if supported by the database.
By default, this parameter is set to false.
Parameter
Description
Document
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
Test Iterator {com.ibi.agents.XDIterTest}. Iterates the loop while (or until) a specific condition is met.
When you add the Test Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate using a comparator
This action iterates a loop while (or until) a specific condition is met.
Determines the loop logic between Do-While {true} or Do-Until {false}.
By default, this parameter is set to true.
Operand One
First of two operands to compare.
Operation
Comparison operator.
By default, this parameter is set to equals case sensitive.
Operand Two
Second of two operands to compare when the operation is dyadic.
Parameter
Description
Document
Document emitted at each iteration is the original document or the result of the previous iteration.
By default, this parameter is set to transient.
Parameter
Description
Document
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
Counter Iterator {com.ibi.agents.XDIterCount}. Iterates a loop a specified number of times.
When you add the Counter Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate using a counter
This action iterates a loop a specific number of times.
Document emitted at each iteration is the original document or the result of the previous iteration.
By default, this parameter is set to transient.
Parameter
Description
Document
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
Delimited Iterator {com.ibi.agents.XDIterDelVal}. Accepts a delimited value input from a stream or flat document, and emits an XML document representing one row at a time to the flow.
When you add the Delimited Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: iterate using delimiter
This action accepts a delimited value input from a stream or flat document, and emits an XML document representing one row at a time to the flow.
Determines whether the first row is a header row. If not (false), then the first row contains data and generated names are used for the elements. If set to true, then the first row holds the names, and the data starts at the second row.
By default, this parameter is set to false.
Delimiter
Determines the delimiter to be used.
By default, this parameter is set to comma.
Parameter
Description
Root Element
Name of the XML outer tag, which wraps the transient document.
Trim Values
Determines whether all values should be trimmed.
By default, this parameter is set to false.
Quotes
Determines whether surrounding quotation marks should be eliminated.
By default, this parameter is set to false.
Empty Elements
Determines whether empty elements at the right should be eliminated.
By default, this parameter is set to false.
Parameter
Description
Document
Final document emitted is a status document, the original document, the result of the last iteration, or an accumulation. Accumulations are memory intensive.
By default, this parameter is set to status.
Iter RVI Relay {com.ibi.agents.XDIterRVIRelay}. Relays messages for external execution.
Note: The Iter RVI Relay Iterator object must be added through the Server Agent object.
When you add the Iter RVI Relay Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Name of the service to execute the current message.
Tolerance
Amount of time (in seconds) to await circuit availability to access the named service.
By default, this parameter is set to 30.
Timeout
Amount of time (in seconds) to await response from the gateway.
By default, this parameter is set to 30.
Attempt Retry
If set to true, a retry exception is generated when no gateway connections are available, a message cannot be written to the gateway, or this service times out while awaiting a response. The retry exception will activate the channel’s pending system, when available. If set to false, this service will attempt to acquire a new connection if the message cannot be written to the gateway and, if a connection is available, will retry automatically. If no connections are available, or if the service times out or otherwise fails while reading the response, the service will return a failure edge.
By default, this parameter is set to true.
Output on Failure
If the relay operation is unsuccessful, this parameter determines whether the agent should return the standard error document, or return its input. If input is selected, then the error document will be stored in the rvi.status register [type:user].
By default, this parameter is set to error.
Method of compression to use
Form of compression that should be used on the input.
By default, this parameter is set to none.
FTP Emit Iterator {com.ibi.agents.XDIterNFTPEmitStdAgent}. Emits through an FTP protocol to a specified host:port using various common FTP commands.
Note: The FTP Emit Iterator must be added through the Server Agent object.
When you add the FTP Emit Iterator object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
DNS name (or IP address) of the FTP server to which you want to connect. Use host:port if not standard port 21.
Remote Port
Port to connect to on the FTP site, blank for default port 21.
User Name
Valid user ID for the FTP server.
Password
Valid password for the user name. You can select to type in the password directly or use a regular expression for the password.
Account Name
Valid account name for the FTP server.
Password
Valid password for the account name. You can select to type in the password directly or use a regular expression for the password.
Use Passive Command
Uses the PASV command if set to true, otherwise, uses the PORT command.
By default, this parameter is set to false.
Timeout
Timeout interval for the socket in seconds.
By default, this parameter is set to 5.
Port Restrictions
If set, restricts the PORT/EPRT command to the following range of ports (for example, 1000-9999, 50000-60000, and so on).
Retry Interval
Retry interval in seconds (allows for xxhxxmxxs format). Omit or use 0 for no retry.
Connection Retry
Number of retry attempts after a failed connection to the FTP server.
By default, this parameter is set to 0.
Parameter
Description
Block Size
Size of the transmission block to send.
By default, this parameter is set to 256.
Input Source
Input from the document (default) or from an external source (MFT use).
By default, this parameter is set to document.
Input Expression
If the Input Source parameter is set to external, then specify the file name in this field. For document source, this parameter is ignored.
Remote Site Folder
Folder or directory on the FTP site that you want to use as a starting location after a connection is established. Leave blank for the login directory.
File Pattern
Output file pattern (* = timestamp). For example, *.xml, *.txt, and so on. Note that *.* is unsupported.
Transfer Mode
When files are transferred in ASCII mode, the transferred data is expected to contain only character formatted text. BINARY mode refers to transferring files as a binary stream of data. Where ASCII mode may use special control characters to format data, BINARY mode transmits the raw bytes of the file being transferred. In this way, the file is transferred in its exact original form.
By default, this parameter is set to ascii.
File Put Protection
Determines whether the PUT is protected by a rename of a temporary file name. Using the rename protection can result in reduced performance, but can protect against partial updates in the event of an error.
By default, this parameter is set to false.
Return
Select one of the following values from the drop-down list:
status. Status document will be the output document.
original. Original input document will be the output document.
By default, this parameter is set to status.
Parameter
Description
Proxy Type
Proxy protocol to use.
By default, this parameter is set to None.
Proxy Host Name
DNS name (or IP address) of the proxy server that you want to connect to.
Proxy Port
Port to connect to on the proxy site.
Proxy User ID
Folder or directory on the FTP site that you want to use as a starting location after a connection is established. Leave blank for the login directory.
Password
Password for the Proxy user ID on the proxy server. You can select to type in the password directly or use a regular expression for the password.
Parameter
Description
Use SSL
If set, the connection is secured through Secure Sockets Layer (SSL).
By default, this parameter is set to false.
Security Protocol
Security protocol
SSL. Supports some version of SSL. May support other versions.
SSLv2. Supports SSL version 2 or higher.
SSLv3. Supports SSL version 3. May support other versions.
TLS. Supports some version of TLS. May support other versions.
TLSv1. Supports TLS version 1. May support other versions.
By default, this parameter is set to SSL. The field is not needed if Keystore is an SSL Provider.
Secure Data Connection
Use a secure data connection, that is, transfer data securely. Used in conjunction with Secure Control Connection.
By default, this parameter is set to false.
Use 128-bit Encryption
Enforces the use of 128-bit encryption.
By default, this parameter is set to false.
SSL Security
FTP Server connection type.
unknown. Defaults to Explicit Security, then fails over to Implicit Security.
explicit. In order to establish the SSL link, explicit security requires that the FTP client issue a specific command to the FTP server after establishing a connection. The default FTP server port is used.
implicit. Implicit security automatically begins with an SSL connection as soon as the FTP client connects to an FTP server. In implicit security, the FTP server defines a specific port for the client (typically 990) to be used for secure connections.
By default, this parameter is set to unknown.
Keystore File or Security Provider
Full path to the Keystore file, which provides certificate material to be used for SSL connection, the name of the Security Provider, or leave blank to use the configured default Security Provider.
Keystore Password
Password to access the Keystore file. Not needed if the Keystore File or Security Provider is the name of a Security Provider.
Keystore Type
Type of the Keystore. Not needed if the Keystore File or Security Provider is the name of a Security Provider.
Parameter
Description
Starting SITE command
SITE command to issue before the transfer of data.
Successful SITE command
SITE command to issue after the successful transfer of data.
Error SITE command
Port to connect to on the proxy site.
The Synch object waits for a condition to be met, such as the expiration of a time limit or the evaluation of an expression as true. The conditions are based on the events created through the Set object.
The Synch object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Synch object to your process flow using iIT, configuration properties for this object are available in the Properties tab and grouped by subtabs.
Expression subtab:
To build a Synch expression, click the Plus button. The default, Condition1, appears under the Name column, as shown in the following image.
You can change the name and select the Event Name, Operation, and Value for the new condition. The Event Name drop-down list consists of the events defined in the Set objects. Add as many conditions as required. Above the condition parameters, select the relationship between these conditions as an AND or OR operation. To delete a condition, select the condition, and click the red X button.
Timeout subtab:
Type a timeout value (in seconds). This is the time period for which the Synch object will wait for the expression to be evaluated as true. A value of zero (0) means that the Synch object will wait indefinitely.
Debug subtab:
The Debug subtab allows you to configure iterative tracing limits. When this object is part of an iterative loop, the maximum number of iterations that can be captured is 20. Tracing can be controlled by specifying the iteration that begins and ends the document capture.
Specify the iterations in which you want the tracing to begin and end.
The following tracing formats are available from the drop-down list:
Standard tracing (default)
Standard tracing displayed in hex format
Just the output document
None, under any circumstances
The Set object initiates one or more process events that corresponding Synch objects are waiting on. Set and Synch objects are used to suspend and resume the execution paths of a process flow.
The Set object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Set object to your process flow using iIT, configuration properties for this object are available in the Properties tab and grouped by subtabs.
Event subtab:
Add one or more events that can be used to meet conditions defined in one or more Synch objects. Click the Plus button and type an event name in the Name column. Then, double-click and select a value and usage from the Value and Usage drop-down lists, and type a description of the event in the Description column.
Debug subtab:
The Debug subtab allows you to configure iterative tracing limits. When this object is part of an iterative loop, the maximum number of iterations that can be captured is 20. Tracing can be controlled by specifying the iteration that begins and ends the document capture.
Specify the iterations in which you want the tracing to begin and end.
The following tracing formats are available from the drop-down list:
Standard tracing (default)
Standard tracing displayed in hex format
Just the output document
None, under any circumstances
The Move object moves the message in the process flow.
The Move object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Move object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Action: move document
This action moves the input document to the output document. This action has no parameters.
Action: move document with delay
This action moves the input document to the output document, with a time delay.
Number of seconds to delay, before returning the output document.
By default, this parameter is set to 0.
The Junction object joins two or more paths of execution into a single path. It does not join documents that travel along the path. For example, if you have five distinct paths that run to a certain point, and then all paths execute the same logic, use the Junction object to consolidate the flow at the point of common execution. You can think of the Junction object as a visual convenience in junction of the multiple threads going into the Junction object and enabling them to execute the same logic after the Junction. You will also notice a dotted-dashed line coming out of the Junction object showing that there are multiple threads of execution on the outbound end.
As a reference, the following two images of the process flow are identical in execution.
With Junction:
Without Junction:
The Junction object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Junction object to your process flow using iIT, configuration properties for this object are available in the Properties tab and grouped by subtabs.
Debug subtab:
The Debug subtab allows you to configure iterative tracing limits. When this object is part of an iterative loop, the maximum number of iterations that can be captured is 20. Tracing can be controlled by specifying the iteration that begins and ends the document capture.
Specify the iterations in which you want the tracing to begin and end.
The following tracing formats are available from the drop-down list:
Standard tracing (default)
Standard tracing displayed in hex format
Just the output document
None, under any circumstances
The Join object combines two or more documents into a single document. The single document then proceeds to the next object in the process flow.
For example, if you have two XML documents:
A:
<A> ... </A>
and B:
<B> ... </B>
The Join object creates the following output:
<JOIN>
<A>
.
.
.
</A>
<B>
.
.
.
</B>
</JOIN>
Caution: Use caution when mixing Join and Junction objects in a process flow. When a Join object is located after a Junction object, results can be unpredictable.
The Join object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Join object to your process flow using iIT, configuration properties for this object are available in the Properties tab and grouped by subtabs.
Timeout subtab:
Timeout is the amount of time (in seconds) that the Join object will wait to receive the documents it must join. The timeout count begins when the first document enters the Join object. If the Join receives all of the documents before the timeout period ends, the join process continues. If all documents needed to satisfy the join are not received, then a status document is generated and sent along the OnTimeout edge.
Select a Timeout value from the Timeout drop-down list.
Debug subtab:
The Debug subtab allows you to configure iterative tracing limits. When this object is part of an iterative loop, the maximum number of iterations that can be captured is 20. Tracing can be controlled by specifying the iteration that begins and ends the document capture.
Specify the iterations in which you want the tracing to begin and end.
The following tracing formats are available from the drop-down list:
Standard tracing (default)
Standard tracing displayed in hex format
Just the output document
None, under any circumstances
Post-Execution subtab:
The End object terminates the process flow. All processes must terminate with at least one End object. There can be multiple End objects in a single process flow.
The End object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the End object to your process flow using iIT, configuration properties for this object are available in the Properties tab and grouped by subtabs.
Configuration subtab:
Terminate. Leave unchecked to pass the document to the listener, or select to suppress transmission of the document to the listener. If your process flow provides all of the output necessary for your application, then you can select the check box in order to bypass the outlets associated with your channel. You can use multiple End objects with different settings in a process flow to direct document flow behavior. If you have multiple End objects which are not terminating, it may result in multiple documents being returned to the listener depending on the application design and multi-threading of the process flow.
Content-Type. Specify the media type of the message being returned from the drop-down list, as shown in the following image.
Schema subtab:
A schema is needed if you intend to expose the process flow as a web service.
If you want to expose the process flow as a web service, specify a schema for the End object in the Schema field. Otherwise, leave this field blank. If you want to view a schema you selected, click View. The schema appears in the browser.
In the Root Tag Element field, type or select the name of the root tag element of the output document for the current process flow.
Debug subtab:
The Debug subtab allows you to configure iterative tracing limits. When this object is part of an iterative loop, the maximum number of iterations that can be captured is 20. Tracing can be controlled by specifying the iteration that begins and ends the document capture.
Specify the iterations in which you want the tracing to begin and end.
The following tracing formats are available from the drop-down list:
Standard tracing (default)
Standard tracing displayed in hex format
Just the output document
None, under any circumstances
The Conditional object evaluates the contents of a document and routes it to the next object(s) based on the values in the document.
Note: The Conditional object is a direct replacement for the Decision Test object, which was available in iWay 7.0.x releases.
The Conditional object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Conditional object to your process flow using iIT, configuration properties for this object are available in the Properties tab and grouped by subtabs.
Operands subtab:
Operands in the Conditional object can be literals, variables, or XPath expressions. The available comparison operations are available in the Operation drop-down list, as shown in the following image.
Occurrences subtab:
When using an XPath expression, many values can be retrieved from the document. The Occurrences subtab allows you to specify how the test comparison should handle multiple values.
Select a test occurrence:
Unique. Only one value can exist in the document.
Any. At least one value must exist in the document.
All. Every value must exist in the document.
Debug subtab:
The Debug subtab allows you to configure iterative tracing limits. When this object is part of an iterative loop, the maximum number of iterations that can be captured is 20. Tracing can be controlled by specifying the iteration that begins and ends the document capture.
Specify the iterations in which you want the tracing to begin and end.
The following tracing formats are available from the drop-down list:
Standard tracing (default)
Standard tracing displayed in hex format
Just the output document
None, under any circumstances
The Choice object evaluates the contents of a document or a variable, and routes the document accordingly, similar to the switch/case construct of other programming languages. The main difference is that the document can match multiple cases simultaneously.
Note: The Choice object is a direct replacement for the Decision Switch object, which was available in iWay 7.0.x releases.
The Choice object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Choice object to your process flow using iIT, configuration properties for this object are available in the Properties tab and grouped by subtabs.
Expression subtab:
The Choice object can direct the document down one or more alternate paths, based on the value of the switch expression. In the following example, the document contains a value indicating the protocol(s) through which it should be routed (FILE, EMAIL, HTTP). To accomplish this, an XPath is constructed to capture the switch value from the document. You can also switch on computed conditions by using a variable that was set to one of your case values earlier in the process flow.
Cases subtab:
Add the Choice case values and descriptions to the table. Each choice case creates a named outlet leaving the Choice node. When the current switch value is equal to a given case, the document will be sent down the corresponding edge for further processing. If the expression recovers multiple switch values, the document will be sent down multiple edges simultaneously.
In the example below, three cases have been added for sending the document down the FILE, EMAIL, or HTTP path line of the process flow for execution, based on the conditional value returned by the expression.
Note that when you will be wiring the edges from the Choice node, you will also have the option to set the standard system edges. You should always ensure that you set the Default edge, in case the expression does not return the expected value.
For illustration purposes, the process flow with a Choice node, three customized edges, and a default edge may look similar to the following image.
Debug subtab:
The Debug subtab allows you to configure iterative tracing limits. When this object is part of an iterative loop, the maximum number of iterations that can be captured is 20. Tracing can be controlled by specifying the iteration that begins and ends the document capture.
Specify the iterations in which you want the tracing to begin and end.
The following tracing formats are available from the drop-down list:
Standard tracing (default)
Standard tracing displayed in hex format
Just the output document
None, under any circumstances
The Catch object catches errors in a process flow. This object implements com.ibi.agents.XDCatchAgent, which triggers the process flow to handle onFailException or onRetryException events.
The concept of the Catch node is similar to a try-catch block in other programming languages.
In other programming languages, a block of code is enclosed between the braces of a try statement. Following the try block is a catch block of code that is enclosed in braces. The code in the catch block has statements that handle any errors that might occur in the try block.
When the thread of execution starts, each line in the try block of code is executed. If each statement is successful, execution continues at the statement following the closing brace of the catch block (assuming that there is not a finally block). If an error occurs within the try block, the thread of execution jumps to the code inside the catch block.
In a process flow, you can add a Catch node in front of the nodes in which an error might occur.
There are three edges off this service:
onFailException
onRetryException
onCompletion. This edge is the default value, when neither the onFailException or onRetryException event is selected.
The completion edge is the thread of execution in which everything works in a perfect scenario. All the edges after the service connected by the onCompletion edge are then connected to the onSuccess edge.
Any errors or failures that occur within the path of the process flow are directed down the onFailException or onRetryException edge. The logic in this branch contains any nodes necessary to handle errors. The onRetryException edge is followed when there is a retry exception. For example, when an SQL Object contains an invalid URL in the process flow.
You can add multiple Catch nodes in a process flow. The error branch is taken off the closest Catch node previous to where the error occurred. In this manner, you can add multiple error conditions for a given process flow, if required.
The catch is hierarchical and each catch is considered nested in the prior Catch node. When a Catch node is triggered, the Special Register (SREG) iway.catchname is set to the name of the Catch node that first catches the error. The register is not replaced as succeeding Catch nodes see the error. This allows higher scopes to ascertain the scope under which the original error is caught. For example, if Task3 fails and the error is caught by CatchScope3, the register will be set to CatchScope3 even though the error may cascade through higher scopes.
The Catch object is located in the iWay Integration Tools (iIT) Palette, under the Flow Control group, as shown in the following image.
When you add the Catch object to your process flow using iIT, configuration properties for this object are available in the Properties tab, as shown in the following image.
Default action: catch handler
This action responds to an exception when an unexpected event in the process flow occurs. If the catch object is successful, execution continues, following the catch object. If an error occurs, the thread of execution jumps to the code inside the catch object to determine the failure.
Maximum number of times a catch will pass the error to an error handler.
The Catch node can be configured to allow only a specified count of catches. This helps to deal with errors in the error handler reached through the catch itself. For example, consider what happens in the process flow shown in Example 2 if the Write Error node fails. In this case, because the Write Error node does not itself provide an onFailException edge and handle the failure, the failure is propagated upward, where it reaches the Catch node. That node passes the error down its failure edge, back to the Write Error node, which might again fail. If this continues, a loop situation arises.
The Max Entries parameter allows a count of the number of times a Catch node will pass the error to an error handler (the default value is 1). If the number of errors reaching the Catch node exceeds this specified count, then the Catch node does not handle the error, but rather allows the error to be propagated upward to the next higher Catch node, or (if none is encountered), terminates the process flow.
The count is reset each time a document passes through the Catch node in the forward direction, so that the catch count applies only to the specific error handling situation.
It is possible to use this facility to add logic to the error handler itself. For example, you may want to apply error handing for up to six times, but only every five seconds. Doing so would provide an external system with time to accept the error. In this case, you might set the Max Entries parameter to six, and add a five second delay, using a move node with delay, into the error handler logic before attempting to deal with the error.
Example1
In this example, consider a process flow where three tasks are performed (called Task1, Task2, and Task3). The process flow performs three tasks, as shown in the following image.
There is a requirement to handle errors in each task separately. So, in our updated process flow, a Catch node precedes each Task node to handle errors in that task., as shown in the following image.
In this example, assume Report1 to Report3 are each an SQL object recording failures. If Task3 (on the main line of the process flow) fails, then the failure is caught by CatchScope3. Report3 records the failure and control passes to Fail3. Fail3 is a Fail service, which has a Bypass Catch Processing parameter set to true.
However, if Report3 fails, then the failure will be caught by CatchScope2. The Catch node for scope three does not catch the Report3 failure as it has already caught a failure. The scope in this example tests to determine whether the failure was in its scope, in which case Report2 will record the failure within the scope, or in a lower scope. It does this by the NotMe2 test, which evaluates the scope. This is a test node, which is set to the following parameter values:
Operand One: _sreg(‘iway.catchname’)
Operation: Not Equal To
Operand Two: CatchScope2
This causes the extra report to be bypassed. In this case, the example uses a Trace service (Trace1, Trace2) to report the error in the lower scope to a simple trace message. Following the trace message reporting a failure in a lower scope, the process flow uses a Fail service to issue the fail that did not get issued in the lower scope. This maintains the statistics of the channel.
In the multiple Catch node use case, setting the Bypass Catch Processing parameter of the Fail service to true will cause the failure request to bypass upper-level Catch nodes, avoiding the need for scope testing (such as with the example in the My Scope tests in upper scopes).
Example 2
In this example, a file is put into a directory after its creation from a previous channel. The sample process flow is responsible for transmitting the file to the customer FTP site.
Since this is an FTP site, it is subject to network and site availability and other possible outside issues. An error handling strategy is required so that none of the documents being processed are lost because of an outside issue.
In the process flow, the Catch node immediately follows the Start block. An onCompletion edge connects the Catch Errors block to the FTP Write block. The FTP Write block is an FTP emitter that is set up to write the file to an FTP site.
Following the FTP Write block is the End block. The edge connecting these two services is an onSuccess edge. If a different edge were used and an error occurred, the error edge off of Catch Errors may not be executed.
The Catch node has onFailException selected for the properties. This edge leads to a file write service, Write Error, which puts the file into a hold directory for later reprocessing. Following Write Error, there is an End with a Terminate since no further processing is required at this point. In a real world scenario, a requirement might be that an email is sent if the site is down.
When the target FTP site is up and available, the files are written to the FTP site. If the FTP site is down or you cannot connect to it, the FTP write service will generate an error. This error causes the next execution point to be the File Write to save the file for further processing.
