Command Line Adapter 2 (V5.2.4.1 and interim fix 5.2.4.1_2 or later)

How the Command Line Adapter 2 Works

Use the Command Line Adapter 2 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 2 configurations, one for each of several specific commands. Alternatively, you can use a single Command Line Adapter 2 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 2.

Implementing the Command Line Adapter 2

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

Before You Begin

Process Overview

To implement the Command Line Adapter 2:

1. Create a Command Line Adapter 2 configuration. For information, see Managing Services and Adapters.
   Note: If you are configuring a Command Line Adapter 2 to start a business process, create the business process before you configure the adapter.
2. Configure the Command Line Adapter 2. For information, see Configuring the Command Line Adapter 2.
3. Create and enable a business process that includes the Command Line Adapter 2.
4. Test the business process and the adapter.
5. Run the business process.

Configuring the Command Line Adapter 2

To create a Command Line Adapter 2 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.

The Application Configuration

The following table describes the fields used to configure the Command Line Adapter 2 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. Note: For backward compatibility, the CLA2 supports the Command Line adapter parameter rmiAddr (at the business process level only).
Remote Port (remotePort)	Remote port is determined by the port configuration of the Command Line Adapter 2 server. Required. Default value: basePort+52.
Access Authentication?	Turn on authentication for this instance? Valid values: Yes (true) – Default No (false) The security default is 30 seconds (3000 milliseconds) and can be adjusted in the CmdLine2server.properties file. Restriction: The Command Line Adapter 2 server cannot have more than one private certificate in the JKS repository. For more information, see Maintaining authentication and SSL keys.
System Authentication Certificate	Select the authentication certificate that you want to run. Default value: cla2auth.
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.
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).
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. Note: For backward compatibility, the CLA2 supports the Command Line adapter parameter cmdl_debug (at the business process level only).
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 2 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. Note: For backward compatibility, the CLA2 supports the Command Line adapter parameter initialWorkFlowId (at the business process level only).
Create Unique working directory	Command Line Adapter 2 creates a unique working directory for each invocation of a business process using the same Command Line Adapter 2 instance. Selecting this option ensures that the adapter instances do not overwrite each other when multiple files with the same name exist.
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 2. 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 2 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 is collected and placed in ProcessData, not as the Primary Document. Default . For example, <assign name="Assign" to="PrimaryDocument" from="CLA2/document/@SCIObjectID"> </assign> 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 2 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.
Use SSL (Note: User Authentication without SSL will result in a weak security configuration.)	Use SSL to secure the Command Line Adapter 2? Valid values: Yes (true) No (false) – Default Restriction: The Command Line Adapter 2 server cannot have more than one private certificate in the JKS repository. For more information, see Maintaining authentication and SSL keys.
SSL Public CA Certificate	Select the SSL Public CA certificate for validation.

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_CommandLine2BP">
  <operation name="Command Line 2 Adapter Run Script">
    <participant name="Sample_CommandLine2_Adapter"/>
    <output message="CmdLine2InputMessage">
        <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 2 to the business process:

Usage Examples

This section contains an example using the Command Line Adapter 2. 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_CommandLine2_BP">
  <operation name="Command Line Adapter 2 Run Script">
    <participant name="Sample_CommandLine2_Adapter"/>
    <output message="CmdLine2InputMessage">
       <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>

Enabling the Command Line Adapter 2

Before you can use the Command Line Adapter 2, you must enable the server by editing the sandbox.cfg file. For more information on installing the Command Line Adapter 2 server remotely, see Installing the Command Line Adapter 2 server remotely.

Also, if you have a custom Command Line Adapter 2, you must reconfigure each of your custom adapters with the authentication and SSL options, see Configuring the Command Line Adapter 2.

To enable the Command Line Adapter 2 locally in your environment:

1. Open sandbox.cfg file that is in the install_dir/install/properties directory.
2. Add the LAUNCH_CLA2_SERVER property and set the value to true.

   LAUNCH_CLA2_SERVER=true

3. Run the setupfile.sh/.cmd to recycle Sterling B2B Integrator.
4. Start and stop the Command Line Adapter 2.
   • Start the Command Line Adapter 2 with the startCmdLine2.sh (UNIX) or the StartCLA2WindowsService.cmd (Windows) script.
   • Stop the Command Line Adapter 2 with the stopCmdLine2.sh (UNIX) or the StopCLA2WindowsService.cmd (Windows) script.

Installing the Command Line Adapter 2 server remotely

For your new or existing Command Line Adapter 2 remote instances you must use these instructions to install and redeploy the Command Line Adapter 2 server. Also, before you begin editing the files on your remote server, you must copy the needed files to your remote server.

To install the Command Line Adapter 2 server remotely:

1. Run the <install>/bin/CLA2makejar.sh(UNIX or Linux® or <install>/bin/CLA2makejar.cmd (Windows) script in your Sterling B2B Integrator instance to create the CLA2RemotePackage.jar in your /bin directory.
2. Copy the CLA2RemotePackage.jar to your remote server.
3. On your remote server, create a directory (<remoteFolder>).
4. Copy the CLA2RemotePackage.jar into your <remoteFolder> and extract the contents of the CLA2RemotePackage.jar.
5. Edit the following scripts in your <remoteFolder> by updating all the remote paths and ports.
   • startCmdLine2.sh (UNIX)

     jvm_args="-Xms128m -Xmx512m -DcmdlineProps2="<remoteFolder>/CmdLine2server.properties" -jar"
     clientJar=<remoteFolder>/CLA2Client.jar
     logOutput=<remoteFolder>/CmdLine2.output
     nohup <remoteFolder>/bin/java $jvm_args $clientJar <remotePort> > $logOutput 2>&1 &
     cmdLine2pid=$!
     echo $cmdLine2pid > <remoteFolder>/cmdline2.pid
     echo CmdLine2 started with PID=$cmdLine2pid

   • stopCmdLine2.sh (UNIX)

     pidFile=<remoteFolder>/cmdline2.pid

   • start_remote_CLA2_console.cmd (Windows)

     <remoteJKDfolder>\bin\java.exe -Xss256k -Xms64m -Xmx512m -DcmdlineProps2=
     <remoteFolder>\CmdLine2server.properties -Djava.io.tmpdir=<remoteFolder> 
     -Djava.class.path=<remoteFolder>\CLA2Client.jar; com.sterlingcommerce.woodstock.
     services.cmdline2.CmdLine2RemoteImpl <remotePort> > <remoteFolder>\cla2client.log 2>&1

6. Edit the CmdLine2server.properties file in your <remoteFolder>.

   keystore_location=<remoteFolder>/cla2_KeyStore.jks

   Tip: The host binding property CLA2NetworkHosts is in the CmdLine2server.properties file and the host binding must include the remote host name for example: localhost,chantico.dub.usoh.ibm.com.
7. Edit the log file location in the Cmdline2server.properties file.

   logLocation=<remoteFolder>/cla2server.log

8. Modify the *.sh files to make them executable.

   chmod 740 *.sh

9. Start the CLA2 server with the start script in your remote directory.
   • startCmdLine2.sh (UNIX)
   • start_remote_CLA2_console.cmd (Windows)
10. Verify that the server started correctly by viewing the cla2client.log file.
11. Stop the Command Line Adapter 2 server with the stop script in your remote directory.
    • stopCmdLine2.sh (UNIX)
    • Ctrl + C (Windows)

Stopping the Command Line Adapter 2

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

Otherwise, once started, the adapter runs silently as configured and does 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.

Maintaining authentication and SSL keys

The Command Line Adapter 2 provides default keys. However, you can use custom keys for authentication and SSL both locally and remotely. For remote custom keys, you must update the Java™ keystore (JKS) file and the property file in your remote directory. For more information on importing keys, see Security.

Changing the default keystore password

You can change the default CLA2 keystore password. This allows you to list the contents of the keystore, change the password to comply with any client policy, and otherwise update the keystore such as adding certificates or removing obsolete certificates.

With all the custom changes, when you upgrade Sterling B2B Integrator, you must back up and restore the keystore with the changed password.

1. Locate your encrypted keystore password from the CmdLine2server.properties file. For example, keystorePassword=CRYPTED:<encrypted password value>
2. Run the following script: CLA2_PasswordUtil.sh -decrypt CRYPTED:<your encrypted password value>. The following message is displayed (as an example only):

   The encrypted password was successfully decrypted: Decrypted value for CRYPTED:yccE7zmaQvxORNHZI88FblGFPL7bLwkjFQijL/VYGms= is:CLA2ServerDefaultPassword40000

3. To change the password, run ./CLA2_PasswordUtil.sh -encrypt on the new password.
4. Paste the encrypted string (including the CRYPTED: prefix) in your CmdLine2server.properties file as the value of the keystorePassword property.