Run OS Shell Command Service (com.ibi.agents.XDRunCmdAgent)

Syntax:

com.ibi.agents.XDRunCmdAgent

iIT Service Object:

operations: Runs a system (OS Shell) command if possible.

Description:

This service runs a system command.

Parameters:

Parameter	Description
Command*	The system command to execute. On Windows platforms, it is common to prepend cmd /C before the command.
Encoding*	The Internet Assigned Numbers Authority (IANA) character set used to decode the command result. You can select a value from the drop-down list or type an encoding name directly in the field.
CData*	Set this parameter to true if the command results are expected to be in CDATA format.
Timeout	The amount of time (in seconds) to wait before the command times out. Enter 0 to set no timeout limit.
Detach	If set to true, the command is executed in a separate thread, while the current process flow continues to execute. Since a success notification is not returned to the process flow, enabling this parameter is not recommended. As an alternative, it is recommended to use the native background processing of the operating system when possible.
Call at EOS	In a streaming environment, a short message is delivered after the last document in the stream is sent to signify the End of Stream (EOS). The Call at EOS parameter determines whether the service should be called for the EOS message. By default, this parameter is set to false.

The Timeout and Detach parameters have entirely different and somewhat mutually exclusive functions.

If defined, the Timeout parameter halts the current thread for the specified amount of time while a command is being executed or until a command result is returned. If a specified timeout value is reached and a command is still being processed, then the process flow returns the fail_timeout edge.

If the Detach parameter is set to true, then any timeout value becomes irrelevant because the command is executed in parallel by a separate thread. As a result, the process flow does not wait for command results from that thread in order to continue. The process flow resumes its execution without delay.

Edges:

The following table lists the available line edges for the Run OS Shell Command Service (com.ibi.agents.XDRunCmdAgent).

Line Edge	Description
OnError	Error
OnSuccess	Success
OnFailure	Failure
OnCustom	OnError OnSuccess OnFailure fail_parse fail_operation fail_timeout

Example #1

The following image shows a configured value for the Command parameter in the iWay Service Manager Administration Console.

cmd /C C:\CoreFTP\coreftp.exe -s -O -site ATST1 -u c:\file\ftpin\*.*

In this example, the Run OS Shell Command service runs a command prompt command to invoke a third-party FTP program (CoreFTP) to perform a required file transfer. Similarly, you can also use this service to run the supported commands in your shell environment as needed by referring to third-party tools.

Example #2

In this example, a UNIX Perl script that takes a substantial amount of time to run must be executed by a customer. In addition, a process flow must be processed immediately, without waiting for the execution of the UNIX Perl script to be completed.

To satisfy this requirement, a Service object for the Run OS Shell Command service (XDRunCmdAgent) can be configured in a process flow where the Detach parameter is set to true, as shown in the following image.

This configuration allows the UNIX Perl script to be executed by a separate thread, while the process flow continues to run without any interruption.

Available Response Failure Edges for the Run OS Shell Command Service (XDRunCmdAgent)

During the configuration of a process flow, when you connect a Service object for the Run OS Shell Command service (XDRunCmdAgent) to an End object using the OnCustom build relation, the available line edges are provided (including response failure edges). For example: