webMethods Flow Steps

BRANCH

The BRANCH step selects and executes a child step based on the value of one or more variables in the pipeline. You indicate the variables you want to branch on by specifying a switch value or by writing an expression that includes the variables.

Branching on a Switch Value

When you branch on a switch value, you specify the switch variable in the Switch property of the BRANCH step. In the Label property for each child step, you specify the value of the switch variable that will cause that child step to execute. At run time, the BRANCH flow step executes the child step that has the same label as the value of the Switch property.

If you want to execute a child step when the value of the Switch property is an empty string, leave the Label property of the child step blank. If you want to execute a child step when the Switch property is a null or unmatched string, set the Label of the child step to $null or $default.

Figure 1. BRANCH flow step using a switch

Branching on Expressions

When you branch on expressions, you set the Evaluate labels property of the BRANCH step to true. In the Label property for each child step, you write an expression that includes one or more variables. At run time, the BRANCH step executes the first child step with an expression that evaluates to true.

If you want to specify a child step to execute when none of the expressions are true, set the label of the child step to $default.

BRANCH Properties

The BRANCH step has the following properties.

Property	Description
Comments	Optional. Specifies a descriptive comment for the step.
Scope	Optional. Specifies the name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	Optional. (Required if you are using this BRANCH step as a target for another BRANCH or EXIT step.) Specifies a name for this instance of the BRANCH step, or a null, unmatched, or empty string ($null, $default, blank).
Switch	Specifies the String field that the BRANCH step uses to determine which child flow step to execute. The BRANCH step executes the child flow step whose label matches the value of the field specified in the Switch property. Do not specify a value if you set the Evaluate labels property to True.
Evaluate labels	Specifies whether or not you want the server to evaluate labels of child steps as conditional expressions. When you branch on expressions, you enter expressions in the Label property for the children of the BRANCH step. At run time, the server executes the first child step whose label evaluates to True. To branch on expressions, select True. To branch on the Switch value, select False.

Conditions that Will Cause a BRANCH Step to Fail

The switch field is not in the pipeline and the BRANCH step does not contain a default child step or a child step to handle null values.
The matching child step fails.
The BRANCH step does not complete before the time-out period expires.

CATCH

The CATCH step contains the sequence of steps that you want executed in the event the preceding TRY step fails. Often, the CATCH step contains recovery logic. The CATCH step must be used in conjunction with the TRY step.

The TRY, CATCH, and FINALLY steps are the webMethods flow language facility for handling failures in flow services

CATCH Properties

The CATCH step has the properties described in the following table.

Property	Description
Comments	An optional descriptive comment for this step.
Scope	The name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	An optional name for this specific step, or a null, unmatched, or empty string ($null, $default, blank). Important: If you use this step as a target for an EXIT step that exits from a specific label, you must specify a value in the Label property. CATCH steps may only be targets of an EXIT step that signals success. For more information about the EXIT step, see The EXIT Step.
Exit on	This property is always set to FAILURE for a CATCH step.
Failures	Specifies the list of failures that the CATCH step either specifically handles or does not handle. When Selection is set to INCLUDE, the Failures property lists the failures the CATCH step handles. When Selection is set to EXCLUDE, the Failures property lists the failures the CATCH step does not handle. Leave the Failures property empty if you want the CATCH step to catch the last failure thrown regardless of what it is.
Selection	Specifies whether the CATCH step handles failure included in the Failures list or only failures that are not in the Failures list.
	Specify	To
	INCLUDE	Catch any of the failures specified in the Failures property.
	EXCLUDE	Catch any failures except those specified in the Failures property.

EXIT

The EXIT step exits the entire flow service, a single flow step, or an iteration of LOOP or REPEAT. Specifically, it may exit from the nearest ancestor LOOP or REPEAT step, an iteration of the nearest ancestor LOOOP or REPEAT step, a specified ancestor step, the parent step, or the entire flow service.

The EXIT step can throw an exception if the exit is considered a failure. When an exception is thrown, user-specified error message text is displayed by typing it directly or by assigning it to a variable in the pipeline.

EXIT Properties

The EXIT step has the following properties.

Property	Description
Comments	Optional. Specifies a descriptive comment for the step.
Label	Optional. (Required if you are using this EXIT step as a target for a BRANCH step.) Specifies a name for this specific step, or a null, unmatched, or empty string ($null, $default, blank).
Exit from	Required. Specifies the flow step or service from which you want to exit.
	Specify this value…	To exit the…
	$parent	Parent flow step, regardless of the type of step. This is the default.
	$loop	Nearest parent LOOP or REPEAT step.
	$flow	Entire flow.
	$iteration	An iteration of the nearest ancestor LOOP or REPEAT flow step.
	`label`	Nearest ancestor step that has a label that matches this value. Note: If the label you specify does not match the label of an ancestor flow step, the flow will exit with an exception.
	<blank>	Nearest ancestor LOOP or REPEAT flow step. This is the same as specifying a value of $loop.
Signal	Required. Specifies whether the exit is considered a success or a failure. A SUCCESS condition exits the flow service or step. A FAILURE condition exits the flow service or step and throws an exception. The text of the exception message is contained in the Failure message property.
Failure name	The fully qualified Java Class name of the Pending Exception that will be created for this Failure. For example: java.lang.Exception com.wm.app.b2b.server.ServiceException com.wm.lang.flow.FlowException com.costomerCo.CustomException Valid class names must be available to the current class loader and must extend java.lang.Exception. If the class name is not valid, Integration Server throws the default Exception with the following message appended to the Failure message value: -- class for specified failure not found or invalid The default value depends on the Exit from value. If Exit from is set to $flow, then the default is com.wm.lang.flow.FlowException. For all other Exit from values, the default is com.wm.lang.FlowFailure. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols (for example, `%failure%`). The variable you specify must be a String. When you want the EXIT step to throw an exception, you specify a value for either Failure name or Failure instance properties. If you specify both, Integration Server uses the Failure instance value. This property is used only when Signal is set to FAILURE.
Failure instance	The name of the pipeline variable that contains an existing Exception instance that you want the EXIT step to identify as the failure. This instance is most likely the `failure` output parameter of the pub.flow:getLastFailureCaught service. The specified pipeline variable must be of type Object. The object variable in the pipeline must extend java.lang.Exception. If it does not, Integration Server throws a FlowException. If you specify a pipeline variable that exists but does not contain an exception at run time or if you specify a variable that does not exist, Integration Server throws a FlowException and exits the flow service. This property is used only when Signal is set to FAILURE.
Failure message	Optional. Specifies the text of the exception message that is displayed when Signal is set to FAILURE. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%mymessage%`. The variable you specify must be a String. This property is used only when Signal is set to FAILURE.

Examples of When to Use an EXIT Step

Exit an entire flow service from within a series of deeply nested steps.
Throwing an exception when you exit a flow or a flow step without having to write a Java service that throws a ServiceException.
Exit a LOOP or REPEAT flow step without throwing an exception.
Completing a flow step abruptly.
Exiting an iteration of a LOOP or REPEAT flow step without exiting the entire LOOP or REPEAT step.

FINALLY

The FINALLY step contains logic that Integration Server executes regardless of whether the TRY step succeeds or fails. Often, the FINALY step contains clean up logic that needs to execute regardless of the outcome of the preceding TRY or CATCH steps, such as releasing resources or closing sockets. The FINALLY step must be used in conjunction with the TRY step and may be used with the CATCH step.

The TRY, CATCH, and FINALLY steps are the webMethods flow language facility for handling failures in flow services

FINALLY Properties

The FINALLY step has the properties described in the following table.

Property	Description
Comments	An optional descriptive comment for this step.
Scope	The name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	An optional name for this specific step, or a null, unmatched, or empty string ($null, $default, blank). Important: If you use this step as a target for an EXIT step that exits from a specific label, you must specify a value in the Label property. FINALLY steps may only be targets of an EXIT step that signals success. For more information about the EXIT step, see The EXIT Step.
Exit on	This property is always set to FAILURE for a FINALLY step.

INVOKE

The INVOKE flow step invokes another service. You can use it to invoke any type of service, including another flow service.

INVOKE Properties

The INVOKE step has the following properties.

Property	Description
Comments	Optional. Specifies a descriptive comment for the step.
Label	Optional. Specifies the name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Service	Required. Specifies the fully qualified name of the service to invoke.
Validate input	Optional. Specifies whether the server validates the input to the service against the service input signature. If you want the input to be validated, select True. If you do not want the input to be validated, select False.
Validate output	Optional. Specifies whether the server validates the output of the service against the service output signature. If you want the output to be validated, select True. If you do not want the output to be validated, select False.

Conditions that Will Cause an INVOKE Step to Fail

The service that is invoked fails.
The specified service does not exist.
The specified service is disabled.

LOOP

The LOOP step takes as input an array variable that is in the pipeline. It loops over the members of an input array, executing its child steps each time through the loop. For example, if you have a service that takes a string as input and a string list in the pipeline, use the LOOP step to invoke the service one time for each string in the string list.

You identify a single array variable to use as input when you set the properties for the LOOP step. You can also designate a single variable for output. The LOOP step collects an output value each time it runs through the loop and creates an output array that contains the collected output values. If you want to collect more than one variable, specify a document that contains the fields you want to collect for the output variable.

LOOP Properties

The LOOP step has the following properties.

Property	Description
Comments	Optional. Specifies a descriptive comment for the step.
Scope	Optional. Specifies the name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	Optional. (Required if you are using this step as a target for a BRANCH or EXIT step.) Specifies a name for this specific step, or a null, unmatched, or empty string ($null, $default, blank).
Input array	Required. Specifies the input array over which to loop. You must specify a variable in the pipeline that is an array data type (that is, String list, String table, document list, or Object list).
Output array	Optional. Specifies the name of the field in which the server places output data for an iteration of the loop. The server collects the output from the iterations into an array field with the same name. You do not need to specify this property if the loop does not produce output values.

Conditions that Will Cause a LOOP Step to Fail

The pipeline does not contain the input array.
The input field is not an array field.
A child step of the LOOP step fails during any iteration of the loop.
The LOOP step does not complete before the time-out period expires.

MAP

The MAP step adjusts the pipeline at any point in a flow. It makes pipeline modifications that are independent of an INVOKE step.

Within the MAP step, you can:

Link (copy) the value of a pipeline input field to a new or existing pipeline output field.
Drop an existing pipeline input field. (Keep in mind that once you drop a field from the pipeline, it is no longer available to subsequent services in the flow.)
Assign a value to a pipeline output field.
Perform document-to-document mapping in a single view by inserting transformers.

MAP Properties

The MAP step has the following properties.

Property	Description
Comments	Optional. Specifies a descriptive comment for this step.
Scope	Optional. Specifies the name of a document (IData) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	Optional. (Required if you are using this step as a target for a BRANCH or EXIT step.) Specifies a name for this specific step, or a null, unmatched, or empty string ($null, $default, blank).

Example of When to Use a MAP Step

You want to assign an initial set of input values in a flow service (that is, to initialize variables). You insert the MAP step at the beginning of the flow, and then use the Set Value modifier to assign values to the appropriate variables in Pipeline Out.
You want to map a document from one format to another (for example, cXML to XML). Insert transformers into the MAP step to perform the needed data transformations.

REPEAT

The REPEAT step repeatedly executes its child steps up to a maximum number of times that you specify. It determines whether to re-execute the child steps based on a Repeat on condition. You can set the repeat condition to one of the following:

Repeat if any one of the child steps fails.
Repeat if all of the elements succeed.

You can also specify a time period that you want the REPEAT flow step to wait before it re-executes its child steps.

REPEAT Properties

The REPEAT step has the following properties.

Property	Description
Comments	Optional. Specifies a descriptive comment for this step.
Scope	Optional. Specifies the name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	Optional. (Required if you are using this step as a target for a BRANCH or EXIT step.) Specifies a name for this specific step, or a null, unmatched, or empty string ($null, $default, blank).
Count	Required. Specifies the maximum number of times the server re-executes the child steps in the REPEAT step. Set Count to `0` (zero) to instruct the server that the child steps should not be re-executed. Set Count to a value greater than zero to instruct the server to re-execute the child steps up to a specified number of times. Set Count to `-1` to instruct the server to re-execute the child steps as long as the specified Repeat on condition is true. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%servicecount%`. The variable you specify must be a String.
Repeat interval	Optional. Specifies the number of seconds the server waits before re-executing the child steps. Specify `0` (zero) to re-execute the child steps without a delay. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%waittime%`. The variable you specify must be a String.
Repeat on	Required. Specifies when the server re-executes the REPEAT child steps. Select SUCCESS to re-execute the child steps when the all the child steps complete successfully. Select FAILURE to re-execute the child steps when any one of the child steps fails.

When Does REPEAT Fail?

The following conditions cause the REPEAT step to fail:

If “Repeat on” is set to…	The REPEAT step fails if…
SUCCESS	A child within the REPEAT block fails.
FAILURE	The Count limit is reached before its children execute successfully.

If the REPEAT step is a child of another step, the failure is propagated to its parent.

Examples of When to Use a REPEAT Step

“Repeat on” property is set to FAILURE. Use when a service accesses a remote server and you want the service to retry if the server is busy. Make the service that accesses the remote server a child element of a REPEAT flow step, and then set the Repeat on property to FAILURE. If the service attempts to access the website and it fails, the REPEAT flow step attempts to retry the service again. You also set a Repeat interval that causes the REPEAT flow condition to wait a period of time before invoking the service again.
“Repeat on” property is set to SUCCESS. Use in a web-automation service when you want to repeat a load and query step and a “Next Page” button exists in the current document, indicating that there are additional pages to be processed. End the REPEAT flow step when the query step fails to retrieve a “Next Page” button in the current document.

SEQUENCE

The SEQUENCE step forms a collection of child steps that execute sequentially. This is useful when you want to group a set of steps as a target for a BRANCH step.

You can set an exit condition that indicates whether the SEQUENCE should exit prematurely and, if so, under what condition. Specify one of the following exit conditions:

Exit the SEQUENCE when a child step fails.Use this condition when you want to ensure that all child steps are completed successfully. If any child step fails, the SEQUENCE ends prematurely and the sequence fails.
Exit the SEQUENCE when a child step succeeds. Use this condition when you want to define a set of alternative services, so that if one fails, another is attempted. If a child step succeeds, the SEQUENCE ends prematurely and the sequence succeeds.
Exit the SEQUENCE after executing all child steps. Use this condition when you want to execute all of the child steps regardless of their outcome. The SEQUENCE does not end prematurely.

SEQUENCE Properties

The SEQUENCE step has the following properties.

Property	Description
Comments	Optional. Specifies a descriptive comment for this step.
Scope	Optional. Specifies the name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	Optional. (Required if you are using this step as a target for a BRANCH or EXIT step.) Specifies a name for this specific step, or a null, unmatched, or empty string ($null, $default, blank).
Exit on	Required. Specifies when to exit the SEQUENCE step.
	Specify this value…	To...
	FAILURE	Exit the SEQUENCE when a child step fails. Execution continues with the next flow step in the flow service. The SEQUENCE step executes its child steps until either one fails or until it executes all its child steps. This is the default.
	SUCCESS	Exit the SEQUENCE when a child step executes successfully or after all child steps fail. Execution continues with the next flow step in the flow service. The SEQUENCE step executes its child steps until either one succeeds or until it executes all its child steps and all of the child steps fail. Note: Successful execution of a MAP step within a SEQUENCE step, including successful execution of any transformers, does not cause the containing SEQUENCE to exit when Exit on is set to SUCCESS.
	DONE	Exit the sequence after all child steps execute. The SEQUENCE step executes all of its child steps regardless of whether they succeed or fail.
	Note: If a SEQUENCE step contains an EXIT step configured to exit from the SEQUENCE, execution of the EXIT step always results in exiting from the SEQUENCE step regardless of whether the SEQUENCE step is configure to exit on success, done, or failure. This occurs regardless of the position of the EXIT step within the SEQUENCE and regardless of whether the EXIT step is configured to signal success or failure.

Conditions that Will Cause the SEQUENCE Step to Fail

This section describes the conditions that cause failure based on the exit condition for the sequence.

If Exit on is set to FAILURE, conditions that will cause a failure include:

One of the child steps fails.
The SEQUENCE step does not complete before the time-out period expires.

If Exit on is set to SUCCESS, conditions that will cause a failure include:

All the child steps fail.
The SEQUENCE step does not complete before the time-out period expires.

If Exit on is set to DONE, conditions that will cause a failure include:

The SEQUENCE step does not complete before the time-out period expires.

TRY

The TRY step contains the sequence of flow steps that you want Integration Server to attempt and for which you want to provide failure handling.

The TRY, CATCH, and FINALLY steps are the webMethods flow language facility for handling failures in flow services

TRY Properties

The following table describes the properties for the TRY step.

Property	Description
Comments	An optional descriptive comment for this step.
Scope	The name of a document (IData object) in the pipeline to which you want to restrict this step. If you want this step to have access to the entire pipeline, leave this property blank.
Timeout	Optional. Specifies the maximum number of seconds that this step should run. If this time elapses before the step completes, Integration Server issues a FlowTimeoutException and execution continues with the next step in the service. If you want to use the value of a pipeline variable for this property, type the variable name between % symbols. For example, `%expiration%`. The variable you specify must be a String. If you do not need to specify a time-out period, leave Timeout blank. For more information about how Integration Server handles flow step timeouts, refer to the description of the watt.server.threadKill.timeout.enabled configuration parameter in webMethods Integration Server Administrator’s Guide .
Label	An optional name for this specific step, or a null, unmatched, or empty string ($null, $default, blank). Important: If you use this step as a target for an EXIT step that exits from a specific label, you must specify a value in the Label property. TRY steps may only be targets of an EXIT step that signals success. For more information about the EXIT step, see The EXIT Step.
Exit on	This property is always set to FAILURE for a TRY step.