Scripting Nuix Collector

Overview

Nuix Collector can perform multiple collections or extractions under the direction of a script, such as a batch file. Scripts are text files containing a series of commands that will be sent one at a time to the command line. To write an effective script, you must understand:

The commands of the scripting language you have selected

The command-line syntax of Nuix Collector (i.e. Collector.exe or Nuix Collector x64.exe)

To make this process easier, sample Windows batch files and Windows PowerShell scripts are available. Command-line switches for Nuix Collector are listed in topic Nuix Collector Command-Line Parameters.

Batch, VBScript and PowerShell scripts are all valid ways of scripting Nuix Collector. Any program which can run other programs from a Windows shell can also script Nuix Collector.

Note: Nuix Collector must be run by a user with local administrator privileges. On Windows 7 and newer, the User Account Control feature will require elevated privileges: If launched from a script, the script must be "Run as Administrator". If the script is launched from a Command Prompt, the Command Prompt itself must be launched with the "Run as Administrator" option. If launched from Task Scheduler – directly or via a script – the task must be configured to run under the account of a local Administrator. On Windows 7 and newer, the Run with highest privileges checkbox within the task must be checked.

Warning: Scripts are powerful and can have unintended consequences if not properly written. Test all scripts in a test environment before executing them in a production environment.

Example Windows batch file

In this example, we will create a simple batch file to run five different collection jobs in succession, without any input from the user.

Open Notepad or another basic text editor.

Type the following lines (see Nuix Collector Command-Line Parameters for syntax details):

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile1.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile2.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile3.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile4.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile5.xml" 2

Note: The quotation marks around the paths are necessary whenever there are spaces in the path or filenames, such as with Program Files and Nuix Collector. If your PC runs a 32-bit edition of Microsoft Windows, you may need to edit the above lines, so that: Nuix Collector x64.exe becomes: Nuix Collector.exe If you installed Nuix Collector Suite into a non-standard programs folder, you will need to edit the above lines, so the batch file can locate the Nuix Collector executable in the proper folder. The "2" parameter specified on the Nuix Collector command line (after the JobFile name) ensures a progress dialog will display during the collection. The "2" parameter also ensures Nuix Collector will exit automatically when done.

So far, our example batch file looks like this.

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile1.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile2.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile3.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile4.xml" 2

start "" /wait "C:\Program Files\Nuix\Nuix Collector\Modules\Nuix Collector x64.exe" "D:\JobFile5.xml" 2

If necessary, edit the batch file and change each occurrence of D:\ to another path where you store your JobFiles.

Save your new batch file, as follows:

In Notepad, go to File > Save As, then change the Save as type to “All Files”

Place the file on your Desktop, or in another folder that is easy for you to locate.

Name the file CollectorRun.cmd

Note: Some text editors will save the file with the name CollectorRun.cmd.txt. Minimize your text editor, then check the folder where you saved the file. Ensure the new file's extension is .cmd. If necessary, close the editor and rename the file.

Create the five JobFiles listed in the batch file, saving them to D:\ (or another folder you have specified in the batch file).

You can use Collector Wizard to produce these JobFiles. Set the job options throughout the Collector Wizard, then from the Wizard's File menu choose the Save JobFile option to save each JobFile.

You can also produce multiple JobFiles by creating one with the Wizard, then copy the JobFile and edit each copy using a text editor.

The batch file can now be run directly, or scheduled via Windows Task Scheduler. This batch file will immediately launch Nuix Collector, which will load the settings stored in JobFile1.xml and begin a collection. Once the first collection finishes, the batch file will launch Nuix Collector again to process JobFile2, followed by JobFile3, JobFile4 and JobFile5.

For a more comprehensive script example, see Appendix F: Script Example.

Running Nuix Collector via scripts on remote systems

It is possible to execute Nuix Collector Portable on a remote system via tools such as Microsoft / SysInternals' PsExec utility or by PowerShell Remoting. Refer to the Knowledgebase on the Nuix Support web site, at https://nuix.service-now.com/support, or contact Nuix Technical Support for details.

Scripting the VerifyFileSafe utility

The VerifyFileSafe utility can be executed from a batch file or other script. The FileSafe to be verified is passed as a command line parameter. From a Command Prompt, run VerifyFileSafe.exe /? or VerifyFileSafe_x64.exe /? for a full list of command-line parameters and numeric Return Codes.

Note: VerifyFileSafe must run by a user with local administrator privileges. On Windows 7 and newer, the User Account Control feature will require elevated privileges: If launched from a script, the script must be "Run as Administrator". If the script is launched from a Command Prompt, the Command Prompt itself must be launched with the "Run as Administrator" option. If launched from Task Scheduler – directly or via a script – the task must be configured to run under the account of a local Administrator. On Windows 7 and newer, the Run with highest privileges checkbox within the task must be checked.

Warning: Scripts are powerful and can have unintended consequences if not properly written. Test all scripts in a test environment before executing them in a production environment.

The following example batch file runs VerifyFileSafe to check a previously saved FileSafe, and tests the Return Codes to see whether the verification succeeded. An installation of Nuix Collector Suite 64-bit is assumed.

@echo off

if not exist "C:\Program Files\Nuix\Nuix Collector\Modules\VerifyFileSafe_x64.exe" goto mf

pushd "C:\Program Files\Nuix\Nuix Collector\Modules"

echo Running VerifyFileSafe...

start "" /wait VerifyFileSafe_x64.exe "D:\Collections\MyFileSafe.mfs01" "D:\VerifyReports"

if "%ERRORLEVEL%" EQU "0" echo Completed - no errors found & goto :report

if ERRORLEVEL 1 echo Found %ERRORLEVEL% errors in the FileSafe & goto :report

if "%ERRORLEVEL%" EQU "-100" echo Error: Could not create reports & goto :ack

if "%ERRORLEVEL%" EQU "-101" echo Error: Failed to open FileSafe & goto :ack

if "%ERRORLEVEL%" EQU "-102" echo Error: Failed verifying metadata files & goto :ack

if "%ERRORLEVEL%" EQU "-103" echo Error: FileSafe does not support verification & goto :ack

if "%ERRORLEVEL%" EQU "-104" echo Error: Failed verifying user files & goto :ack

if "%ERRORLEVEL%" EQU "-105" echo Error: Failed closing the FileSafe & goto :ack

if "%ERRORLEVEL%" EQU "-106" echo Error: FileSafe requires a password & goto :ack

if "%ERRORLEVEL%" EQU "-107" echo Error: Failed decrypting the password & goto :ack

if "%ERRORLEVEL%" EQU "-108" echo Error: Could not reach network location & goto :ack

if "%ERRORLEVEL%" EQU "-109" echo Error: Password is incorrect & goto :ack

echo Undocumented error %ERRORLEVEL%

goto :ack

:mf

echo Unable to find the VerifyFileSafe utility, i.e.

echo C:\Program Files\Nuix\Nuix Collector\Modules\VerifyFileSafe_x64.exe

goto :EOF

:ack

echo See the error log in file %CD%\VerifyErrorLog.txt

popd

goto :EOF

:report

echo See reports in folder D:\VerifyReports

popd