Commandline

The adapter calls an external application or an external command via a Command Line of the operating system with any number of arguments. The adapter expects an adapter-specific input XML structure with Base64-encoded data and outputs an XML document with the Base64-encoded results of StdOut and/or StdErr, as well as the returned exit code.

Properties

Operation

Defines the operation executed by the adapter

Possible values: Execute: Call application/command via Command Line

Parameters

Adapter	Main adapter class (do not change!) Possible values: `de.softproject.integration.adapter. osprocess.OsProcessAdapter`: Main class (default)
WorkingDirectory	Working directory for the executed application call; might be overwritten by the working directory specified within the input XML; If both are empty, the X4 Server working directory will be used. Possible values: Any valid path (e.g. `C:\X4\temp\`) `(empty`): No default working directory (set manually via input XML, else the X4 Server working directory will be used. (default)
CollectStdOut	Capture the Standard Output stream of the called program Possible values: `true`: Save Base64-encoded Standard Output stream of the called program within the result XML document in element `<StdOut>` (default) `false`: Do not consider the Standard Output (element `<StdOut>` in the result XML document remains empty)
CollectStdErr	Capture Standard Error stream of the called program Possible values: `true`: Save Base64-encoded Standard Error stream of the called program within the result XML document in element `<StdErr>` (default) `false`: Do not consider the Standard Error (element `<StdErr>` in the result XML document remains empty)
MergeStdErrIntoStdOut	Output both Base64-encoded Standard Error stream and Base64-encoded Standard Output stream together within the element `<StdOut>` Possible values: `true`: Output Standard Error and Standard Output merged together `false`: Output data streams separately (default)

Input

The adapter expects an XML document having the following pattern:

HTML/XML

<Command>
	<WorkingDirectory>
		<!--Working directory (optional)-->
 	</WorkingDirectory>
  	<Application>
		<!-- Command line name or complete path of the application -->
	</Application>
 	<!-- Any number of arguments (observe sequence!) -->
 	<Argument>
		<!--Argument/Parameter-->
	</Argument>
  	<Environment clear="Work only with the following environment variables (true/false)">
     	<!-- any number of environment variables -->
     	<Entry name="Environment variable name"><!--Wert--></Entry>
  	</Environment>
  	<Input>
		<!-- Base64-encoded data to be processed by the external application -->
	</Input> 
  	<Copy>
   		<!-- Any string/XML structure to be bypassed without modification -->
  	</Copy>
</Command>

Explanation:

<WorkingDirectory> (optional): Working directory in which the called application operates; overwrites the value of parameter WorkingDirectory ); does not correspond to the path of the application (see below)!
<Application>: Application or command line name with or without the complete path (if the application path is already set within the environment variables). As an alternative, use cmd.exe under Windows and specify the application as first argument.
<Environment>: Defines environment variables; Using the attribute clear="true" you can control, whether the command will be executed only with the environment variables defined within the element <Environment>. With clear="false" the environment variables defined within the element <Environment> will be added to the existing ones.
<Input> (optional) Contains Base64-encoded input data
<Copy> (optional): Contains an XML structure or any string to be bypassed without modification.

Unlike in case of adapter parameters, you can use placeholders like %USER_COLLECTION% within the input XML!

Example

Within the following input XML structure, the Windows default Command Line cmd.exe will be executed in the working directory C:\, and the environment variables name and age are set using the command argument set. With the argument /c the command will be executed in character order and then it will be terminated. With clear="true" the command will be executed only with the environment variables defined here.

HTML/XML

<Command>
  <WorkingDirectory>C:\</WorkingDirectory>
  <Application>cmd.exe</Application>
  <Argument>/c</Argument>
  <Argument>set</Argument>
  <Environment clear="true">
    <Entry name="name">Theo Test</Entry>
    <Entry name="age">35</Entry>
  </Environment>
  <Input></Input>
  <Copy>
  </Copy>
</Command>

Output

The function adapter outputs an XML document with the following pattern:

HTML/XML

<CommandResult>
   <ExitCode>Exit code of the application</ExitCode>
   <StdOut>Base64-encoded output data of the application</StdOut>
   <StdErr>Base64-encoded error output of the application</StdErr>
   <Copy>String/XML structure bypassed without modification</Copy>
</CommandResult>

Status values

1	The call has been executed. The status value 1 is independent of the exit code of the called application.
-1	The call could not be executed (e. g. application was not found).