x

The Server Startup process flow is executed by the iSM initialization routines as iSM starts its execution. This process flow can check for the availability of resources that are required by iSM, and can prevent iSM from starting if the resources are not available. A return of success allows iSM to continue its startup sequence. Otherwise the iSM startup is terminated.

The Server Startup process flow cannot start channels, since iSM is not ready to run channels at this early (startup) stage.

The name of the Server Startup process flow must be entered in the Recovery area of the General Settings page (Process Name field), as shown in the following image.

The following table lists and describes the possible edges that are returned by the Server Startup process flow.

Edge	Description
success	Continue with iSM startup.
<other> or flow fails	Do not continue to start iSM.

x

This process flow is executed when the iWay Business Activity Monitor (BAM) drivers lose connectivity to the BAM database. The process flow can notify an operation area of the problem, and can determine how iSM should continue:

• iSM continues, but BAM update is ignored.
• iSM terminates.
• iSM maintains a local file on disk containing BAM information and attempts to update the database when connectivity is restored.

x

The channel failure process flow is executed if the channel fails during its normal run cycle. iSM monitors the channels, and attempts to intercept failures within the channel that are not handled by normal channel and server error management. If such an error is detected, the ChannelFailure exit is entered. The input document to the process flow signals the cause of the failure, along with statistical and other information as available. This process flow must be published to the system, and is executed whenever the channel encounters an error that cannot be handled by normal logic. The process flow is often used to send an email to alert an administrator of the issue.

iSM divides channel operation into three parts:

• Initialization
• Startup
• Message Handling

The channel failure process flow applies for initialization and startup only to channels that are not started by a specific manual command. This is because the operator is usually starting the channel and is monitoring its startup.

To configure a channel failure process, enter the name of the published process flow to run in the Channel Failure Flow field of your listener configuration, as shown in the following image.

Note: Although iWay attempts to maintain document structure, the nature of this channel failure process flow opportunity may require changes at any time. iWay will attempt to guarantee the structure between releases and service packs, but additional information may be added at any time. Any such changes will be documented in the release or patch release notes.

The channel failure process flow receives a signal message document for processing. The signal message document uses the following structure and format:

<channelfail name="File" state="4" statename="active" time="2013-09-20T16:18:11Z" type="unexpected" version="7.0.0">
  <exception>
    <cause>java.lang.NullPointerException</cause>
    <stacktrace>
      java.lang.NullPointerException&#xd;
      at com.ibi.edaqm.XDFileMaster.run(XDFileMaster.java:301)&#xd;
      at java.lang.Thread.run(Thread.java:724)&#xd;
    </stacktrace>
  </exception>
  <statistics completed="177" failed="2"/>
</channelfail>

A startup failure process flow may receive the following document:

<channelfail name='channelname' protocol='protocol' state='statecode'statename='init'  failures='2' version='7.0.0'= time='2013-09-20T16:18:11Z' type='init'>
    <message>Cannot locate file directory</message>
</channelfail>

The type attribute identifies the form of the failure trap, which is listed and described in the following table.

Attribute	As Of iSM Release	Applies to Manual Start?	Description
unexpected	7.0	Yes	An unhandled runtime exception was encountered at some stage of channel execution. Usually this indicates a programming problem and should be reported to iWay Customer Service.
retry	7.0	No	An error was encountered, but it was handled directly by the channel. The channel elected to set itself into a retry state, meaning that it will be restarted by iSM following a configured wait time.
init	6.1.8	No	The channel could not be initialized. Usually this means the resources needed could not be located.
start	6.1.8	No	The channel could not be started. Usually this phase attempts to actually access resources.

The process flow can return instructions to iSM to control special handling. This is accomplished by ending the process flow on an End node of one of the names that is listed and described in the following table.

End Node Name	Applies To Attribute	Description
config	unexpected, retry, start, and init	Leave the channel in a configuration error state. Retry will not be attempted, and a manual start is not accepted.
stop	unexpected, retry, start, and init	Place the channel in a stopped state. A start command is required to restart the channel.
retry	unexpected and retry	Place the channel into a retry state. This is the default action for a retry or startup event.

Information in the channelfail document is listed and described in the following table.

Parameter	Description
name	The name of the configured channel to which this flow applies.
statename	The current state of the channel, which can be set by the process flow. config. Cannot start due to a configuration error. The channel start will not be retried. retry. The channel will attempt to restart after a configured retry interval. stopped. The channel is not running and can only be restarted by a specific (manual or programmed message) command.
state	The internal code that refers to the channel state. The statename usually explains this, and the code is provided to assist in issue isolation.
protocol	The protocol of the channel (for example, File and MQ.)
failures	Applies only to init and start entry. This is the number of sequential failures encountered during the channel startup cycle.
version	The version of the ism server, and thus this document.
time	The time that the document was created.
statistics	For runtime retry, this is the number of messages processed.

In the following simplified example, a failure results in an email being sent to an identified party followed by a check to see if the number of sequential failures exceeds a designated limit (in this example, 3).

Normally this process flow would run during iSM startup or channel restart. To have the process flow run if the start is attempted from an iSM start command whether standalone or in a script, use the -doflow switch on the start command. For more information on using the start command, see the iWay Service Manager Command Reference Guide.

x

Messages can be queued for retry on channels that support this facility. This includes queue-based channels, the File channel, and the Internal Queue channel. The retries are triggered by logic in the process flow. In this circumstance, the message is re-executed on a periodic basis until expiration has been reached.

At the expiration point, a process flow can be executed to take recovery actions including notification, and optionally, changing the destination address or restarting with a changed (extended) expiration time.

Enter the name of a published process flow to be executed in the Expired Retry Flow field, as shown in the following image. This field is a common channel property that is available for all iSM listeners.

On entry, the process flow receives the document as it exists, at the point at which the process flow is called. The following table lists and describes several special registers that are available in the Retry Expired process flow to assist during the analysis.

Register Name	Description
iway.eventflow.exitflow	Identifies the purpose of the process flow (for example, expiredRetry).
iway.eventflow.attempts	Count of the number of retry attempts made before the expiration.
iway.eventflow.expiredtime	Time of the expiration.

The following table lists and describes the possible edges that are returned by the Retry Expired process flow.

Edge	Description
success	The process flow overrules the expiration. iSM will attempt to resend, this time with the output of the process flow.
<other> or flow fails	An error document is sent to the error addresses.

x

A reply designation associated with a document triggers an emit operation following completion of the process flow. If the emit operation is not successful, the Failed ReplyTo process flow is triggered.

Enter the name of a published process flow to be executed in the Failed ReplyTo Flow field, as shown in the following image. This field is a common channel property that is available for all iSM listeners.

On entry, the process flow receives the document as it exists, at the point at which the process flow is called. The following table lists and describes several special registers that are available in the Failed ReplyTo process flow to assist during the analysis.

Register Name	Description
iway.eventflow.exitflow	Identifies the purpose of the process flow (for example, failedReply).
iway.eventflow.replyname	Configured name of the reply or error specification.
iway.eventflow.destination	The address configured for the emit, as evaluated for use.
iway.eventflow.errormsg	An error message, if any, describing the cause of the failure that caused this event to be generated.
iway.eventflow.replyprotocol	Protocol used for the emit attempt (for example, File, MQ, and so on).

The following table lists and describes the possible edges that are returned by the Failed ReplyTo process flow.

Edge	Description
success	The process flow took responsibility to deliver the message.
<other> or flow fails	An error document is sent to the error addresses.

Each ReplyTo and ErrorTo is treated separately. If an error occurs for one, an attempt is made to handle the error, and iSM continues with the rest of the list. Error handling, however, differs for ReplyTo versus ErrorTo.

A failed ReplyTo causes the Failed ReplyTo process flow to execute (if present). If the process flow is successful (by terminating at an End node called success), the error is considered to be handled and iSM continues through the rest of the address list. If the process flow is absent, fails, or reaches an End node with a different name, then iSM creates an error document and attempts to send it to the ErrorTo instances recursively. All ErrorTo instances will be called for each ReplyTo that fails.

Document siblings are treated as independent documents. The net effect should be similar to sending the document first, and then each of its siblings one by one. iSM does not expect error documents to contain siblings. However, if present, they too will be sent as top-level documents (which may or may not be in error).

x

Messages queued for emitting at a later time, using the ReplyTo and ErrorTo channel configurations, or the Emit object in a process flow, are sent when the outlet of the channel is executed. Messages can also have alternate addresses if required.

If all attempts to emit the message fail, then by default, the message is written to a configured dead letter directory.

If an emit failed process flow is configured, then the process flow can examine the message, redirect it, replace it, and potentially notify an appropriate authority. It can then send the message to another channel for a retry attempt or continue to allow the message to be written to the dead letter queue.

Enter the name of a published process flow to be executed in the Dead Letter Flow field, as shown in the following image. This field is a common channel property that is available for all iSM listeners.

On entry, the Send to Dead Letter process flow receives the document as it exists at the point at which the process flow is called. The following table lists and describes several Special Registers (SREGs) that are available in the process flow to assist during the analysis.

Register Name	Description
iway.eventflow.exitflow	Identifies the purpose of the process flow (for example, deadLetter).
iway.eventflow.replyname	Configured name of the reply or error specification.
iway.eventflow.destination	The address configured for the emit, as evaluated for use.
iway.eventflow.errormsg	An error message, if any, describing the cause of the failure that caused this event to be raised.
iway.eventflow.replyprotocol	Protocol used for the emit attempt (for example, File, MQ, and so on).

The following table lists and describes the possible edges that are returned by the Send to Dead Letter process flow.

Edge	Description
success	The message was successfully handled.
<other> or flow fails	The output of the process flow to be written to the dead letter directory, if configured.

Each ReplyTo and ErrorTo is treated separately. If an error occurs for one, an attempt is made to handle the error, and iSM continues with the rest of the list. Error handling, however, differs for ReplyTo versus ErrorTo.

A failed ReplyTo causes the Failed ReplyTo process flow to execute (if present). If the process flow is successful (by terminating at an End node called success), the error is considered to be handled and iSM continues through the rest of the address list. If the process flow is absent, fails, or reaches an End node with a different name, then iSM creates an error document and attempts to send it to the ErrorTo instances recursively. All ErrorTo instances will be called for each ReplyTo that fails. ErrorTo instances are used to communicate errors to administrators who are able to resolve such situations.

A failed ErrorTo causes the Send to Dead Letter process flow to execute (if present). If the process flow returns success, iSM considers the error to be handled and continues with the rest of the address list. If the process flow is absent, fails, or reaches an End node with a different name, then iSM attempts to write a file under the configured dead letter directory.

Sending an error to an empty list of ErrorTo instances is an error. It is handled the same way as a failed ErrorTo.

Notice that only error documents are sent to the configured dead letter directory. If an error cannot be reported (because an ErrorTo fails or there are no ErrorTo instances), then iSM attempts to send the error document to the dead letter directory to keep a record for manual processing. An error document contains a copy of the original document that generated the error.

iSM attempts to avoid sending to a duplicate address within the list if iSM already knows it is a bad address. This could happen when an ErrorTo is also a ReplyTo. A duplicate bad address is treated the same as a regular failed ReplyTo or ErrorTo, except the IO was never attempted.

Document siblings are treated as independent documents. The net effect should be similar to sending the document first, and then each of its siblings one by one. iSM does not expect error documents to contain siblings. However, if present, they too will be sent as top-level documents (which may or may not be in error).

x

The Parse Failure flow is invoked if an incoming message fails the parse to XML operation for a channel. This does not apply to a parse that is handled within a process flow by a service (agent) for that purpose.

The incoming document to the flow contains the message that failed parsing. The standard Special Registers (SREGs) for the protocol are available in the flow. For example, a bad message on a File listener will provide the usual information on the source of the file.

The Parse Failure flow can also be used to send a notification.

The flow can replace the document that could not be parsed. This might be done to fill in an element in a large batch managed by a splitting preparser. To replace the message, set the document on output to the message required, and return through an End node named Replace. The replaced message will then pass through the normal channel cycle. It may be necessary in your application to set a SREG in order to notify subsequent processes that this is a placeholder message. If this technique is used, then remember to set the SREG at the channel level, so as to make it available beyond the scope of the flow.

On entry to the event flow, the SREG iway.parsefail will be set to the count of the number of parse failures in this channel for this transaction. This count is useful for batch handling, in which a splitting preparser divides the batch into a sequence of sub-messages. For example, your flow might determine that the count of placeholder messages returned to the channel has exceeded a threshold, and so elects to take application action to reject the batch.