Command Line Adapter

How the Command Line Adapter Works

Use the Command Line adapter in a business process to run any program from the command line, including executable programs, scripts, or OS commands external to Sterling B2B Integrator. The types of activities that can be performed include data encryption and decryption, file manipulation, data manipulation, and initiation of a process on a remote system.

You can create multiple Command Line adapter configurations, one for each of several specific commands. Alternatively, you can use a single Command Line adapter configuration to perform different commands by specifying the command line process (cmdLine) and working directory (workingDir) in the business process. See Command Line for details on these parameters.

For example, your company communicates with a legacy database that is important to its daily business. You want to retrieve some customer billing information in the database and send it within a business process in Sterling B2B Integrator to your accounting department. You can write your own executable program to communicate with your legacy system and run it using the Command Line adapter.

Implementing the Command Line Adapter

The information in this section applies to both of the above implementations.

Before You Begin

Process Overview

Configuring the Command Line Adapter

To create a Command Line adapter configuration, you must specify field settings in Sterling B2B Integrator and in the GPM. For general information about service and adapter configurations, see Managing Services and Adapters.

Sterling B2B Integrator Configuration

The following table describes the fields used to configure the Command Line adapter in Sterling B2B Integrator.

Field	Description
Name	Unique and meaningful name for the adapter configuration. Required.
Description	Meaningful description for the adapter configuration, for reference purposes. Required.
Select a Group	Select a Service Group to associate with this adapter. Valid values: None – You do not want to include this configuration in a group at this time. Default. Create New Group – You can enter a name for a new group in this field, which is then created along with this configuration. Select Group – If you have already created one or more groups for this service type, they are displayed in the list. Select a group from the list. Note: A Service Group is a group of services or adapters of the same type that can act as peers. A Service Group name is used in BPML in place of the Service Configuration name. Service Groups show up in the GPM as if they were Service Configurations. For more information about Service Groups, see Managing Services and Adapters.
Remote Name (remoteName)	Remote host name or IP address where the remote adapter implementation is running. Required. Default value is localhost. If you have an instance of the Command Line adapter that uses the rmiAddr parameter, this parameter must be updated with the name of the machine where CLA2Client.jar is running.
Remote Port (remotePort)	Remote port that the remote adapter implementation is listening on. Required. Default value: Port on which the CLA2Client.jar was autostarted, normally basePort+52. If you have an instance of the Command Line adapter that uses the rmiAddr parameter, this parameter must be updated with the port number where CLA2Client.jar is running.
Command Line (cmdLine)	Command line process you want to run. Do one of the following: If you want to set this parameter in the GPM/business process, leave the field blank. Type the command line process in this field exactly as you would from the command line. If you want to use a command that redirects input or output (through the use of >, <, or |), you must do so using a script file. If you do not know the input or output file name, type the following parameters in the command line process as placeholders: • $Input • $Output These parameters are typed directly in the command line process. You can use these parameters on the command line in any order and multiple times if necessary. At run time, they are replaced with the actual file name. If you want to enter user parameters, use the following placeholders: $0 – $9. These placeholders are resolved by the parm0 – parm9 parameters defined in the GPM or using BPML. Note: If $Input or $Output resolves to a filename that contains one or more spaces, automatic quoting will be performed before the command line is executed. For example, If the original command line was test.sh $Input, and $Input resolves to file 1, then the final command line, before execution, will be test.sh “file 1”. Therefore, do not put quotes around $Input or $Output. Note: An example of a command line entry is test.sh $Input $Output $0 $1 $2 $3 $4 $5 $6 $7 $8 $9. This runs the shell script test.sh taking an input file, using ten parameters, and producing an output file. Note: If your input is a string (not a file), for example if you are using the DOS Find operation, you must put quotes around it. This actually results in double quotes when the command resolves.
Working Directory (workingDir)	Location of the directory to use for executing the command line process. Optional. Default is the current working directory of the JVM running CLA2Client.jar. CAUTION: Using this adapter to call a Unix script modifies the directory path of the environment variable LD_LIBRARY_PATH. To keep your current path, your script should include either the LD_LIBRARY_PATH path or a reference to your .profile (which includes the LD_LIBRARY_PATH path). Note: The CLAClient.jar is no longer used.
Turn on debugging messages? (cla2_debug)	Turn on debugging for this adapter instance? Valid values: Yes (true) – Logging is turned on and the messages are written to the system log. No (false) – Default. Note: This turns on debugging for this specific adapter instance. These messages are logged in the system log in the install_dir/logs directory. This parameter is read-only in the GPM.
Wait on the process to complete before continuing? (waitOnProcess)	Wait on the process to complete before continuing the business process. Valid values: Yes (true) – If the value is Yes, a status report is created if any stdout/stderr is generated by the process. If an error occurs while the service is processing output data, the advanced status contains the error message instead of the return code value. No (false) Note: If Use the output generated by the command line process is set to Yes, the value of this parameter is assumed to be Yes because the service cannot use output if it does not wait for the process to complete. This parameter is read-only in the GPM.
Does this service start a business process? (bootstrap)	Whether the service starts a business process. Required. Valid values: Yes (true) No (false) Note: This parameter is read-only in the GPM.
Business process (initialWorkFlowName)	Business process you want the Command Line adapter to start. This field is required only if you selected Yes in Does this service start a business process? . If you prefer to configure this parameter in the GPM, select Not Applicable.
Document Storage Type (docStorageType)	Defines how the document is stored in the system. Required when the adapter starts a business process. Valid values: System Default – Default Database File System Note: For more information on document storage types, see Managing Services and Adapters.
Run as User	Applies to the scheduling of the business process. The Run As User field only displays as an option if Does this service start a business process? is set to Yes. Type the user ID to associate with the schedule, or click the icon and select a user ID from the list. Valid value is any valid Sterling B2B Integrator user ID. Note: This parameter allows someone who doesn't have rights to a specific business process to run it. If you select Admin as the user ID, you will inherit Administrative rights (for this run of the business process only), and enable the scheduled run.
Use 24 Hour Clock Display	If selected, the adapter will use the 24-hour clock instead of the default 12-hour clock.
Schedule	Information about scheduling the business process invoked by the Command Line adapter. The Schedule field only displays as an option if Does this service start a business process? is set to Yes. Valid values: Do not use schedule If this field is selected, the adapter does not start a business process and does not run on a schedule. Run based on timer Valid values are the hour and minutes at which to run the adapter. If you choose to select a time interval, the valid values are the hours and minutes for the intervals. Add or delete selections as necessary. Specify any schedule exclusions or date exclusions. Indicate whether you want the adapter to run at startup. Run daily Valid values are the hour and minutes at which to run the adapter, daily. If you choose to select a time interval, the valid values are the hour and minute for the interval. Add or delete selections as necessary. Specify any date exclusions. Indicate whether you want the adapter to run at startup. Run based on day(s) of the week Valid values are the day of the week, the hour, and the minute that specify when to run the adapter. If you choose to select a time interval, the valid values are the hours and minutes for the intervals. Add or delete selections as necessary. Specify any date exclusions. Run based on day(s) of the month Valid values are the day of the month, hour, and minute that specify when to run the adapter. If you choose to select a time interval, the valid values are the hours and minutes for the intervals. Add or delete selections as necessary. Specify any date exclusions.
Does the command line process require an input file? (useInput)	Defines whether the command line process requires an input file? Required. Valid values: Yes (true) – The primary document of the current business process context is written out to the file system in the working directory and is used as input to the process. Default. No (false) – No file is written to disk even if a document exists in the business process context. Note: This parameter is read-only in the GPM.
Input File Name (inputName)	Input file name, if the command line process requires an input file. Any occurrences of $Input in the command line are replaced with this name. Optional. If you leave this field blank, the default is the primary document name. Note: It is important to have a unique input file name for all concurrently running instances of Command Line adapters. If more than one instance of the Command Line adapter can be executing at the same time, you must create a dynamic, unique name to keep the instances from overwriting each other and causing the process to fail. This can be done by concatenating the current process ID on to a file's base name. This dynamic name may also need to be passed to the cmdLine.
Delete input file after process completes? (inputDelete)	Defines whether the input file is deleted after the process completes? Valid values: Yes (true) – Default No (false) Note: To delete the input file, Wait on the process to complete before continuing? must also be Yes. This parameter is read-only in the GPM.
Use the output generated by the command line process? (useOutput)	Use output generated by the command line process? Required. Valid values: Yes (true) – The adapter will attempt to read the output of the process. If bootstrapping a workflow, the file will become the primary document in the new workflow. If not bootstrapping, the file will become the primary document of the current workflow. Default . No (false) – No file is read into the business process context even if one is generated by the command line process. Note: This parameter is read-only in the GPM.
Output File Name (outputName)	Output file name, if you want to use the output generated by the command line process. Any occurrences of $Output in the command line are replaced with this name. Optional. If you leave this field blank, the default is the business process primary document name. Note: It is important to have a unique output file name for all concurrently running instances of command line adapters. If more than one instance of the Command Line adapter can be executing at the same time, you must create a dynamic unique name to keep the instances from overwriting each other and causing the process to fail. This can be done by concatenating the current process ID on to a file's base name. This dynamic name may also need to be passed to the cmdLine.
Delete output file after process completes? (outputDelete)	Specifies whether the output file is deleted after it is collected?Valid values: Yes (true) – Default No (false) Note: This parameter is read-only in the GPM.

GPM Configuration

The following screen shows a graphical view of some GPM parameters for the Command Line adapter. The dimmed values were specified using the Command Line adapter configuration. The active fields are env0 and env1, which cannot be configured in the service configuration.

The following example shows the corresponding business process solution using BPML.

<process name="Example_CommandLineBP">
  <operation name="Command LineAdapter Run Script">
    <participant name="Sample_CommandLine_Adapter"/>
    <output message="CmdLineInputMessage">
    <assign to="."> from="*"/>
    <assign to="parm0">VAR1</assign>
      <assign to="parm1">USER</assign>
      <assign to="parm2">10</assign>
    <assign to="env0">VAR1=TEST</assign>
      <assign to="env1">USER=ME</assign>
    </output>
    <input message="inmsg">
      <assign to="." from="*"></assign>
    </input>
  </operation> 
</process>

The following table describes the fields used to configure the Command Line adapter in the GPM. This table contains the fields that are only configured in the GPM. Other fields may also be configured if they were left blank in the Sterling B2B Integrator configuration.

Output from Adapter to Business Process

The following table contains the parameters passed from the Command Line adapter to the business process:

Usage Examples

This section contains an example using the Command Line adapter. Examples are included using both the GPM and BPML.

Invoking the Command Line Adapter to Run a Shell Script

GPM Example

The following example illustrates the above business process using the GPM.

Business Process Modeling Language (BPML) Example

The following example illustrates the same business process using BPML.

<process name="Example_CommandLine_BP">
  <operation name="Command Line Adapter Run Script">
    <participant name="Sample_CommandLine_Adapter"/>
    <output message="CmdLineInputMessage">
    <assign to="."> from="*"/>
    <assign to="parm0">VAR1</assign>
      <assign to="parm1">USER</assign>
      <assign to="parm2">10</assign>
    <assign to="env0">VAR1=TEST</assign>
      <assign to="env1">USER=ME</assign>
    </output>
    <input message="inmsg">
      <assign to="." from="*"></assign>
    </input>
  </operation> 
</process>

Invoking the Command Line Adapter

Adapter startup at the time of Sterling B2B Integrator startup is driven by (Windows) startWindowsService.cmd or (UNIX) the run.sh script.

Stopping the Command Line Adapter

If Sterling B2B Integrator is shut down with (Windows) stopWindowsService.cmd or (UNIX) hardstop.sh script, the Command Line adapter also shuts down.

Otherwise, once started, the adapter runs silently as configured and will not return to the command line until it is finished, interrupted, or fails. Therefore, you cannot use that command line to execute any other commands.