LauncherParams JobFile structure
1. LauncherParams element
  1. Process element

LauncherParams JobFile structure

This section describes the settings available for configuring a Launch Command job. Launch Command jobs are supported in all editions of Nuix Enterprise Collection Center 7.2 and newer. Launch command jobs are not supported in Nuix Collector Suite.

The root element for a Launch Command JobFile is a pair of <JobParameters>..</JobParameters> elements. The opening <JobParameters> tag appears just after the XML Declaration. This opening tag should include optional attributes for the XML namespace and schema, as follows:

<?xml version="1.0" encoding="UTF-16"?>

<JobParameters

xmlns="-//nuix.com/2014/CollectorEngine"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="-//nuix.com/2014/CollectorEngine

./CollectorEngine.xsd">

</LauncherParams>

</WorkerParameters>

</JobParameters>

Within the <JobParameters> element, the <WorkerParameters> child element contains a <LauncherParams> child element, described below.

LauncherParams element

</LauncherParams>

</WorkerParameters>

The <LauncherParams> element contains no attributes or text value. It merely is the parent element for a <Process> child element, described below.

Process element

</Process>

</LauncherParams>

</WorkerParameters>

The <Process> element contains several attributes and child elements which specify the program or script to run, its optional parameters, and other related settings. Only one <Process> element is permitted in each JobFile.

The KillProcess attribute specifies whether to kill the process if it runs longer than the specified TimeOut. Can be Yes or No:

Yes

Kill the process if it is still running after the duration specified in TimeOut.

Allow the process to run indefinitely.

The TimeOut attribute specifies the number of seconds to allow the process to run before killing the process. Ignored if KillProcess is set to "No".

The SuccessCode attribute specifies the expected ERRORLEVEL returned by <ExecutableFile> to indicate a successful run. Typically 0. <ExecutableFile> is described, below.

The StdErrorMode attribute specifies the text encoding expected by ECC for monitoring console output. When launching a console program with ASCII encoding, set this value to "Text". When launching a console program with Unicode encoding, set this value to "Binary".

The UI-RunInCommandShell attribute is for NUIX INTERNAL USE ONLY. Used internally by Nuix ECC Admin Console to indicate whether the <ExecutableFile> is a batch file or script to run inside of CMD.EXE (on Windows).

ExecutableFile element

C:\some\path\my-program.exe

</ExecutableFile>

</Process>

The file specification of the program or script to run. Can be %ComSpec% to run cmd.exe, with parameters specified by <Params>, below.

The MD5 attribute (optional) specifies the pre-computed MD5 hash value for the <ExecutableFile>. ECC Client will verify the MD5 hash of the executable file or script matches this value, if specified, to ensure the file has not been altered prior to executing the file.

Params element

C:\some\path\my-program.exe

</ExecutableFile>

<Params>-Input \\MyServer\MyShare\items.txt</Params>

</Process>

The value of this element specifies the command-line parameters to be passed to the program specified by <ExecutableFile>, above.

Individual parameters can instead be specified in one or more <Param> child elements.

Param element

C:\some\path\my-program.exe

</ExecutableFile>

<Param>-Input<Param>

<Param>\\MyServer\MyShare\items.txt<Param>

</Params>

</Process>

Each <Param> child element specifies a single command-line parameter to be passed to the program specified by <ExecutableFile>, above. <Param> child elements are an alternative to specifying the command-line parameters directly in the value of the <Params> element.

NetworkCredentials element

C:\some\path\my-program.exe

</ExecutableFile>

<Params>-Input \\MyServer\MyShare\items.txt</Params>

<!—One or more <Credentials> "child" elements go here -->

</NetworkCredentials>

</Process>

Contains one or more <Credentials> child elements, which provide access to the <ExecutableFile> (and/or any related files) when they reside on one or more network shares.

Credentials element

C:\some\path\my-program.exe

</ExecutableFile>

<Params>-Input \\MyServer\MyShare\items.txt</Params>

<Credentials LoginUser="Alice"

Password="G1sv4zz2#"

LoginDomain="MYCOMPANY">MyServer</Credentials>

</NetworkCredentials>

</Process>

Each credentials element specifies the hostname and login credentials for accessing a network share. This allows launching programs located on network shares, or saving output files to such shares.

The text value contains the name of the network machine to connect to. The attributes contain account credentials for access to the machine over the network.

The UserName attribute specifies the user ID for accessing the <ExecutableFile> and/or related files. Needed only when the file(s) reside on a password-protected network share.

The Password attribute specifies the password for accessing the <ExecutableFile> and/or related files. Needed only when the file(s) reside on a password-protected network share.

The Domain attribute specifies the domain for accessing the <ExecutableFile> and/or related files. Needed only when the file(s) reside on a password-protected network share on an Active Directory domain.

PayloadVerify element

C:\some\path\my-program.exe

</ExecutableFile>

<Params>-Input \\MyServer\MyShare\items.txt</Params>

<!—One or more <FilePath> "child" elements go here -->

</PayloadVerify>

</Process>

Contains one or more <FilePath> child elements, each of which will be verified against a pre-computed MD5 hash value. This ensures that the file has not been altered before it is executed or otherwise loaded.

FilePath element

C:\some\path\my-program.exe

</ExecutableFile>

<Params>-Input \\MyServer\MyShare\items.txt</Params>

\\MyServer\MyShare\items.txt

</FilePath>

</PayloadVerify>

</Process>

Each <FilePath> element contains the full path to a file to verify. This can be the <ExecutableFile>, or a file passed as a parameter via <Params>.

The MD5 attribute specifies the pre-computed MD5 hash value for the file specified by <FilePath>. ECC Client will verify the MD5 hash of this file matches this value, if specified, to ensure the file has not been altered prior to executing the <ExecutableFile>.