1. iWay Integration Tools
  2. Chapter 1. iWay Components
  3. 1.7 Concept: iWay Flow Controls
  4. Iterator Object

Iterator Object

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.

Flow Control Iterator Object

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.

Iterator Condition

Default action: iterate based on condition

This action iterates a loop while (or until) a condition is met.

Parameter Groups

Parameter Description
Do-While 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.

Iterator Chunk Configuration

Default action: iterate over chunks

This action splits the input document into chunks of equal size.

Parameters

Parameter Description
Do-While Size of the chunks, in bytes.

The default value is 8192 bytes.

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.

Iterator Line Configuration

Default action: iterate over each line

This action iterates a loop for each line in the input document.

Parameter Groups

Parameter Description
Skip Lines 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.

Iterator JSON Configuration

Default action: iterate over JSON

This action iterates a loop for each value selected from a JSON value.

Parameter Groups

Parameter Description
Path Expression 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.

Iterator Sibling Configuration

Default action: iterate over sibling documents

This action iterates a loop for each sibling document.

Parameters

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.

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.

Iterator XML Configuration

Default action: iterate over XML

This action iterates a loop for each portion of an XML document.

Parameters

Parameter Description
Snip levels 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.

Iterator Attachment Configuration

Default action: iterate through attachments

This action handles each attachment of the current document iteratively.

Parameter Groups

Parameter Description
Handling Option 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.

Iterator SQL Configuration

Default action: iterate through JDBC result set

This action sends out rows, one at a time, to the flow.

Parameter Groups

Parameter Description
Select SQL 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.

Iterator Test Configuration

Default action: iterate using a comparator

This action iterates a loop while (or until) a specific condition is met.

Parameter Groups

Parameter Description
Do-While 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.

Iterator Counter Configuration

Default action: iterate using a counter

This action iterates a loop a specific number of times.

Parameter Groups

Parameter Description
Iterations Number of times to repeat the loop.

By default, this parameter is set to 1.
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.

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.

Iterator Delimited Configuration

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.

Parameter Groups

Parameter Description
Header 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.

Iterator Relay Configuration

Agent Type: RVI Relay: Relays messages for external execution. Iterates responses {com.ibi.agents.XDIterRVIRelay}

This action relays messages for external execution.

Parameters

Parameter Description
Service Name 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.

Iterator FTP Emit Configuration

Agent Type: FTP Emit Iterator {com.ibi.agents.XDIterNFTPEmitStdAgent}

This action emits through an FTP protocol to a specified host:port using various common FTP commands.

Parameter Groups

 
Parameter Description
Host Name 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.