Nuix SDK – Getting Started

Getting Started: SSL Configuration

Thu, 29 Jul 2021 00:00:00 +0000

To ensure that all communications within Nuix RESTful Service are protected, Secure Sockets Layer (SSL) should be enabled before using the application in a production environment.

Before You Begin

It is recommended that SSL be implemented with a valid certificate obtained from a trusted Certificate Authority (CA).

To enable SSL, Nuix RESTful Service requires:

A PKCS12 (Recommended) or JKS keystore
A PEM or DER based certificate

Generating a Self-Signed Certificate

Certificates being used in a production environment should be obtained and signed by a trusted Certificate Authority (CA). In some circumstances, however, it may be necessary to generate a self-signed certificate for testing purposes.

Use the following procedure to generate a self-signed PKCS12 based keystore for use with Nuix RESTful Service.

From a command prompt, navigate to the Java installation directory used by Nuix RESTful Service:
- Windows: C:\Program Files\Common Files\i4j_jres\11.0.3\bin
- Linux: $JAVA_HOME/bin

Run the following command to generate the keystore.

keytool -genkeypair -alias nuixrest -keyalg RSA -keysize 4096 -storetype PKCS12 -keystore nuixrest.p12 -validity 3650 -storepass changeit -keypass changeit

Proceed to Enableing SSL to complete the configuration.

Importing a PEM Certificate to a PKCS12 Keystore

If using a certificate from a trusted CA, use the following procedure to import the PEM based key and certificate to the PKCS12 keystore:

Note

Ensure that an OpenSSL Binary has been download and installed before proceeding

From a command prompt with elevated privileges, enter the following command:

openssl pkcs12 -export -out nuixrest.p12 -inkey privkey.pem -in cert.pem -name nuixrest

Proceed to Enableing SSL to complete the configuration.

Enabling SSL

Use the following procedure to enable SSL for Nuix RESTful Service after importing your certificate to the keystore:

Navigate to the following location within the Nuix RESTful Service installation directory.
- Windows default: C:\Program Files\Nuix\Nuix RESTful Service\settings
- Linux default: /opt/nuix-restful-service/settings
Using a text editor, open application.properties.

Update the values of the following existing properties to provide the details of your keystore and enable SSL:

server.port=8443
server.ssl.key-store=/path/to/generated/keystore/nuixrest.p12
server.ssl.key-store-password=changeit
server.ssl.key-store-type=PKCS12
server.ssl.key-alias=nuixrest
server.ssl.key-password=changeit
server.ssl.enabled-protocols=TLSv1.2

Save the file and exit.
Restart Nuix RESTful Service for the changes to take effect.

After restarting, Nuix RESTful Service will be accessible at the following URL: https://127.0.0.1:8443/nuix-restful-service/svc/docs

Note

If using a self-signed certificate, the Nuix RESTful Service reference documentation will not be accessible if using a Chrome based browser.

Getting Started: Version 9.4 Release Notes

Tue, 27 Jul 2021 00:00:00 +0000

Nuix Engine

Nuix RESTful Service has been updated to use version 9.4 of the Nuix Engine. Details about what is included with this update can be found in the v9.4 changelog.

Nuix Collector for Microsoft 365

Nuix RESTful Service now supports the ability to ingest data directly from Microsoft Office 365 using the following new processing endpoint.

POST /cases/{caseId}/evidence/ms365

Using the new endpoint in conjunction with your Microsoft tenant and the Microsoft Graph API, you can now access data from the following Office 365 applications:

Teams
- Threaded channel and private messages
- Attachments
- Calendars
Exchange
- Email
- Contacts
SharePoint
- Sites
- Subsites
- Lists (Retrieval of list attachments is not supported.)

For more information, see Ingesting from Microsoft Office 365.

Access

Nuix RESTful Service now supports the ability to configure specific license server types during installation. Supported server types include:

Nuix Management Server (NMS)
Relay server with NMS users
Relay server with CLS users
Cloud License Server (CLS)

For more information, see Licensing Configuration.

Culling

Item sets

The GET /cases/{caseId}/itemSets/{itemSetName}/items endpoint has been enhanced to now support item marshaling through a new optionsRequest parameter. The new parameter includes the following configurable options:

{
  "caseId": "string",
  "query": "string",
  "startIndex": 0,
  "numberOfRecordsRequested": 100,
  "deduplicate": "md5",
  "metadataProfile": "string",
  "fieldList": [
    "string"
  ],
  "customMetadataList": [
    "string"
  ],
  "propertyList": [
    "string"
  ],
  "itemParameterizedFields": [
    "string"
  ],
  "sortField": "string",
  "sortOrder": "asc"
}

Deprecated endpoints

The following endpoints have been deprecated as they include a payload body which has no defined semantic meaning within a DELETE request:

DELETE /cases/{caseId}/itemTags
DELETE /cases/{caseId}/tags
DELETE /cases/{caseId}/itemCustomMetadata
DELETE /cases/{caseId}/itemSets/{itemSetName}/items

The functionality of the deprecated DELETE endpoints has been integrated in the following new PATCH endpoints:

PATCH /cases/{caseId}/itemTags

Create or remove tags from query items in bulk.
PATCH /cases/{caseId}/tags

Create or delete tags for a case in bulk.
PATCH /cases/{caseId}/itemCustomMetadata

Add or remove custom metadata on items in bulk.
PATCH /cases/{caseId}/itemSets/{itemSetName}/items

Add or delete items to an item set in bulk.

Default JVM arguments

The following JVM arguments are no longer required and have been removed from the default startup configuration of Nuix RESTful Service:

-Dnuix.processing.worker.timeout=3600

Sets the timeout in seconds before an item is considered poisoned.
-Dnuix.region.enableIterruptChecking=true

Controls whether interrupts are checked when data is read.
-Dnuix.storage.index.lazyLoadFields=false

Minor search performance improvement.
-Dnuix.storage.index.readers=shared

Minor search performance improvement.
-Dnuix.store.textIndexDirectoryType=mmap

Specifies the type of directory to use.

The following JVM argument has been added:

-Dnuix.worker.useNuixFs=false

Controls whether to use Nuix fs for local or remote workers.

Export

When generating thumbnails, if an export directory has not been defined, thumbnails will be exported to a default directory and a warning message will be logged.

Resolved Issues

The name parameter is now required within the request body of the POST /cases/{caseId}/itemSets endpoint to prevent errors when creating a new item set.

Getting Started: Installing on Windows

Thu, 22 Jul 2021 00:00:00 +0000

Nuix RESTful Service provides a wizard-based installer that guides you through the installation and initial configuration of the application. Follow the steps in this section to complete your installation of Nuix RESTful Service in a Windows environment.

If performing an upgrade, ensure that a backup of your existing Java Options is made prior to installation as these values will be overwritten. These values can be found in the bin/setenv.bat file within your installation directory. See Verifying Java Options after completing your upgrade for steps on adding these configurations back to installation.

Installation

To get started, perform the following steps to install:

Download the Windows installer from the Nuix Customer Portal.
Browse to the location that contains the installer.
Right-click on the installer and choose Run as administrator, even if you are already running as an administrator. The installer may take a moment to prepare for the installation. When the initial preparation is complete, follow the steps within the wizard to complete the installation.
From the Welcome Screen, click Next to begin.
Note

If a previous version of Nuix RESTful Service is already installed, the following options are provided:
- Update the existing installation
- Create a new installation in a separate location.
Choosing to update will bypass all further configuration steps within the wizard and begin the installation process using the configurations defined within the previous installation.
Read and understand the terms included in the Nuix End User License Agreement.
- If you agree to the terms, select I accept the agreement, and click Next.
If installing for the first time, choose a location to install Nuix RESTful Service.
- Click Next to accept the default location and proceed.
- Alternatively, click Browse to choose a specific location for the installation.
Click Next to begin the installation.
On the License Server Type screen, select the option that matches the server type you are using for licensing, then click Next.
- Nuix Management Server (NMS)
- Relay server with NMS users
- Relay server with CLS users
- Cloud License Server (CLS)
If NMS or a Relay server was selected, enter the following details on the License Server Configuration screen, then click Next:

Note
If CLS is selected as the server type, this step is skipped.
- Server address: The URL used to access a configured Nuix Management Server.
- Server port: The server port used to access the configured Nuix Management Server.
On the License Server Credentials screen, enter the credentials for an account that has access to the selected server type, then click Next.
Review and make changes, if necessary, to the details provided on the Java & Folder Options screen.

Option	Description
Java Options	Optimize the Java settings used by Nuix RESTful Service to suit your hardware specifications. Define one argument per line. Default settings are recommended for most configurations. For help or assistance with tuning your JVM settings, contact the Nuix Support team at https://nuix.service-now.com/support.
IP Address or Hostname	The URL used to access Nuix RESTful Service.
Connection Timeout	Specify the amount of time that REST should wait for a response after accepting a connection. Use a value of -1 to indicate no timeout.
HTTP Port	The server port used to access Nuix RESTful Service.
Case Directory	Specify a location where case files are stored.
User Scripts Directory	Specify a location where user generated scripts are stored.
Logs Directory	Specify a location to save logs generated by Nuix RESTful Service.

After reviewing the Java & Folder Options screen, click Next to continue.
Specify how Nuix RESTful Service should be run:

Option	Description
Service	Run Nuix RESTful Service in the background as a Windows service.
Application	Run Nuix RESTful Service as a standalone application. See Starting in Application Mode after installation completes for details on starting the application.
Start Service	Select this checkbox, if the Service option was selected, to start Nuix RESTful Service when installation completes.

Click Finish to complete the setup and exit the wizard.

Post-Installation Configurations

After completing the installation of Nuix RESTful Service, the following configurations should be reviewed.

Windows Service User Account

If Nuix RESTful Service is configured to be run as a Windows service, the default Log On account associated with the service must be changed when performing a new installation to ensure proper operation of the application.

Tip

If upgrading an existing installation, all previous configurations, including the service’s Log On account, are preserved.

To update the Log On account associated with Nuix RESTful Service:

Use the Keyboard shortcut Win + R to open the Windows Run dialog box.
Type services.msc in the text field, then press OK.
In the Windows Services Manager, locate the Nuix-Rest service.
Right-click on the service and select Properties.
Select the Log On tab.
Select This Account, and provide the appropriate credentials for an account to use
Click Apply.

Verifying Java Options

If upgrading from an installation earlier than version 7.8, backed up Java Options can be added back to the installation after the upgrade using the following steps.

To add any of these options to your existing installation:

Navigate to the location where Nuix RESTful Service is installed.

Default path: C:\Program Files\Nuix\Nuix RESTful Service
Locate and open Nuix-REST.vmoptions within a text editor.
Modify the file, adding one argument per line.
Save and exit the editor.
Restart Nuix RESTful Service.

Starting in Application Mode

If Nuix RESTful Service was configured to be run as a standalone application, the service must be manually started and stopped.

To start Nuix RESTful Service in Application Mode:

Open a command prompt.
Navigate to the location where Nuix RESTful Service is installed.

Default path: C:\Program Files\Nuix\Nuix RESTful Service
Start the application using the following command:

Nuix-REST.exe /run
Stop the application using the following key combination within the command prompt:

Ctrl + C

Verifying Your Installation

Once your installation is complete, complete the following steps to verify your deployment:

Open a web browser and enter the following URL

localhost:8080/nuix-restful-service/svc/v2/about
If the installation was successful, the response body will return with information about the RESTful service.

{
 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "72670a5e-f0e1-4046-8b2e-22a42fe2ac9a",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null 
}

API Documentation

The Nuix RESTful Service provides a robust Application Programming Interface (API) that enables you to integrate your product or application with the Nuix Engine. For information about the endpoints that are available within the API, refer to the Nuix RESTful Service API documentation.

The API reference documentation is included with Nuix Restful Service and can be accessed at the following URL after installation.

http://<localhost>:8080/nuix-restful-service/svc/docs

Getting Started: Microsoft Azure Tenant Configuration

Wed, 21 Jul 2021 00:00:00 +0000

The Nuix connector for Microsoft Office 365 utilizes the Microsoft Graph API to authenticate and interact with the Office 365 suite of applications. Authentication is facilitated by creating an Azure application with appropriate permissions on the Azure Active Directory (AD) tenant where Microsoft Office 365 is hosted.

Important

The Azure application described in the following sections must be registered and approved by Microsoft before the Nuix connector endpoint can be used. Details about receiving this protected API access approval is detailed later within this tutorial.

Microsoft Graph Authentication Methods

The following authentication methods are implemented within this topic:

OAuth 2.0 client credentials grant flow.
- Used for certificate and client secret-based authentication.
- Learn more: https://docs.microsoft.com/en-us/graph/auth-v2-service#4-get-an-access-token
OAuth 2.0 Resource Owner Password Credentials (ROPC) grant flow.
- Used to retrieve Teams calendar data.
- Learn more: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth-ropc

Use the steps in the following sections to create and register an Azure application with the appropriate permissions to provide a method of authentication for your Azure tenant.

Registering a New Application with Azure

Use the following procedure to register and configure an Azure application that can be used by Nuix to authenticate with your Microsoft Office 365 Instance.

Important

This procedure must be performed by a user within your Azure tenant that has Global Administrator privileges.

Access the Microsoft Azure portal (https://portal.azure.com).
Log into the portal using an account that has been assigned the role of Global Administrator for your tenant.
If your account is associated with multiple tenants, switch to the Active Directory tenant where Microsoft Office 365 is configured. To do this:
1. Click on your account name from the upper right side of the Azure portal.
2. Click Switch directory from the pane.
3. Choose an available directory from the menu.
From the Azure portal Home page, select Azure Active Directory from the Azure services menu.
From the left navigation panel, select App registrations.
Click New registration from the top navigation bar within the view.
Provide the following details to register the application.
1. A descriptive name for the application. For example: Nuix Authentication
2. Under Supported account types, select Accounts in this organizational directory only (Single tenant).
3. Click Register to register the new app.
After registering the application, the Overview page displays. Copy the following displayed values for later use:
- Application (client) ID
- Directory (tenant) ID
Proceed to the following section to set up authentication.

Configuring an Authentication Method

After successfully registering your Azure application, an authentication method must be configured. The method that is chosen will determine how the Nuix connector authenticates with Microsoft Office 365.

Use the following procedure to configure an authentication method:

From the Overview page of your Azure application, select Certificates & secrets from the left navigation panel.

Tip
To access the Overview page from the Azure portal Home page, select Azure Active Directory from the Azure services list, then App registrations from the left navigation panel. Finally, click on the name of the new application to access its Overview page.

Two types of authentication are available for Azure Active Directory applications:
- Certificate-based authentication
- Password-based authentication (application secret)
Both methods are supported by the Nuix Connector for Microsoft Office 365 and provide the same level of access to the Azure tenant.
Implement one of the methods using the procedures in the following sections.

Certificate-Based Authentication

To configure certificate-based authentication, the selected certificate must meet the following requirements:

PKCS#12 based certificate store.
- Public key (.CER, .PEM, or .CRT) Applied within Azure.
- Private key (.PFX or .P12) Applied within the Nuix Connector endpoint.
RSA key algorithm
2048 key size

Note

The certificate store being used must not include more than one key value pair.

Use the following procedure to configure certificate-based authentication within your Azure tenant:

From the Certificates & secrets panel, locate the Certificates section and click Upload certificate.

Use the file explorer to select a valid certificate (public key) with either a .CER, .PEM, or .CRT file extension.

Note
Certificates should be obtained and signed by a trusted Certificate Authority (CA). If necessary, self-signed certificates can be used for testing purposes only.
Click Add to upload and apply the certificate.
Proceed to the next topic to apply API permissions to the Azure application.

Password-Based Authentication

Use the following procedure to configure password-based authentication within your Azure tenant.

From the Certificates & secrets panel, locate the Client secrets section and click New client secret.
Provide a description for the new client secret.
Select an expiration period for the client secret.

Note
When the client secret expires, this process must be repeated to create a new client secret for your application.
Click Add to generate the new client secret.
Copy the generated value to a secure location. The client secret is required when making requests to the Office 365 connector endpoint.

Warning
The client secret value is only visible at the time of creation. If lost, a new secret key must be generated for the application.
Proceed to the next topic to apply API permissions to the Azure application.

Getting Started: Licensing Configuration

Fri, 16 Jul 2021 00:00:00 +0000

During installation, Nuix RESTful Service can be configured to acquire licenses from either an available Nuix Management Server (NMS) or the Nuix Cloud License Server (CLS). After installation, you may need to eventually update the URL, server type, or credentials being used to acquire licenses. Use the details within this topic to update your license server connection information.

Nuix RESTful Service supports the following four license server types:

Nuix Management Server (NMS)

Acquire licenses directly from an NMS instance.
Relay server with NMS users

Connect to an NMS instance configured as a relay server to acquire licenses from CLS using NMS user authentication.
Relay server with CLS users

Connect to an NMS instance configured as a relay server to acquire licenses from CLS using CLS user authentication.
Cloud License Server (CLS)

Acquire licenses directly from CLS.

Note

For more information on CLS or how to configuring NMS as a relay server, see the Cloud License Server Getting Started Guide.

Updating License Server Configurations

Use the following procedure to update the license server configuration of your Nuix RESTful Service installation:

Prerequisites:

If configuring CLS for licensing, you must have a valid CLS user account and credentials to connect to the Nuix CLS portal (https://my.nuix.com).
Ensure that Nuix RESTful service is not running by closing the application or stopping the service before proceeding.

Configuration:

Navigate to the settings directory within the location where Nuix RESTful Service is installed.
- Windows: C:\Program Files\Nuix\Nuix RESTful Service\settings
- Debian/Ubuntu: /opt/nuix-restful-service/settings
Locate and open the application.properties file within a text editor.
Update the following properties with values based on the license server type being used.
nuix.license.source=
Specify the server type to use. Valid values include:
- server - Nuix Management Server (NMS)
- local-relay-server-local-users - Relay server with NMS users
- local-relay-server-cls-users - Relay server with CLS users
- cloud-server - Cloud License Server (CLS)
nuix.registry.servers=

The URL of the licensing server being used. To connect to CLS, specify licence-api.nuix.com.
Save and exit the file.
Restart Nuix RESTful Service for the changes to take effect.

If the credentials for accessing the license server have changed, proceeded to the next section.

Updating License Server Credentials

The stored credentials used to access your configured license server can be updated directly using the API. Use the following procedure to update the credentials associated with your specific NMS or CLS connection:

Submit a request to the /authenticatedUsers/login endpoint to log in and acquire a license using your updated credentials.

curl -L -X PUT 'http://127.0.0.1:8080/nuix-restful-service/svc/authenticatedUsers/login' \
-H 'Content-Type: application/json' \
--data-raw '{
    "username": "user1",
    "password": "newPassword",
    "licenseShortName": "enterprise-workstation",
    "workers": 2
}'

{
  "username": "user1",
  "authToken": "49e225d7-b88d-4d1b-9cbc-296e83706a60",
  "licenseShortName": "enterprise-workstation",
  "workersGranted": 1
}

Using the acquired authentication token, call the licenseServer/credentials endpoint, providing your updated license server credentials.

curl --location --request PUT 'localhost:8080/nuix-restful-service/svc/v1/licenseServer/credentials' \
--header 'Content-Type: application/json' \
--header 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60' \
--data-raw '{
  "username": "user1",
  "password": "newPassword"
}'

{
    "message": "Success.",
    "status": "PERSISTENT"
}

If the call is made successfully, and the provided credentials are valid, the password will be encrypted and the following properties within the application.properties file will be automatically updated, replacing any previous values

nuix.license.server.username=

Username of the CLS or NMS account being used for license acquisition.
nuix.license.server.securePassword=

The encrypted password associated with the license server username.

Getting Started: Application Settings

Thu, 06 May 2021 00:00:00 +0000

Application Properties

Configurable properties for the Nuix RESTful Service application are located within the application.properties file. To access this file, navigate to the settings directory within the Nuix RESTful Service installation directory.

Windows default: C:\Program Files\Nuix\Nuix RESTful Service\settings
Linux default: /opt/nuix-restful-service/settings

After modifying the file, restart Nuix RESTful Service for the changes to take effect.

Setting	Description	Example
autoMigrateCases	When set to `true`, cases will be automatically migrated to the current installed version of the Nuix Engine when opened.	false
asyncFunctionResultRetention	The length of time in milliseconds to retain the results of asynchronous functions.	300000
cluster.enabled	Set to `true` to enable clustering on an instance of Nuix RESTful Service.	false
cluster.license	License to acquire when operating in a cluster for non-worker based operations. (Optional)
cluster.roles	A list of cluster roles. Set to `producer`, `consumer`, or `producer,consumer` to configure the node role in a cluster. Only valid when `cluster.enabled=true`.
configurationFolder	The location where REST application configuration files are stored.	/settings
cors.allow.origin	A comma-separated list of permitted cross origin hosts. A value of `*` allows all domains.	*
closeCasesIfIdleInMinutes	The length of time a case can remain idle before being automatically closed. If set to `0`, idle cases will never close automatically.	10
function.queue.pause.timeout	The length of time in minutes that the asynchronous function queue will pause when paused.	5
hazelcastTcpIpMembers	A comma-separated list of IP addresses that identifies all nodes included in a cluster. Only valid when `cluster.enabled=true`.	192.168.111.60,192.168.111.61
ignoreDerbyCases	Disallows the creation of Derby cases.	false
inventoryLocations	A comma-separated list of directory paths where cases are stored.	/cases
inventoryRefresh	The length of time in milliseconds to wait before checking the case inventory for updates.	60000
exportsFolder	The location where exports are saved.	/exports
logging.config	The location of the Logback configuration file.	settings/logback.xml
logging.json.enabled	Set to `true` to enable the generation of REST logs in JSON format. This format is easier to process in applications like Filebeat.	false
logging.file.name	The name of the file where logs are output.	nuix-rest.log
maxItemTextLength	The maximum number of characters to return for each item. If no value is set, all item text is returned.
nuix.engine.path	The location where the Nuix Engine is installed.	/nuix-engine
nuix.engine.userDataDirs	A comma-separated list of paths to the Nuix Engine user-data directories.	user-data,shared-user-data
nuix.logdir	The location where Nuix worker logs are stored.	/logs
nuix.registry.servers	The URL of a Nuix Management Server (NMS) or Nuix Cloud License Server (CLS).	licence-api.nuix.com (CLS)
nuix.license.source	The method being used for license acquisition. See Licensing Configuration for additional information on configuring different license sources.	`server` = NMS `cloud-server` = CLS
nuix.license.server.username	The username of an NMS or CLS account, determined by `nuix.license.source`, that will be used to perform license checks.
nuix.license.server.password	The plaintext password of the licensing user. Use this property when changing the password of your licensing user. Note: After restarting the application, the password is encrypted and saved to `nuix.license.server.securePassword` and the plaintext value is cleared.
nuix.license.server.securePassword	The encrypted password of the licensing user. Note: If a new password is entered for `nuix.license.server.password`, the value of this property will be automatically updated for the new password once the application is restarted.
pathToResources	The location of the resources directory. The specified directory path should include the queryValidationCase, which is included during installation.	/resources
publicURL	The domain URL of the Nuix RESTful Service application.	http://localhost:nuix-restful-service/svc:8080
returnNuixLicenseIfIdleInMinutes	The length of time a user can remain idle before being logged out and the license is reclaimed. Setting a value of `0` will cause sessions not to expire when idle.	30
searchThumbnailsExportDirectory	The location where thumbnails are stored.	/thumbnails
serverId	A unique identifier for the Nuix RESTful Service instance.	rest-1
server.name	A name for the Nuix RESTful Service instance.	worker-1
server.port	The port the application listens on.	8080
server.tags	A comma separated list of tags to identify a node within a clustered environment. See Clustering server tags for additional information.	coordinator,worker
server.servlet.context-path	The `context path` is the name of the URL at which the Nuix RESTful Service application is accessed.	/nuix-restful-service/svc
server.tomcat.basedir	The base directory where Apache Tomcat® is located.	INSTALLATION_DIRECTORY
server.tomcat.accesslog.buffered	Whether to buffer output such that it is flushed only periodically.	false
server.tomcat.accesslog.directory	The location where access logs are written.	/logs
server.tomcat.accesslog.enabled	Enable or Disable the creation of access logs.	false
server.tomcat.accesslog.prefix	Access log prefix.	nuix_rest_access_log
spring.http.multipart.max-file-size	The maximum upload size for multipart/form-data.	1000MB
spring.http.multipart.max-request-size	The maximum request size for multipart/form-data.	1000MB
threadpool.asyncfunction	Control the number of threads available for asynchronous functions.	4
threadpool.nativesearch	Control the number of threads available to marshal search items.	10
threadpool.searchUnsortedManager	Control the number of threads available for unsorted search functions.	4
threadpool.searchUnsorted	Control the number of threads available to marshal unsorted search items.	4
userScriptsLocation	The location where user scripts are read from for execution.	/user-scripts

JVM Arguments

The following Java Virtual Machine (JVM) settings are included in the default configuration of Nuix RESTful Service. To access these settings, locate the following file within the Nuix RESTful Service installation directory.

Windows default: C:\Program Files\Nuix\Nuix RESTful Service\Nuix-REST.vmoptions
Linux default: /opt/nuix-restful-service/Nuix-REST.vmoptions

After modifying the file, restart Nuix RESTful Service for the changes to take effect.

Setting	Description	Default
-Xmx	Sets the maximum Java heap size.	6G
-XX:+UseParallelGC	Enable parallel garbage collection. This setting is recommended for improved performance.
-Djna.nosys	Require Java Native Access (JNA) to only load native libraries and ignore system libraries.	true
-Djava.io.tmpdir	The temporary directory used by the Java Virtual Machine (JVM) to create and store temporary files.	$INSTALLATION_DIRECTORY/temp
-Dnuix.investigator.bulkProcessingTemp	The temporary directory used for bulk processing operations (populating stores, OCR, etc).	$INSTALLATION_DIRECTORY/temp/bulk
-Dnuix.worker.tmpdir	The default temporary directory used by workers.	$INSTALLATION_DIRECTORY/temp/worker
-Dspring.config.location	The location where the application.properties file is stored.	$INSTALLATION_DIRECTORY/settings
-Dnuix.worker.jvm.arguments	JVM arguments that are applied specifically to Nuix workers.	-Dlog4j.configuration= file:$INSTALLATION_DIRECTORY/nuix-engine/config/log4j.properties

Getting Started: Set Up your Development Environment

Mon, 08 Mar 2021 00:00:00 +0000

Before proceeding with the steps outlined below, ensure that the following prerequisites have been completed:

Nuix RESTful Service is installed and running.
Access to Nuix Licensing is configured using any of the following options:
- Nuix Management Server (NMS)
- Nuix Cloud License Server (CLS)

You will also need to know the following details about your installation.

The server location of your REST installation.
- Default location: <localhost>:8080/nuix-restful-service/svc/
- This URL is used throughout the provided examples to make calls to the API.
The location of the API reference documentation.
- Default location: <localhost>:8080/nuix-restful-service/svc/docs

Nuix RESTful Service is a language agnostic tool capable of interpreting calls over HTTP(s) using the method of your choice. To explore the API, any tool capable of performing HTTP requests can be used.

Postman

For the purposes of these quick start topics, simple cURL commands are provided that can be run within Postman. To use Postman, visit the following URL and download the API client for the operating system you are using.

https://www.postman.com/downloads/

Once downloaded, run the installer to setup Postman on your computer. Details about the installation process can be located on the Postman website.

https://learning.postman.com/docs/getting-started/installation-and-updates/

After the installation completes, launch the application by clicking the Postman icon on your desktop.

Import the OpenAPI Specification

The Nuix RESTful Service API documentation can be imported directly into Postman using any of the following methods. The steps outlined below are based on Postman Version 7.36.4.

Option 1: Run in Postman

To get started quickly, click the Run in Postman button below and follow the prompts to import the complete API directly into Postman with just a few clicks.

Option 2: Link Import

Use the following procedure to import the Nuix RESTful Service API into Postman using a link to the API specification:

Navigate to the Nuix RESTful Service reference documentation to locate a direct link to the OpenAPI specification.

Default docs location: <localhost>:8080/nuix-restful-service/svc/docs
Right-click the URL below the heading at the top of the page, then select Copy link address to copy the location of the openapi-docs.json specification file.
Within Postman, expand the File menu, and then click import.
From the Import window, select the Link tab. Paste the address you copied in Step 2 into the URL field, and then click Continue.
Confirm the details of the import and make the following additional selections:
- Under the Link this collection as menu, select Integration Test.
- Click Show advanced settings and confirm the following selections:

Advanced Option	Recommended Setting
Naming requests	`Fallback`
Request parameter generation	`Example`
Response parameter generation	`Example`
Folder organization	`Tags`

Click Import.

When the import is complete, a new collection named Nuix REST-API Reference will be available from the Collections tab. The available endpoints are organized according to how they are listed in the API reference documentation.

Option 3: File Import

If you do not have a running instance of Nuix RESTful Service, but have previously downloaded the specification in either openapi.yaml or openapi-docs.json format, you can upload the API documentation directly into Postman with the specification that you have saved using the following procedure.

Within Postman, expand the file menu, and then click Import.
From the File tab, click Upload Files and then locate and select a previously downloaded API documentation file. (openapi.yaml or openapi-docs.json)
Confirm the details of the import and make the following additional selections:
- Under the Link this collection as menu, select Integration Test.
- Click Show advanced settings and confirm the following selections:

Advanced Option	Recommended Setting
Naming requests	`Fallback`
Request parameter generation	`Example`
Response parameter generation	`Example`
Folder organization	`Tags`

Click Import.

Advanced Postman Setup

Postman provides an interface that allows you to create and test calls to an API. Postman also allows you to configure variables for commonly used parameters that can be used to streamline your workflow when constructing API calls.

Use the following procedure to setup a few basic configurations in your Postman installation:

With Postman open, select an existing collection or click on New Collection to create a location to save any API calls that you create for the Nuix RESTful Service.
- Provide a name for the new collection and optionally a description.
Select the Variables tab and define the following variables based on your installation:

Variable	Current Value
`base-url`	The URL of your Nuix RESTful Service installation. Default URL: http://127.0.0.1:8080/nuix-restful-service/svc
`nuix-auth-token`	The authorization token that was issued to you when a license is acquired. Note: Since a license has not yet been acquired, leave this field empty.

Note

The variable values identified in the table map to parameters used in the Nuix RESTful Service API.

Click Create to finalize the new collection.

The newly created collection will be displayed in the left sidebar of Postman under the Collections tab. As you create and test calls to the REST API, you can save them to your newly created collection and access them from this location within Postman.

To create a new request, click the + button located at the top of the builder window.

To save a request to your Postman collection, use the following procedure:

Expand the Save button drop-down menu next to the URL input field and select Save As from the menu.
Provide a Request name, such as Server Status, for the call.
Select the Collection to save the request in, then click Save.

Getting Started: Simple Case Creation

Thu, 11 Feb 2021 00:00:00 +0000

Create a Case

Now that you are authenticated, lets create your first Nuix simple case.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloWorld",
   "location":"inventory0",
   "description":"My first simple Nuix case",
   "compound":false,
   "investigator":"Inspector Gadget"
}'

{
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "name": "HelloWorld",
    "path": "/Cases/HelloWorld",
    "description": "My first simple Nuix case",
    "investigator": "Inspector Gadget",
    "creationDate": 1612906749154,
    "compound": false,
    "elastic": false,
    "binaryStoreLocation": "",
    "indexId": "",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "casePath": "/Cases/HelloWorld",
    "caseDescription": "My first simple Nuix case",
    "caseCreationDate": 1612906749154,
    "caseInvestigator": "Inspector Gadget",
    "caseName": "HelloWorld"
}

You have now successfully created your first case! Next, let’s ingest some data!

Getting Started: Viewing the Cluster

Thu, 11 Feb 2021 00:00:00 +0000

View Cluster

Once you have your cluster configured, you can view the cluster using the cluster endpoint.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/cluster' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \

{
    "nodes": [
        {
            "hostAddress": "192.168.1.160",
            "hostName": "localhost",
            "port": 5601,
            "details": {
                "serverId": "nuix-restful-server1",
                "publicURL": "http://192.168.1.160:8080",
                "name": "Coordinator Node",
                "tags": [
                    "coordinator"
                ],
                "guid": "353a72fc-43ed-394a-b015-aa2caa2d048b"
            }
        },
        {
            "hostAddress": "192.168.1.161",
            "hostName": "localhost",
            "port": 5601,
            "details": {
                "serverId": "nuix-restful-server-2",
                "publicURL": "http://192.168.1.161:8080",
                "name": "Worker Node",
                "tags": [
                    "worker"
                ],
                "guid": "63f2fc6b-b6b9-32be-93db-51f1f01d602e"
            }
        }
    ]
}

Getting Started: Part 1: Verifying your Installation

Tue, 09 Feb 2021 00:00:00 +0000

About

Before you begin, it is a good idea to verify your installation and make sure Nuix REST is up and running. You can easily do this by using the /v2/about endpoint.

The unauthenticated version of this endpoint will only return the server and serverId fields. All other fields will be null and require an authentication token to view them.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v2/about'

{
    "server": "http://localhost:8080",
    "serverId": "nuix-restful-server-1",
    "startupTime": null,
    "nuixRestfulVersion": null,
    "engineVersion": null
}

Getting Started: Introduction

Mon, 11 Jan 2021 00:00:00 +0000

SUPPORTED LANGUAGES

Ruby
JavaScript
Python

CONFIGURATION

There are two ways to execute user scripts. They can either be submitted directly as a string to the /userScripts or /cases/{caseId}/userScripts endpoints in the script field, or you can place your script in a file in the user scripts directory and invoke them from the same endpoints by specifying the script name in the fileName field.

The user scripts directory is configurable and can be set in the application.properties file.

userScriptsLocation="/Path/To/UserScripts/Directory"

VARIABLES

Each script has several common local variables injected, all of which are available both with and without a leading dollar sign ($):

current_case (also as currentCase):This is the Java nuix.Case object. It is only available in the case-specific endpoint /cases/{caseId}/userScripts.
utilities: This is the Java nuix.Utilities object for the current environment.
request: This is the Java HttpServletRequest object.
response: This provides methods for customising the object that is returned from the server. These methods are:
- setStatus(int httpStatusCode): This sets the HTTP status code.
- addHeader(String headerName, String headerValue): This adds a header to the actual HTTP response that comes back from the server.
- setBody(Object body): This sets the payload of the response.
progress : This provides methods for updating the progress of the script when run in an asynchronous manner. These methods are:
- setStatus(String status): This sets an arbitrary status value. This will be reflected in the ‘‘status’’ variable in the AsyncFunctionStatus response.
- setEstimatedFinalValue(long value)): This sets an estimate for the final progress value. This will be reflected in the ‘‘total’’ variable in the AsyncFunctionStatus response, and will be used as the denominator when calculating percent complete.
- setCurrentValue(long value): This sets the current progress value. This will be reflected in the ‘‘progress’’ variable in the AsyncFunctionStatus response, and will be used as the numerator when calculating percent complete.
custom_arguments (also as customArguments): This is the map of provided custom arguments.

Getting Started: Elasticsearch Case Subset

Mon, 13 Jan 2020 00:00:00 +0000

Example Scripts

class ElasticsearchCaseSubset
  def initialize(exportPath, query)
        @exportPath = exportPath
        @query = query
        @out = Hash.new
        @exceptions = Array.new
  end

  def process
    begin
      items = $current_case.search(@query);
      @out[:item_count] = items.size();
      @out[:exportPath] = @exportPath
      options = {
        "evidenceStoreCount" => 1,
        "includeFamilies" => false,
        "copyTags" => false,
        "copyComments" => false,
        "copyCustodians" => false,
        "copyItemSets" => false,
        "copyClassifiers" => false,
        "copyMarkupSets" => false,
        "copyProductionSets" => false,
        "copyClusters" => false,
        "copyCustomMetadata" => false,
        "caseMetadata" => {
          "name" => "ESCaseSubset",
          "description" => "About My simple Case",
          "investigator" => "Inspector Gadget",
          "elasticSearchSettings" => {
            "index.refresh_interval" => "60s",
            "nuix.transport.hosts" => "127.0.0.1:9300",
            "cluster.name" => "elasticsearch",
            "index.number_of_replicas" => "0",
            "nuix.index.auto_close" => "false",
            "index.number_of_shards" => "5",
            "xpack.security.transport.ssl.enabled" => "false"
            }
        }
      }
      @out[:started] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
      $utilities.getCaseSubsetExporter().exportItems(items, @exportPath, options);
    rescue => exception
       @exceptions << {:class => exception.class.name, :message => exception.message}
    end
    @out[:exceptions] = @exceptions
    @out[:finished] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
    return @out
  end
end
$response.setBody(ElasticsearchCaseSubset.new("/Cases/ESCaseSubsetUserScript", "file-extension:html").process)

function ElasticsearchCaseSubset(exportPath, query) {
  this.exportPath = exportPath;
  this.query = query;
}

ElasticsearchCaseSubset.prototype.process = function() {
  var out = {};
  try {
    var items = current_case.search(this.query);
    out['item_count'] = items.length;
    out['exportPath'] = this.exportPath;

    var options = {};
    options['evidenceStoreCount'] = 1;
    options['includeFamilies'] = false;
    options['copyTags'] = false;
    options['copyComments'] = false;
    options['copyCustodians'] = false;
    options['copyItemSets'] = false;
    options['copyClassifiers'] = false;
    options['copyMarkupSets'] = false;
    options['copyProductionSets'] = false;
    options['copyClusters'] = false;
    options['copyCustomMetadata'] = false;

    var elasticSearchSettings = {};
    elasticSearchSettings['index.refresh_interval'] = '60s';
    elasticSearchSettings['nuix.transport.hosts'] = '127.0.0.1:9300';
    elasticSearchSettings['cluster.name'] = 'elasticsearch';
    elasticSearchSettings['index.number_of_replicas'] = '0';
    elasticSearchSettings['nuix.index.auto_close'] = 'false';
    elasticSearchSettings['index.number_of_shards'] = '5';
    elasticSearchSettings['xpack.security.transport.ssl.enabled'] = 'false';

    var caseMetadata = {};
    caseMetadata['name'] = 'ESCaseSubset';
    caseMetadata['description'] = 'About my simple case.';
    caseMetadata['investigator'] = 'Inspector Gadget';
    caseMetadata['elasticSearchSettings'] = elasticSearchSettings;

    options['caseMetadata'] = caseMetadata;

    out['started'] = new Date().getTime().toString();
    utilities.getCaseSubsetExporter().exportItems(items, this.exportPath, options);
  } catch(err) {
    out['exceptions'] = err.message;
  }
  out['finished'] = new Date().getTime().toString();
  return out;
}

$response.setBody(new ElasticsearchCaseSubset("/Cases/ESCaseSubsetUserScript", "file-extension:html").process())

import time

class ElasticsearchCaseSubset: 

  def __init__(self, exportPath, query): 
    self.exportPath = exportPath 
    self.query = query
    self.out = {}
    self.exceptions = []

  def process(self):
    try:
      items = current_case.search(self.query);
      self.out['item_count'] = len(items)    
      self.out['exportPath'] = self.exportPath

      options = {
        "evidenceStoreCount": 1,
        "includeFamilies": False,
        "copyTags": False,
        "copyComments": False,
        "copyCustodians": False,
        "copyItemSets": False,
        "copyClassifiers": False,
        "copyMarkupSets": False,
        "copyProductionSets": False,
        "copyClusters": False,
        "copyCustomMetadata": False,
        "caseMetadata": {
          "name": "ESCaseSubset",
          "description": "About My simple Case",
          "investigator": "Inspector Gadget",
          "elasticSearchSettings": {
            "index.refresh_interval": "60s",
            "nuix.transport.hosts": "127.0.0.1:9300",
            "cluster.name": "elasticsearch",
            "index.number_of_replicas": "0",
            "nuix.index.auto_close": "false",
            "index.number_of_shards": "5",
            "xpack.security.transport.ssl.enabled": "false"
          }
        }
      }
      self.out['started'] = int(round(time.time() * 1000))
      utilities.getCaseSubsetExporter().exportItems(items, self.exportPath, options);
    except Exception, e: 
      self.exceptions.append(str(e))

    self.out['finished'] = int(round(time.time() * 1000))
    return self.out

processor = ElasticsearchCaseSubset("/Cases/ESCaseSubsetUserScript", "file-extension:html")
response.setBody(processor.process())

Example Request

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/ab490af89d29460db0011f105ce6a340/userScripts' \
--header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "fileName": "ElasticsearchCaseSubset.rb",
  "language": "RUBY",
  "async": false
}'

wget --no-check-certificate --quiet \
  --method PUT \
  --timeout=0 \
  --header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --body-data '{
  "fileName": "ElasticsearchCaseSubset.rb",
  "language": "RUBY",
  "async": false
}' \
   'http://localhost:8080/nuix-restful-service/svc/v1/cases/ab490af89d29460db0011f105ce6a340/userScripts'

Getting Started: Tagging

Sun, 12 Jan 2020 00:00:00 +0000

Example Scripts

query="file-extension:pdf"
items=$current_case.searchUnsorted(query)

items.each do |item|
    item.addTag("pdf")
end

response.setBody(items.length())

query="file-extension:pdf"
items=current_case.searchUnsorted(query)

for (item in items) {
    item.addTag("pdf");
}

response.setBody(items.length)

query="file-extension:pdf"
items=current_case.searchUnsorted(query)

for item in items:
    item.addTag("pdf")
    
response.setBody(len(items))

Example Request

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/{caseId}/userScripts' \
--header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "fileName": "tagItems.rb",
  "language": "RUBY",
  "async": false
}'

wget --no-check-certificate --quiet \
  --method PUT \
  --timeout=0 \
  --header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --body-data '{
  "fileName": "tagItems.rb",
  "language": "RUBY",
  "async": false
}' \
   'http://localhost:8080/nuix-restful-service/svc/v1/cases/{caseId}/userScripts'

Getting Started: Install on Linux

Thu, 22 Jul 2021 00:00:00 +0000

Depending on the configuration of your system, Nuix RESTful Service can be installed into both graphical and non-graphical environments using the same installer.

Warning

A JRE is not bundled with the Linux installers provided by Nuix RESTful Service. The latest version of Java 11 for your environment must be installed prior to installing Nuix RESTful Service on Linux.

If performing an upgrade, ensure that a backup of your existing Java Options is made prior to installation as these values will be overwritten. These values can be found in the bin/setenv.sh file within your installation directory. See Verifying Java Options after completing your upgrade for steps on adding these configurations back to installation.

Prerequisites

The following prerequisites must be installed prior to using Nuix RESTful Service in a Linux environment.

GTK+ graphical user interface library
X11 Screen Saver extension library
Chromium browser (if using OCR)

Perform the following steps to install all prerequisites:

Open a terminal within your Linux environment:
Based on your operating system, enter one of the following commands to install the dependences:
- Debian/Ubuntu: apt-get install libgtk-3-0 libxss1 xvfb
If using the Nuix OCR Addon, install the Chromium browser using the following command:
```
sudo apt install --assume-yes chromium-browser
```
After installation completes, start the X-Server Virtual Framebuffer using the following command:
```
Xvfb :1 &
```
Note
This command only needs to be performed after the initial installation or if the xvfb process is ever terminated.

Installation

Perform the following steps to install Nuix RESTful Service.

Download the Linux installer from the Nuix Customer Portal.
Open a terminal and navigate to the directory that contains the installer.

Enter the following command to untar the installer:

tar xvf [path to installer]rest-OEM-linux_[version].tar

Enter the following command to assign execute privileges for the installer to the current user:
```
sudo chmod u+x rest-OEM-linux_[version].sh
```
Enter the following command to run the installer:
```
./rest-OEM-linux_[version].sh
```
The installer may take a moment to prepare the wizard. When complete, follow the steps within the wizard to complete the installation. If installing in a non-graphical environment, the following steps will be presented within the terminal.
From the Welcome Screen, click Next to begin.

Note

If a previous version of Nuix RESTful Service is already installed, the following options are provided:

Update the existing installation
Create a new installation in a separate location.

Choosing to update will bypass all further configuration steps within the wizard and begin the installation process using the configurations defined within the previous installation.

Read and understand the terms included in the Nuix End User License Agreement.
- If you agree to the terms, select I accept the agreement, and click Next.
If installing for the first time, choose a location to install Nuix RESTful Service.
- Click Next to accept the default location and proceed.
- Alternatively, click Browse to choose a specific location for the installation.
Click Next to perform the installation.
On the License Server Type screen, select the option that matches the server type you are using for licensing, then click Next.
- Nuix Management Server (NMS)
- Relay server with NMS users
- Relay server with CLS users
- Cloud License Server (CLS)
If NMS or a Relay server was selected, enter the following details on the License Server Configuration screen, then click Next:

Note
If CLS is selected as the server type, this step is skipped.
- Server address: The URL used to access a configured Nuix Management Server.
- Server port: The server port used to access the configured Nuix Management Server.
On the License Server Credentials screen, enter the credentials for an account that has access to the selected server type, then click Next.
Review and make changes, if necessary, to the details provided on the Java & Folder Options screen.

Option	Description
Java Options	Optimize the Java settings used by Nuix RESTful Service to suit your hardware specifications. Define one argument per line. Default settings are recommended for most configurations. For help or assistance with tuning your JVM settings, contact the Nuix Support team at https://nuix.service-now.com/support.
IP Address or Hostname	The URL used to access Nuix RESTful Service.
Connection Timeout	Specify the amount of time that REST should wait for a response after accepting a connection. Use a value of -1 to indicate no timeout.
HTTP Port	The server port used to access Nuix RESTful Service.
Case Directory	Specify a location where case files are stored.
User Scripts Directory	Specify a location where user generated scripts are stored.
Logs Directory	Specify a location to save logs generated by Nuix RESTful Service.

After reviewing the Java & Folder Options screen, click Next to continue.
Specify how Nuix RESTful Service should be run:

Option	Description
Service	Run Nuix RESTful Service in the background as a service.
Application	Run Nuix RESTful Service as a standalone application. See Starting in Application Mode after installation completes for details on starting the application.
Start Service	Select this checkbox, if the Service option was selected, to start Nuix RESTful Service when installation completes.

Click Finish to complete the setup and exit the wizard.

Post-Installation Configuration

After completing the installation of Nuix RESTful Service, the following configurations should be considered.

Verifying Java Options

If upgrading from an installation earlier than version 7.8, backed up Java Options can be added back to the installation after the upgrade using the following steps.

To add any of these options to your existing installation:

Navigate to the location where Nuix RESTful Service is installed.
- Debian/Ubuntu default path: /opt/nuix-restful-service
Locate and open Nuix-REST.vmoptions within a text editor.
Modify the file, adding one argument per line.
Save and exit the editor.
Restart Nuix RESTful Service.

Starting in Application Mode

If Nuix RESTful Service was configured to be run as a standalone application, the service must be manually started and stopped.

To start Nuix RESTful Service in Application Mode:

Open a terminal.
Navigate to the location where Nuix RESTful Service is installed.
- Debian/Ubuntu default path: /opt/nuix-restful-service
Start the application using the following command:
```
./nuix-rest start
```
Stop the application using the following command:
```
./nuix-rest stop
```

Verifying Your Installation

Once your installation is complete, complete the following steps to verify your deployment:

Open a web browser and enter the following URL

localhost:8080/nuix-restful-service/svc/v2/about

If the installation was successful, the response body will return with information about the RESTful service.

 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "72670a5e-f0e1-4046-8b2e-22a42fe2ac9a",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null
}

API Documentation

The API reference documentation is included with Nuix Restful Service and can be accessed at the following URL after installation.

http://<localhost>:8080/nuix-restful-service/svc/docs

Getting Started: Applying Permissions to the Application

Wed, 21 Jul 2021 00:00:00 +0000

Once you have registered and configured an authentication method for your Azure application, API permissions must be assigned to the application to allow access to specific data types within Microsoft Office 365.

Perform the following steps to apply the required API permissions to the application.

Access the Overview page of your newly created application.

Tip
To access this page from the Azure portal Home page, select Azure Active Directory from the home page then App registrations from the left navigation panel. Finally, click on the name of the new application to access its Overview page.
Select API permissions from the left navigation panel and then click Add a permission.
From the list of Commonly used Microsoft APIs, select Microsoft Graph.
Click Delegated permissions and then select the following permission:

API/Permission Name	Type	Description
`Chat.Read`	Delegated	Read user chat messages
`Group.Read.All`	Delegated	Read all groups
`Mail.Read`	Delegated	Read user mail
`User.Read.All`	Delegated	Read all users' full profiles

Return to the top of the page and click Application permissions to change the permission type, then select the following permissions:

API/Permission name	Type	Description
`Calendars.Read`	Application	Read Calendars in all mailboxes
`Channel.ReadBasic.All`	Application	Read the names and descriptions of all channels
`ChannelMember.Read.All`	Application	Read the members of all channels
`ChannelMessage.Read.All`	Application	Read the chat messages from all channels
`ChannelSettings.Read.All`	Application	Read the names, descriptions, and settings of all channels
`Chat.Read.All`	Application	Read all chat messages
`Contacts.Read`	Application	Read contacts in all mailboxes
`Directory.Read.All`	Application	Read directory data
`Files.Read.All`	Application	Read files in all site collections
`Group.Read.All`	Application	Read all groups
`Mail.Read`	Application	Read mail in all mailboxes
`OrgContact.Read.All`	Application	Read organizational contacts
`Sites.Read.All`	Application	Read items in all site collections (preview)
`User.Read.All`	Application	Read all users' full profiles

After all the specified API permissions have been selected, click Add permissions from the bottom of the view to apply the selections.
The newly added API permissions are initially displayed with a Not Granted status. Click Grant admin consent for <AD Tenant name> to update the status.

Note
By granting admin consent, the Service Principal account for the selected AD tenant is granted access to the selected API permissions. The defined application permissions provide access to specific data contained within Microsoft Teams, Exchange, and SharePoint.
Proceed to the next topic to request access to the protected APIs.

Getting Started: Clustering

Thu, 22 Apr 2021 00:00:00 +0000

Important

Pilot Program Only - Not GA until Nuix 10.0. Please direct all inquires regarding the Pilot Program to rest-pilot@nuix.com.

Nuix RESTful Service supports clustered installations to enable distributed workloads across multiple nodes within a cluster. When configured as a cluster, requests submitted to REST are managed and distributed across the cluster with no further action from the user.

Clustering Concepts

A clustered environment consists of two or more Nuix RESTful Service instances that have been configured to communicate and share data with each other over a network. Each instance represents a node within the cluster. Nodes are further classified by roles, which are defined during setup and determine what function the node can perform within the cluster. The following two roles are available.

Producer role: Nodes that are assigned the producer role function as the primary server (base URL) for all calls submitted to the API. Producer nodes are responsible for receiving incoming calls, queuing requests, processing non-cluster-enabled functions, and relaying results from across the cluster back to the user.
Consumer role: Nodes that are assigned the consumer role are responsible for performing the cluster-enabled requests in the job queue based on the node’s capacity and availability.

As requests are submitted to the cluster, they are picked up and processed immediately. If the cluster is at capacity, the requests will instead be added to a queue and processed by the first consumer node that becomes available or gains additional capacity.

Consumer nodes can accept new requests if the following criteria are met:

The request is for a cluster-enabled function.
The request can be performed immediately.
The case associated with a request is available to the node.
The node has capacity, which is defined by the following restrictions:
- Worker-based tasks: Limited to one request per node simultaneously.
- Non-worker-based tasks: Can perform multiple requests simultaneously.
- Based on the resources available to the node, it may be capable of performing both types of requests simultaneously.

If any of the criteria cannot be met by a consumer node, the request will remain in the queue until another node within the cluster becomes available.

Note

Communication between nodes is not encrypted by default.

Server Tags

To optimize and steer the distribution of requests throughout a cluster, server tags can be implemented to control the type of requests that are performed by specific nodes. Server tags are simple user-defined labels, such as OCR or Worker-Based, that are applied to consumer nodes during clustering setup.

Once configured, requests that are submitted with a specific server tag will be routed to and processed by a node that has a matching tag. Requests submitted without a tag will continue to be processed by the first available consumer node.

Warning

Requests that are submitted with a server tag that does not exist within the cluster will never be processed.

To identify server tags that exist within the cluster before submitting a request, see Viewing the Cluster.

The practice of server tagging can be beneficial if trying to prioritize calls that are submitted to the API. For instance, separating worker-based requests from non-worker-based requests. Functions that require workers, such as ingestion, OCR, and exports can often be long running resource intensive processes. By using server tags, these types of requests can be steered towards dedicated nodes within the cluster that are better provisioned to handle these types of jobs.

Tip

Nodes that have been configured with server tags are not restricted from processing untagged requests. If a request is submitted to the cluster and a tagged node is the first available node to meet all criteria required to accept a request, it will do so.

Prerequisites for Creating a Cluster

To set up a Nuix RESTful Service clustered environment, the following prerequisites must be addressed.

Two or more installed instances of Nuix RESTful Service.
- The IP addresses of all nodes included in the cluster must be known to complete the following configurations.
Access to Nuix Licensing using any of the following options:
- Nuix Management Server (NMS)
- Nuix Cloud License Server (CLS)
Networked file storage for shared resources.
Elasticsearch v7.8.1

Important

Only Elasticsearch based cases are supported within clustered environments.

Clustering requires the use of networked file storage to ensure all nodes within the cluster have access to the same data. Before you begin, ensure that a network file share is available and accessible from all nodes included in the Nuix RESTful Service cluster.

Note

The location of all network shares must be accessible using UNC paths.

The following directories must be created and configured as individual network shares:

Share Name	Description
`source data/`	Location to store raw evidence that has not yet been processed into a case.
`cases/`	An Elasticsearch based inventory location where cases are created and stored.
`user-data/`	Location to store artifacts and profiles that are used when processing evidence. The `user-data` directory is comprised of the following sub-directories that each store a different type of artifact. Tip: Create only the subdirectories that will be used in your workflows. `
`exports/`	Location to store exports generated by Nuix RESTful Service.
`thumbnails/`	Location to store thumbnails that are generated within a case.
`scripts/`	Location to store user-generated scripts for use with Nuix RESTful Service.

Configuring REST Instances

After all prerequisites have been addressed, use the following procedure to set up a clustered Nuix RESTful Service environment.

Note

This procedure must be performed on each node within the cluster.

Ensure that the instance of Nuix RESTful Service being modified has been stopped.
Navigate to the settings directory within the Nuix RESTful Service installation.
- Windows: <InstalDir>/Nuix/Nuix RESTful Service/settings
- Linux: /opt/nuix-restful-service/settings
Open the application.properties file within a text editor.
Modify the file by configuring the following properties to enable clustering and identify the role of the node within the cluster.
1. Enable the node to participate in the cluster by adding the following property:
```
cluster.enabled=true
```
2. Add one of the following properties to specify the node’s role within the cluster:
  - Producer role: The primary server for all calls submitted to the API. Producer nodes are responsible for receiving incoming calls, queuing requests, and relaying results from across the cluster back to the user.
  - Consumer role: Consumer nodes are responsible for performing the queued requests based on the node’s availability.
```
cluster.roles=producer
```
  Note: The cluster must contain at least one producer and consumer node.
3. Optionally, define a server tag that can be used to steer requests to this specific node.
```
server.tags=Worker-based
```
  If the node is expected to receive multiple types of requests, a comma separated list of tags can also be defined:
```
server.tags=Worker-based,OCR,Export
```
4. Update the values of the following existing properties to reflect the UNC paths of the network share locations that were previously created .
```
exportsFolder=\\10.130.138.177\exports
inventoryLocations=\\10.130.138.177\cases
searchThumbnailsExportDirectory=\\10.130.138.177\thumbnails
userScriptsLocation=\\10.130.138.177\scripts\
nuix.engine.userDataDirs=\\10.130.138.177\user-data\
```
5. Add the following property to identify nodes within the cluster. Provide a comma-separated list of IP addresses that represent all nodes included within the cluster.
```
hazelcastTcpIpMembers=<IPofNode1>,<IPofNode2>,<IPofNode3>
```
6. Verify that the publicURL property is set to an address that is accessible from all other nodes within the cluster.
Save and exit the file.
Restart Nuix RESTful Service.
Repeat this procedure until all nodes within the cluster have been configured.

Viewing the Cluster

After all nodes within your environment have been configured for clustering, you can check your cluster by submitting a GET request to the /cluster endpoint. This request should be submitted to a node within the cluster that has been configured with the producer role.

curl -L -X GET 'http://10.30.100.58:8080/nuix-restful-service/svc/v1/cluster' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "nodes": [
        {
            "hostAddress": "192.168.7.32",
            "hostName": "node01.nuix.com",
            "port": 5601,
            "details": {
                "serverId": "637edbff-3e1c-4f63-921e-da022a763fbf",
                "publicURL": "http://10.30.100.58:8080",
                "name": "REST-Node-1",
                "tags": [OCR,Export],
                "guid": "210ee909-3cdf-3f3a-b973-2cf4d7c7aea2"
            }
        },
                {
            "hostAddress": "192.168.7.12",
            "hostName": "node02.nuix.com",
            "port": 5602,
            "details": {
                "serverId": "432iunff-5h1a-8j67-738b-ic9344f643unf",
                "publicURL": "http://10.30.100.83:8080",
                "name": "REST-Node-2",
                "tags": [Worker-based],
                "guid": "468uj828-7uct-6h1s-m878-5hg5d9v6ema1"
            }
        }
    ]
}

After submitting the request, details about each available node are returned, including:

The name and location of the node.
The port where the node is operating.
Any server tags associated with the node.
A unique server GUID, useful for identifying a specific node.

Submitting Requests to the Cluster

When operating within a clustered Nuix RESTful Service environment, the process of submitting requests is no different from interacting with a single instance of Nuix REST.

To get started, you need to know the location of a node within the cluster that has been designated as a Producer. If multiple producers are available, any one can be used. Once identified, all calls to the cluster should be made to that node.

After a request is received, if the call is for a cluster-enabled function, the request will be added to the queue for the first available consumer node to pick up. If the call is for a non-cluster-enabled function, the producer node will simply perform the request itself.

Cluster-enabled functions are those that can be run asynchronously by any consumer node within the cluster. These functions are identified within the embedded API reference documentation (localhost:8080/nuix-restful-service/svc/docs) using the Cluster Enabled Operation label.

Submitting Requests with Server Tags

If server tags have been implemented within your cluster, you can use them in your calls by defining the following RAW data in the body of your requests.

--data-raw 
'{
  "restClusterSettings": {
      "nodeTags": {
          "defaultTags": ["Worker-based"]
      }
  },
}'

Getting Started: Checking Server Status

Thu, 22 Apr 2021 00:00:00 +0000

Before making any calls to the Nuix RESTful Service API, it is best practice to first ensure that the service is running and available.

The Nuix RESTful Service server status can be checked using the following GET request to the /about endpoint.

curl -X GET "http://127.0.0.1:8080/nuix-restful-service/svc/about" -H "accept: application/vnd.nuix.v2+json"

{
 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "rest-oem-server",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null
}

If the service is available, a response similar to this example will be returned.

Note: In this example, some of the response values have returned null values. These values are intentionally not returned because the request was submitted without an authentication token.

Getting Started: Version 9.2 Release Notes

Tue, 20 Apr 2021 00:00:00 +0000

Nuix Engine

Nuix RESTful Service has been updated to use version 9.2 of the Nuix Engine. Details about what is included with this update can be found in the v9.2 changelog.

Nuix Developer Documentation

Nuix is proud to announce the introduction of the Nuix Developer Portal as a new source for online based Nuix SDK developer documentation.

Access the portal to find the latest documentation for installing and configuring your instance of Nuix RESTful Service, API references, quick start guides, tutorials, code samples, and more.

Visit https://nuix.github.io/sdk-docs/latest/ to access to the latest Nuix SDK developer documentation to help automate your workflows using the Nuix APIs.

Promote to Nuix Discover®

Nuix RESTful Service now supports the ability to export items from a Nuix case directly to an existing Nuix Discover SaaS case using the new Promote to Nuix Discover endpoint

/cases/{caseId}/promoteToDiscover/{discoverCaseId}

With this endpoint, users can promote a subset of discoverable items to an existing Nuix Discover SaaS case for further analysis, review, and production.

Access

The /authenticatedUsers/login endpoint has been updated to now accept both US and UK spellings of the licenseShortName parameter. Accepted parameter spellings include:

licenseShortName - (US)
licenceShortName - (UK)

Processing

The default values associated with the ProcessorSettings parameter have been updated to match the current version of the Nuix Engine.

General Enhancements

The Dnuix.executor.threads system property has been removed from the default startup java options used by Nuix RESTful service.

Resolved Issues

Nuix RESTful Service no longer sets a system path variable for the Nuix Engine in Windows based installations. This modification allows multiple instances of the Nuix Engine to coexist on the same machine.
Instances where source evidence is missing or has been removed from a case are now indicated with the correct error message.
An issue has been resolved that caused a null pointer exception to occur when making calls to the /cases/{caseId}/thumbnails endpoint.
Nuix Server has been added as a valid Nuix license type that can be consumed by Nuix RESTful Service.
Accessing the API Swagger documentation at http://<serverName>:8080/nuix-restful-service/svc/docs no longer causes a 401 Unauthorized Error due to a jsessionid being appended to the URL after redirect.
Custom processing profiles are no longer ignored and replaced with default processing settings when using the Nuix Scripting API.

Getting Started: Compound Case Creation

Thu, 11 Feb 2021 00:00:00 +0000

Create a Compound Case

Now that you are authenticated, lets create your first Nuix compound case.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloCompoundCase",
   "location":"inventory0",
   "description":"My first Nuix compound Case",
   "compound":true,
   "investigator":"Inspector Gadget"
}'

{
    "caseId": "967db64ab9944daebf4d34fcad6b5e8f",
    "name": "HelloCompoundCase",
    "path": "/Cases/HelloCompoundCase",
    "description": "My first Nuix compound Case",
    "investigator": "Inspector Gadget",
    "creationDate": 1613066921882,
    "compound": true,
    "elastic": false,
    "binaryStoreLocation": "",
    "indexId": "",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "caseName": "HelloCompoundCase",
    "casePath": "/Cases/HelloCompoundCase",
    "caseDescription": "My first Nuix compound Case",
    "caseCreationDate": 1613066921882,
    "caseInvestigator": "Inspector Gadget"
}

You have now successfully created your first compound case! Take note of your case ID 967db64ab9944daebf4d34fcad6b5e8f. Next, we have to add simple child cases to the compound case. Let’s create two simple child cases and add them to the compound case.

Create Child Case 1

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloChild-1",
   "location":"inventory0",
   "description":"About My first child case",
   "compound":false,
   "investigator":"Inspector Gadget"
}'

{
    "caseId": "521b4f8f875541d2b2c5912f927897e2",
    "name": "HelloChild-1",
    "path": "/Cases/HelloChild-1",
    "description": "About My first child case",
    "investigator": "Inspector Gadget",
    "creationDate": 1613067156583,
    "compound": false,
    "elastic": false,
    "binaryStoreLocation": "",
    "indexId": "",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "caseName": "HelloChild-1",
    "casePath": "/Cases/HelloChild-1",
    "caseDescription": "About My first child case",
    "caseCreationDate": 1613067156583,
    "caseInvestigator": "Inspector Gadget"
}

Create Child Case 2

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloChild-2",
   "location":"inventory0",
   "description":"About My second child case",
   "compound":false,
   "investigator":"Inspector Gadget"
}'

{
    "caseId": "1a33156e3be34e7ea74a77912be526f3",
    "name": "HelloChild-2",
    "path": "/Cases/HelloChild-2",
    "description": "About My second child case",
    "investigator": "Inspector Gadget",
    "creationDate": 1613067352626,
    "compound": false,
    "elastic": false,
    "binaryStoreLocation": "",
    "indexId": "",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "caseName": "HelloChild-2",
    "casePath": "/Cases/HelloChild-2",
    "caseDescription": "About My second child case",
    "caseCreationDate": 1613067352626,
    "caseInvestigator": "Inspector Gadget"
}

Adding Child Cases to a Compound Case

Finally, let’s add our two simple child cases that we just created to our compound case. The childCases endpoint simply acknowledges the addition of the child cases to the compound case by returning a HTTP status code of 200

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/967db64ab9944daebf4d34fcad6b5e8f/childCases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '[ "521b4f8f875541d2b2c5912f927897e2", "1a33156e3be34e7ea74a77912be526f3" ]'

You have now successfully created your first compound case! Next, let’s ingest some data!

Getting Started: Node Steering

Thu, 11 Feb 2021 00:00:00 +0000

Steering Tags

While no action is required to perform tasks in the cluster, it is possible to steer requests to a specific server or a group of servers. This is accomplished by providing an array of server tags specified in the server.tags field for the server in the application.properties file in combination with nodeTags provided on the request itself.

This example will assume we have two servers. The first server is configured on the server side as a coordinator node. All clustered HTTP requests should be sent through a coordinator node. The second server is configured on the server side as a consumer with a server.tags field equal to worker.

Ingestion Steering

As you can see this request differs slightly from a typical file ingestion request. We have added the restClusterSettings object to the request and have specified that a server tagged as a worker should process this request through the use of nodeTags on the request.

Note

We do not need to submit this request directly to the worker server. Instead, we will submit the request to the coordinator and let Nuix REST handle the task distribution internally.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/776a45b03d1841379b1dea524098a33b/evidence/file' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "processorSettings": {
   	"storeBinary": true
   },
   "target": {
    "path": "/Engines/9.0.0.171/doc"
  },
  "restClusterSettings": {
      "nodeTags": {
          "defaultTags": [ "worker" ]
      }
   }
}
'

{
    "functionKey": "62a120ce-bebe-492c-bbb5-fd68c99bb0db",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/62a120ce-bebe-492c-bbb5-fd68c99bb0db"
}

Ingestion Status

The functionKey field returned from the ingestion endpoint above can be polled for status.

Note

It is important to note that we are polling status from the coordinator node. Nuix REST will handle retrieving status from node that is actually performing the work.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/62a120ce-bebe-492c-bbb5-fd68c99bb0db' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "eb4afd86-913f-4b52-8781-07d0523a5fd1",
    "functionKey": "62a120ce-bebe-492c-bbb5-fd68c99bb0db",
    "progress": 7581225,
    "total": 0,
    "percentComplete": null,
    "updatedOn": 1613072891973,
    "status": null,
    "statusId": null,
    "requestTime": 1613072849860,
    "startTime": 1613072850818,
    "finishTime": 1613072895964,
    "caseId": "776a45b03d1841379b1dea524098a33b",
    "caseName": "HelloElasticCase",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "/Cases/HelloElasticCase",
    "requestor": "username",
    "action": "AsyncBulkIngestionFunction",
    "options": {
        "reloadQuery": null,
        "processorSettings": {
            "processText": null,
            "processLooseFileContents": null,
            "processForensicImages": null,
            "analysisLanguage": null,
            "stopWords": null,
            "stemming": null,
            "enableExactQueries": null,
            "extractNamedEntities": null,
            "extractNamedEntitiesFromText": null,
            "extractNamedEntitiesFromProperties": null,
            "extractNamedEntitiesFromTextStripped": null,
            "extractShingles": null,
            "processTextSummaries": null,
            "calculateSSDeepFuzzyHash": null,
            "detectFaces": null,
            "extractFromSlackSpace": null,
            "carveFileSystemUnallocatedSpace": null,
            "carveUnidentifiedData": null,
            "carvingBlockSize": null,
            "recoverDeletedFiles": null,
            "extractEndOfFileSlackSpace": null,
            "smartProcessRegistry": null,
            "identifyPhysicalFiles": null,
            "createThumbnails": null,
            "skinToneAnalysis": null,
            "calculateAuditedSize": null,
            "storeBinary": true,
            "maxStoredBinarySize": null,
            "maxDigestSize": null,
            "digests": [],
            "addBccToEmailDigests": null,
            "addCommunicationDateToEmailDigests": null,
            "reuseEvidenceStores": null,
            "processFamilyFields": null,
            "hideEmbeddedImmaterialData": null,
            "reportProcessingStatus": null,
            "workerItemCallback": null,
            "workerItemCallbacks": null
        },
        "evidence": [
            {
                "guid": null,
                "name": null,
                "customMetadata": null,
                "encoding": null,
                "custodian": null,
                "timeZone": null,
                "description": null,
                "locale": null,
                "files": [
                    {
                        "path": "/Engines/9.0.0.171/doc"
                    }
                ],
                "exchangeMailboxes": null,
                "s3Buckets": null,
                "sqlServers": null,
                "enterpriseVaults": null,
                "sharepointSites": null,
                "mailStores": null,
                "loadFiles": null,
                "centeraClusters": null,
                "splitFiles": null,
                "dropboxes": null,
                "sshServers": null
            }
        ],
        "localWorkerCount": 1,
        "repositories": [],
        "parallelProcessingSettings": {
            "workerCount": null,
            "workerMemory": null,
            "workerTemp": null,
            "brokerMemory": null,
            "workerBrokerAddress": null,
            "useRemoteWorkers": false,
            "embedBroker": true
        },
        "rescanEvidenceRepositories": false,
        "loadProcessingJob": {
            "casePath": "/Cases/HelloElasticCase",
            "jobGuid": "143cae10-1825-433b-8de4-71aa5ac0a722",
            "processingMode": "Load",
            "startDate": 1613072863682,
            "workerCount": 1,
            "finished": true,
            "paused": false,
            "masterAddress": "192.168.86.53",
            "bytesProcessed": 7581225,
            "itemsProcessed": 192,
            "jobSizeTotalBytes": 0
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-2",
    "errorMsg": null
}

As you can see from polling the status, the response contains a processedBy field and this task was processed by nuix-restful-server-2.

Congratulations! You have successfully performed your first clustered ingestion and have distributed your workload.

Getting Started: Part 2: Verifying your Licenses

Tue, 09 Feb 2021 00:00:00 +0000

Licensing

Prior to consuming endpoints from the Nuix RESTful Service, it is important to have your licensing properly configured. You can check if your license server has been properly configured by invoking the /v1/licenses endpoint. This endpoint does not require authentication.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/licenses'

[
    {
        "source": null,
        "type": null,
        "location": null,
        "shortname": "enterprise-workstation",
        "count": 10,
        "configuredCount": 10,
        "description": "Nuix eDiscovery Workstation",
        "workers": 10,
        "configuredWorkers": 10,
        "audited": false,
        "auditThreshold": 0,
        "expiry": null,
        "features": null,
        "legalHoldHoldCountLimit": null,
        "concurrentUserLimit": null,
        "canChooseWorkers": true
    }
]

Getting Started: Running Scripts In Nuix Workstation

Tue, 16 Jun 2020 00:00:00 +0000

Nuix provides an API which supports execution of scripts written in Ruby, Python and ECMA Script (AKA Javascript). Scripts can be used to automate almost anything that can be accomplished manually through the Graphical User Interface (GUI) of Nuix Workstation. Scripts also enable more advanced processes which cannot be easily accomplished manually in the GUI. A script can be executed several different ways:

The scripts menu in Nuix Workstation provides a convenient way to execute scripts:

System level scripts accessible to all users on the system can be placed in the directory C:\ProgramData\Nuix\Scripts
User level scripts accessible to a particular user can be placed in the directory C:\Users\USERNAME\AppData\Roaming\Nuix\Scripts where USERNAME is the specific user’s name.

Scripts placed in these directories are discovered in one of the following ways:

As individual files with extensions .rb for Ruby, .py for Python and .js for ECMA Script (AKA Javascript) (see below)
As script bundles (see below)

Individual files

As individual files with extensions .rb for Ruby, .py for Python and .js for ECMA Script (AKA Javascript) (see below) As script bundles (see below)

.rb for Ruby
.py for Python
.js for ECMA Script (AKA Javascript)

While populating entries in the Scripts menu, Nuix inspects the first several lines of each script file found for the presence of several special comments:

Menu Title – Specifies the label used for this script’s entry in the Scripts menu.
Needs Case – Specifies whether this script requires a case to be open in the Workstation interface before the script can be ran. A value of true means the script will be disabled in the menu when no case is open. If your script is going to work with the global variable $current_case, it is a good idea to set this to true.
Needs Selected Items – Specifies whether this script requires items to be checked in the results view before this script can be ran. A value of true means the script will be disabled in the menu if no items are currently checked in the results view. If your script is going to work with the global variable $current_selected_items, it is a good idea to set this to true.

An example of this in a Ruby script looks like the following:

# Menu Title: My Export Script
# Needs Case: true
# Needs Selected Items: true

puts "Export code would go here..."

This is convenient for single file scripts. As a script gets more complex it may begin to span multiple files, in which case you may want to instead use a script bundle (see below).

Script bundles

Scripts which are more complex and span multiple files are better served as a script bundle. When using a script bundle multiple script files are represented in the scripts menu as only a single menu entry. For example, imagine you have a Ruby script which consists of 3 files, the main script file and 2 supporting files which are loaded by the main script file at run-time. Without a script bundle, each of the 3 files would get a script menu entry, while only 1 of those files is intended actually be executed directly.

To make a script bundle, you need to do several things:

Place your script in a sub-directory of a scripts folder with a name ending in .nuixscript, for example a directory named MyExportScript.nuixscript
In your script bundle sub-directory have a file named metadata.properties (more on this below)
In your script bundle sub-directory have one or more script files (.rb, .py, .js)

The metadata.properties file is a standard Java properties formatted file. This files provides Nuix information about the script similar to the special comments which can be provided in individual script files. This file supports the following entries:

MainScript – This required entry instructs Nuix of the primary script file in the Script Bundle which is to be executed when the corresponding Scripts menu entry is clicked.
MenuTitle – This entry instructs Nuix as to what label should be used in the Scripts menu for this script.
NeedsCase – This entry instructs Nuix as to whether your script requires that a case be open in the Nuix Workstation GUI before being ran. When this value is set to true, the script’s entry in the Scripts menu will be disabled if a case is not currently open.
NeedsSelectedItems – This entry instructs Nuix as to whether you script requires that items are checked in the results view before being ran. When this value is set to true, the script’s entry in the Scripts menu will be disabled if no items are currently checked in the results view.
SmallIcon – This entry specifies the icon used for this script’s menu entry. Value provided should be the file name (without directory) of an image file in the same directory as the metadata.properties file. Most common image formats are supported, but PNG files are the convention.
MenuKeyboardShortcut – This entry specifies a keyboard shortcut to be associated to this script’s menu entry.
MenuMnemonic – This entry specifies the mnemonic underlined in the menu. Provided value should be a single character which is present in the name.

An example of this file might look like the following:

MainScript=MyExportScript.rb
MenuTitle=My Export Script
NeedsCase=true
NeedsSelectedItems=true
SmallIcon=icon.png
MenuKeyboardShortcut=ctrl shift E
MenuMnemonic=E

From the Script Console

You can also run a script using the Script Console dialog in the Workstation interface:

Once the script console dialog is up, you may paste or type your code into the upper text area. Make sure you select the appropriate script language. Then click the Execute button to run it. While your script is running you may click the Cancel button to terminate it early.

Note

When a script is executed via the scripts menu, the output of that script will also show up in the script console’s output area.

From the Command Line Interface

When you install Nuix Workstation, part of that installation is the executable file nuix_console.exe. This is a “headless” version of Nuix which specializes in executing scripts. When ran, this version of Nuix will startup without a GUI and then proceed to execute the script you specify.

If you have Nuix Workstation installed here: C:\Program Files\Nuix\Nuix 7.8

And you have a Ruby script located here: D:\NuixScripts\MyExportScript.rb

Than you can run the following command to run that script using nuix_console.exe:

"C:\Program Files\Nuix\Nuix 7.8\nuix_console.exe"

"D:\NuixScripts\MyExportScript.rb"

nuix_console.exe supports many of the same arguments that the Nuix Workstation executable does: "C:\Program Files\Nuix\Nuix 7.8\nuix_console.exe" -Xmx24g -licencesourcetype dongle "D:\NuixScripts\MyExportScript.rb"

If you intend to run nuix_console.exe with a license obtained from a Nuix license server that requires username/password authentication, you will need to set environment variables with appropriate values for username and password. In Windows this can be accomplished by doing the following in a batch file:

SET NUIX_USERNAME=username
SET NUIX_PASSWORD=password
"C:\Program Files\Nuix\Nuix 7.8\nuix_console.exe" ^
-Xmx24g ^
-Dnuix.registry.servers=127.0.0.1 ^
"D:\NuixScripts\MyExportScript.rb"

It is worth noting that scripts executed using nuix_console.exe will not have the following variables populated as they would be in the GUI:

$current_case – Since there is no GUI for the user to have opened a case in.
$current_selected_items – Since there is no GUI for the user to have selected items in.
$window – Since there is no GUI for the Window object to refer to.

Getting Started: Custom Processing

Sun, 12 Jan 2020 00:00:00 +0000

class CustomProcessor
    def initialize(case_path, case_name, process_this)
        @case_path = case_path
        @case_name = case_name
        @process_this = process_this
        @out = Hash.new
        @items = Array.new
        @exceptions = Array.new
    end

    def process
        begin
            case_settings = {:compound => false, :name => "#{@case_name}", :description => "Simple Case", :investigator => "Inspector Gadget"}
            current_case = $utilities.caseFactory.create("/Cases/CustomProcessing", case_settings)
            processor = current_case.createProcessor()
            processor.processing_settings = {:report_processing_status => "physical_files",
                                             :enable_custom_processing => ["text", "properties", "binary"]
            }
            processor.parallel_processing_settings = {:worker_count => 2, :worker_memory => 2000 }
            processor.when_item_processed do | callback |
                begin
                    item = Hash.new
                    item[:mimetype] = callback.getMimeType()
                    unless callback.getBinaryFile().nil?
                        item[:path_to_binary] = callback.getBinaryFile().toString()
                    end
                    item[:properties] = callback.properties
                    item[:text] = callback.getText()
                    item[:path] = callback.path
                    @items << item
                rescue => exception
                   @exceptions << {:class => exception.class.name, :message => exception.message}
                end
            end
            container = processor.new_evidence_container("Evidence-#{Time.now.strftime('%Y-%m-%d_%H-%M-%S')}")
            container.addFile(@process_this)
            container.save
            @out[:processing_started] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
            processor.process
            @out[:final_item_count] = @items.length()
            current_case.close
        rescue => exception
           @exceptions << {:class => exception.class.name, :message => exception.message}
        end
        @out[:exceptions] = @exceptions
        @out[:items] = @items
        @out[:processing_finished] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
        return @out
    end
end
$response.setBody(CustomProcessor.new("/Cases", "CustomProcessing", "/Engines/9.0.0.171/doc/api").process)

function CustomProcessor(casePath, caseName, processThis) {
  this.casePath = casePath;
  this.caseName = caseName;
  this.processThis = processThis;
  this.items = [];
  this.exceptions = [];
  this.out = {};
}

CustomProcessor.prototype.process = function() {
  try {
    var caseSettings = {};
    caseSettings['compound'] = false;
    caseSettings['name'] = this.caseName;
    caseSettings['description'] = 'Simple Case';
    caseSettings['investigator'] = 'Inspector Gadget';

    var currentCase = utilities.getCaseFactory().create(this.casePath + '/' + this.caseName, caseSettings);
    var processor = currentCase.createProcessor();

    var processingSettings = {};
    processingSettings['report_processing_status'] = 'physical_files';
    processingSettings['enable_custom_processing'] = ["text", "properties", "binary"];

    var parallelProcessingSettings = {};
    parallelProcessingSettings['worker_count'] = 2;
    parallelProcessingSettings['worker_memory'] = 2000;

    processor.setProcessingSettings(processingSettings);
    processor.setParallelProcessingSettings(parallelProcessingSettings);

    var self = this;
    processor.whenItemProcessed(function(callback) {
      try {
        var item = {};
        item['mimtype'] = callback.getMimeType();

        if(callback.getBinaryFile()) {
          item['path_to_binary'] = callback.getBinaryFile().toString();
        }

        item['properties'] = callback.getProperties();
        item['text'] = callback.getText();
        item['path'] = callback.getPath();
        self.items.push(item);
      } catch (err) {
        self.exceptions.push(err.message);
      }
    });

    var startTime = new Date().getTime().toString();
    var container = processor.newEvidenceContainer('Evidence-' + startTime);
    container.addFile(this.processThis);
    container.save();
    this.out['processing_started'] = startTime;
    processor.process();
    this.out['final_item_count'] = this.items.length;
    currentCase.close();
  } catch (err) {
    this.exceptions.push(err.message);
  }
  this.out['exceptions'] = this.exceptions;
  this.out['items'] = this.items;
  this.out['processing_finished'] = new Date().getTime().toString();
  return this.out;
}

$response.setBody(new CustomProcessor("/Cases", "CustomProcessing", "/Engines/9.0.0.171/doc/api").process())

import time
import os

class CustomProcessor:

  def __init__(self, case_path, case_name, process_this):
    self.case_path = case_path
    self.case_name = case_name
    self.process_this = process_this
    self.out = {}
    self.exceptions = []
    self.items = []

  def when_item_processed(self, callback):
    try:
      item = {}
      item['mimetype'] = callback.getMimeType();

      if callback.getBinaryFile() is not None:
        item['path_to_binary'] = callback.getBinaryFile().toString()

      item['properties'] = callback.getProperties()
      item['text'] = callback.getText()
      item['path'] = callback.getPath()
      self.items.append(item)
    except Exception, e:
      self.exceptions.append(str(e))


  def process(self):
    try:
      case_settings = {"compound": False, "name": self.case_name, "description": "Simple Case", "investigator": "Inspector Gadget"}
      current_case = utilities.getCaseFactory().create(os.path.join(self.case_path, self.case_name), case_settings)
      processor = current_case.createProcessor()
      processing_settings = {"report_processing_status": "physical_files", "enable_custom_processing": ["text", "properties", "binary"]}
      parallel_processing_settings = {"worker_count": 2, "worker_memory": 2000}

      processor.setProcessingSettings(processing_settings)
      processor.setParallelProcessingSettings(parallel_processing_settings)
      processor.whenItemProcessed(self.when_item_processed)
      started = int(round(time.time() * 1000))
      container = processor.newEvidenceContainer("Evidence-" + str(started))
      container.addFile(self.process_this)
      container.save()
      self.out['processing_started'] = started
      processor.process()
      self.out['final_item_count'] = len(self.items)
      current_case.close()
    except Exception, e:
      self.exceptions.append(str(e))

    self.out['finished'] = int(round(time.time() * 1000))
    self.out['exceptions'] = self.exceptions
    self.out['items'] = self.items
    return self.out

processor = CustomProcessor("/Cases", "CustomProcessing", "/Engines/9.0.0.171/doc/api")
response.setBody(processor.process())

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/userScripts' \
--header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"async": false,
"fileName": "customProcessing.rb",
"language": "RUBY"
}
'

wget --no-check-certificate --quiet \
  --method PUT \
  --timeout=0 \
  --header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --body-data '{
  "async": false,
  "fileName": "customProcessing.rb",
  "language": "RUBY"
}
' \
   'http://localhost:8080/nuix-restful-service/svc/v1/userScripts'

Getting Started: Requesting Access to Protected APIs

Wed, 21 Jul 2021 00:00:00 +0000

Some of the selected API permissions required by the newly registered Azure application provide access to sensitive data within the tenant. Microsoft considers these protected APIs. To use these APIs with the registered Azure application, additional validation and approval is required by Microsoft.

To request access to protected Microsoft Graph APIs, visit the following site and complete the form provided by Microsoft.

https://aka.ms/teamsgraph/requestaccess

The form includes several questions concerning the intended use of the protected APIs. The following table includes quick answers to the required questions included on the form.

Question	Answer
Publisher name	Enter the name of your company or organization.
App name	Enter the name of the Azure application that you registered. For example: Nuix Authentication
App ID	Provide the Client ID of the registered Azure application.
What does your app do?	The application provides a method of authentication that allows chat data to be retrieved from Microsoft Teams.
Why does your app need access to all messages?	The application is being used to retrieve data for eDiscovery.
Data retention	Select: “It is obvious to any admin installing this app that it will make a copy of Microsoft Teams messages.”
What are the tenant ID’s that this app needs to run in?	Provide the AD tenant ID where the Azure application was registered.
Does your organization own all of the specified tenants?	Provide an answer based on the response to the previous question.

After completing all fields, click Next to submit the form.

Microsoft reviews access requests every Wednesday and deploys approvals every Friday, except during major holiday weeks in the U.S. Submissions during those weeks will be processed the following non-holiday week. For additional information, see Protected APIs in Microsoft Teams.

Proceed to the next topic to learn how to ingest data from Office 365 using Nuix RESTful Service.

Getting Started: Manage Licenses with REST

Thu, 22 Apr 2021 00:00:00 +0000

An authentication token is required to access most endpoints within the Nuix RESTful Service API. To get an authentication token, a request must be submitted to the API to retrieve a license from your configured NMS instance. If the requested license is available on the licensing server, an authentication token will be issued in the request response. This token can then be used during your session to make authenticated calls to the API.

Note: Based on the configuration of your installation of Nuix RESTful Service, your authentication token may expire if your session becomes inactive. If this occurs, a new token must be retrieved using the steps within this topic.

Within this topic, you’ll learn how to:

Identify which Nuix license types are available for use.
Request an authentication token.
Release your license to end your session.

License Availability

Nuix offers several different license types that provide various functionality for different use cases. When submitting a request to retrieve an authentication token, you may want to know what license types are available to you.

Check which Nuix license types are available on your configured NMS instance using the following GET request to the /licenses endpoint.

curl -X GET "http://127.0.0.1:8080/nuix-restful-service/svc/licenses" -H "accept: application/vnd.nuix.v1+json"

{
  "shortname": "enterprise-workstation",
  "count": 8,
  "configuredCount": 10,
  "description": "Nuix eDiscovery Workstation",
  "workers": 6,
  "configuredWorkers": 10,
  "audited": false,
  "auditThreshold": 0,
  "source": null,
  "type": null,
  "location": null,
  "expiry": null,
  "legalHoldHoldCountLimit": null,
  "concurrentUserLimit": null,
  "canChooseWorkers": null
}

If the license server is accessible, a response similar to this shortened example will be returned. The response includes details about each license type that exists on the configured licensing server.

Identify the license type that meets the needs of your job, then locate its associated short name. The short name is used during license acquisition to request a specific license type.

License Acquisition

A license is required in order to gain full access to the Nuix REST API. When you request a license, you are issued an authentication token that can then be used in all subsequent requests to the API.

Submit a request to retrieve a license and authentication token from your licensing server using the following PUT request to the /authenticatedUsers/login endpoint.

curl -L -X PUT 'http://127.0.0.1:8080/nuix-restful-service/svc/authenticatedUsers/login' \
-H 'Content-Type: application/json' \
--data-raw '{
    "username": "user1",
    "password": "password",
    "licenseShortName": "enterprise-workstation",
    "workers": 2
}'

{
  "username": "user1",
  "authToken": "49e225d7-b88d-4d1b-9cbc-296e83706a60",
  "licenseShortName": "enterprise-workstation",
  "workersGranted": 1
}

In this example, four parameters are submitted in the body of the request as JSON.

username: The username for an account that has access to the licensing server.
password: The password associated with the username.
licenseShortName: (Optional) The short name of the license to be retrieved.
workers: (Optional) The number of workers to request with the license.

Both licenseShortName and workers are optional parameters. If left undefined, the first license offered by the licensing server will be claimed. Additionally, if the selected license type supports the use of workers, a default value of one or two workers, assigned by the Nuix Engine, will also be assigned.

Note: Workers are a consumable entity within your environment like licenses. If no workers are available at the time that a license is requested, no workers will be assigned. Similarly, if many workers are requested, but only a few are available, a subset of the total requested workers equal to the number of available workers will be assigned.

The response from the license acquisition request displays the issued authentication token, retrieved license type, and the number of workers that have been assigned to the license.

After obtaining the authentication token, provide it within the header of all subsequent calls to make authenticated requests to the API.

For example:

When checking the server status by calling the /about endpoint, if the request is made using an authentication token, the response will include details about the REST server instead of null values.

curl -L -X GET 'http://127.0.0.1:8080/nuix-restful-service/svc/about' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "server" : "http://127.0.0.1:8080/nuix-restful-service/svc",
    "serverId" : "rest-oem-server",
    "startupTime": 1602193993435,
    "nuixRestfulVersion": "9.4.0",
    "engineVersion": "${nuix-engine}"
}

License Revocation

When you are finished making calls to the Nuix RESTful Service API, it is best practice to end your session. Performing this action revokes your authentication key and returns your license and any assigned workers back to the licensing server for other users to consume.

Submit a DELETE call to the /authenticatedUsers/{username) endpoint, specifying the username used to log in and your authentication token in the header of the request to revoke your license and authentication token.

curl -L -X DELETE 'http://127.0.0.1:8080/nuix-restful-service/svc/authenticatedUsers/user1' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "success": true
}

When this request is performed, if your session is active with running or queued functions, you will be asynchronously logged out. This default behavior allows the session to remain active until the functions have completed. At that time, the session will end, and your license will be returned.

Getting Started: Version 9.0 Release Notes

Tue, 20 Apr 2021 00:00:00 +0000

Nuix Engine

Nuix RESTful Service has been updated to use version 9.0 of the Nuix Engine. Details about what is included with this update can be found in the v9.0 changelog.

Java 11

Nuix RESTful Service has been upgraded to OpenJDK 11.

Elasticsearch 7.8.1

Nuix RESTful Service has been updated to support Elasticsearch v7.8.1. To use existing Elasticsearch based Nuix cases, your Elasticsearch cluster must first be upgraded to v7.8.1.

Refer to the Elasticsearch Reference [7.8] documentation for details on performing this upgrade.

Note

Nuix RESTful Service v9.0 is not compatible with earlier versions of Elasticsearch.

Culling

The AsyncItemSetDelete function of the /cases/{caseId}/itemSets/{itemSetName} endpoint has been modified to now function asynchronously.

OCR Profile Details

A new OCR endpoint has been added that enables users to retrieve the template details of a specified OCR profile.

GET /ocrProfiles/{name}/details

Paginated Results

The numberOfRecordsRequested parameter used by search-based endpoints has been modified to now return paginated results by default. This changes the previous default behavior which was to return all results at once. Calls to any of the following endpoints will now return results in increments of 100 by default. This value can be modified by updating the numberOfRecordsRequested parameter with a custom value.

Endpoints affected by this change include:

/cases/{caseId}/clusterRuns/{clusterRunName}/items
/cases/{caseId}/itemSets/{itemSetName}/items
/cases/{caseId}/productionSets/{productionSetId}/items
/cases/{caseId}/search

General Enhancements

All code and dependencies associated with the User Management Server (UMS) have been removed from Nuix RESTful Service as UMS is not functionally required for the operation of Nuix REST.

Resolved Issues

An issue has been resolved that prevented failed functions from returning a failure status.
OCR text output is now immediately available to the case when an OCR function completes successfully.
MD5 deduplicated requests to the /v1/cases/{caseId}/count endpoint no longer generates a null pointer exception.

Getting Started: Elastic Case Creation

Wed, 10 Feb 2021 00:00:00 +0000

Create an Elastic Case

Now that you are authenticated, let’s create an Elasticsearch case. Configuration of Elasticsearch is outside the scope of this tutorial. Additionally, sharding strategies and replicas are also outside the scope of this tutorial. In order to create an Elasticsearch case you will need to know the Elasticsearch cluster name and host name. For this example, we will use a single shard and zero replicas.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloElasticCase",
   "location":"inventory0",
   "description":"My first Nuix Elasticsearch case",
   "compound":false,
   "investigator":"Inspector Gadget",
   "elasticSearchSettings": {
   	"cluster.name": "elasticsearch",
   	"index.number_of_shards": 1,
   	"index.number_of_replicas": 0,
   	"nuix.transport.hosts": ["127.0.0.1"],
    "nuix.http.hosts": ["127.0.0.1"] 
   }
}
'

{
    "caseId": "776a45b03d1841379b1dea524098a33b",
    "name": "HelloElasticCase",
    "path": "/Cases/HelloElasticCase",
    "description": "My first Nuix Elasticsearch case",
    "investigator": "Inspector Gadget",
    "creationDate": 1613068118333,
    "compound": false,
    "elastic": true,
    "binaryStoreLocation": "/Cases/HelloElasticCase/Stores/BinaryStore",
    "indexId": "nuix-776a45b03d1841379b1dea524098a33b",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "caseName": "HelloElasticCase",
    "casePath": "/Cases/HelloElasticCase",
    "caseDescription": "My first Nuix Elasticsearch case",
    "caseCreationDate": 1613068118333,
    "caseInvestigator": "Inspector Gadget"
}

You have now successfully created your first Elasticsearch case! Next, let’s ingest some data!

Getting Started: Part 3: Authentication

Tue, 09 Feb 2021 00:00:00 +0000

Authentication

Now that you know your server is properly installed and configured, the first thing you will want to do is authenticate.

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/authenticatedUsers/login' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
	"username":"username",
	"password":"password",
    "licenceShortName": "enterprise-workstation",
    "workers": 2
}'

{
    "username": "username", 
    "authToken": "9729a460-eda7-48dc-ba70-d12b3aae3c8d",
    "licenseShortName": "enterprise-workstation",
    "workersGranted": 2
}

Note

The licenceShortName and workers fields in the request body are optional. If they are excluded any license will be selected and 1 worker will be granted.

Note

Please note the authToken field returned in the response will need to be submitted in the nuix-auth-token request header field on all subsequent requests.

You have now successfully authenticated to Nuix RESTful Service!

Getting Started: Docker

Wed, 06 Jan 2021 00:00:00 +0000

Follow the procedures in this section to install and deploy the Nuix RESTful Service Docker image within a Ubuntu Linux environment using Compose.

The Nuix RESTful Service Docker image is intended for development purposes only. Usage of this installation in a production environment is not supported.

Prerequisites

Before proceeding, the following prerequisites must be installed within your environment:

Docker Engine: An open-source containerization technology.
- Visit Get Docker Engine - Community for Ubuntu for complete instructions on installing the Docker Engine on Ubuntu.
  Note:To ensure proper operation, the Docker Engine requires a minimum of 8 GB of memory.
Docker Compose: A tool used to define and run multi-container Docker applications.
- Visit Install Docker Compose for complete instructions on installing Docker Compose.
  Note:The Docker Engine must be installed and running before installing Docker Compose. View the Post-installation steps for Linux for details on configuring different startup methods for Docker.

Preparing the Target Directory

Use the following procedure to download and extract the Nuix RESTful Service Linux archive.

Download the Docker Image for Linux 64-bit package from the Nuix Customer Portal.
Open a terminal and enter the following command to create a target directory for the package:
```
sudo mkdir -p /opt/nuix/rest
```
Note: /opt/nuix/rest is the recommended location for this package.
Extract the contents of the rest-docker-compose archive to the target directory:
```
sudo tar xzf rest-docker-compose-VERSION.tar.gz -C /opt/nuix/rest
```
Navigate to the target directory to view the extracted contents of the package:
```
cd /opt/nuix/rest
```

The rest directory contains the directory structure described in the following table:

    .
    |-- bin                                       # Binaries and support scripts
        |-- clean.sh                              # Script to remove user data and restore directories
        |-- configure.sh                          # Script to configure the Nuix License Server settings
        |-- create-service.sh                     # Script to create a service
        |-- install.sh                            # Script to install the Nuix RESTful Service
    |-- cases                                     # Default Inventory Location for cases on the host
    |-- docs                                      # Documentation
    |-- exports                                   # Default Nuix exports directory on the host
    |-- images                                    # Distributed Docker images
    |-- logs                                      # Default Nuix logs directory on the host
    |-- raw-data                                  # Default Nuix raw-data directory on the host
    |-- scripts                                   # Default Nuix scripts directory on the host
    |-- secrets                                   # Sensitive properties used by the Nuix Rest SDK
        |-- nuix-rest-secret.properties           # Sensitive Nuix License Server properties
    |-- tmp                                       # Default Nuix tmp directory on the host
    |-- user-data-extra                           # Default Nuix user-data-extra folder on the host
    |-- .env                                      # Docker compose environment configuration.
    |-- rest.env                                  # Nuix RESTful Service environment configuration
    |-- docker-compose.yml                        # Docker compose file

Installing the Docker Image

After extracting the package to the target directory, use the following procedure to complete the installation process using the provided scripts.

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to begin the installation.
```
sudo ./bin/install.sh
```
The install.sh script verifies that all prerequisites are in place before loading the included Nuix RESTful service Docker images and calling all other scripts that are required for the installation.
Note: The first time install.sh is run, a warning is returned indicating that rest.env is missing and will be created from an example file that contains default values. This is expected and can be ignored. See Post-Installation Configuration after completing the installation for information on modifying the default environment configurations.
When prompted, specify the Nuix License Server that will be used for licensing.
1. Enter a URL where the license server can be accessed.
2. Provide user credentials for an account associated within the specified license server.

After installation completes, proceed to the remaining sections in this guide for information on:

Post-Installation Configuration

After completing the installation of Nuix RESTful Service, the following configurations can be made to the installation.

Configuring Environment Settings

Nuix RESTful Service includes several configurations that can be modified to change the how the application operates.

Use the following procedure to access the available environment configurations:

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Using the editor of your choice, open the following configuration file.
```
rest.env
```
Review the properties included within the file and make changes as necessary.

The following table provides details about the properties that are configurable.

Option	Description
`JAVA_OPTS_HEAP`	Optimize the Java heap size ranges used by Nuix RESTful service. * -Xms512m Default minimum memory allocation * -Xmx6g Default maximum memory allocation
`publicURL`	The URL used to access Nuix RESTful Service.
`logging_level`	Specify the logging level to be used with REST.
`logging_level_com_nuix_us`	Specify the logging level to be used for workers.
`casePrivilegeSecurityEnabled`	Enable or disable the ability to restrict cases from view using case security.
`threadpool_nativesearch`	The number of threads available for retrieving item metadata when searches are performed.
`threadpool_asyncfunction`	The number of threads available to perform background tasks such as tagging, exclusions, or highlighting.
`threadpool_searchUnsortedManager`	The number of threads available for retrieving item counts for the provided analytics.
`threadpool_searchUnsorted`	The number of threads available to run queries and aggregate the data required to populate the provided analytics.
`serverId`	A unique identifiable name for the REST instance.
`xpack_security_transport_ssl_enabled`	Enable or disable TLS/SSL.
`ignoreDerbyCases`	Restrict REST from processing Derby-based cases.
`nuix_engine_userDataDirs`	Specify the locations where artifacts used by the Nuix Engine are stored.
`inventoryLocations`	Specify the location where cases are stored. Mapped network drives can be configured within Linux environments if a symbolic link has been created between the mapped and local drive.
`sandboxDirectory`	Specify a location where unprocessed evidence is stored.
`server_contextPath`	Specify a context path prefix to use within the Nuix RESTful Service URL.
`workerAgentStatusHistoryUpdateIntervalMs`	Specify the frequency (in milliseconds) in which worker agent status is retrieved.
`workerAgentStatusHistoryMaxValues`	Specify the maximum number of times that worker agent status can be retrieved.
`registerAsApplication`	Specify how Nuix RESTful Service should be run.
`maxSimultaneousWorkers`	Specify the total number of workers that can be distributed by this REST instance at any given time.
`workerAgentTempPath`	Specify the path to a directory, such as /tmp, that can be used by worker agents for temporary storage. The specified location should be on performant local storage with ample space for best results.
`nuix_logdir`	Specify the directory where logs generated by Nuix RESTful Service are stored.
`nuix_engine_path`	Specify the directory where the Nuix Engine is installed.
`logging_file`	Specify the path and file name to use for the log file.
`logging_config`	Specify the path and file name of the logging configuration file.

When finished, save and exit the file, then restart Nuix RESTful Service for the changes to take effect.

Updating Nuix License Server Settings

If required, the configured Nuix License Server can be updated after the initial installation using a provided script.

Use the following procedure to update the Nuix License Server connection details:

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to run the script and update the connection details.
```
sudo ./bin/configure.sh
```
When prompted, specify the Nuix License Server to be used for licensing.
1. Enter a URL where the license server can be accessed.
2. Provide user credentials for an account associated within the specified license server.

The updated settings are saved to the ./secrets/nuix-rest-secret.properties file as well as the ./rest.env file.

Once complete, restart Nuix RESTful Service for the changes to take effect.

Removing Existing Data

Nuix RESTful Service provides a script that allows all case, evidence, and user data to be removed without impacting the installation. This script can be used to return the Docker image back to a default state when testing different scenarios.

To remove existing data from the installation:

Warning

All existing cases, engine artifacts, and raw evidence will be deleted.

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to run the script.
```
sudo ./bin/clean.sh
```

Running Nuix RESTful Service

Once the Docker image has been properly deployed and configured on your system, Docker Compose can be used to quickly start Nuix RESTful Service.

To start the service in the foreground:

Navigate to the target directory where Nuix RESTful Service is installed:
```
cd /opt/nuix/rest
```
Start the service using the following command:
```
sudo docker-compose up
```
Note:This startup method returns all logs within the terminal which may be helpful when troubleshooting an issue. While the service is running, the terminal cannot be used.
To stop the service, press Ctrl-C within the terminal.

To start the service in the background:

Navigate to the target directory where Nuix RESTful Service is installed:
```
cd /opt/nuix/rest
```
Start the service using the following command:
```
sudo docker-compose up -d
```
Note: This startup method does not return logs but allows continued use of the terminal.
To stop the service, enter the following command:
```
sudo docker-compose stop
```

Starting as a Service

The installation script provided with Nuix RESTful Service creates all required Docker entries to allow the image to be run as a service. By default, the services are not started or configured to start on boot, however, these configurations can be changed using the following commands.

Start as a service:

sudo systemctl start docker-compose@nuix-rest-sdk

Stop the service from running:

sudo systemctl stop docker-compose@nuix-rest-sdk

Configure Nuix RESTful Service to run at startup:

sudo systemctl enable docker-compose@nuix-rest-sdk

Verifying the Installation

Once your installation is complete, verify your deployment using one of the following methods.

From a web browser, access the following URL:

localhost:8080/nuix-restful-service/svc/v2/about

From the terminal, enter the following cURL:

curl http://localhost:8080/nuix-restful-service/svc/v2/about

If the installation was successful, the response body for either method will return with information about the RESTful service.

{
 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "rest-oem-server",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null
}

Getting Started: Using the Java Engine

Thu, 05 Jan 2017 00:00:00 +0000

Overview

When you run a script in Nuix you can think of your script as being at an inner most level in a series of nested technologies:

A Java Virtual Machine (JVM) executes the code of Nuix. Nuix in turn relies on one of several interpreter libraries to run your script:

JRuby to run Ruby code
Jython to run Python code
Rhino to run ECMA Script (AKA Javascript) code

Your script then makes calls into the Nuix API (which is written in Java) facilitated by the intervening interpreter which provides a translation layer between your script’s code and the Nuix API. The interpreter presents objects exposed by the Nuix API in a manner which makes them seem (mostly) native to the scripting language you employ.

When using the Java Engine API, this concept is inverted slightly. Rather than Nuix using an interpreter such as JRuby to run your script’s code, your Java code runs in the JVM and then invokes methods in the Nuix API:

This provides several benefits:

You can develop your code in an Integrated Development Environment (IDE) such as Eclipse, IntelliJ or NetBeans.
Write your code in the statically typed language Java.
Compile your code into a single JAR file rather than having a series of script files.

This also means that the code you write has some additional work to perform before making use of the Nuix API. When running a script in Nuix Workstation, either through the Graphical User Interface (GUI) or nuix_console.exe (the “headless” version of Nuix Workstation), you can rely on a few things having already happened:

Nuix has started and therefore the Nuix Engine has been initialized.
A license has been obtained.

When developing an application using the Java Engine API, your code is responsible for taking the steps to initialize the Nuix Engine and get it licensed before you begin interacting with the Nuix API.

Setup

The first thing you need to do is download a Nuix Java Engine API release. This contains all the Nuix code and dependencies. The latest release of the Java Engine API can be downloaded here:

https://download.nuix.com/releases/engine

Once downloaded, extract the contents of the downloaded Zip file to a directory accessible to your IDE. Ideally the directory name should be relatively short, for example:

C:\engine-releases\8.0.3.121

Note

Storing the engine release in a longer directory name can pose potential issues later when Nuix Worker processes are started for something Processing, OCR or Exporting due to the way some information is passed to the workers about the class path.

Additionally you need to add some entries into the PATH environment variable so that Nuix can resolve some of its dependencies properly at run-time. The PATH environment variable needs entries pointing to the bin and bin/x86 sub-directories of the engine release. For example, if you have extracted your engine release to C:\engine-releases\8.0.3.121 you will want to add the following directories to you PATH environment variable:

C:\engine-releases\8.0.3.121\bin
C:\engine-releases\8.0.3.121\bin\x86

Created a new Java project in your IDE of choice. Add all the JAR files in the lib sub-directory of the engine release directory. For example if you have extracted your engine release to C:\engine-releases\8.0.3.121 then you will want to add all the JAR files in the directory C:\engine-releases\8.0.3.121\lib to your project’s build path.

Initializing the Engine

In this section we are going to review the basic steps needed to initialize the engine. For a more detailed implementation with some additional features, check out the EngineWrapper class in the GitHub repository Nuix Java Engine Baseline. That project provides a baseline implementation which can be used for your own project.

Before your code can make use of the Nuix Java Engine API, several steps need to be accomplished:

A GlobalContainer instance must be created (if one does not already exist).
An Engine instance needs to be created.
That Engine instance needs some basic configuration.
That Engine instance needs to be licensed by acquiring a license from a license source.
Once licensed, we can obtain the Utilities object from our engine instance. This Utilities object acts as our entry point into the rest of the API’s functionality.

Create a GlobalContainer

Their can only be one GlobalContainer instance per JVM. In many scenarios your code will likely create a GlobalContainer and Engine instance, make use of the API and then dispose of those things when done with them. In a more advanced scenario you may instead wish to create a GlobalContainer instance and then instantiate and dispose of Engine instances throughout the lifetime of your application.

You create a GlobalContainer instance using the nuix.engine.GlobalContainerFactory:

import nuix.engine.GlobalContainer;
import nuix.engine.GlobalContainerFactory;

GlobalContainer container = GlobalContainerFactory.newContainer();

Once you have your GlobalContainer instance you can create an Engine instance. When we create our Engine instance we will need to specify a couple settings:

user - The user associated with the session, used by the engine to associate a user’s actions to them in case history events.
userDataDirs - A directory containing some engine configuration data. Each engine release comes with a recommended base line user data directory in the user-data sub directory. For example, if you extracted your engine release to C:\engine-releases\8.0.3.121 then you will want to specify C:\engine-releases\8.0.3.121\user-data.

//Define our engine configuration settings
Map<Object,Object> engineConfiguration = new HashMap<Object,Object>();
engineConfiguration.put("user", System.getProperty("user.name"));
engineConfiguration.put("userDataDirs", userDataDirs);

//Create an engine instance
engine = container.newEngine(engineConfiguration);

Obtaining a Dongle License

Before you can interact with the Nuix Engine API, your engine instance must be licensed. We obtain a license by first obtaining a Licensor from the Engine instance we created. You then ask the Licensor to seek out available licenses, acquiring one of your choosing.

// Get our engine instance licensor
Licensor licensor = engine.getLicensor();

// Define where we want the licensor to look for a license
Map<String,Object> licenseOptions = new HashMap<String,Object>();
licenseOptions.put("sources","dongle");

// Ask licensor to see what available licenses it can find
Iterable<AvailableLicence> licences = licensor.findAvailableLicences(licenseOptions);

// Iterate available licenses, we can then inspect properties of each
// license we iterate, acquiring the one that meets our needs, below
// we just acquire the first available license.
for(AvailableLicence license : licences) {
	license.acquire();
}

Once you have acquired a license, your Engine instance is licensed. You may then obtain a Utilities object using the method Engine.getUtilities. From the Utilities object the rest of the Nuix Engine API is available.

Utilities utilities = engine.getUtilities();

It is important to note that the Engine object implements Closeable meaning it has a close() method. Calling the close() method releases the license held by the Engine instance, so you will want to call it when you are done using the Nuix Engine API (but not before!).

Obtaining a Server License

Obtaining a license from a Nuix Management Server (license server) is similar to obtaining a license from a dongle with a few extra steps:

You will want to specify where the license server is located. While the license discovery process may be able to determine this on its own eventually, its best to point it in the right direction.
You will want to provide credentials used to authenticate with the license server.
Your engine instance and the license server communicate over a secure channel, but the engine expects your code to determine whether the certificate of the license server can be trusted or not.

String userName = "Nuix";
String password = "Password";

// Specify location of license server
System.getProperties().put("nuix.registry.servers", "127.0.0.1");

// Here is where we provide the engine with logic that will
// either trust or reject certificate of license server, below
// example trusts all certificates.
engine.whenAskedForCertificateTrust(new CertificateTrustCallback() {
	@Override
	public void execute(CertificateTrustCallbackInfo info) {
		System.out.println("Trusting certificate blindly!");
		info.setTrusted(true);
	}
});

// We provide credentials for authenticating with the license server
// through this callback.
engine.whenAskedForCredentials(new CredentialsCallback(){
	public void execute(CredentialsCallbackInfo info) {
		info.setUsername(userName);
		info.setPassword(password);
	}
});

// Get our engine instance licensor
Licensor licensor = engine.getLicensor();

// Define where we want the licensor to look for a license
Map<String,Object> licenseOptions = new HashMap<String,Object>();
licenseOptions.put("sources","server");

// Ask licensor to see what available licenses it can find
Iterable<AvailableLicence> licences = licensor.findAvailableLicences(licenseOptions);

// Iterate available licenses, we can then inspect properties of each
// license we iterate, acquiring the one that meets our needs, below
// we just acquire the first available license.
for(AvailableLicence license : licences) {
	license.acquire();
}

Simple Example

Note this example just demonstrates the basic steps involved and does not include proper error handling. See the EngineWrapper class in the Nuix Java Engine Baseline repository on GitHub for a more fleshed out implementation.

package com.nuix.engineexample;

import nuix.Utilities;
import nuix.engine.AvailableLicence;
import nuix.engine.Engine;
import nuix.engine.GlobalContainer;
import nuix.engine.GlobalContainerFactory;
import nuix.engine.Licensor;

public class EngineSetup {
	private static GlobalContainer container = null;

	public static Utilities intializeEngine(File userDataDirs){
		Engine engine = null;

		// Create global container if it does not already exist
		if(container == null){
			container = GlobalContainerFactory.newContainer();
		}

		//Define our engine configuration settings
		Map<Object,Object> engineConfiguration = new HashMap<Object,Object>();
		engineConfiguration.put("user", System.getProperty("user.name"));
		engineConfiguration.put("userDataDirs", userDataDirs);

		//Create an engine instance
		engine = container.newEngine(engineConfiguration);

		// Get our engine instance licensor
		Licensor licensor = engine.getLicensor();

		// Define where we want the licensor to look for a license
		Map<String,Object> licenseOptions = new HashMap<String,Object>();
		licenseOptions.put("sources","dongle");

		// Ask licensor to see what available licenses it can find
		Iterable<AvailableLicence> licences = licensor.findAvailableLicences(licenseOptions);

		// Iterate available licenses, we can then inspect properties of each
		// license we iterate, acquiring the one that meets our needs, below
		// we just acquire the first available license.
		for(AvailableLicence license : licences) {
			license.acquire();
		}

		// If everything has worked up to this point, our engine instance should
		// be licensed, so now we can obtain the Utilities object from the engine
		// and return it to the caller.  The Utilities object then acts as the
		// entry point into the rest of the API.
		//
		// Note: Engine.close() should be called when we are done using the API and
		// ready to release the obtained license.  In this example we are expecting
		// the caller will do this!
		return engine.getUtilities();
	}
}

Getting Started: Using the Microsoft Office 365 Endpoint

Mon, 26 Jul 2021 00:00:00 +0000

Before you begin, ensure that your Azure tenant has been configured as described in the previous Microsoft Office 365 topics.

When processing data into a Nuix case, there are many configurable parameters that can be used to tailor what data is retrieved, how it is processed, where it is stored, and what resources should be used to perform the work. The details provided within this topic cover only the endpoint parameters related to retrieving data from Office 365.

For details about all other configurable parameters for the /cases/{caseId}/evidence/ms365 endpoint, view the reference documentation.

Important

To avoid reduced performance and potential data loss resulting from connection throttling, it is recommended to not use more than four workers when ingesting data from Office 365 with this endpoint.

Use the following details to ingest data from the following Microsoft Office 365 applications:

Microsoft Teams
Microsoft Exchange
Microsoft SharePoint

To get started, first create a case then submit a POST request to the /cases/{caseId}/evidence/ms365 endpoint.

The following example performs a basic ingestion from Office 365, retrieving Teams chats and the Exchange mailbox of a single user from a time period of one year.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/cases/36c83aabe9d74808ac1d47300909b016/evidence/ms365' \
-H 'nuix-auth-token: 974cd40d-a5b8-45b1-936f-9f3745a783be' \
-H 'Content-Type: application/json' \
--data-raw '{
    "processingProfile": "Default",
    "target": {
        "tenantId": "<tenantId>",
        "clientId": "<clientId>",
        "clientSecret": "<clientSecret>",
        "from": "2019-01-01",
        "to": "2021-01-01",
        "username": "user@email.com",
        "password": "pAsSwOrD",
        "userPrincipalNames": [
            "user@email.com"
        ],
        "mailboxRetrievals": [ "MAILBOX"],
        "retrievals": [
            "USERS_CHATS", "USERS_EMAILS"
        ]
    }
}'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "974cd40d-a5b8-45b1-936f-9f3745a783be",
    "functionKey": "58abc476-c7d0-44c5-b71c-4abd2982212f",
    "progress": 0,
    "total": 0,
    "percentComplete": null,
    "updatedOn": 1627314002180,
    "status": null,
    "statusId": null,
    "requestTime": 1627313971596,
    "startTime": 1627313971596,
    "finishTime": 1627314004551,
    "caseId": "36c83aabe9d74808ac1d47300909b016",
    "caseName": "MSOffice365",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "C:\\ProgramData\\Nuix\\NuixCases\\MSOffice365",
    "requestor": "nuix",
    "licenseShortName": "enterprise-workstation",
    "action": "AsyncBulkIngestionFunction",
    "options": {
        "reloadQuery": null,
        "processorSettings": {
            "processText": null,
            "processLooseFileContents": null,
            "processForensicImages": null,
            "analysisLanguage": null,
            "stopWords": null,
            "stemming": null,
            "enableExactQueries": null,
            "extractNamedEntities": null,
            "extractNamedEntitiesFromText": null,
            "extractNamedEntitiesFromProperties": null,
            "extractNamedEntitiesFromTextStripped": null,
            "extractNamedEntitiesFromTextCommunications": null,
            "extractShingles": null,
            "processTextSummaries": null,
            "calculateSSDeepFuzzyHash": null,
            "calculatePhotoDNARobustHash": null,
            "detectFaces": null,
            "classifyImagesWithDeepLearning": null,
            "imageClassificationModelUrl": null,
            "extractFromSlackSpace": null,
            "carveFileSystemUnallocatedSpace": null,
            "carveUnidentifiedData": null,
            "carvingBlockSize": null,
            "recoverDeletedFiles": null,
            "extractEndOfFileSlackSpace": null,
            "smartProcessRegistry": null,
            "identifyPhysicalFiles": null,
            "createThumbnails": null,
            "skinToneAnalysis": null,
            "calculateAuditedSize": null,
            "storeBinary": null,
            "maxStoredBinarySize": null,
            "maxDigestSize": null,
            "digests": [],
            "addBccToEmailDigests": null,
            "addCommunicationDateToEmailDigests": null,
            "reuseEvidenceStores": null,
            "processFamilyFields": null,
            "hideEmbeddedImmaterialData": null,
            "reportProcessingStatus": null,
            "enableCustomProcessing": [],
            "performOcr": null,
            "ocrProfileName": null,
            "createPrintedImage": null,
            "imagingProfileName": null,
            "exportMetadata": null,
            "metadataExportProfileName": null,
            "workerItemCallback": null,
            "workerItemCallbacks": null,
            "traversalScope": null,
            "namedEntities": null
        },
        "evidence": [
            {
                "guid": null,
                "name": null,
                "customMetadata": null,
                "encoding": null,
                "custodian": null,
                "timeZone": null,
                "description": null,
                "locale": null,
                "files": null,
                "exchangeMailboxes": null,
                "s3Buckets": null,
                "sqlServers": null,
                "oracleServers": null,
                "enterpriseVaults": null,
                "sharepointSites": null,
                "mailStores": null,
                "loadFiles": null,
                "centeraClusters": null,
                "splitFiles": null,
                "dropboxes": null,
                "sshServers": null,
                "twitterLocations": null,
                "documentumServers": null,
                "ms365Locations": [
                    {
                        "type": "microsoft_graph",
                        "username": "************",
                        "password": "************",
                        "tenantId": "<tenantId>",
                        "clientId": "<clientId>",
                        "clientSecret": "************",
                        "certificateStorePath": null,
                        "certificateStorePassword": null,
                        "from": 1546315200000,
                        "to": 1625630400000,
                        "teamNames": null,
                        "userPrincipalNames": [
                            "user@email.com"
                        ],
                        "retrievals": [
                            "USERS_CHATS",
                            "USERS_EMAILS"
                        ],
                        "mailboxRetrievals": [
                            "MAILBOX"
                        ],
                        "versionFilters": null
                    }
                ]
            }
        ],
        "localWorkerCount": 2,
        "repositories": [],
        "parallelProcessingSettings": {
            "workerCount": null,
            "workerMemory": null,
            "workerTemp": null,
            "brokerMemory": null,
            "workerBrokerAddress": null,
            "useRemoteWorkers": false,
            "embedBroker": true
        },
        "rescanEvidenceRepositories": false,
        "loadProcessingJob": {
            "casePath": "C:\\ProgramData\\Nuix\\NuixCases\\MSOffice365",
            "jobGuid": "b9f4933c-96b5-4bc1-9d48-23f1046da79e",
            "processingMode": "Load",
            "startDate": 1627313976482,
            "workerCount": 2,
            "finished": true,
            "paused": false,
            "masterAddress": "192.168.56.1",
            "bytesProcessed": 0,
            "itemsProcessed": 2,
            "jobSizeTotalBytes": 0
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "72670a5e-f0e1-4046-8b2e-22a42fe2ac9a",
    "errorMsg": null
}

A complete list of target parameters for this endpoint are described below.

Credential Parameters

The following parameters are used to authenticate with the Microsoft Azure tenant.

Parameter	Required	Description
`tenantId`	Yes	The ID of the Azure Active Directory (AAD) tenant where the Azure authentication application is registered.
`clientId`	Yes	The application ID of the registered authentication application.
`clientSecret`	Yes	The authentication key string associated with the Application (Client) ID. Note: Use this parameter if not authenticating with a private key certificate.
`certificateStorePath`	Yes	The location of a PKCS#12 based private key certificate. Note: Use this parameter if not authenticating with a client secret.
`certificateStorePassword`	Yes	The password associated with the PKCS#12 based private key certificate.
`username`	No	The username of a Microsoft Teams user to retrieve calendar data from. Note: Required only if the `TEAMS_CALENDARS` retrieval parameter has been defined.
`password`	No	The password associated with a Microsoft Teams user.

Scoping Parameters

The following parameters can be used to narrow the scope of data ingested into your case.

parameter	Required	Description
`from`	Yes	Retrieve only the items with a Last Modified date on or after the specified date. If a Last Modified date does not exist, the item’s Creation Date will be used.
`to`	Yes	Retrieve only the items with a Last Modified date on or before the specified date.
`teamNames`	No	Scope the ingestion to specific Microsoft Teams by specifying a semicolon separated list of Team names.
`userPrincipalNames`	No	Scope the ingestion to specific users by specifying a semicolon separated list of Office 365 User Principal Names. Note: A User Principal Name (UPN) is the name of a Windows Active Directory system user in the format of an email address. For example: john.doe@domain.com.

The from and to date filters apply only to the following Office 365 item types:

Exchange mail messages
Teams chat messages
Calendar events (filtered by scheduled event start time)
Resources from SharePoint and OneDrive for Business

Note

If retrieving calendar data (USERS_CALENDARS or TEAMS_CALENDARS), the date rage must not exceed five years (1825 days).

Retrieval Parameters

The following retrieval parameter options are available to specify which Office 365 data is collected.

Retrievals	Service	Retrieves…
`TEAMS_CHANNELS`	Teams	Channel data such as chat messages and attachments from all public channels within a team. Note: User emoji reactions to chat messages are included as child items of the parent message.
`TEAMS_CALENDARS`	Teams	Teams calendar data from all teams that a specific user is a member of. Note: If selected, the `username` and `password` of a Microsoft Teams user must be provided in order for their calendar data to be retrieved.
`USERS_CHATS`	Teams	Chat messages from one-on-one or group conversations that take place outside of a public channel. Note: See Private Chat Limitations for additional information on how user chats are retrieved.
`USERS_CALENDARS`	Teams	Individual user calendar data from the members of a team.
`USERS_CONTACTS`	Exchange	Personal contacts that have been saved by individual users.
`USERS_EMAILS`	Exchange	Individual user mailboxes. Tip: Select Extract from mailbox slack space when configuring your data processing settings to also retrieve deleted and other lower-level slack space items from the mailbox.
`ORG_CONTACTS`	Exchange	Contacts created by an administrator that are shared to all users in an organization. Also known as Mail Contacts within Exchange.
`SHAREPOINT`	SharePoint	Data from SharePoint sites, subsites, lists, and users. Note: The retrieval of SharePoint list attachments is not supported.

Private Chat Limitations

Due to restrictions in how private chat data is retrieved using the Microsoft Graph API, certain limitations exist when determining the recipients of specific messages within a chat. Limitations include:

Chat/conversation IDs are only generated when a new chat is initiated. The generated ID is persisted for the entire life of the chat, regardless of whether participants are later added or removed.
The To communication metadata property, which identifies the participants of a chat, represents only the list of participants that are included in the chat at the time of ingestion. Due to this limitation, the following must be considered:
- New participants who are added to an existing conversation are identified within the metadata as a chat recipient. However, based on the Microsoft Teams chat history settings selected when adding the new participant, they may or may not have been granted access to view messages that were sent prior to them joining the chat.
- Participants who left a chat after receiving messages will not be identified within the metadata as a recipient at all.

Workaround:

To establish a complete view of recipients and verify who received messages from a private chat conversation, the specified private conversation must be examined from the /Users/<userName>/Chats directory of each suspected participant. For example:

To verify if John saw a specific private chat message, the messages located within /Users/John/Chats must be examined. Looking at the same chat but from a different participant, /Users/Jane/Chats, may not properly confirm if John saw a specific message because Jane’s chat history may be incomplete and reflect only a portion of the conversation due to the limitations previously noted.

Mailbox Retrieval Parameters

The following mailbox retrieval parameter options are available to specify which Exchange mailbox data collected.

Mailbox Retrievals	Required	Retrieves…
`MAILBOX`	No	All current mailbox data, including recoverables such as deletions and purges.
`DELETIONS`	No	Items that have been deleted from any folder and placed in the Deleted items default folder.
`RECOVERABLE_ITEMS`	No	Items that have been deleted from the Deleted items default folder.
`PURGES`	No	Deleted items that have been marked to be removed from the mailbox database.
`ARCHIVE`	No	All archived mailbox data, including archived recoverables such as deletions and purges.
`ARCHIVE_DELETIONS`	No	Archived items that have been deleted from any folder and placed in the Deleted items default folder.
`ARCHIVE_RECOVERABLE_ITEMS`	No	Archived items that have been deleted from the Deleted items default folder.
`ARCHIVE_PURGES`	No	Archived deleted items that have been marked to be removed from the mailbox database.
`PUBLIC_FOLDERS`	No	Shared folders within an organization.

Version Filter Parameters

The following version filter parameters can be configured to also include item versions during ingestion. With these parameters, you can choose to ingest only the latest version of a item, a selection of recent versions, or all available versions.

Note

Only item versions with a Last Modified date within the specified from / to date range will be retrieved.

Version filters apply to all files and attachments retrieved from Microsoft Office 365 in which versions are maintained, including data from SharePoint, OneDrive for Business, and Teams.

If the following parameters are left undefined only the latest version of a file or attachment will be retrieved.

Version Filters	Required	Description
`versionRetrievalEnabled`	No	Set to `true` to retrieve all versions of an item. Set to `false` (default) to retrieve only the latest version of an item.
`versionRetirevalLimit`	No	Specify an integer value to limit the number of retrieved versions to a specific number of recent versions. Requires `versionRetrievalEnabled` be set to `true`. A value of `-1` will retrieve all available versions.

Version Metadata

When item versions are included in a case, the following version related metadata is applied to all applicable items:

Metadata	Value	Description
`Flag: versioned`	boolean	Indicates that multiple versions of the selected item exist and have been ingested.
`Flag: current_version`	boolean	Indicates if an item is the most recent version. Determined at the time of ingestion.
`Property: Version Age`	integer	Identifies the version of the selected item in relation to the latest known version. A value of 0 represents the latest version. Each increment of 1 indicates a subsequent older version. Warning: If the data within a case is updated by reloading the source data or scanning for new child items, the Version Age of an item will change if newer versions of that item are found.
`Property: Version Group ID`	string	A unique identifier that is used to link all versioned items that originate from the same item. The Version Group ID value is derived from the original item’s ID value.
`Property: Version Value`	integer	Identifies the exact version of the selected item based on source data. Note: Microsoft 365 uses a basic sequential numbering method (1.0, 2.0, 3.0) when assigning version values. Other data sources may assign non-readable values, such as a hash, when defining this value.

Querying Items Based on Version Metadata

The following table contains example queries that can be used after ingestion to locate versioned items based on their metadata:

Query	Returns…
`Flag: versioned`	All items that have multiple versions.
`flag:(versioned AND current_version)`	The latest version of each item that has multiple versions.
`flag:(versioned AND NOT current_version)`	All versions of an item except for the latest version.
`integer-properties:"Version Age":(0 to 10)`	The most recent version (indicated by 0) and the previous 10 versions.
`properties:"Version Value:2.0"`	All items that have a version value that matches the value specified in the query (2.0).
`properties:"Version Group ID:<GROUPIDGUID>"`	All versions of an item, including the original, that match the group ID specified in the query.

Getting Started: Manage Cases within your Inventory

Thu, 22 Apr 2021 00:00:00 +0000

All data that is ingested and processed using the Nuix Engine is done so within a Nuix case. The case acts as a container for the collections of data and evidence related to an investigation. Nuix supports two types of cases:

Simple: A single case that contains all data for an investigation.
Compound: A collection of two or more related simple cases that can be accessed concurrently as a single large case.

After choosing the type of case best suited for your purpose, you can ingest evidence and begin any required post processing activities. All cases that are created are saved within your case inventory, which was defined during the installation of Nuix RESTful Service.

Within this topic, you’ll learn how to:

Create a new case.
View existing cases.
Close a case.
Delete a case.

Creating a Case

New cases can be created by submitting a POST request to the /cases endpoint. Use the following request to create a simple case. For information on creating other case types, such as compound or elastic-based cases, see the Nuix RESTful Service API reference documentation.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/cases' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60' \
-H 'Content-Type: application/json' \
--data-raw '{
  "compound": false,
  "location": "inventory0",
  "name": "MyNuixCase",
  "description": "A simple case created using the REST API",
  "investigator": "Your Name"
}'

{
    "caseId": "0eedda2d297046ae8e67fbda9f192df9",
    "name": "MyNuixCase",
    "path": "C:\\Program Files\\Nuix\\Nuix RESTful Service\\cases\\MyNuixCase",
    "description": "A simple case created using the REST API",
    "investigator": "Your Name",
    "creationDate": 1602818339843,
    "compound": false,
    "elastic": false,
    "binaryStoreLocation": "",
    "indexId": "",
    "caseSize": 0,
    "casePathParent": "C:\\Program Files\\Nuix\\Nuix RESTful Service\\cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "casePath": "C:\\Program Files\\Nuix\\Nuix RESTful Service\\cases\\MyNuixCase",
    "caseName": "MyNuixCase",
    "caseCreationDate": 1602818339843,
    "caseDescription": "A simple case created using the REST API",
    "caseInvestigator": "Your Name"
}

In the example above, five parameters are submitted in the body of the request as JSON as well as an authentication token in the header of the request.

compound: The type of case to create. A value of false will create a simple case.
location: A relative or absolute path that is within the defined inventory location used by REST where the case will be saved. A value of inventory0 references the first defined inventory location within your installation of REST.
name: A unique name to identify the case. This value also defines the name of the directory which contains the case on the file system.
description: (Optional) A brief description to indicate the contents or purpose of the case.
Investigator: The name of the person creating the case.

After submitting the request, details about the newly created case are included in the response, including the caseId of the case. The caseId value is a required parameter in all requests involving a case.

Identifying Existing Cases

If cases have already been created within your inventory, they can be identified by submitting a GET request to the /inventory/digest endpoint with your authentication token. Doing so will return information for all cases that exist within your configured inventory locations.

This request can be helpful if you need to look up details about a case, such as its caseId.

curl -L -X GET 'http://127.0.0.1:8080/nuix-restful-service/svc/v1/inventory/digest' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60' \

[
    {
        "caseId": "0eedda2d297046ae8e67fbda9f192df9",
        "name": "MyNuixCase",
        "path": "C:\\ProgramData\\Nuix\\NuixCases\\MyNuixCase",
        "description": "A case created using the REST API",
        "investigator": "Your Name",
        "creationDate": 1609909619982,
        "compound": false,
        "elastic": false,
        "binaryStoreLocation": "",
        "indexId": "",
        "productName": "Nuix",
        "version": "8.7.1",
        "isOpen": true,
        "childCases": [],
        "url": "http://10.101.100.66:8080",
        "serverId": "fdfc0544-4421-40df-bbd6-a200371b200d"
    }
]

Closing a Case

Any time a new case is created, or an existing case is used in a request, the case is considered open. When cases are opened, they become locked to prevent other users from accessing the case at the same time.

The status of a case can be determined by calling the /inventory/digest endpoint or the /inventory/{caseId} endpoint, if the caseId is known, to retrieve details about the case.

The response body to these requests includes the following parameter.

"isOpen": true

A value of true indicates that the case is open.

When you are finished working with a case, it should be closed so that it becomes unlocked and available to other users.

To close a case, submit a POST request to the /cases/{caseId}/close endpoint.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/cases/0eedda2d297046ae8e67fbda9f192df9/close' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "success": true
}

Deleting a Case

To delete a case from your inventory, submit a DELETE request to the /cases/{caseId} endpoint.

curl -L -X DELETE 'http://127.0.0.1:8080/nuix-restful-service/svc/cases/0eedda2d297046ae8e67fbda9f192df9' \
-H 'nuix-auth-token: fabbd5b7-8e4d-4af8-a970-feed76a34f46'

{
    "caseId": "0eedda2d297046ae8e67fbda9f192df9",
    "success": true,
    "childCases": null
}

Getting Started: Compound Elastic Case Creation

Fri, 12 Feb 2021 00:00:00 +0000

Create a Compound Elastic Case

Now that you are authenticated, let’s create a compound Elasticsearch case. Configuration of Elasticsearch is outside the scope of this tutorial. Additionally, sharding strategies and replicas are also outside the scope of this tutorial. In order to create an Elasticsearch case you will need to know the Elasticsearch cluster name and host name. For this example, we will use a single shard and zero replicas.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloCompoundElasticsearchCase",
   "location":"inventory0",
   "description":"My first compound Elasticsearch case",
   "compound":true,
   "investigator":"Inspector Gadget",
   "elasticSearchSettings": {
   	"cluster.name": "elasticsearch",
   	"index.number_of_shards": 1,
   	"index.number_of_replicas": 0,
   	"nuix.transport.hosts": ["127.0.0.1"],
    "nuix.http.hosts": ["127.0.0.1"] 
   }
}
'

{
    "caseId": "a571f00ec43d41538d9e8c4f0bf1bda5",
    "name": "HelloCompoundElasticsearchCase",
    "path": "/Cases/HelloCompoundElasticsearchCase",
    "description": "My first compound Elasticsearch case",
    "investigator": "Inspector Gadget",
    "creationDate": 1613154608469,
    "compound": true,
    "elastic": true,
    "binaryStoreLocation": "/Cases/HelloCompoundElasticsearchCase/Stores/BinaryStore",
    "indexId": "nuix-a571f00ec43d41538d9e8c4f0bf1bda5",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "casePath": "/Cases/HelloCompoundElasticsearchCase",
    "caseDescription": "My first compound Elasticsearch case",
    "caseCreationDate": 1613154608469,
    "caseInvestigator": "Inspector Gadget",
    "caseName": "HelloCompoundElasticsearchCase"
}

You have now successfully created your first compound Elasticsearch case! Take note of your case ID a571f00ec43d41538d9e8c4f0bf1bda5. Next, we have to add elastic simple child cases to the compound case. Let’s create two elastic simple child cases and add them to the compound case.

Create Elasticsearch Child Case 1

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloElasticChild1",
   "location":"inventory0",
   "description":"My elastic child case 1",
   "compound":false,
   "investigator":"Inspector Gadget",
   "elasticSearchSettings": {
   	"cluster.name": "elasticsearch",
   	"index.number_of_shards": 1,
   	"index.number_of_replicas": 0,
   	"nuix.transport.hosts": ["127.0.0.1"],
    "nuix.http.hosts": ["127.0.0.1"] 
   }
}
'

{
    "caseId": "0d4060b5d16046e58172286266a80980",
    "name": "HelloElasticChild1",
    "path": "/Cases/HelloElasticChild1",
    "description": "My elastic child case 1",
    "investigator": "Inspector Gadget",
    "creationDate": 1613155151596,
    "compound": false,
    "elastic": true,
    "binaryStoreLocation": "/Cases/HelloElasticChild1/Stores/BinaryStore",
    "indexId": "nuix-0d4060b5d16046e58172286266a80980",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "casePath": "/Cases/HelloElasticChild1",
    "caseDescription": "My elastic child case 1",
    "caseCreationDate": 1613155151596,
    "caseInvestigator": "Inspector Gadget",
    "caseName": "HelloElasticChild1"
}

Create Elasticsearch Child Case 2

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "name":"HelloElasticChild2",
   "location":"inventory0",
   "description":"My elastic child case 2",
   "compound":false,
   "investigator":"Inspector Gadget",
   "elasticSearchSettings": {
   	"cluster.name": "elasticsearch",
   	"index.number_of_shards": 1,
   	"index.number_of_replicas": 0,
   	"nuix.transport.hosts": ["127.0.0.1"],
    "nuix.http.hosts": ["127.0.0.1"] 
   }
}
'

{
    "caseId": "8c680473e5274719a585ba77eb4f9ca5",
    "name": "HelloElasticChild2",
    "path": "/Cases/HelloElasticChild2",
    "description": "My elastic child case 2",
    "investigator": "Inspector Gadget",
    "creationDate": 1613155276207,
    "compound": false,
    "elastic": true,
    "binaryStoreLocation": "/Cases/HelloElasticChild2/Stores/BinaryStore",
    "indexId": "nuix-8c680473e5274719a585ba77eb4f9ca5",
    "caseSize": 0,
    "casePathParent": "/Cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "casePath": "/Cases/HelloElasticChild2",
    "caseDescription": "My elastic child case 2",
    "caseCreationDate": 1613155276207,
    "caseInvestigator": "Inspector Gadget",
    "caseName": "HelloElasticChild2"
}

Adding Elasticsearch Child Cases to an Elasticsearch Compound Case

Finally, let’s add our two simple Elasticsearch child cases that we just created to our Elasticsearch compound case. The childCases endpoint simply acknowledges the addition of the child cases to the compound case by returning a HTTP status code of 200

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/a571f00ec43d41538d9e8c4f0bf1bda5/childCases' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '[ "0d4060b5d16046e58172286266a80980", "8c680473e5274719a585ba77eb4f9ca5" ]'

You have now successfully created your first Elasticsearch compound case! Next, let’s ingest some data!

Getting Started: Part 5: Ingestion

Wed, 10 Feb 2021 00:00:00 +0000

Ingestion

For the purposes of this example, we are going to use the following request to ingest the Nuix Engine documentation that is distributed as part of the Nuix RESTful Service installation. After performing the request, an asynchronous function key will be returned which can then be polled for status.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/evidence/file' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "processorSettings": {
   	"storeBinary": true
   },
   "target": {
    "path": "/Engines/9.0.0.171/doc"
  }
}
'

{
    "functionKey": "814388bb-d0fe-4a75-a4cb-02d1f46213e2", 
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/814388bb-d0fe-4a75-a4cb-02d1f46213e2"
}

Ingestion Status

The functionKey field returned from the ingestion endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/814388bb-d0fe-4a75-a4cb-02d1f46213e2' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
   "done":true,
   "cancelled":false,
   "result":true,
   "token":"db63fbfc-a5fd-494e-974b-cc17f6b2a56a",
   "functionKey":"814388bb-d0fe-4a75-a4cb-02d1f46213e2",
   "progress":7581225,
   "total":0,
   "percentComplete":null,
   "updatedOn":1612973812631,
   "status":null,
   "statusId":null,
   "requestTime":1612973782299,
   "startTime":1612973782299,
   "finishTime":1612973817411,
   "caseId":"43b070164ce8453ca30ed9e2dfcce67b",
   "caseName":"HelloWorld",
   "hasSuccessfullyCompleted":true,
   "friendlyName":"Evidence Ingestion Function",
   "caseLocation":"/Cases/HelloWorld",
   "requestor":"nuixadmin",
   "action":"AsyncBulkIngestionFunction",
   "options":{
      "reloadQuery":null,
      "processorSettings":{
         "processText":null,
         "processLooseFileContents":null,
         "processForensicImages":null,
         "analysisLanguage":null,
         "stopWords":null,
         "stemming":null,
         "enableExactQueries":null,
         "extractNamedEntities":null,
         "extractNamedEntitiesFromText":null,
         "extractNamedEntitiesFromProperties":null,
         "extractNamedEntitiesFromTextStripped":null,
         "extractShingles":null,
         "processTextSummaries":null,
         "calculateSSDeepFuzzyHash":null,
         "detectFaces":null,
         "extractFromSlackSpace":null,
         "carveFileSystemUnallocatedSpace":null,
         "carveUnidentifiedData":null,
         "carvingBlockSize":null,
         "recoverDeletedFiles":null,
         "extractEndOfFileSlackSpace":null,
         "smartProcessRegistry":null,
         "identifyPhysicalFiles":null,
         "createThumbnails":null,
         "skinToneAnalysis":null,
         "calculateAuditedSize":null,
         "storeBinary":true,
         "maxStoredBinarySize":null,
         "maxDigestSize":null,
         "digests":[
            
         ],
         "addBccToEmailDigests":null,
         "addCommunicationDateToEmailDigests":null,
         "reuseEvidenceStores":null,
         "processFamilyFields":null,
         "hideEmbeddedImmaterialData":null,
         "reportProcessingStatus":null,
         "workerItemCallback":null,
         "workerItemCallbacks":null
      },
      "evidence":[
         {
            "guid":null,
            "name":null,
            "customMetadata":null,
            "encoding":null,
            "custodian":null,
            "timeZone":null,
            "description":null,
            "locale":null,
            "files":[
               {
                  "path":"/Engines/9.0.0.171/doc"
               }
            ],
            "exchangeMailboxes":null,
            "s3Buckets":null,
            "sqlServers":null,
            "enterpriseVaults":null,
            "sharepointSites":null,
            "mailStores":null,
            "loadFiles":null,
            "centeraClusters":null,
            "splitFiles":null,
            "dropboxes":null,
            "sshServers":null
         }
      ],
      "localWorkerCount":2,
      "repositories":[
         
      ],
      "parallelProcessingSettings":{
         "workerCount":null,
         "workerMemory":null,
         "workerTemp":null,
         "brokerMemory":null,
         "workerBrokerAddress":null,
         "useRemoteWorkers":false,
         "embedBroker":true
      },
      "rescanEvidenceRepositories":false,
      "loadProcessingJob":{
         "casePath":"/Cases/HelloWorld",
         "jobGuid":"e22b159b-477e-41fe-878f-91984f60e3c9",
         "processingMode":"Load",
         "startDate":1612973784905,
         "workerCount":2,
         "finished":true,
         "paused":false,
         "masterAddress":"1.1.1.1",
         "bytesProcessed":7581225,
         "itemsProcessed":192,
         "jobSizeTotalBytes":0
      }
   },
   "participatingInCaseFunctionQueue":true,
   "processedBy":"nuix-restful-server-1",
   "errorMsg":null
}

Getting Started: Part 6: Asynchronous Functions

Thu, 05 Aug 2021 00:00:00 +0000

Asynchronous Functions

Asynchronous functions are used for long-running operations. Some examples of operations that return asynchronous function keys include:

Ingestions
Optical Character Recognition (OCR)
Bulk Operations
- Case Subset
- Exclude
- Include

Asynchronous Responses

An asynchronous response contains a function key and a location that can be polled for status. It has the following structure:

{
    "functionKey": "814388bb-d0fe-4a75-a4cb-02d1f46213e2", 
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/814388bb-d0fe-4a75-a4cb-02d1f46213e2"
}

Polling for Status

To retrieve the status of an asynchronous function, use the GET /asyncFunctions/{functionKey} endpoint. When polling for status, an AsyncFunctionResponse is returned. Asynchronous function responses have a set of common fields as well as a result field.

Note

The result field will be different depending on the return type of function.

All asynchronous functions have the following fields:

Field	Description	Examples
done	A boolean value indicating that the function is no longer running.
cancelled	A boolean value indicating if the function was cancelled.
result	The result of the function. This will differ based on the return type of the function.
token	The user token executing the function.
functionKey	A unique identifier for the function.
progress	The value of the progress indicator for the function. This will differ from type to type.
total	The value of the total progress indicator for the function. This will differ from type to type.
percentComplete	The percent complete for the function if available.
updatedOn	The time in milliseconds that the function was last updated.
status	The status of the function if available.	ABORTED, STOPPING, CANCELLED
statusId	A status identifier if available.
requestTime	The time in milliseconds the function was requested.
startTime	The time in milliseconds the function started.
finishTime	The time in milliseconds the function finished.
caseId	The case ID the function is executing on.
caseName	The name of the case.
hasSuccessfullyCompleted	A boolean value indicating that the function has successfully completed.
friendlyName	The name of the function.
caseLocation	The path to the case on disk.
requestor	The user who ran the function.
action	The function class.
options	The options for the function. This will differ from type to type.
participatingInCaseFunctionQueue	A boolean value indicating whether the function is participating in the case queue.
processedBy	The server ID that processed the function.
errorMsg	The error message if an error occurred.

Incomplete Function

A function that is still running will have the done flag set to false. The following response is truncated for brevity.

{
    "done": false,
    "cancelled": false,
    "result": null,
    "token": "6ddef3c9-b40e-45fa-9d96-03765ac0f7a8",
    "functionKey": "814388bb-d0fe-4a75-a4cb-02d1f46213e2",
    "caseId": "6d0029b6a9204d75a1812713571253f1",
    "caseName": "AsyncPolling",
    "hasSuccessfullyCompleted": false,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "/Cases/AsyncPolling",
    "requestor": "user1",
    "action": "AsyncBulkIngestionFunction",
    "participatingInCaseFunctionQueue": true
}

Completed Function

A completed function will have the done flag set to true. Additionally, if the function completed successfully, the hasSuccessfullyCompleted flag will bet set to true.

The following truncated example is of an Evidence Ingestion Function that completed successfully. This particular function returns a boolean, indicated within the result field with the value true. The licenseShortName used to process the data is also included in the response and in this example is enterprise-workstation. The progress field shows the number of bytes ingested. Lastly, the processedBy field shows the server ID of the server that processed the request.

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "6ddef3c9-b40e-45fa-9d96-03765ac0f7a8",
    "functionKey": "814388bb-d0fe-4a75-a4cb-02d1f46213e2",
    "progress": 8453258,
    "updatedOn": 1628696051251,
    "requestTime": 1628695978730,
    "startTime": 1628695978749,
    "finishTime": 1628696053912,
    "caseId": "6d0029b6a9204d75a1812713571253f1",
    "caseName": "AsyncPolling",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "/Cases/AsyncPolling",
    "requestor": "user1",
    "licenseShortName": "enterprise-workstation",
    "action": "AsyncBulkIngestionFunction",
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-2"
}

Getting Started: Microsoft Office 365 Data Overview

Mon, 26 Jul 2021 00:00:00 +0000

Once ingested into a Nuix case, the data from Microsoft Office 365 is organized in a logical hierarchical structure that provides a clear view of the information.

Within the user-defined evidence container, a Microsoft Graph directory is generated for each Microsoft Office 365 connection. This directory contains all data ingested from the Azure tenant organized into the following folders:

Teams
Users
Organizational Contacts
SharePoint

The following diagram illustrates the typical data structure that is created when performing an ingestion using the Nuix Connector for Microsoft Office 365 endpoint.

+Microsoft Graph
|  +--Teams
|  |  +--TeamX
|  |  |  +--Channels
|  |  |  |  +--ChannelA
|  |  |  |  |  +--Chat Conversation
|  |  |  |  |  |  +--Chat message
|  |  |  |  |  |  |  |--Chat message attachment
|  |  |  |  |  |  +--Chat message
|  |  |  |  +--ChannelB
|  |  |  +--Calendars
|  |  |  |  +--Calendar event
|  |  |  |  |  |--Calendar event attachment
|  |  +--TeamY
|  |
|  +--Users
|  |  +--User1
|  |  |  +--Calendars
|  |  |  |  +--Calendar event
|  |  |  |  |  |--Calendar event attachment
|  |  |  +--Chats
|  |  |  |  +--Chat conversation
|  |  |  |  |  +--Chat message
|  |  |  |  |  |  |--Chat message attachment
|  |  |  +--Contacts
|  |  |  |  +--Contact or folder
|  |  |  |  |  |--Contact
|  |  |  +--Exchange
|  |  |  |  |--Recoverable items
|  |  |  |  +--Top of information store
|  |  |  |  |  +--Mail folder
|  |  |  |  |  |  +--Sub mail folder
|  |  |  |  |  |  |  |--Recursive containing more sub-folders and/or emails
|  |  |  |  |  |--Email
|  |  +--User2
|  |
|  +--Organizational Contacts
|  |  |--Org contact
|  |
|  +SharePoint
|  |  +--Site1
|  |  |  |--Drive1
|  |  |  +--List1
|  |  |  |  |--List item1
|  |  |  +--SubSite1
|  |  |  |  +--Drive2
|  |  |  |  |  +--Folder1
|  |  |  |  |  |  |--Item1
|  |  |  |  |  |--Item2
|  |  |  |  |--List2
|  |  |  |  |--SubSite2
|  |  +--Site2

As with all data that is ingested using the Nuix Engine, the contents of the evidence set is analyzed to ensure that all content as well as available metadata is extracted into the case.

The following table identifies the Mime-types that are used to classify Microsoft Office 365 data.

Mime Type Kind	Mime Type	Description
container	application/vnd.microsoft.m365.account	Microsoft Office 365 Tenant/Account
container	application/vnd.microsoft.m365.contact-folder	Contact folder
container	application/vnd.microsoft.m365.exchange.folder	Exchange mail folder
container	application/vnd.microsoft.m365.folder	Nuix generated folder used to organize data retrieved from Office 365
container	application/vnd.microsoft.m365.sharepoint.drive	SharePoint drive
container	application/vnd.microsoft.m365.sharepoint.drive.folder	SharePoint drive folder
container	application/vnd.microsoft.m365.sharepoint.list	SharePoint list
container	application/vnd.microsoft.m365.sharepoint.site	SharePoint site or subsite
container	application/vnd.microsoft.m365.team	Team within Teams
container	application/vnd.microsoft.m365.teams.channel	Channel within a team
container	application/vnd.microsoft.m365.user	Office 365 user
chat-conversation	application/vnd.microsoft.m365.teams.channel-conversation	Conversation or thread within a channel
chat-conversation	application/vnd.microsoft.m365.teams.chat-conversation	Conversation within private chats
chat-message	application/vnd.microsoft.m365.message.reaction	Reaction to a message
chat-message	application/vnd.microsoft.m365.teams.message	Deprecated in v9.0. Message within a chat or channel
chat-message	application/vnd.microsoft.m365.teams.channel-message	Message within a channel
chat-message	application/vnd.microsoft.m365.teams.chat-message	Message within a chat
calendar	application/vnd.microsoft.m365.calendar-event	Team calendar event
contact	application/vnd.microsoft.m365.contact	Contact
other-document	application/vnd.microsoft.m365.sharepoint.item	SharePoint item (such as a list)
other-document	application/vnd.microsoft.m365.teams.unknown-attachment	Unknown message attachment type
other-document	application/vnd.microsoft.teams.card.o365connector	An Office 365 card added to a channel (RSS feed as an example)

Getting Started: Process Data into a Nuix Case

Thu, 22 Apr 2021 00:00:00 +0000

After acquiring a license and creating a case, you can then begin ingesting data into the case using the Nuix Engine. Nuix RESTful Service provides multiple endpoints that can be used to ingest data from different data sources. These endpoints are described within the Processing category of the Nuix RESTful Service API reference documentation.

Within this topic, you’ll learn how to:

Perform a simple ingestion.
Checking the status of the request.

Ingesting Data into a Case

When processing data into a Nuix case, there are many configurable parameters that can be used to tailor what data is retrieved, how it is processed, where it is stored, and what resources should be used to perform the work. The settings used are often determined by the type of investigation being performed and the level of detail that is required.

Details about these parameters can be found within the reference documentation for the endpoint.

For the purposes of this example, a simple ingestion can be performed by submitting a POST request to the /cases/{caseId}/evidence/file endpoint. This request ingests the contents of a single file or directory into an evidence container within the case using basic processing settings.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/v1/cases/0eedda2d297046ae8e67fbda9f192df9/evidence/file' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60' \
-H 'Content-Type: application/json' \
--data-raw '{
  "container": {
    "custodian": "John Doe",
    "name": "Evidence Container 1"
  },
  "target": {
    "path": "C:/LocationOfData"
  },
  "processorSettings": {
    "analysisLanguage" : "en",
    "processText" : true,
    "reportProcessingStatus": "physical_files",
    "traversalScope" : "full_traversal"  
  }
}'

{
    "functionKey": "72744ec6-6de1-488c-bbec-ff27b64974e3",
    "location": "http://127.0.0.1:8080/nuix-restful-service/svc/v1/asyncFunctions/72744ec6-6de1-488c-bbec-ff27b64974e3"
}

In this example, the following parameters are submitted in the body of the request as raw data.

custodian: The name of the person who owns the data being ingested.
name: The name of the evidence container where the custodian’s data is being ingested.
path: The absolute path to the file or directory being ingested.
analysisLanguage: The language to use for text analysis when indexing the data.
processText: Store and index the text of data items.
reportProcessingStatus: Calculates the physical file size of the evidence before ingestion. This data can then be used to report the progress of the ingestion.
traversalScope: Indicates what files should be processed. The full_traversal value ensures that all loose files and forensic images are processed, including their contents.

Any number and combination of parameters can be submitted in the request. If you find that you use consistent processor settings when performing ingestions, an external processing profile can also be used to supply the settings rather than defining them individually within the body of the request.

To use a processing profile, specify the name of the profile using the processingProfile parameter. The profile must exist within the ..\nuix-engine\user-data\Processing Profiles directory of your REST installation.

See the reference documentation for the endpoint to learn more about available parameters.

After submitting the request to perform an ingestion, a GET request to the /asyncFunctions/{key} endpoint using the returned functionKey can be used to retrieve details about the ingestion request, including:

The status of the function.
Details about the request.
The processing settings used.
A summary of the processed data.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/72744ec6-6de1-488c-bbec-ff27b64974e3' \
--header 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "49e225d7-b88d-4d1b-9cbc-296e83706a60",
    "functionKey": "72744ec6-6de1-488c-bbec-ff27b64974e3",
    "progress": 135591,
    "total": 135591,
    "percentComplete": 100.0000,
    "updatedOn": 1610047993132,
    "status": null,
    "statusId": null,
    "requestTime": 1610047968056,
    "startTime": 1610047968056,
    "finishTime": 1610047996497,
    "caseId": "8ca047e086aa4497bc311ef5cb4bada7",
    "caseName": "MyNuixCase",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "C:\\ProgramData\\Nuix\\NuixCases\\MyNuixCase",
    "requestor": "user1",
    "action": "AsyncBulkIngestionFunction",
    "options": {
        "reloadQuery": null,
        "processorSettings": {
            "processText": true,
            "processLooseFileContents": null,
            "processForensicImages": null,
            "analysisLanguage": "en",
            "stopWords": null,
            "stemming": null,
            "enableExactQueries": null,
            "extractNamedEntities": null,
            "extractNamedEntitiesFromText": null,
            "extractNamedEntitiesFromProperties": null,
            "extractNamedEntitiesFromTextStripped": null,
            "extractShingles": null,
            "processTextSummaries": null,
            "calculateSSDeepFuzzyHash": null,
            "detectFaces": null,
            "extractFromSlackSpace": null,
            "carveFileSystemUnallocatedSpace": null,
            "carveUnidentifiedData": null,
            "carvingBlockSize": null,
            "recoverDeletedFiles": null,
            "extractEndOfFileSlackSpace": null,
            "smartProcessRegistry": null,
            "identifyPhysicalFiles": null,
            "createThumbnails": null,
            "skinToneAnalysis": null,
            "calculateAuditedSize": null,
            "storeBinary": null,
            "maxStoredBinarySize": null,
            "maxDigestSize": null,
            "digests": [],
            "addBccToEmailDigests": null,
            "addCommunicationDateToEmailDigests": null,
            "reuseEvidenceStores": null,
            "processFamilyFields": null,
            "hideEmbeddedImmaterialData": null,
            "reportProcessingStatus": null,
            "workerItemCallback": null,
            "workerItemCallbacks": null
        },
        "evidence": [
            {
                "guid": null,
                "name": "Evidence Container 2",
                "customMetadata": null,
                "encoding": null,
                "custodian": "Jane Doe",
                "timeZone": null,
                "description": null,
                "locale": null,
                "files": [
                    {
                        "path": "C:/LocationOfData"
                    }
                ],
                "exchangeMailboxes": null,
                "s3Buckets": null,
                "sqlServers": null,
                "enterpriseVaults": null,
                "sharepointSites": null,
                "mailStores": null,
                "loadFiles": null,
                "centeraClusters": null,
                "splitFiles": null,
                "dropboxes": null,
                "sshServers": null
            }
        ],
        "localWorkerCount": 2,
        "repositories": [],
        "parallelProcessingSettings": {
            "workerCount": null,
            "workerMemory": null,
            "workerTemp": null,
            "brokerMemory": null,
            "workerBrokerAddress": null,
            "useRemoteWorkers": false,
            "embedBroker": true
        },
        "rescanEvidenceRepositories": false,
        "loadProcessingJob": {
            "casePath": "C:\\ProgramData\\Nuix\\NuixCases\\MyNuixCase",
            "jobGuid": "989b79fe-43e6-4fa4-9466-19ea3d5ef644",
            "processingMode": "Load",
            "startDate": 1610047968374,
            "workerCount": 2,
            "finished": true,
            "paused": false,
            "masterAddress": "10.20.100.50",
            "bytesProcessed": 135591,
            "itemsProcessed": 12,
            "jobSizeTotalBytes": 135591
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "fdfc0544-4421-40df-bbd6-a200371b200d",
    "errorMsg": null
}

Getting Started: Unified Logging with Elasticsearch

Mon, 11 Jan 2021 00:00:00 +0000

Use the following topic to enable unified logging using the Elasticsearch ELK stack.

Prerequisites

Elasticsearch v7.8.1
Filebeat v7.8.1
Kibana v7.8.1
Nuix REST v9.0

This topic assumes that you already have a running instance of Nuix RESTful Service version 9.0 installed at the following location:

Windows: C:\Program Files\Nuix\Nuix RESTful Service
Linux: /opt/nuix-restful-service

The installation and configuration of Elasticsearch and Kibana are outside the scope of this topic.

Note

Before proceeding, ensure that the installed Nuix-REST service is not running.

Windows Filebeat Installation and Configuration

Use the following procedure to install Filebeat on Windows:

Download Filebeat (https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-7.8.1-windows-x86_64.zip)
Unzip the Filebeat installer to C:\Program Files\Filebeat.
Navigate to the C:\Program Files\Filebeat installation directory.
Rename filebeat.yml to filebeat.yml.backup.

Create a new filebeat.yml file in C:\Program Files\Filebeat and include the following configuration.

Click to View Windows Filebeat Configuration

filebeat.yaml

filebeat.inputs:
  -
  type: log
  enabled: true
  paths:
    - 'C:\Program Files\Nuix\Nuix RESTful Service\logs\**\*.json'
      json.message_key: message
      json.keys_under_root: true
      json.overwrite_keys: true
      json.add_error_key: true
     
  processors:
    - rename:
      fields:
      - from: "file"
      to: "file.source"
      ignore_missing: true
     
  output.elasticsearch:
  hosts: 'masterdata-node-0.elasticsearch.aws.chdev.nuix.com'

Open a command prompt with elevated administrative priviledges and navigate to C:\Program Files\Filebeat.
Enter the following command to install Filebeat in UnRestricted mode. Choose [R] to Run Once.

PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-filebeat.ps1

Filebeat is now installed and configured as a service but is not yet running.

Linux Filebeat Installation and Configuration

Use the following procedure to install Filebeat on Linux:

Download Filebeat using the following command:

curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-7.10.1-amd64.deb

Install Filebeat using the following command:
```
sudo dpkg -i filebeat-7.8.1-amd64.deb
```
Navigate to the installation directory and create a backup of the Filebeat configuration file:
```
cd /etc/filebeat
sudo mv filebeat.yml filebeat.yml.backup
```

Within the same directory, create a new filebeat.yml file and include the following configuration.

Click to View Linux Filebeat Configuration

filebeat.yaml

filebeat.inputs:
  -
  type: log
  enabled: true
  paths:
    - '/opt/nuix-restful-service/logs/**/*.json'
      json.message_key: message
      json.keys_under_root: true
      json.overwrite_keys: true
      json.add_error_key: true
     
  processors:
    - rename:
      fields:
      - from: "file"
      to: "file.source"
      ignore_missing: true
     
  output.elasticsearch:
  hosts: 'masterdata-node-0.elasticsearch.aws.chdev.nuix.com'

Filebeat is now installed and configured as a service but is not yet running.

Nuix RESTful Service Configuration Changes

Use the following procedures to configure the logging settings within your instance of Nuix RESTful Service.

Application Log Configuration

Navigate to the settings directory within your Nuix RESTful Service installation and locate application.properties.

Windows: C:\Program Files\Nuix\Nuix RESTful Service\settings\application.properties
Linux: /opt/nuix-restful-service/settings/application.properties

Using a text editor with elevated administrative priviledges, open application.properties.
Add the following property to the file to configure Nuix RESTful Service to generate JSON formatted log files.
```
logging.json.enabled=true
```

After adding this property and saving the file, the new defaut log becomes ${logging.path}\nuix-rest.log.json.

Worker Log Configuration

Navigate to the Nuix RESTful Service installation directory and locate the Nuix-REST.vmoptions file.

Windows: C:\Program Files\Nuix\Nuix RESTful Service\Nuix-REST.vmoptions
Linux: /opt/nuix-restful-service/nuix-rest.vmoptions

Using a text editor with elevated administrative priviledges, open Nuix-REST.vmoptions.
Locate the -Dnuix.worker.jvm.arguments property and make the following modification to change its value from log4j.properties to the log4j-logstash.xml configuration that ships with the application. This change configures workers to generate JSON formatted log files.

Windows:

-Dnuix.worker.jvm.arguments=-Dlog4j.configuration=file:/C:/Program%20Files/Nuix/Nuix%20RESTful%20Service/nuix-engine/config/log4j-logstash.xml

Linux:

-Dnuix.worker.jvm.arguments=-Dlog4j.configuration=file:/opt/nuix-restful-service/nuix-engine/config/log4j-logstash.xml

After modifying this property and saving the file, the new default worker log becomes ${logging.path}\job-${UUID}\${UUID2}.

Services

Start up all installed services once Filebeat and Nuix RESTful Service have been installed and configured.

Start the Nuix REST service
- On Linux: sudo service nuix-rest start
Start the Filebeat service
- On Linux: sudo service filebeat start

Log Viewing

Logs can now be viewed using Kibana. The installation and configuration of Kibana is outside the scope of this article, however, you can quickly look at logs if you have Docker installed using the following Docker command:

docker run -it \
    -e ELASTICSEARCH_HOSTS=http://your.elasticsearch.node.com:9200 \
    -p 5601:5601 \
    -e XPACK_SECURITY_ENABLED=false \
    -e MONITORING_ENABLED=false \
    -e XPACK_ML_ENABLED=false \
    -e XPACK_GRAPH_ENABLED=false \
    -e XPACK_REPORTING_ENABLED=false \
    docker.elastic.co/kibana/kibana:7.8.1

In a browser, navigate to http://localhost:5601

Getting Started: Part 7: Search

Thu, 05 Aug 2021 00:00:00 +0000

Search

Now that we have data in a case. Let’s search it. As part of a search we can specify a Default metadata profile to use. This will return the fields Name, File Type, and File Path for each item. Note that we can also limit the number of results returned using the request parameter numberOfRecordsRequested. In this example we are only returning 5 results at a time. The total number of hits was 364 as noted by the count field in the response.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v2/cases/43b070164ce8453ca30ed9e2dfcce67b/search?query=*&metadataProfile=Default&numberOfRecordsRequested=5' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "request": {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
            "query": "*",
            "sortField": null,
            "sortOrder": null,
            "startIndex": 0,
            "numberOfRecordsRequested": 5,
            "deduplicate": null,
            "metadataProfile": "Default",
            "fieldList": null,
            "customMetadataList": null,
            "propertyList": null,
            "itemParameterizedFields": null,
            "showAvailableThumbnails": false,
            "useCache": false,
            "forceCacheDelete": false,
            "searchRetry": 0,
            "relationType": null,
            "entities": [],
            "p": 5,
            "s": 0,
            "customMetadataField": null,
            "field": null,
            "property": null
    },
    "startedOn": 1612985518529,
        "completedOn": 1612985518552,
        "elapsedTimeForSearch": 17,
        "elapsedTimeForSort": 0,
        "elapsedTimeForMarshal": 2,
        "elapsedTimeForDeduplicate": 0,
        "elapsedTotal": 23,
        "metadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
        "localizedMetadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
        "metadataItemDetails": [
        {
            "name": "Name",
            "localisedName": "Name",
            "type": "String"
        },
        {
            "name": "File Type",
            "localisedName": "File Type",
            "type": "String"
        },
        {
            "name": "Path Name",
            "localisedName": "Path Name",
            "type": "String"
        }
    ],
        "resultList": [
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "allclasses.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "4350a26e-0582-4cdd-8903-feb2454b66ad"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "allclasses-index.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "48fdd676-ecdf-4271-8fb0-a312570888a5"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "allpackages-index.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "b5d26466-0b5f-4b01-bc2e-7ebe6c6d3294"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "index.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "8bc28b97-6d5a-4755-8066-4fa2102705de"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "constant-values.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "ee4cb26f-30b5-4a76-8789-dfbd7fdecf65"
        }
    ],
        "count": 364,
        "deduplicatedCount": 364
}

Paging

When limiting the numberOfRecordsRequested field, we need to page the result list. To get the next page of results set the startIndex request paramter equal to 5. Now we are retrieving the next 5 results.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v2/cases/43b070164ce8453ca30ed9e2dfcce67b/search?query=*&metadataProfile=Default&numberOfRecordsRequested=5&startIndex=5' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "request": {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
        "query": "*",
        "sortField": null,
        "sortOrder": null,
        "startIndex": 5,
        "numberOfRecordsRequested": 5,
        "deduplicate": null,
        "metadataProfile": "Default",
        "fieldList": null,
        "customMetadataList": null,
        "propertyList": null,
        "itemParameterizedFields": null,
        "showAvailableThumbnails": false,
        "useCache": false,
        "forceCacheDelete": false,
        "searchRetry": 0,
        "relationType": null,
        "entities": [],
        "p": 5,
        "s": 5,
        "customMetadataField": null,
        "field": null,
        "property": null
    },
    "startedOn": 1612985803142,
    "completedOn": 1612985803161,
    "elapsedTimeForSearch": 13,
    "elapsedTimeForSort": 0,
    "elapsedTimeForMarshal": 2,
    "elapsedTimeForDeduplicate": 0,
    "elapsedTotal": 19,
    "metadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "localizedMetadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "metadataItemDetails": [
        {
            "name": "Name",
            "localisedName": "Name",
            "type": "String"
        },
        {
            "name": "File Type",
            "localisedName": "File Type",
            "type": "String"
        },
        {
            "name": "Path Name",
            "localisedName": "Path Name",
            "type": "String"
        }
    ],
    "resultList": [
        {
            "File Type": "Ini Style Configuration File",
            "Name": "member-search-index.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "a5ee8532-868e-4abf-bc74-c066e82f234a"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "deprecated-list.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "be263fae-48e5-4c3f-bcd1-3c354960173b"
        },
        {
            "File Type": "JSON Data File",
            "Name": "member-search-index.json",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/member-search-index.zip",
            "guid": "ae36f963-93c6-43b4-b359-70f9e937d197"
        },
        {
            "File Type": "Plain Text",
            "Name": "element-list",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "a6230532-2bff-445a-9fa3-9a683dcbaadc"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "overview-summary.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "d5ead71c-08ac-49f9-a27c-ee2257706c63"
        }
    ],
    "count": 364,
    "deduplicatedCount": 364
}

Getting Started: Troubleshooting Microsoft Office 365 Errors

Mon, 26 Jul 2021 00:00:00 +0000

This topic provides details for troubleshooting known errors that result in inaccessible items (mime-type:"filesystem/inaccessible“) that may be encountered when processing data.

ERROR: com.nuix.data.util.RetryCallable - Final retry attempt number 10 failed

Description: The request to retrieve data from Office 365 has failed. This error is likely to occur after a connection has been throttled and the maximum number of retries has been reached.
Impact: Data will be missing from the evidence set.
Resolution: Retry the ingestion once the connection is no longer being throttled.
Important: To reduce the potential for data loss resulting from connection throttling, it is recommended to not use more than four workers when ingesting data from Office 365.

To try and prevent future failures of this type, the following system properties can also be configured at startup:

Increase the default (10) maximum retry count:
nuix.data.msgraph.retries=10
Increase the default (1 second) retry delay:
nuix.data.msgraph.retryDelay=1
Increase the default (5 seconds) retry delay increment:
nuix.data.msgraph.retryDelayIncrement=5

Errors: com.nuix.data.network.microsoftgraph.client.exception.MsGraphMailboxItemMissingException: The user mailbox does not contain the requested item. Missing id: ArchiveMsgFolderRoot; com.nuix.data.network.microsoftgraph.client.exception.MsGraphMailboxItemMissingException: The user mailbox does not contain the requested item. Missing id: ArchiveRecoverableItemsRoot

Description: A request was made to retrieve a mailbox that does not exist for a user. For example: Requesting to ingest archived mailboxes from a user with no archives.
Impact: Result set includes Inaccessible Items.

Error: MsGraphApiException: Failed to retrieve data from Microsoft Graph API: Access is denied. Check credentials and try again.

Description: Indicates that an error with code “ErrorAccessDenied” was returned from the Microsoft Graph API for this request.
Impact: Data is inaccessible, potentially due to a missing application permission or invalid credentials.
Resolution: Verify that the credentials being used are correct and review Applying Permissions to the Application to ensure that all required permissions are applied within your Azure tenant.

Error: RuntimeException: REST API is not yet supported for this mailbox.

Description: Indicates that the user associated with a particular mailbox has not been issued a license.

Error: java.net.SocketException: Connection reset by peer: socket write error.

Description: Indicates that long-lived connections are being closed, potentially due to firewall configurations.
Impact: Attachments are missing when retrieving Teams messages.
Resolution: Set the following system property at startup to allow the embedded Apache HTTPClient to accept additional Java system properties, such as proxy settings.

nuix.data.msgraph.http.use-system-props=true

See HttpClientConfiguration for details on configuring the Apache HTTPClient.

Getting Started: Checking the Status of a Function

Thu, 22 Apr 2021 00:00:00 +0000

When submitting requests to perform long running asynchronous tasks, a simple response like the following example is returned which includes a functionKey and location.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/evidence/file' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "processorSettings": {
   	"storeBinary": true
   },
   "target": {
    "path": "/Engines/9.0.0.171/doc"
  }
}
'

{
    "functionKey": "814388bb-d0fe-4a75-a4cb-02d1f46213e2", 
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/814388bb-d0fe-4a75-a4cb-02d1f46213e2"
}

The functionKey is a unique identifier for the function that can be used to query its status. The location URL provides a direct request to the /asyncFunctions/{key} endpoint. Making calls to this endpoint with the returned functionKey will return details about the associated function.

While an asynchronous function is running, this endpoint can by queried to check the status of the function and eventually retrieve the final output of the request.

Note

The results of asynchronous functions, such as ingestion, are only maintained for five minutes after the completion of the function. To change this time period, modify the asyncFunctionResultRetention property within the Application Settings.

Getting Started: Part 8: Exclusions

Thu, 05 Aug 2021 00:00:00 +0000

Exclusions

As part of the culling process, it is sometimes necessary to exclude items from your case. For this example, let’s exclude all Javascript files (*.js) from the case using the excludedItems endpoint.

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/excludedItems' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "excludeDescendants": true,
  "includeDuplicates": true,
  "includeFamily": true,
  "includeNearDuplicates": true,
  "nearDuplicatesThreshold": 0,
  "query": "file-extension:js",
  "reason": "Exclude script files from the case"
}'

{
    "functionKey": "575f4966-1103-43fb-b6bb-03f52b7b3022",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/575f4966-1103-43fb-b6bb-03f52b7b3022"
}

Exclusion Status

The functionKey field returned from the excludedItems endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/575f4966-1103-43fb-b6bb-03f52b7b3022' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "37741b6c-43e2-49d1-9354-04bd397984b5",
    "functionKey": "575f4966-1103-43fb-b6bb-03f52b7b3022",
    "progress": 1,
    "total": 1,
    "percentComplete": 100.0000,
    "updatedOn": 1613578572593,
    "status": null,
    "statusId": null,
    "requestTime": 1613578565663,
    "startTime": 1613578565663,
    "finishTime": 1613578572594,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Bulk Exclude Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "username",
    "action": "AsyncBulkExcludeFunction",
    "options": {
        "exclusionName": "Exclude script files from the case",
        "query": "file-extension:js"
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-1",
    "errorMsg": null
}

Verifying Exclusions

Let’s verify the items have been excluded from the case using the search endpoint.

Note

The search endpoint will return ALL items regardless of whether they have been excluded. It is the responsibility of the client to exclude items from search. This can be done by appending an exclusion suffix to the query. For example, tag:HTMLFiles AND has-exclusion: 0.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v2/cases/43b070164ce8453ca30ed9e2dfcce67b/search?query=has-exclusion:1&metadataProfile=Default&numberOfRecordsRequested=100' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "request": {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
        "query": "has-exclusion:1",
        "sortField": null,
        "sortOrder": null,
        "startIndex": 0,
        "numberOfRecordsRequested": 16,
        "deduplicate": null,
        "metadataProfile": "Default",
        "fieldList": null,
        "customMetadataList": null,
        "propertyList": null,
        "itemParameterizedFields": null,
        "showAvailableThumbnails": false,
        "useCache": false,
        "forceCacheDelete": false,
        "searchRetry": 0,
        "relationType": null,
        "entities": [],
        "s": 0,
        "p": 16,
        "customMetadataField": null,
        "property": null,
        "field": null
    },
    "startedOn": 1613579723060,
    "completedOn": 1613579723087,
    "elapsedTimeForSearch": 13,
    "elapsedTimeForSort": 0,
    "elapsedTimeForMarshal": 10,
    "elapsedTimeForDeduplicate": 0,
    "elapsedTotal": 27,
    "metadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "localizedMetadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "metadataItemDetails": [
        {
            "name": "Name",
            "localisedName": "Name",
            "type": "String"
        },
        {
            "name": "File Type",
            "localisedName": "File Type",
            "type": "String"
        },
        {
            "name": "Path Name",
            "localisedName": "Path Name",
            "type": "String"
        }
    ],
    "resultList": [
        {
            "File Type": "Plain Text",
            "Name": "jquery-3.3.1.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery",
            "guid": "192d4465-4120-4f70-9ecc-21e75fa00fdb"
        },
        {
            "File Type": "Ini Style Configuration File",
            "Name": "member-search-index.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "a5ee8532-868e-4abf-bc74-c066e82f234a"
        },
        {
            "File Type": "Plain Text",
            "Name": "jszip.min.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery/jszip/dist",
            "guid": "fae2d24a-d398-46e1-aad1-2d3ba315680e"
        },
        {
            "File Type": "Ini Style Configuration File",
            "Name": "package-search-index.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "985bf725-9480-407c-a149-6295dbbff792"
        },
        {
            "File Type": "Plain Text",
            "Name": "jszip-utils-ie.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery/jszip-utils/dist",
            "guid": "0734cf5b-626b-48ee-accb-feae91f6d333"
        },
        {
            "File Type": "Plain Text",
            "Name": "script.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "edf629f6-2183-4b61-8ab5-cc38ee6c2fe6"
        },
        {
            "File Type": "Plain Text",
            "Name": "jszip-utils-ie.min.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery/jszip-utils/dist",
            "guid": "2f014b44-1f68-4604-aa91-16aa9b03df45"
        },
        {
            "File Type": "Plain Text",
            "Name": "search.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "3c284b55-d0e3-414a-93b6-549b3483c090"
        },
        {
            "File Type": "Plain Text",
            "Name": "jszip-utils.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery/jszip-utils/dist",
            "guid": "11b2e9cd-b61c-4b0b-9977-c0140c8d3ee8"
        },
        {
            "File Type": "Ini Style Configuration File",
            "Name": "type-search-index.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "d5d111b5-eda3-40bb-ac55-ae9c5267e1ee"
        },
        {
            "File Type": "Plain Text",
            "Name": "jszip-utils.min.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery/jszip-utils/dist",
            "guid": "25662c95-f31d-4ccf-8cde-f30d3d209801"
        },
        {
            "File Type": "Plain Text",
            "Name": "jquery-migrate-3.0.1.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery",
            "guid": "7f53b31e-dbb6-40a8-9094-c95ed8b26ee5"
        },
        {
            "File Type": "Plain Text",
            "Name": "jquery.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery/external/jquery",
            "guid": "1dfd0e2f-1c60-4e59-b5d4-8afeba538368"
        },
        {
            "File Type": "Plain Text",
            "Name": "jquery-ui.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery",
            "guid": "76e84607-0fed-423a-a8e8-bcd3ae41738e"
        },
        {
            "File Type": "Plain Text",
            "Name": "jquery-ui.min.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery",
            "guid": "3c0cc58f-5b3f-40fb-8aec-6176126bd855"
        },
        {
            "File Type": "Plain Text",
            "Name": "jszip.js",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api/jquery/jszip/dist",
            "guid": "2613381e-a406-4e3e-afaa-f0366f818887"
        }
    ],
    "count": 16,
    "deduplicatedCount": 16
}

Viewing Exclusion Reasons

We can retrieve the list of exclusion reasons from a case using the exclusions endpoint.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/exclusions' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

[
    "Exclude script files from the case"
]

Getting Started: Retrieving Diagnostics

Thu, 22 Apr 2021 00:00:00 +0000

Nuix RESTful Service provides the ability to retrieve diagnostics at any time to troubleshoot issues that may be impacting the health of the service. When requested, a ZIP archive is generated that contains the following diagnostics:

Logs
Product versions
Configured environment variables
System properties
Licence properties
Storage details
Process information
JVM arguments and settings
Installed and missing dependencies

To perform this action, submit a POST request to the /system/diagnostics endpoint to retrieve the data asynchronously. The diagnostics endpoint can also be called using the GET method to retrieve results synchronously.

Tip

If retrieving diagnostics from a clustered environment, the request must be performed asynchronously using the POST method.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/system/diagnostics?includeResourceDetails=false' \
-H 'nuix-auth-token: cf472e00-89c2-4006-ba59-4949b5dafce8'

{
    "functionKey": "a80b5f19-c4f0-4a32-8ef4-e43ff6bea980",
    "location": "http://127.0.0.1:8080/nuix-restful-service/svc/v1/asyncFunctions/a80b5f19-c4f0-4a32-8ef4-e43ff6bea980"
}

As an asynchronous request, a functionKey is returned with the request so its progress can be tracked.

Using the functionKey, call the /asyncFunctions/{key} endpoint, identified by the returned location value, to retrieve information about the function, including:

The status of the function.
The location of the generated diagnostics, when complete.
User and server information.

When diagnostics are retrieved from a cluster, a single ZIP archive is generated. Within the archive, diagnostics for each node are provided within subfolders labeled using the node’s IP address.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/a80b5f19-c4f0-4a32-8ef4-e43ff6bea980' \
--header 'nuix-auth-token: cf472e00-89c2-4006-ba59-4949b5dafce8'

{
    "done": true,
    "cancelled": false,
    "result": {
        "key": "e9924103-d9e2-4901-b82f-60b60d47bd33",
        "location": "http://10.30.100.58:8080/nuix-restful-service/svc/v1/downloads/e9924103-d9e2-4901-b82f-60b60d47bd33",
        "members": [
            {
                "member": "[127.0.0.1]:5601",
                "exception": null,
                "additionalInfo": ""
            }
        ]
    },
    "token": "cf472e00-89c2-4006-ba59-4949b5dafce8",
    "functionKey": "a80b5f19-c4f0-4a32-8ef4-e43ff6bea980",
    "progress": 1,
    "total": 1,
    "percentComplete": 100.0000,
    "updatedOn": 1611610309395,
    "status": null,
    "statusId": null,
    "requestTime": 1611610305962,
    "startTime": 1611610305962,
    "finishTime": 1611610309396,
    "caseId": null,
    "caseName": null,
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Distributed System Diagnostic Function",
    "caseLocation": null,
    "requestor": "nuixuser",
    "action": "MultiNodeAsyncSystemDiagnosticsFunction",
    "options": null,
    "participatingInCaseFunctionQueue": false,
    "processedBy": "637edbff-3e1c-4f63-921e-da022a763fbf",
    "errorMsg": null
}

Getting Started: Part 9: Item Sets and Deduplication

Thu, 05 Aug 2021 00:00:00 +0000

Item Sets

An item set is a collection of items that have been classified as originals or duplicates based on whether there are multiple items with the same hash value. For the purposes of this tutorial, let’s ingest the Nuix Engine documentation into this case again for a second time, create an item set, and deduplicate the items.

Ingestion of Duplicate Data

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/evidence/file' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "processorSettings": {
   	"storeBinary": true
   },
   "target": {
    "path": "/Engines/9.0.0.171/doc"
  }
}
'

{
    "functionKey": "2322f9d3-678b-4ff4-b2bd-3a04d61510cb",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/2322f9d3-678b-4ff4-b2bd-3a04d61510cb"
}

Ingestion Status

The functionKey field returned from the ingestion endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/2322f9d3-678b-4ff4-b2bd-3a04d61510cb' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "1091c265-fce6-44ff-b5d4-3a30ff5273fa",
    "functionKey": "2322f9d3-678b-4ff4-b2bd-3a04d61510cb",
    "progress": 7581225,
    "total": 0,
    "percentComplete": null,
    "updatedOn": 1613591215161,
    "status": null,
    "statusId": null,
    "requestTime": 1613591186910,
    "startTime": 1613591186910,
    "finishTime": 1613591217939,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "username",
    "action": "AsyncBulkIngestionFunction",
    "options": {
        "reloadQuery": null,
        "processorSettings": {
            "processText": null,
            "processLooseFileContents": null,
            "processForensicImages": null,
            "analysisLanguage": null,
            "stopWords": null,
            "stemming": null,
            "enableExactQueries": null,
            "extractNamedEntities": null,
            "extractNamedEntitiesFromText": null,
            "extractNamedEntitiesFromProperties": null,
            "extractNamedEntitiesFromTextStripped": null,
            "extractShingles": null,
            "processTextSummaries": null,
            "calculateSSDeepFuzzyHash": null,
            "detectFaces": null,
            "extractFromSlackSpace": null,
            "carveFileSystemUnallocatedSpace": null,
            "carveUnidentifiedData": null,
            "carvingBlockSize": null,
            "recoverDeletedFiles": null,
            "extractEndOfFileSlackSpace": null,
            "smartProcessRegistry": null,
            "identifyPhysicalFiles": null,
            "createThumbnails": null,
            "skinToneAnalysis": null,
            "calculateAuditedSize": null,
            "storeBinary": true,
            "maxStoredBinarySize": null,
            "maxDigestSize": null,
            "digests": [],
            "addBccToEmailDigests": null,
            "addCommunicationDateToEmailDigests": null,
            "reuseEvidenceStores": null,
            "processFamilyFields": null,
            "hideEmbeddedImmaterialData": null,
            "reportProcessingStatus": null,
            "workerItemCallback": null,
            "workerItemCallbacks": null
        },
        "evidence": [
            {
                "guid": null,
                "name": null,
                "customMetadata": null,
                "encoding": null,
                "custodian": null,
                "timeZone": null,
                "description": null,
                "locale": null,
                "files": [
                    {
                        "path": "/Engines/9.0.0.171/doc"
                    }
                ],
                "exchangeMailboxes": null,
                "s3Buckets": null,
                "sqlServers": null,
                "enterpriseVaults": null,
                "sharepointSites": null,
                "mailStores": null,
                "loadFiles": null,
                "centeraClusters": null,
                "splitFiles": null,
                "dropboxes": null,
                "sshServers": null
            }
        ],
        "localWorkerCount": 1,
        "repositories": [],
        "parallelProcessingSettings": {
            "workerCount": null,
            "workerMemory": null,
            "workerTemp": null,
            "brokerMemory": null,
            "workerBrokerAddress": null,
            "useRemoteWorkers": false,
            "embedBroker": true
        },
        "rescanEvidenceRepositories": false,
        "loadProcessingJob": {
            "casePath": "/Cases/HelloWorld",
            "jobGuid": "3658161a-2a7d-423c-b288-0f839f2da367",
            "processingMode": "Load",
            "startDate": 1613591191176,
            "workerCount": 1,
            "finished": true,
            "paused": false,
            "masterAddress": "1.1.1.1",
            "bytesProcessed": 7581225,
            "itemsProcessed": 192,
            "jobSizeTotalBytes": 0
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-1",
    "errorMsg": null
}

Create an Item Set

Let’s go ahead and create an item set. By default, items are deduplicated by their MD5 hash.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/itemSets' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
	"name": "HelloItemSet",
	"description": "My first item set"
}'

{
    "functionKey": "12d214b2-d4fc-4f6d-8142-b33df4c18f89",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/12d214b2-d4fc-4f6d-8142-b33df4c18f89"
}

Item Set Status

The functionKey field returned from the ingestion endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/12d214b2-d4fc-4f6d-8142-b33df4c18f89' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "1091c265-fce6-44ff-b5d4-3a30ff5273fa",
    "functionKey": "12d214b2-d4fc-4f6d-8142-b33df4c18f89",
    "progress": 730,
    "total": 730,
    "percentComplete": 100.0000,
    "updatedOn": 1613591533221,
    "status": null,
    "statusId": null,
    "requestTime": 1613591533023,
    "startTime": 1613591533023,
    "finishTime": 1613591533501,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Item Set Creation Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "username",
    "action": "AsyncItemSetCreationFunction",
    "options": {
        "itemSetName": "HelloItemSet",
        "batchName": null,
        "itemSetDescription": "My first item set",
        "dedupByArg": null,
        "itemSetContructionQuery": "",
        "custodianList": null,
        "dedupArg": "MD5"
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-1",
    "errorMsg": null
}

Adding Items to an Item Set

Next, we are going to add our items to the item set and deduplicate.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/itemSets/HelloItemSet/items' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
	"batchName": "AllItems",
	"query": ""
}'

{
    "functionKey": "9490cb69-508b-43a2-8e60-351e42c7db4d",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/9490cb69-508b-43a2-8e60-351e42c7db4d"
}

Add Items Status

The functionKey field returned from the add items endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/9490cb69-508b-43a2-8e60-351e42c7db4d' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "1091c265-fce6-44ff-b5d4-3a30ff5273fa",
    "functionKey": "9490cb69-508b-43a2-8e60-351e42c7db4d",
    "progress": 0,
    "total": 730,
    "percentComplete": 0.0000,
    "updatedOn": 1613592046841,
    "status": null,
    "statusId": null,
    "requestTime": 1613592046840,
    "startTime": 1613592046840,
    "finishTime": 1613592046898,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Item Set Add Items Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "username",
    "action": "AsyncItemSetAddItemsFunction",
    "options": {
        "itemSetName": "HelloItemSet",
        "batchName": "AllItems",
        "itemSetContructionQuery": ""
    },
    "participatingInCaseFunctionQueue": false,
    "processedBy": "nuix-restful-server-1",
    "errorMsg": null
}

Item Set Details

Let’s retrieve some details about the item set we just created.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/itemSets/HelloItemSet' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "name": "HelloItemSet",
    "description": "My first item set",
    "batches": [
        {
            "batchName": "AllItems",
            "createdOn": 1613592046847
        },
        {
            "batchName": "21/02/17 14:52:13 EST",
            "createdOn": 1613591533141
        }
    ]
}

Item Set Duplicates

Let’s retrieve the duplicate items from the item set. There are 344 duplicates in this item set.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/itemSets/HelloItemSet/duplicates' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "duplicates": [
        "192d4465-4120-4f70-9ecc-21e75fa00fdb",
        "69204627-94dc-441a-a285-ba30ba5889f9",
        "50ce3b7d-8eb5-49a5-af5b-0ad69367b8f5",
        "5cd8a487-37e9-43b3-aec3-1f5b47a18f52",
        "6392ced4-f3af-4978-a61a-a1543bdbf235",
        "59585660-9ade-4856-950d-fb606a6f9dd5",
        "615768ce-8421-42a2-a9aa-e2e38323073f",
        "d4fc148f-db20-4a56-89e0-c1689fe920cd",
        "33dcbb88-eb12-40f5-aab4-fbf1fa56194f",
        "d7eec968-5034-4c82-a16a-a2ab0004b2e4",
        "1ba9ae97-c48c-42eb-a640-5395fd6a9947",
        "cd147740-2323-4b8c-8302-75b8d1152062",
        "7d93b4b9-49c2-42d8-8f4e-becbf06a2f7d",
        "e7cf0ef5-3863-4b9b-b056-b2db5662ec40",
        "fb0a2f1c-f605-48d3-97ca-2eacbb819b7b",
        "49e1273a-dc20-4ab5-a844-c947c24ff653",
        "d0689df1-b19e-45e8-87f9-f603a4e6229a",
        "2d2beb9d-9a8a-4c86-a06c-d0c8b780929f",
        "f5be4e17-b3d0-427c-9e45-228d1401f62c",
        "36b5af07-d640-49c8-89d2-6982bd9ce2e8",
        "5909249c-f595-49a0-9083-8dbb7aa9adef",
        "b0a336df-7160-4e34-9c67-0c52f305f60e",
        "70a65d83-f82f-4d98-ad63-301a93d5a62d",
        "421b9636-d756-453e-b4ae-011df0bb3a40",
        "3aa3110a-f877-4d9f-9e45-6e5c84ee7b03",
        "3943799e-eb7c-4215-bf01-1748fcfb7c35",
        "d965949d-34bb-403c-ae0a-c5a43c229574",
        "98da888b-7e03-4a78-bcc2-0e53087ff45b",
        "e797ff62-086e-40a7-a08f-4a1acc989d12",
        "def5ba51-1c23-4f2b-9e85-5a6ce76a015d",
        "641d4627-1c5a-4b29-86ff-deb63d682da9",
        "354e021f-a375-47be-9379-638ee14d6dd0",
        "02c32fdf-2f5f-4d65-95aa-64ea73d301c5",
        "5c05e778-f348-4c1a-80d1-d25563a51a6c",
        "cdf87e96-6ba6-4fca-9d74-54dbf9849c69",
        "82547af3-8eb6-401f-9264-d81314864f52",
        "9aae6735-3e64-4047-9e10-8260d8dd61db",
        "8f430563-6c7d-4870-81d3-f206735eb0e8",
        "7d57b451-2bd6-4128-aade-137839abccf8",
        "f15f6647-ee54-435e-8627-c1617d7e4a5b",
        "6ed745e9-7c3f-4323-90f3-510d49e081fa",
        "3eb87859-b52e-4c29-81fa-3d1e9adcd488",
        "5afb1fdb-d363-4da0-add9-d86825e28a3c",
        "80620833-afb1-45e0-9384-337dec5028d0",
        "1fed7de1-d150-4cf6-b5aa-eb2e5f87058d",
        "3099fd8e-2633-4071-97fc-3a337a954fda",
        "25c0b8dc-c783-4ad2-adc6-b2f303ed92da",
        "f1b05001-3b14-4c85-b07c-e6aa9a49d611",
        "c8fb7bc7-600b-4fd0-80e2-114a97c87f9b",
        "e22cdd4d-2cea-463c-893c-e3bf55e2ec5a",
        "1d5845dd-8f42-4aa0-9fc9-60028b846126",
        "596e9178-e3b5-474c-bcce-bd26af84174b",
        "81f69274-3707-4d03-8608-1e4a3a7ab8ac",
        "77897169-4839-4ff8-bfde-f5be066f7bb6",
        "48783fea-ed1e-4da4-afb4-e4e13168b77b",
        "62877335-b628-4f2c-951f-beb64e9221e7",
        "accce1a5-c5ff-498f-88a8-987d662c8f98",
        "5b07a955-fdcb-409a-a3b6-a6be82b80652",
        "24a64dfc-6a10-41f9-9912-3ba32a482e1e",
        "2ff5b86c-7d80-488b-bee9-564a8df3d05b",
        "8edbe74e-f3f7-44e5-9bb8-86364069e82c",
        "966da79b-abaa-4c7a-a55e-169d598e1cb2",
        "70f97097-e8c8-4e07-af68-3dc5733170ea",
        "d8918e4c-bca9-4426-9637-cde92619f4c2",
        "011d60e8-6ea2-4590-82ec-7ca1e809b6d5",
        "a32a3ac8-8df3-4836-9a94-5a9cc1e50791",
        "9ffd7d91-8c01-49f3-892c-bf86e9ccb176",
        "d78913f2-d9e5-481c-8bad-0d6632022e03",
        "45233604-6d08-4684-bf21-b96ed6c6bf0c",
        "48bea607-903e-40cc-968f-7940536f9553",
        "060af451-7949-4ae9-a35b-c4bdae9347f9",
        "51933023-0e3d-4d17-9804-5bfe125ddbaa",
        "6c1f742a-2f09-4b72-bf5b-ca226d49e2a6",
        "c0ed30f7-2451-45af-9af0-6ded2a2211cf",
        "e1b8a691-3a14-4648-b9d5-d4e1057cc0f8",
        "0f2a5eed-5843-450a-8207-4712c4e1bafb",
        "bb1d853d-b4a0-47bf-9aa0-092631bde92b",
        "90f2b351-0fd9-4257-99aa-243294515067",
        "3d26cf69-a12c-45b4-b464-17b0a225213e",
        "16f852e0-ffe8-4acd-92c5-68535f51d3f5",
        "9ad7d617-a6cd-42e3-8871-b133f102945a",
        "a046d0a1-eff4-40ec-9eda-fea5ef30c914",
        "5dc0b129-ffa1-4367-9a92-d322a8b2569b",
        "ace342cd-3f1e-463b-a5a3-3be751362227",
        "7401ef1e-eb92-4132-9c88-059a53a52ccf",
        "9f7f2dcd-0578-4c9f-891e-39fadd7c872e",
        "7163b094-4e5e-4a6b-9058-0c723f464a3a",
        "bd7afaf5-99e6-4e1d-8951-a7f291160b5c",
        "12329d30-93b1-46fa-872c-9b27f571050e",
        "5b8a3812-16d5-45d6-bceb-85b639a34a1e",
        "a68939f0-502c-482a-bf3a-68bc0d4a5a7d",
        "9d2c8516-4d6e-4056-a512-f5421fb6e4c7",
        "5655c3ec-1ed7-4a07-8862-62826de5320d",
        "a9e2dad3-1e14-4e99-b91f-7dffbd8a06e9",
        "fa40773a-c889-4f04-8066-b3dce8d3cef0",
        "15e575fb-fcf9-445e-b165-64f1c55354a1",
        "befb11ed-0851-4e21-8089-8e11562721fc",
        "3afa6979-4039-4b48-8303-c683c163cc4a",
        "4dc31d4b-0fe5-43cf-be45-0a993307e2b7",
        "0dba92f2-9098-4ef3-a4f8-b43f1de44b47",
        "a93485a2-c9b6-439f-a35d-a2f2143f2870",
        "f0e13f75-0b47-4369-8e10-94676b01bba4",
        "69b19079-2baf-47e0-9c5a-c4919225b4ac",
        "68e04266-6e0a-49d8-ae2d-51428b349d93",
        "ff7374b0-5e60-4603-8026-08e0b0f657f9",
        "1b427285-83a5-46eb-97db-0c09b5734b66",
        "eb6fef94-d43e-4916-9b11-12704b531f03",
        "a611ca69-7d1d-4736-a6a3-05cbca76bc16",
        "8c2d3f75-2f27-4e22-80df-900b3b004de0",
        "37f04030-03aa-4d4e-9b38-6836465944c6",
        "0a80c14f-f299-4985-9366-c7d5f112d595",
        "fded93d5-49ef-4d25-a581-9b9eab8a7255",
        "2b0d8e22-a7c6-43f2-825e-1eece4b9cfbf",
        "33c9fbea-5151-42c7-be04-871adddb7e12",
        "be2bc1bc-ccf1-4d0b-a1e3-011258e2dcfe",
        "f5a9e1e3-0b4c-4b97-b2e2-ece62a02e750",
        "ea233053-720e-4bc2-9898-51d99707fd1f",
        "f5ffbedf-b5e4-4274-8572-77e5655feb26",
        "5b7b695f-6b69-4b77-80cb-95e31f74b108",
        "7082f088-e558-4f5b-9ae8-418db1e1a3b1",
        "91738acd-8f4d-4ac5-874a-5ef97e3bdd05",
        "74a80c52-1649-4af4-a230-3effd3f89f06",
        "845ec518-629a-41ba-aa5e-05d41fc079ad",
        "ecdfe041-7e28-4159-ad11-95bb74680e43",
        "f1801614-7286-4a76-a9ac-0e1d5c8ec25c",
        "cd1172bd-1edb-4e66-bbd6-0f7a30cfd869",
        "8e1b2483-2924-4961-8d01-5e8228f2a1bf",
        "b518a531-1fb5-4d6d-9608-940a57b59c02",
        "53eed8ec-7204-4da7-8179-0c0f6fb276ab",
        "1305823c-272f-4e6f-b1b2-19b8bd2e1da2",
        "4d27d90c-597d-47b6-bec5-10ec58f76929",
        "914ea784-706c-4da4-b138-bb6e81939ac6",
        "77219f44-f9b3-4636-8f40-c485f0b1386a",
        "2c91111f-776f-49db-a260-f30b00729ad2",
        "d95adc83-2051-486e-8c22-ab9ad9b9b856",
        "7afbc31f-9d76-4bce-a185-ae3e28f690f4",
        "5a048e18-d437-4be9-baa1-fd8b4f5e08f3",
        "f466612d-bbeb-4739-a895-a6a8e1f74832",
        "4eaca35e-0adc-4996-a52b-1114ee85170e",
        "875df35a-aedb-43f2-aca5-7cd3b87fc2e5",
        "00ae438b-5547-4495-94c1-c3a4cec30829",
        "7f43d3b0-2840-4e4c-8cb0-21d27de6d181",
        "2571bb06-3a07-4633-ad07-802c6ab60242",
        "f593a196-d6c5-43ee-8672-e4c470bb01e6",
        "c9c0daaa-df79-424a-8e08-51b0b3947783",
        "dfcfa2d3-3823-43e0-b07d-d609daa41451",
        "a568caec-05e4-4fde-b952-39f8df69eb0e",
        "d582ee4c-9246-466c-96a3-2b174c462169",
        "f9d0e1b9-2150-41c1-8af6-3301000d3ebb",
        "cc720409-02a5-46cf-9fa2-9ab05b0da254",
        "46763e9c-243b-43c5-87a9-f3e9c8a1fcab",
        "e5fcf39b-bce8-49bb-abe7-063422d9f752",
        "08d89c1d-f1e0-4a28-81f1-e7c72217d71f",
        "4b191168-c260-4d09-a2e2-ec9df3cdb47b",
        "1944dbf4-ff4f-46d8-b15b-aee2ba5b0a60",
        "48a6181e-55ce-455b-a29b-59195b73a31d",
        "bbc7b8b9-9838-4404-9359-37c2a5750670",
        "59c0ad6e-d6a2-4dd9-8462-1a48568ca75f",
        "ea651780-173a-451d-b0eb-882ce356c545",
        "267242a0-95a0-4a20-a64f-1779d8d605ac",
        "d2fb2fe0-94d7-4185-a8e9-f0b8c78ecba2",
        "e50ce77b-e07e-4c90-8216-c572e6f7af87",
        "a4a1ef9e-f1e2-4745-afef-23ab7ce13ca0",
        "58cfa2d7-41b7-4156-9d1e-f7ef14c4f924",
        "531273a9-5e9f-42e3-863e-85ae1308d7d6",
        "1ade2935-089e-4260-a3ed-55418746e848",
        "c2d8c530-d96d-436c-bc2a-d279276b5ae2",
        "9694266a-6950-4bff-97e4-ed1aabb38cc1",
        "888512af-2564-4ef7-ab7b-87997a33041d",
        "e27dd502-3d55-4b93-b006-51531ada6886",
        "02259947-ff53-4c41-ad92-ebae6bc10841",
        "dece6369-361b-46e8-a3bf-e0012a3407b3",
        "cee2bb44-2306-4077-be25-ed3539285fa0",
        "6d21e34b-96f6-4009-8c87-5b77c5693b22",
        "d7ac1c40-7581-4df9-a9d8-064affdc5bfc",
        "bb2cbf39-fc89-42a0-b076-7153020cae76",
        "be55540c-699c-4d67-abb9-1cc4405ae92d",
        "20935378-c0ed-49b8-ac5c-144f6c298520",
        "56061170-6d14-4be9-9956-9abdc8319622",
        "5564662f-58b1-4e9e-970a-551593b87321",
        "00605178-da28-4e22-804e-9d68c18d2852",
        "89157531-b38b-4366-89df-eaf8568c4a24",
        "d96c1bb1-8f4b-46f0-9f0f-db954d2e594a",
        "6b1fab8f-9a35-4e47-8b8b-6d8fea2ac42a",
        "eca63772-7be1-4ea8-8219-7416848ec249",
        "fe7bb180-696f-4dee-88e3-f223872974c6",
        "ae8d40d5-6ad1-4698-ad17-0b418d8fb52c",
        "ba9cc861-3609-4ca6-88d8-43a3fb9cb728",
        "5cc8867d-2fcc-4724-b4f6-fd738ba1c671",
        "99a1979d-cb2b-42e0-b67b-e9059ff5137f",
        "fd35756a-ebec-4784-9588-449b8600010d",
        "33362229-520a-45c1-b843-2072ee029ce5",
        "4306b9b7-d37d-461a-b88e-fd2370989c51",
        "ac645149-f832-4af7-8b91-47aa5f72d3c4",
        "c7d03133-060d-46a4-ad63-59c57eb2144a",
        "f3f197af-84ec-4aaf-af8a-116f30531f5b",
        "2162cbcb-9ece-422a-821c-12f1b1de2e8c",
        "1053bffc-5646-4b4f-bc95-1ba843b6088d",
        "b6a21b72-a9b1-42cc-8b4c-c34f9e454c66",
        "a736384b-89e4-4284-9f71-e1843a9d478b",
        "afcdb5fb-36be-44b1-9320-501d7f487355",
        "a222f874-d5f5-46f5-9454-75a5e6d808cb",
        "41ccc128-0991-4d4f-accf-70ad2ea41d95",
        "5ff74eba-f3cc-4a3a-98b9-066b2886c2c8",
        "6c248e89-94bc-4255-84c7-cb09a42e086c",
        "d1773f81-601c-43e2-9f1e-d978e5e09656",
        "21b7aa8a-c7cf-4847-8bff-07eaa570e8a0",
        "f0d0944e-34f4-4b8f-b072-69cb740f47a9",
        "4b39aa39-5d56-4408-955d-141e5c4d181f",
        "9cd57e88-35e3-42dd-99a1-16a7f21949ee",
        "12f24503-c781-4678-8cc1-6ddf49af2ed2",
        "c1bc2518-1c61-4c5c-8d45-35ff256c66f4",
        "722d206c-a4e5-4350-9c44-0cb6092cf9c7",
        "bf6479ab-21a1-4e4a-ba47-1bc36d853efb",
        "7709e135-e5b5-4558-8946-1787b92d5260",
        "5a614ed9-a292-45c6-819a-720f3741661a",
        "8755246b-8ec6-4a63-aee6-ee1caab0721d",
        "6ff0011e-3a9c-4150-9688-4932b7c1ba78",
        "c117a2d9-a3aa-4932-bbff-c6e6b6da1bc0",
        "38277004-af1c-488b-b326-684d01b9757b",
        "d26cf5fb-219d-48fe-bc37-5fe83890913d",
        "c0783a0c-f76f-4dcb-aaae-4949194d87a3",
        "b895106e-2f76-4355-8a2d-f44dfb7a75bd",
        "0348a75d-4609-43c9-8944-f3efb8ca2a4b",
        "b14ba50c-5cbd-4c8e-b14e-9982e3ad2a33",
        "8dbac113-563b-45ee-a9c8-37c272ab0da3",
        "862b5b45-950b-4f62-9ab9-6c53fcbf17d6",
        "3e3bb8bb-09ac-48e1-a059-bb852f2a68b7",
        "533ab1a0-6b03-41d9-9dd2-fb416ebbdaa4",
        "529d6c44-7d35-4182-9a21-6a5a2077748b",
        "dd67e6f4-5a0e-402f-bb95-e332a5bccd94",
        "fd0352de-1315-4abb-9111-fa4fe1751013",
        "e51a282e-7d74-4146-9456-fa2f9932db6e",
        "ec108563-d0d8-4005-bb61-46439de8d667",
        "3b9b0e34-dea3-4f74-83df-1af53f70056e",
        "fc50a41e-1bb1-451e-860b-f04ce1508ba5",
        "89275ca0-6170-43e9-9d91-8c7fe9ec0464",
        "3a3e36e7-1302-4f0b-abb3-85c2c96cc89c",
        "3aaf1277-ab4b-4c34-9b6a-5246a32e4d02",
        "00b4cc85-6d22-4b94-8854-1fc0b2056d1e",
        "bcf489ef-dec8-4bb6-960d-e848335c851d",
        "25bfa985-1742-4ca2-9f63-63d7717345de",
        "66518129-37d6-4614-be18-631de52e2f8a",
        "d8169b84-6e64-41a3-a6dc-64efb351cecb",
        "6ad10241-f5ed-4d24-b533-7fe593209430",
        "850447f3-b22a-45ea-83ee-e612ef9b14e6",
        "dccad404-fe95-4f8a-a739-6c1c576093cf",
        "ef4debf1-70fc-4448-a001-8f0d461b786a",
        "dd8d7ab7-bc62-4ed7-a690-a8eb717117fe",
        "41d63136-b1e8-421d-be0f-037d73a8690d",
        "26ed1ca7-7190-43ff-ad91-f062bd4432aa",
        "e2db1c03-2205-43f7-888b-3a2708f8e8a4",
        "ae50c435-d2d4-4f9b-a358-b1c0bfccee17",
        "73826713-5619-4207-995b-229133775ec3",
        "cf7a498b-a96f-44eb-8b36-a829802664b6",
        "24c90145-ad7d-47ab-b4f4-cba6df24a662",
        "59ade687-aaaf-457c-b8c9-f9537a6ad4f9",
        "cbd05bc5-142e-4429-a8de-3b14418dd980",
        "3b8217d1-0e9b-4e85-acd4-658c581fa9f4",
        "e89dc911-0922-4aa4-8d54-83f39e1083b5",
        "f7065a52-45eb-4d30-acf2-b3470bf8a58e",
        "11e864ee-f1e0-4160-a6c3-20553dccf761",
        "b5ba63d7-60e2-4d71-9e44-0652d9610765",
        "70643357-2142-47be-98bf-660c96be806e",
        "daf0312d-5cc9-474a-9854-4dc8a7660b20",
        "4ba29be6-b125-4624-8957-c9233268c447",
        "4c6c802e-2898-4829-82aa-d5f62a17873b",
        "75cef09b-9592-4f38-a1fd-7911ac644195",
        "51762c95-9192-4810-81b2-110bf2c5915d",
        "b066b177-53f5-4bbe-8afc-0df7124d03ea",
        "e8551f36-317e-4718-8425-6827e0656f72",
        "3d83138c-9ea9-4381-af11-bb1ebdd8c321",
        "c9b6632a-a5b9-4a78-86bb-460559006290",
        "b9651bed-a163-4110-a998-8ebfebd0b4de",
        "51102838-ef06-4e1f-87bc-f726daa76d86",
        "bb6828c2-9d0b-4f95-a479-c8df06752fea",
        "96d40ca3-e41b-4a60-878c-e4f377ead0a9",
        "5b212c18-a5fc-42e9-b738-0eca4db5a79b",
        "60b0c015-7797-426e-8fec-7d663db35375",
        "bd49a135-5799-40f2-b245-4641905cf317",
        "6263d314-b3e8-4573-b7ab-48d5deeec3b6",
        "6d103232-2269-4275-a1e3-2eb9079fcd53",
        "913e1d3e-786c-4f3a-b27c-9b92b7e2300f",
        "897ea5d9-0e32-47ee-a3ba-6de93ccf213e",
        "f25288fc-7ed2-44f2-94a8-22892a8c2e30",
        "03f335a8-62b2-4199-a464-d541015d9b24",
        "a5960fe9-cbc3-4aa3-8878-bbd144b1803e",
        "f28cd50d-f73b-4954-84a5-af7efa81f4aa",
        "5872e56d-8698-44a7-afec-673c5d31cc23",
        "77c7dad8-99aa-4555-b2bf-2173f3e894a8",
        "db7d4c77-45ea-4e5f-8ece-f1fae9c3da1f",
        "21f11d05-8877-4314-bd96-5619d5f9055e",
        "4b698d27-04a0-4dfe-881d-f6baeac6efbd",
        "51ec29f1-bb27-4a36-b143-e6230762aa75",
        "28b42916-32f2-4735-864d-8c83d16b0faf",
        "75be53d0-9ecc-4920-98bc-ff4672f71576",
        "f42ead25-6085-4cde-9d02-80fdc4b1c560",
        "07679a57-21d9-4405-bccd-980c36305703",
        "852afa09-6a0f-4cd8-b4b6-23537d28e5db",
        "10501808-adf3-497c-9f89-40174d8ce843",
        "f3858449-dfe3-4754-bc64-afb7cdd3a806",
        "4c2f890e-6671-4aa3-8b85-a50a4500b2d7",
        "641911f6-a5d0-4065-82d2-fbae4d8faa17",
        "836a3258-0f12-4559-ad33-621fbc6e8e02",
        "45b07948-ebf8-4696-b9ae-0b0148586ba1",
        "1ad7d492-3b21-4a1d-bf30-2aa2f3c32023",
        "b402ea86-3aa7-4ce3-a78b-286f00036640",
        "60497511-8a19-48bb-aef5-638e88f240bc",
        "e2f2f131-4de0-4288-93b7-9e3cf5361cd1",
        "bc70adad-4e24-4d05-88a7-1a25d2796328",
        "7d3b6b7e-f82b-4444-94b1-f3ee95f77901",
        "2347f415-9338-4bb1-9081-975a681800ed",
        "a70af5c5-c92e-4b0d-8d12-0e17b2cda9f7",
        "e914d510-d80d-47cc-98e2-6e36ac5e6962",
        "f819cd03-09b3-4a21-abd7-64cf9df375a5",
        "c60db473-f4c1-4dc7-85f0-82ed89777cbb",
        "86205408-aa38-446a-b831-1de9187c6b18",
        "6a89a136-effb-4b9f-9548-8e31cd4701f0",
        "fc8178d1-c12b-441c-b22c-772d6c37e964",
        "233722f4-1b45-48e5-88a4-889feb0ed324",
        "7d653c8d-0535-42fa-943e-3435bbbe7744",
        "9cefbf00-ed92-4de2-aed6-fe00180282ce",
        "721f4f92-a253-46fc-8e7e-1f40e60cc4e2",
        "9bbff842-9116-4c92-bcfc-cdf0f354e723",
        "66157bf3-3ff7-4a8a-aefb-85a12ccc8bc9",
        "2526daca-f956-4e50-b5ac-b445f6f5b544",
        "d8fa6085-380b-4b55-91d6-d08317075918",
        "58fbb1d3-3831-4de9-bd74-af29589b9e1b",
        "bd05bd49-5d93-47c9-a9f8-0b8bfee92db3",
        "080218b1-7722-4a5c-a436-654bd1a71089",
        "9445eb38-5490-4c4f-9dc8-73f783571800",
        "5abee805-2c39-4a3a-84be-a3d087b10104",
        "7c8fcd2e-b9c8-41ec-bee9-b8a66c92779c",
        "51693fc1-0fba-4a2b-b8f7-6fc36d025cda",
        "669b1097-5a8a-4927-af04-f7bf85276ac5",
        "22af615e-473e-4a66-ae61-12216c428d13",
        "14eb4d44-980e-4933-a498-77142523fba1",
        "701b26a8-868e-4bfc-af0e-489e4cc5c075",
        "c77218f8-9e61-42db-b725-eb196fe9c227",
        "d643d1f5-cb81-458c-9899-9c4f5bb8e0f1",
        "8b732d40-4a85-46aa-a532-4633d35dc87e",
        "0441bb00-b804-433c-be20-ee1ceb6a9dbb",
        "8256f64c-2f1a-4fad-84da-c885e67d6ce3",
        "82fc8dd1-ccbd-41e6-bfed-fd87f1d06ced"
    ]
}

Deduplicated Items

Finally, Let’s retrieve the deduplicated items from the item set using our search endpoint. For brevity, the max number of records requested has been reduced to 5. As you can see, there are 386 items returned using the item-set-originals query.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v2/cases/43b070164ce8453ca30ed9e2dfcce67b/search?query=item-set-originals:HelloItemSet&metadataProfile=Default&numberOfRecordsRequested=5' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "request": {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
        "query": "item-set-originals:HelloItemSet",
        "sortField": null,
        "sortOrder": null,
        "startIndex": 0,
        "numberOfRecordsRequested": 5,
        "deduplicate": null,
        "metadataProfile": "Default",
        "fieldList": null,
        "customMetadataList": null,
        "propertyList": null,
        "itemParameterizedFields": null,
        "showAvailableThumbnails": false,
        "useCache": false,
        "forceCacheDelete": false,
        "searchRetry": 0,
        "relationType": null,
        "entities": [],
        "s": 0,
        "p": 5,
        "customMetadataField": null,
        "property": null,
        "field": null
    },
    "startedOn": 1613594869418,
    "completedOn": 1613594869432,
    "elapsedTimeForSearch": 9,
    "elapsedTimeForSort": 0,
    "elapsedTimeForMarshal": 1,
    "elapsedTimeForDeduplicate": 0,
    "elapsedTotal": 14,
    "metadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "localizedMetadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "metadataItemDetails": [
        {
            "name": "Name",
            "localisedName": "Name",
            "type": "String"
        },
        {
            "name": "File Type",
            "localisedName": "File Type",
            "type": "String"
        },
        {
            "name": "Path Name",
            "localisedName": "Path Name",
            "type": "String"
        }
    ],
    "resultList": [
        {
            "File Type": "Nuix Evidence File",
            "Name": "d29719c8-517e-48cb-9fd6-983dd2d6671b",
            "Path Name": "/",
            "guid": "75f02dfe-989d-4f93-aade-cd4334042254"
        },
        {
            "File Type": "Directory",
            "Name": "doc",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b",
            "guid": "97806413-9715-48ed-a08c-03fc0c79f8b9"
        },
        {
            "File Type": "Nuix Evidence File",
            "Name": "e1746668-8eca-48b2-a8bd-14f17c59c1e1",
            "Path Name": "/",
            "guid": "668c6144-071d-420e-9fe5-a11bd63e2326"
        },
        {
            "File Type": "Nuix Evidence File",
            "Name": "8c970c8e-8e9d-4dcb-bb42-07d2980a6b3f",
            "Path Name": "/",
            "guid": "087eb560-5e5b-4c7e-a745-028602ce0104"
        },
        {
            "File Type": "Directory",
            "Name": "api",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc",
            "guid": "dfb9d2b2-3a5b-4013-9c6d-1ed44910d49a"
        }
    ],
    "count": 386,
    "deduplicatedCount": 386
}

Getting Started: Part 10: OCR

Thu, 05 Aug 2021 00:00:00 +0000

In this example, we will ingest the Nuix logo below into our case and perform Optical Character Recognition (OCR) on it. Right click on the image in your browser to save the image to disk as nuix.png.

Verify OCR Capability

In order to perform an OCR, the OCR plugin from https://download.nuix.com/releases/addons needs to be installed. To verify that the OCR plugin is installed call the resources/ocr endpoint.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/resources/ocr' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "success": true
}

File Ingestion of Image

Next, let’s ingest our image with text.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/evidence/file' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "processorSettings": {
   	"storeBinary": true
   },
   "target": {
    "path": "/Images/nuix.png"
  }
}
'

{
    "functionKey": "f599c065-523e-4dd5-8ab1-82cad97afe8b",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/f599c065-523e-4dd5-8ab1-82cad97afe8b"
}

File Ingestion Status

The functionKey field returned from the ingestion endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/f599c065-523e-4dd5-8ab1-82cad97afe8b' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "a3b10cf2-1c75-4507-86dd-865eb56555b7",
    "functionKey": "f599c065-523e-4dd5-8ab1-82cad97afe8b",
    "progress": 7011,
    "total": 0,
    "percentComplete": null,
    "updatedOn": 1613506664487,
    "status": null,
    "statusId": null,
    "requestTime": 1613506653553,
    "startTime": 1613506653553,
    "finishTime": 1613506666353,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "nuixadmin",
    "action": "AsyncBulkIngestionFunction",
    "options": {
        "reloadQuery": null,
        "processorSettings": {
            "processText": null,
            "processLooseFileContents": null,
            "processForensicImages": null,
            "analysisLanguage": null,
            "stopWords": null,
            "stemming": null,
            "enableExactQueries": null,
            "extractNamedEntities": null,
            "extractNamedEntitiesFromText": null,
            "extractNamedEntitiesFromProperties": null,
            "extractNamedEntitiesFromTextStripped": null,
            "extractShingles": null,
            "processTextSummaries": null,
            "calculateSSDeepFuzzyHash": null,
            "detectFaces": null,
            "extractFromSlackSpace": null,
            "carveFileSystemUnallocatedSpace": null,
            "carveUnidentifiedData": null,
            "carvingBlockSize": null,
            "recoverDeletedFiles": null,
            "extractEndOfFileSlackSpace": null,
            "smartProcessRegistry": null,
            "identifyPhysicalFiles": null,
            "createThumbnails": null,
            "skinToneAnalysis": null,
            "calculateAuditedSize": null,
            "storeBinary": true,
            "maxStoredBinarySize": null,
            "maxDigestSize": null,
            "digests": [],
            "addBccToEmailDigests": null,
            "addCommunicationDateToEmailDigests": null,
            "reuseEvidenceStores": null,
            "processFamilyFields": null,
            "hideEmbeddedImmaterialData": null,
            "reportProcessingStatus": null,
            "workerItemCallback": null,
            "workerItemCallbacks": null
        },
        "evidence": [
            {
                "guid": null,
                "name": null,
                "customMetadata": null,
                "encoding": null,
                "custodian": null,
                "timeZone": null,
                "description": null,
                "locale": null,
                "files": [
                    {
                        "path": "/Images/nuix.png"
                    }
                ],
                "exchangeMailboxes": null,
                "s3Buckets": null,
                "sqlServers": null,
                "enterpriseVaults": null,
                "sharepointSites": null,
                "mailStores": null,
                "loadFiles": null,
                "centeraClusters": null,
                "splitFiles": null,
                "dropboxes": null,
                "sshServers": null
            }
        ],
        "localWorkerCount": 1,
        "repositories": [],
        "parallelProcessingSettings": {
            "workerCount": null,
            "workerMemory": null,
            "workerTemp": null,
            "brokerMemory": null,
            "workerBrokerAddress": null,
            "useRemoteWorkers": false,
            "embedBroker": true
        },
        "rescanEvidenceRepositories": false,
        "loadProcessingJob": {
            "casePath": "/Cases/HelloWorld",
            "jobGuid": "55480a21-720c-4f3e-baa6-c7c5b53b28b0",
            "processingMode": "Load",
            "startDate": 1613506654064,
            "workerCount": 1,
            "finished": true,
            "paused": false,
            "masterAddress": "1.1.1.1",
            "bytesProcessed": 7011,
            "itemsProcessed": 1,
            "jobSizeTotalBytes": 0
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-1",
    "errorMsg": null
}

Item Verification

Let’s verify that we have the item (nuix.png) in our case by doing a search. We will also retrieve the guid of the item for OCR.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v2/cases/43b070164ce8453ca30ed9e2dfcce67b/search?query=nuix.png&metadataProfile=Default&numberOfRecordsRequested=100' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "request": {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
        "query": "nuix.png",
        "sortField": null,
        "sortOrder": null,
        "startIndex": 0,
        "numberOfRecordsRequested": 1,
        "deduplicate": null,
        "metadataProfile": "Default",
        "fieldList": null,
        "customMetadataList": null,
        "propertyList": null,
        "itemParameterizedFields": null,
        "showAvailableThumbnails": false,
        "useCache": false,
        "forceCacheDelete": false,
        "searchRetry": 0,
        "relationType": null,
        "entities": [],
        "s": 0,
        "p": 1,
        "customMetadataField": null,
        "field": null,
        "property": null
    },
    "startedOn": 1613507186542,
    "completedOn": 1613507186598,
    "elapsedTimeForSearch": 50,
    "elapsedTimeForSort": 0,
    "elapsedTimeForMarshal": 1,
    "elapsedTimeForDeduplicate": 0,
    "elapsedTotal": 56,
    "metadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "localizedMetadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "metadataItemDetails": [
        {
            "name": "Name",
            "localisedName": "Name",
            "type": "String"
        },
        {
            "name": "File Type",
            "localisedName": "File Type",
            "type": "String"
        },
        {
            "name": "Path Name",
            "localisedName": "Path Name",
            "type": "String"
        }
    ],
    "resultList": [
        {
            "File Type": "Portable Network Graphic",
            "Name": "nuix.png",
            "Path Name": "/e1746668-8eca-48b2-a8bd-14f17c59c1e1",
            "guid": "519ca60c-a397-4d1b-a5aa-547287a8ad1a"
        }
    ],
    "count": 1,
    "deduplicatedCount": 1
}

OCR

Let’s OCR the item using the guid returned from our search query.

519ca60c-a397-4d1b-a5aa-547287a8ad1a

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/items/ocr' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "parallelProcessingSettings": {
    "embedBroker": true,
    "workerCount": 4,
    "workerMemory": 2048
  },
  "query": "guid:519ca60c-a397-4d1b-a5aa-547287a8ad1a"
}'

{
    "functionKey": "f534cd08-c374-4c7a-acf4-32ec613adbff",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/f534cd08-c374-4c7a-acf4-32ec613adbff"
}

OCR Status

The functionKey field returned from the OCR endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/f534cd08-c374-4c7a-acf4-32ec613adbff' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": {
        "total": 1,
        "failure": 0
    },
    "token": "a3b10cf2-1c75-4507-86dd-865eb56555b7",
    "functionKey": "f534cd08-c374-4c7a-acf4-32ec613adbff",
    "progress": 1,
    "total": 1,
    "percentComplete": 100.0000,
    "updatedOn": 1613507447309,
    "status": null,
    "statusId": null,
    "requestTime": 1613507437697,
    "startTime": 1613507437698,
    "finishTime": 1613507449524,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "OCR Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "username",
    "action": "AsyncOcrFunction",
    "options": {
        "ocrOptions": {
            "regeneratePdfs": null,
            "updatePdf": null,
            "updateText": null,
            "textModification": null,
            "quality": null,
            "rotation": null,
            "deskew": null,
            "clearOcrCache": null,
            "outputDirectory": null,
            "languages": [
                "ENGLISH"
            ],
            "timeout": null,
            "updateDuplicates": null,
            "ocrProfileName": null
        },
        "localWorkerCount": 1,
        "parallelProcessingSettings": {
            "workerCount": 4,
            "workerMemory": 2048,
            "workerTemp": null,
            "brokerMemory": null,
            "workerBrokerAddress": null,
            "useRemoteWorkers": false,
            "embedBroker": true
        },
        "query": "guid:519ca60c-a397-4d1b-a5aa-547287a8ad1a",
        "ocrProfile": null,
        "ocrImagingSettings": null,
        "exportProcessingJob": {
            "casePath": "/Cases/HelloWorld",
            "jobGuid": "145e16b9-7800-4240-b108-a2e8ecc58724",
            "processingMode": "Export",
            "startDate": 1613507437889,
            "workerCount": 9,
            "finished": true,
            "paused": false,
            "masterAddress": "1.1.1.1",
            "currentStage": "TEXT_REPLACEMENT",
            "currentStageDuration": "0 seconds",
            "currentStageExportedItemsCount": 1,
            "failedItemCount": 0,
            "totalItemCount": 1
        },
        "imagingProfile": null,
        "tags": null
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-1",
    "errorMsg": null
}

Item Text

Finally, let’s retrieve the item text of the image using the itemText endpoint.

curl --location --request GET 'http://localhost:8080/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/items/519ca60c-a397-4d1b-a5aa-547287a8ad1a/itemText' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "text": "nuix",
    "binaryAvailable": true,
    "htmlEscape": false,
    "totalTextLength": 4,
    "blank": false
}

The text field in the response is nuix and we have successfully performed an OCR on this image.

Getting Started: Part 11: Tagging

Thu, 05 Aug 2021 00:00:00 +0000

Tagging

Let’s tag some items in the case. For this example, we will tag all files with an HTML file extension. Additionally, we want to exclude duplicates so we are going to use the item set we created earlier in the tutorial.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v2/cases/43b070164ce8453ca30ed9e2dfcce67b/itemTags' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "query": "item-set-originals:HelloItemSet AND file-extension:html",
  "tagList": [
    "HTMLFiles"
  ]
}'

{
    "tagList": [
        "HTMLFiles"
    ],
    "successfulTags": [
        "HTMLFiles"
    ],
    "failedTags": []
}

Tag Verification

Let’s verify the items that we have tagged using a simple synchronous search. We will use the query tag:HTMLFiles. The search returned 302 results.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v2/cases/43b070164ce8453ca30ed9e2dfcce67b/search?query=tag:HTMLFiles&metadataProfile=Default&numberOfRecordsRequested=5' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "request": {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
        "query": "tag:HTMLFiles",
        "sortField": null,
        "sortOrder": null,
        "startIndex": 0,
        "numberOfRecordsRequested": 5,
        "deduplicate": null,
        "metadataProfile": "Default",
        "fieldList": null,
        "customMetadataList": null,
        "propertyList": null,
        "itemParameterizedFields": null,
        "showAvailableThumbnails": false,
        "useCache": false,
        "forceCacheDelete": false,
        "searchRetry": 0,
        "relationType": null,
        "entities": [],
        "p": 5,
        "s": 0,
        "customMetadataField": null,
        "field": null,
        "property": null
    },
    "startedOn": 1612986781150,
    "completedOn": 1612986781172,
    "elapsedTimeForSearch": 16,
    "elapsedTimeForSort": 0,
    "elapsedTimeForMarshal": 2,
    "elapsedTimeForDeduplicate": 0,
    "elapsedTotal": 22,
    "metadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "localizedMetadataItems": [
        "Name",
        "File Type",
        "Path Name"
    ],
    "metadataItemDetails": [
        {
            "name": "Name",
            "localisedName": "Name",
            "type": "String"
        },
        {
            "name": "File Type",
            "localisedName": "File Type",
            "type": "String"
        },
        {
            "name": "Path Name",
            "localisedName": "Path Name",
            "type": "String"
        }
    ],
    "resultList": [
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "allclasses.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "4350a26e-0582-4cdd-8903-feb2454b66ad"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "allclasses-index.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "48fdd676-ecdf-4271-8fb0-a312570888a5"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "allpackages-index.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "b5d26466-0b5f-4b01-bc2e-7ebe6c6d3294"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "index.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "8bc28b97-6d5a-4755-8066-4fa2102705de"
        },
        {
            "File Type": "Hypertext Markup Language Document",
            "Name": "constant-values.html",
            "Path Name": "/d29719c8-517e-48cb-9fd6-983dd2d6671b/doc/api",
            "guid": "ee4cb26f-30b5-4a76-8789-dfbd7fdecf65"
        }
    ],
    "count": 302,
    "deduplicatedCount": 302
}

Counting Tags

Instead of using search, let’s verify how many items we have tagged using the count endpoint. The response verifies that we have tagged 302 HTML files.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/count' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "tag:HTMLFiles"
}'

{
    "count": 302,
    "query": "tag:HTMLFiles",
    "casePath": "/Cases/HelloWorld",
    "caseGuid": "43b070164ce8453ca30ed9e2dfcce67b"
}

Getting Started: Part 12: Production Sets

Thu, 05 Aug 2021 00:00:00 +0000

Production Sets

Now that we have culled some data. Let’s create a production set. Creating a production set is an asynchronous task. The response is an asynchronous function key that we can poll for status.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/productionSets' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "description": "My first production set",
  "name": "HelloProductionSet",
  "query": "tag:HTMLFiles"
}'

{
    "functionKey": "d1471527-dd28-46cf-a5cd-e2f4efc8d9ed",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/d1471527-dd28-46cf-a5cd-e2f4efc8d9ed"
}

Production Set Status

We have now created a production set with 302 elements. Take note of the production set ID that is returned in the result field of the asynchronous function response. You will need this for a legal export.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/d1471527-dd28-46cf-a5cd-e2f4efc8d9ed' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": "59d69780-963a-478c-9f4b-0d2bb4c84a3f",
    "token": "db63fbfc-a5fd-494e-974b-cc17f6b2a56a",
    "functionKey": "d1471527-dd28-46cf-a5cd-e2f4efc8d9ed",
    "progress": 302,
    "total": 302,
    "percentComplete": 100.0,
    "updatedOn": 1612987413154,
    "status": null,
    "statusId": null,
    "requestTime": 1612987408327,
    "startTime": 1612987408327,
    "finishTime": 1612987413257,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Production Set Creation Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "username",
    "action": "AsyncProductionSetCreationFunction",
    "options": {
        "productionSetName": "HelloProductionSet",
        "numberingPrefix": "nuix",
        "query": "tag:HTMLFiles",
        "applyHighlights": true,
        "includeFamilies": false,
        "generatePdfStores": null,
        "productionSetDescription": "My first production set",
        "markupSets": null,
        "parallelProcessingSettings": null,
        "pdfStoresQuery": "",
        "guid": "59d69780-963a-478c-9f4b-0d2bb4c84a3f",
        "startingDocumentNumber": "nuix000000001",
        "endingDocumentNumber": "nuix000000302",
        "applyRedactions": true,
        "nextDocumentNumber": "nuix000000303"
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restfuls-server-1",
    "errorMsg": null
}

Getting Started: Part 13: Case Subset

Thu, 05 Aug 2021 00:00:00 +0000

Case Subset

Let’s create a case subset of our tagged HTML files using the query tag:HTMLFiles.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/subset' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
	"query": "tag:HTMLfiles",
	"location": "inventory0",
	"evidenceStoreCount": 1,
	"includeFamilies": false,
	"copyTags": false,
	"copyComments": false,
	"copyCustodians": false,
	"copyItemSets": false,
	"copyClassifiers": false,
	"copyMarkupSets": false,
	"copyProductionSets": false,
	"copyClusters": false,
	"copyCustomMetadata": false,
	"caseMetadata": {
		"name": "HelloHTMLFiles",
		"description": "HTML files case subsetted",
		"investigator":"Inspector Gadget"
	}
}'

{
    "functionKey": "7cdcba36-7d9d-4d55-a9f7-b0e179fa5162",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/7cdcba36-7d9d-4d55-a9f7-b0e179fa5162"
}

Case Subset Status

The functionKey field returned from the case subset endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/7cdcba36-7d9d-4d55-a9f7-b0e179fa5162' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": "cc58650fb513494e944166cfb39494d5",
    "token": "7a40f78e-48f0-4a2c-b9aa-423251e2b4c1",
    "functionKey": "7cdcba36-7d9d-4d55-a9f7-b0e179fa5162",
    "progress": 314,
    "total": 1,
    "percentComplete": 31400.0000,
    "updatedOn": 1613163116856,
    "status": null,
    "statusId": null,
    "requestTime": 1613163085787,
    "startTime": 1613163090254,
    "finishTime": 1613163121958,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Case Subset Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "nuixadmin",
    "action": "AsyncCaseSubsetFunction",
    "options": {
        "query": "tag:HTMLfiles",
        "options": {
            "copyComments": false,
            "copyCustodians": false,
            "evidenceStoreCount": 1,
            "copyCustomMetadata": false,
            "copyItemSets": false,
            "copyProductionSets": false,
            "copyTags": false,
            "copyClusters": false,
            "copyMarkupSets": false,
            "includeFamilies": false,
            "copyClassifiers": false,
            "caseMetadata": {
                "investigator": "Inspector Gadget",
                "name": "HelloHTMLFiles",
                "description": "HTML files case subsetted",
                "binaryStoreLocation": null
            }
        },
        "location": "/Cases/HelloHTMLFiles"
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-2",
    "errorMsg": null
}

Inventory Verification

The result field in the polled response is the case ID of the newly created case. Let’s verify it exists in our inventory.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/inventory/digest' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

[
      {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
        "name": "HelloWorld",
        "path": "/Cases/HelloWorld",
        "description": "My first simple Nuix case",
        "investigator": "Inspector Gadget",
        "creationDate": 1612906749154,
        "compound": false,
        "elastic": false,
        "binaryStoreLocation": "",
        "indexId": "",
        "productName": "Nuix",
        "version": "8.9.1",
        "isOpen": false,
        "childCases": [],
        "url": "http://localhost:8080",
        "serverId": "nuix-restful-server-1"
     }, 
     {
        "caseId": "cc58650fb513494e944166cfb39494d5",
        "name": "HelloHTMLFiles",
        "path": "/Cases/HelloHTMLFiles",
        "description": "HTML files case subsetted",
        "investigator": "Inspector Gadget",
        "creationDate": 1613163100246,
        "compound": false,
        "elastic": false,
        "binaryStoreLocation": "",
        "indexId": "",
        "productName": "Nuix",
        "version": "8.9.1",
        "isOpen": false,
        "childCases": [],
        "url": "http://localhost:8080",
        "serverId": "nuix-restful-server-1"
    }
]

The new case HelloHTMLFiles is in the inventory with case ID cc58650fb513494e944166cfb39494d5.

Elasticsearch Case Subset

We can also take our HelloWorld case, and create a case subset for an Elasticsearch case. Let’s try it out. Elasticsearch settings are provided in the caseMetadata field.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/subset' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
	"query": "tag:HTMLfiles",
	"location": "inventory0",
	"evidenceStoreCount": 1,
	"includeFamilies": false,
	"copyClassifiers": false,
	"copyMarkupSets": false,
	"copyProductionSets": false,
	"copyClusters": false,
	"copyCustomMetadata": false,
	"caseMetadata": {
		"name": "HelloElasticHTMLFiles",
		"description": "HTML files case subsetted into Elasticsearch",
		"investigator":"Inspector Gadget",
        "elasticSearchSettings" : {
            "cluster.name": "elasticsearch",
            "nuix.transport.hosts": ["127.0.0.1"],
            "nuix.http.hosts": ["127.0.0.1"],
            "index.number_of_shards": 1
        }
	}
}'

{
    "functionKey": "ec04c044-66f6-4f9e-af4f-583b51f22d55",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/ec04c044-66f6-4f9e-af4f-583b51f22d55"
}

Elasticsearch Case Subset Status

Again, the functionKey field returned from the case subset endpoint above can be polled for status.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/ec04c044-66f6-4f9e-af4f-583b51f22d55' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'
--header 'Cookie: JSESSIONID=64EC387C1A3CD403896EF14506B03BD9'

{
    "done": true,
    "cancelled": false,
    "result": "664649c33a064ba796b28f65caac77c2",
    "token": "7a40f78e-48f0-4a2c-b9aa-423251e2b4c1",
    "functionKey": "ec04c044-66f6-4f9e-af4f-583b51f22d55",
    "progress": 0,
    "total": 1,
    "percentComplete": 0.0000,
    "updatedOn": 1613164209724,
    "status": null,
    "statusId": null,
    "requestTime": 1613164206990,
    "startTime": 1613164209722,
    "finishTime": 1613164215014,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Case Subset Function",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "nuixadmin",
    "action": "AsyncCaseSubsetFunction",
    "options": {
        "query": "tag:HTMLfiles",
        "options": {
            "copyComments": false,
            "copyCustodians": false,
            "evidenceStoreCount": 1,
            "copyCustomMetadata": false,
            "copyItemSets": false,
            "copyProductionSets": false,
            "copyTags": false,
            "copyClusters": false,
            "copyMarkupSets": false,
            "includeFamilies": false,
            "copyClassifiers": false,
            "caseMetadata": {
                "investigator": "Inspector Gadget",
                "name": "HelloElasticHTMLFiles",
                "description": "HTML files case subsetted into Elasticsearch",
                "binaryStoreLocation": null,
                "elasticSearchSettings": {
                    "index.refresh_interval": "60s",
                    "nuix.transport.hosts": [
                        "127.0.0.1"
                    ],
                    "cluster.name": "elasticsearch",
                    "index.number_of_replicas": 0,
                    "nuix.http.hosts": [
                        "127.0.0.1"
                    ],
                    "nuix.index.auto_close": false,
                    "index.number_of_shards": 1,
                    "xpack.security.transport.ssl.enabled": false
                }
            }
        },
        "location": "/Cases/HelloElasticHTMLFiles"
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-2",
    "errorMsg": null
}

Inventory Verification

The result field in the polled response is the case ID of the newly created Elasticsearch case. Let’s verify it exists in our inventory.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/inventory/digest' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

[
     {
        "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
        "name": "HelloWorld",
        "path": "/Cases/HelloWorld",
        "description": "My first simple Nuix case",
        "investigator": "Inspector Gadget",
        "creationDate": 1612906749154,
        "compound": false,
        "elastic": false,
        "binaryStoreLocation": "",
        "indexId": "",
        "productName": "Nuix",
        "version": "8.9.1",
        "isOpen": false,
        "childCases": [],
        "url": "http://localhost:8080",
        "serverId": "nuix-restful-server-1"
     }, 
     {
        "caseId": "cc58650fb513494e944166cfb39494d5",
        "name": "HelloHTMLFiles",
        "path": "/Cases/HelloHTMLFiles",
        "description": "HTML files case subsetted",
        "investigator": "Inspector Gadget",
        "creationDate": 1613163100246,
        "compound": false,
        "elastic": false,
        "binaryStoreLocation": "",
        "indexId": "",
        "productName": "Nuix",
        "version": "8.9.1",
        "isOpen": false,
        "childCases": [],
        "url": "http://localhost:8080",
        "serverId": "nuix-restful-server-1"
    },
    {
        "caseId": "664649c33a064ba796b28f65caac77c2",
        "name": "HelloElasticHTMLFiles",
        "path": "/Cases/HelloElasticHTMLFiles",
        "description": "HTML files case subsetted into Elasticsearch",
        "investigator": "Inspector Gadget",
        "creationDate": 1613164125600,
        "compound": false,
        "elastic": true,
        "binaryStoreLocation": "/Cases/HelloElasticHTMLFiles/Stores/BinaryStore",
        "indexId": "nuix-664649c33a064ba796b28f65caac77c2",
        "productName": "Nuix",
        "version": "8.9.1",
        "isOpen": false,
        "childCases": [],
        "url": "http://localhost:8080",
        "serverId": "nuix-restful-server-1"
    }
]

The new case HelloElasticHTMLFiles is in the inventory with case ID 664649c33a064ba796b28f65caac77c2.

Getting Started: Part 14: Exports

Thu, 05 Aug 2021 00:00:00 +0000

Legal Export

Let’s go ahead and do a legal export of our production set. We will use the production set ID

59d69780-963a-478c-9f4b-0d2bb4c84a3f

returned from the previous create production set task.

For this example, we will create a Ringtail (now, Nuix Discover®), load file and export both natives and PDF files.

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/export' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "exportType": "LEGAL",
  "productionSets": [
      "59d69780-963a-478c-9f4b-0d2bb4c84a3f"
  ],
  "path": "/Exports/legalExport",
  "loadFileTypes": [
    "RINGTAIL"
  ],
  "productTypes": [
    "NATIVE",
    "PDF"
  ],
  "parallelProcessingSettings": {
  	"workerCount": 1
  }
}'

{
    "functionKey": "11f72ad8-3540-4751-89f1-8759af5ae9bb",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/11f72ad8-3540-4751-89f1-8759af5ae9bb"
}

Legal Export Status

We can now poll for the legal export status of our production set and review the export.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/11f72ad8-3540-4751-89f1-8759af5ae9bb' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": [
        true
    ],
    "token": "db63fbfc-a5fd-494e-974b-cc17f6b2a56a",
    "functionKey": "b2da1a23-037e-4218-800e-7a61e4911128",
    "progress": 0,
    "total": 1,
    "percentComplete": 0.0000,
    "updatedOn": 1612989562059,
    "status": null,
    "statusId": null,
    "requestTime": 1612989562058,
    "startTime": 1612989562058,
    "finishTime": 1612990079261,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Chained Functions",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "nuixadmin",
    "action": "AsyncFunctionChain",
    "options": {
        "functions": [
            "59d69780-963a-478c-9f4b-0d2bb4c84a3f"
        ],
        "59d69780-963a-478c-9f4b-0d2bb4c84a3f": {
            "productionSetName": "HelloProductionSet",
            "path": "/Exports/legalexport/20210210153922/HelloProductionSet",
            "localWorkerCount": 2,
            "parallelProcessingSettings": {
                "workerCount": 1,
                "workerMemory": null,
                "workerTemp": null,
                "brokerMemory": null,
                "workerBrokerAddress": null,
                "useRemoteWorkers": false,
                "embedBroker": true
            },
            "exportType": "LEGAL",
            "productTypes": [
                "NATIVE",
                "PDF"
            ],
            "exportProcessingJob": {
                "casePath": "/Cases/HelloWorld",
                "jobGuid": "d48ca147-3325-450a-be29-e1a465800685",
                "processingMode": "Export",
                "startDate": 1612989562423,
                "workerCount": 9,
                "finished": true,
                "paused": false,
                "masterAddress": "192.168.86.53",
                "currentStage": "LOAD_FILES",
                "currentStageDuration": "0 seconds",
                "currentStageExportedItemsCount": 302,
                "failedItemCount": 0,
                "totalItemCount": 302
            },
            "exportId": "20210210153922",
            "loadFileTypes": [
                "RINGTAIL"
            ],
            "productionSetId": "59d69780-963a-478c-9f4b-0d2bb4c84a3f"
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "admin-console-nuix-ims1-server",
    "errorMsg": null
}

Item Export

We can also export items using a query. Let’s export the HTML files from this case. For this example, we will export both natives and PDF files.

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/export' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "exportType": "ITEM",
  "path": "/Exports/itemExport",
   "productTypes": [
    "NATIVE",
    "PDF"
  ],
  "queries": [
    "tag:HTMLFiles"
  ],
  "parallelProcessingSettings": {
  	"workerCount": 1
  }
}'

{
    "functionKey": "e89de475-ea07-4a22-a6d9-633f4701b73e",
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/e89de475-ea07-4a22-a6d9-633f4701b73e"
}

Item Export Status

We can now poll the item export status and review the export.

curl --location --request GET 'http://localhost:8080/svc/v1/asyncFunctions/e89de475-ea07-4a22-a6d9-633f4701b73e' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'

{
    "done": true,
    "cancelled": false,
    "result": [
        true
    ],
    "token": "a3b10cf2-1c75-4507-86dd-865eb56555b7",
    "functionKey": "e89de475-ea07-4a22-a6d9-633f4701b73e",
    "progress": 0,
    "total": 1,
    "percentComplete": 0.0000,
    "updatedOn": 1613501410724,
    "status": null,
    "statusId": null,
    "requestTime": 1613501408202,
    "startTime": 1613501408202,
    "finishTime": 1613501437129,
    "caseId": "43b070164ce8453ca30ed9e2dfcce67b",
    "caseName": "HelloWorld",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Chained Functions",
    "caseLocation": "/Cases/HelloWorld",
    "requestor": "username",
    "action": "AsyncFunctionChain",
    "options": {
        "functions": [
            "ef0d71a8-f815-4392-bff2-82d78f17d872"
        ],
        "ef0d71a8-f815-4392-bff2-82d78f17d872": {
            "path": "/Exports/itemExport/20210216135011",
            "localWorkerCount": 1,
            "parallelProcessingSettings": {
                "workerCount": 1,
                "workerMemory": null,
                "workerTemp": null,
                "brokerMemory": null,
                "workerBrokerAddress": null,
                "useRemoteWorkers": false,
                "embedBroker": true
            },
            "exportType": "ITEM",
            "query": "tag:HTMLFiles",
            "productTypes": [
                "NATIVE",
                "PDF"
            ],
            "exportProcessingJob": {
                "casePath": "/Cases/HelloWorld",
                "jobGuid": "e199e3b3-698d-4b73-aefb-f5d48a5705e0",
                "processingMode": "Export",
                "startDate": 1613501418417,
                "workerCount": 9,
                "finished": true,
                "paused": false,
                "masterAddress": "1.1.1.1",
                "currentStage": "CREATE_PRODUCTION_SET",
                "currentStageDuration": "0 seconds",
                "currentStageExportedItemsCount": 302,
                "failedItemCount": 0,
                "totalItemCount": 302
            },
            "exportId": "20210216135011",
            "loadFileTypes": []
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "nuix-restful-server-1",
    "errorMsg": null
}

Item Download

We can also download individual items in their native format. For this example, we will just select an HTML file at random.

curl --location --request GET 'http://localhost:8080/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/items/4350a26e-0582-4cdd-8903-feb2454b66ad/download' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d'
--header 'Content-Type: application/json' \
--header 'Accept: application/octet-stream' \
--data-raw ''

<!DOCTYPE HTML>
<!-- NewPage -->
<html lang="en">

<head>
	<!-- Generated by javadoc (11.0.6) on Fri Jan 08 17:38:21 AEDT 2021 -->
	<title>All Classes (Nuix Core 9.0.0.171)</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<meta name="dc.created" content="2021-01-08">
	<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
	<link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
	<script type="text/javascript" src="script.js"></script>
	<script type="text/javascript" src="jquery/jszip/dist/jszip.min.js"></script>
	<script type="text/javascript" src="jquery/jszip-utils/dist/jszip-utils.min.js"></script>
	<!--[if IE]>
<script type="text/javascript" src="jquery/jszip-utils/dist/jszip-utils-ie.min.js"></script>
<![endif]-->
	<script type="text/javascript" src="jquery/jquery-3.3.1.js"></script>
	<script type="text/javascript" src="jquery/jquery-migrate-3.0.1.js"></script>
	<script type="text/javascript" src="jquery/jquery-ui.js"></script>
</head>

<body>
	<h1 class="bar">All&nbsp;Classes</h1>
	<main role="main" class="indexContainer">
		<ul>
			<li><a href="nuix/AddedWorkers.html"
					title="interface in nuix"><span class="interfaceName">AddedWorkers</span></a></li>
			<li><a href="nuix/Address.html" title="interface in nuix"><span class="interfaceName">Address</span></a>
			</li>
			<li><a href="nuix/AfterExportCallback.html"
					title="interface in nuix"><span class="interfaceName">AfterExportCallback</span></a></li>
			<li><a href="nuix/AfterExportCallbackInfo.html"
					title="interface in nuix"><span class="interfaceName">AfterExportCallbackInfo</span></a></li>
			<li><a href="nuix/engine/AvailableLicence.html"
					title="interface in nuix.engine"><span class="interfaceName">AvailableLicence</span></a></li>
			<li><a href="nuix/annotation/AvailableWithAnyLicence.html"
					title="annotation in nuix.annotation">AvailableWithAnyLicence</a></li>
			<li><a href="nuix/annotation/AvailableWithFeature.html"
					title="annotation in nuix.annotation">AvailableWithFeature</a></li>
			<li><a href="nuix/annotation/AvailableWithNonAuditedLicence.html"
					title="annotation in nuix.annotation">AvailableWithNonAuditedLicence</a></li>
			<li><a href="nuix/locations/AwsLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">AwsLocation</span></a></li>
			<li><a href="nuix/BatchExporter.html"
					title="interface in nuix"><span class="interfaceName">BatchExporter</span></a></li>
			<li><a href="nuix/BatchLoadDetails.html"
					title="interface in nuix"><span class="interfaceName">BatchLoadDetails</span></a></li>
			<li><a href="nuix/BeforeExportCallback.html"
					title="interface in nuix"><span class="interfaceName">BeforeExportCallback</span></a></li>
			<li><a href="nuix/BeforeExportCallbackInfo.html"
					title="interface in nuix"><span class="interfaceName">BeforeExportCallbackInfo</span></a></li>
			<li><a href="nuix/BelongsToCompoundCaseException.html"
					title="class in nuix">BelongsToCompoundCaseException</a></li>
			<li><a href="nuix/Binary.html" title="interface in nuix"><span class="interfaceName">Binary</span></a></li>
			<li><a href="nuix/BinaryData.html"
					title="interface in nuix"><span class="interfaceName">BinaryData</span></a></li>
			<li><a href="nuix/BulkAnnotater.html"
					title="interface in nuix"><span class="interfaceName">BulkAnnotater</span></a></li>
			<li><a href="nuix/BulkSearcher.html"
					title="interface in nuix"><span class="interfaceName">BulkSearcher</span></a></li>
			<li><a href="nuix/BulkSearcherResult.html"
					title="interface in nuix"><span class="interfaceName">BulkSearcherResult</span></a></li>
			<li><a href="nuix/Case.html" title="interface in nuix"><span class="interfaceName">Case</span></a></li>
			<li><a href="nuix/management/CaseAdministrationJob.html"
					title="interface in nuix.management"><span class="interfaceName">CaseAdministrationJob</span></a>
			</li>
			<li><a href="nuix/management/CaseBackupDescriptor.html"
					title="interface in nuix.management"><span class="interfaceName">CaseBackupDescriptor</span></a>
			</li>
			<li><a href="nuix/management/CaseBackupJob.html"
					title="interface in nuix.management"><span class="interfaceName">CaseBackupJob</span></a></li>
			<li><a href="nuix/management/CaseBackupUtility.html"
					title="interface in nuix.management"><span class="interfaceName">CaseBackupUtility</span></a></li>
			<li><a href="nuix/CaseCustomMetadataMap.html"
					title="interface in nuix"><span class="interfaceName">CaseCustomMetadataMap</span></a></li>
			<li><a href="nuix/CaseFactory.html"
					title="interface in nuix"><span class="interfaceName">CaseFactory</span></a></li>
			<li><a href="nuix/management/CaseImportExportJob.html"
					title="interface in nuix.management"><span class="interfaceName">CaseImportExportJob</span></a></li>
			<li><a href="nuix/management/CaseImportExportUtility.html"
					title="interface in nuix.management"><span class="interfaceName">CaseImportExportUtility</span></a>
			</li>
			<li><a href="nuix/CaseNotesStore.html"
					title="interface in nuix"><span class="interfaceName">CaseNotesStore</span></a></li>
			<li><a href="nuix/CaseStatistics.html"
					title="interface in nuix"><span class="interfaceName">CaseStatistics</span></a></li>
			<li><a href="nuix/CaseUtility.html"
					title="interface in nuix"><span class="interfaceName">CaseUtility</span></a></li>
			<li><a href="nuix/engine/CertificateTrustCallback.html"
					title="interface in nuix.engine"><span class="interfaceName">CertificateTrustCallback</span></a>
			</li>
			<li><a href="nuix/engine/CertificateTrustCallbackInfo.html"
					title="interface in nuix.engine"><span class="interfaceName">CertificateTrustCallbackInfo</span></a>
			</li>
			<li><a href="nuix/Cluster.html" title="interface in nuix"><span class="interfaceName">Cluster</span></a>
			</li>
			<li><a href="nuix/ClusterItem.html"
					title="interface in nuix"><span class="interfaceName">ClusterItem</span></a></li>
			<li><a href="nuix/ClusterRun.html"
					title="interface in nuix"><span class="interfaceName">ClusterRun</span></a></li>
			<li><a href="nuix/Communication.html"
					title="interface in nuix"><span class="interfaceName">Communication</span></a></li>
			<li><a href="nuix/CompoundCase.html"
					title="interface in nuix"><span class="interfaceName">CompoundCase</span></a></li>
			<li><a href="nuix/ConfigurationProfile.html"
					title="interface in nuix"><span class="interfaceName">ConfigurationProfile</span></a></li>
			<li><a href="nuix/ConfigurationProfileStore.html"
					title="interface in nuix"><span class="interfaceName">ConfigurationProfileStore</span></a></li>
			<li><a href="nuix/profile/ContinuousPageNumberingStrategy.html"
					title="interface in nuix.profile"><span class="interfaceName">ContinuousPageNumberingStrategy</span></a>
			</li>
			<li><a href="nuix/profile/ContinuousPageNumberingStrategyBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ContinuousPageNumberingStrategyBuilder</span></a>
			</li>
			<li><a href="nuix/engine/CredentialsCallback.html"
					title="interface in nuix.engine"><span class="interfaceName">CredentialsCallback</span></a></li>
			<li><a href="nuix/engine/CredentialsCallbackInfo.html"
					title="interface in nuix.engine"><span class="interfaceName">CredentialsCallbackInfo</span></a></li>
			<li><a href="nuix/credentials/CredentialsStore.html"
					title="interface in nuix.credentials"><span class="interfaceName">CredentialsStore</span></a></li>
			<li><a href="nuix/Custodian.html" title="interface in nuix"><span class="interfaceName">Custodian</span></a>
			</li>
			<li><a href="nuix/CustomMetadataMap.html"
					title="interface in nuix"><span class="interfaceName">CustomMetadataMap</span></a></li>
			<li><a href="nuix/CustomMetadataTemplate.html"
					title="interface in nuix"><span class="interfaceName">CustomMetadataTemplate</span></a></li>
			<li><a href="nuix/CustomMetadataTemplateField.html"
					title="interface in nuix"><span class="interfaceName">CustomMetadataTemplateField</span></a></li>
			<li><a href="nuix/CustomMetadataTemplateStore.html"
					title="interface in nuix"><span class="interfaceName">CustomMetadataTemplateStore</span></a></li>
			<li><a href="nuix/CustomNamedEntity.html"
					title="interface in nuix"><span class="interfaceName">CustomNamedEntity</span></a></li>
			<li><a href="nuix/CustomNamedEntityStore.html"
					title="interface in nuix"><span class="interfaceName">CustomNamedEntityStore</span></a></li>
			<li><a href="nuix/profile/DatabaseParameters.html"
					title="interface in nuix.profile"><span class="interfaceName">DatabaseParameters</span></a></li>
			<li><a href="nuix/profile/DatabaseParametersBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">DatabaseParametersBuilder</span></a>
			</li>
			<li><a href="nuix/DateRange.html" title="interface in nuix"><span class="interfaceName">DateRange</span></a>
			</li>
			<li><a href="nuix/DetectedFace.html"
					title="interface in nuix"><span class="interfaceName">DetectedFace</span></a></li>
			<li><a href="nuix/DigestCollection.html"
					title="interface in nuix"><span class="interfaceName">DigestCollection</span></a></li>
			<li><a href="nuix/DigestListStore.html"
					title="interface in nuix"><span class="interfaceName">DigestListStore</span></a></li>
			<li><a href="nuix/profile/DocumentIdNumberingStrategy.html"
					title="interface in nuix.profile"><span class="interfaceName">DocumentIdNumberingStrategy</span></a>
			</li>
			<li><a href="nuix/profile/DocumentIdNumberingStrategyBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">DocumentIdNumberingStrategyBuilder</span></a>
			</li>
			<li><a href="nuix/DocumentNumber.html"
					title="interface in nuix"><span class="interfaceName">DocumentNumber</span></a></li>
			<li><a href="nuix/DuplicateCaseException.html" title="class in nuix">DuplicateCaseException</a></li>
			<li><a href="nuix/DuplicateCaseItemException.html" title="class in nuix">DuplicateCaseItemException</a></li>
			<li><a href="nuix/graph/Edge.html"
					title="interface in nuix.graph"><span class="interfaceName">Edge</span></a></li>
			<li><a href="nuix/engine/Engine.html"
					title="interface in nuix.engine"><span class="interfaceName">Engine</span></a></li>
			<li><a href="nuix/locations/EnterpriseBoxLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">EnterpriseBoxLocation</span></a>
			</li>
			<li><a href="nuix/locations/EnterpriseVaultLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">EnterpriseVaultLocation</span></a>
			</li>
			<li><a href="nuix/Entity.html" title="interface in nuix"><span class="interfaceName">Entity</span></a></li>
			<li><a href="nuix/EvidenceContainer.html"
					title="interface in nuix"><span class="interfaceName">EvidenceContainer</span></a></li>
			<li><a href="nuix/locations/ExchangeWSLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">ExchangeWSLocation</span></a></li>
			<li><a href="nuix/ExportDetails.html"
					title="interface in nuix"><span class="interfaceName">ExportDetails</span></a></li>
			<li><a href="nuix/ExportItemInfo.html"
					title="interface in nuix"><span class="interfaceName">ExportItemInfo</span></a></li>
			<li><a href="nuix/ExportItemOutputInfo.html"
					title="interface in nuix"><span class="interfaceName">ExportItemOutputInfo</span></a></li>
			<li><a href="nuix/ExportProcessingJob.html"
					title="interface in nuix"><span class="interfaceName">ExportProcessingJob</span></a></li>
			<li><a href="nuix/ExportProcessorCallback.html"
					title="interface in nuix"><span class="interfaceName">ExportProcessorCallback</span></a></li>
			<li><a href="nuix/FailedElementCallback.html"
					title="interface in nuix"><span class="interfaceName">FailedElementCallback</span></a></li>
			<li><a href="nuix/FailedElementInfo.html"
					title="interface in nuix"><span class="interfaceName">FailedElementInfo</span></a></li>
			<li><a href="nuix/profile/FileNamingStrategy.html"
					title="interface in nuix.profile"><span class="interfaceName">FileNamingStrategy</span></a></li>
			<li><a href="nuix/profile/FileNamingStrategyBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">FileNamingStrategyBuilder</span></a>
			</li>
			<li><a href="nuix/profile/FormattedDocumentIdNumberingStrategy.html"
					title="interface in nuix.profile"><span class="interfaceName">FormattedDocumentIdNumberingStrategy</span></a>
			</li>
			<li><a href="nuix/profile/FormattedDocumentIdNumberingStrategyBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">FormattedDocumentIdNumberingStrategyBuilder</span></a>
			</li>
			<li><a href="nuix/Formatter.html" title="interface in nuix"><span class="interfaceName">Formatter</span></a>
			</li>
			<li><a href="nuix/FuzzyHashListStore.html"
					title="interface in nuix"><span class="interfaceName">FuzzyHashListStore</span></a></li>
			<li><a href="nuix/engine/GlobalContainer.html"
					title="interface in nuix.engine"><span class="interfaceName">GlobalContainer</span></a></li>
			<li><a href="nuix/engine/GlobalContainerFactory.html"
					title="class in nuix.engine">GlobalContainerFactory</a></li>
			<li><a href="nuix/graph/Graph.html"
					title="interface in nuix.graph"><span class="interfaceName">Graph</span></a></li>
			<li><a href="nuix/graph/GraphBuilder.html"
					title="interface in nuix.graph"><span class="interfaceName">GraphBuilder</span></a></li>
			<li><a href="nuix/graph/GraphProvider.html"
					title="interface in nuix.graph"><span class="interfaceName">GraphProvider</span></a></li>
			<li><a href="nuix/graph/GraphProviderFactory.html"
					title="interface in nuix.graph"><span class="interfaceName">GraphProviderFactory</span></a></li>
			<li><a href="nuix/Highlight.html" title="interface in nuix"><span class="interfaceName">Highlight</span></a>
			</li>
			<li><a href="nuix/HistoryEvent.html"
					title="interface in nuix"><span class="interfaceName">HistoryEvent</span></a></li>
			<li><a href="nuix/Image.html" title="interface in nuix"><span class="interfaceName">Image</span></a></li>
			<li><a href="nuix/ImageInfo.html" title="interface in nuix"><span class="interfaceName">ImageInfo</span></a>
			</li>
			<li><a href="nuix/ImagePage.html" title="interface in nuix"><span class="interfaceName">ImagePage</span></a>
			</li>
			<li><a href="nuix/ImagingConfigurable.html"
					title="interface in nuix"><span class="interfaceName">ImagingConfigurable</span></a></li>
			<li><a href="nuix/profile/ImagingProfile.html"
					title="interface in nuix.profile"><span class="interfaceName">ImagingProfile</span></a></li>
			<li><a href="nuix/profile/ImagingProfileBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ImagingProfileBuilder</span></a></li>
			<li><a href="nuix/ImagingProfileConfigurable.html"
					title="interface in nuix"><span class="interfaceName">ImagingProfileConfigurable</span></a></li>
			<li><a href="nuix/profile/ImagingProfileRule.html"
					title="interface in nuix.profile"><span class="interfaceName">ImagingProfileRule</span></a></li>
			<li><a href="nuix/profile/ImagingProfileRuleBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ImagingProfileRuleBuilder</span></a>
			</li>
			<li><a href="nuix/profile/ImagingProfileStore.html"
					title="interface in nuix.profile"><span class="interfaceName">ImagingProfileStore</span></a></li>
			<li><a href="nuix/annotation/ImplementedByClientCode.html"
					title="annotation in nuix.annotation">ImplementedByClientCode</a></li>
			<li><a href="nuix/Item.html" title="interface in nuix"><span class="interfaceName">Item</span></a></li>
			<li><a href="nuix/profile/ItemCondition.html"
					title="interface in nuix.profile"><span class="interfaceName">ItemCondition</span></a></li>
			<li><a href="nuix/profile/ItemConditionBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ItemConditionBuilder</span></a></li>
			<li><a href="nuix/ItemCustomMetadataMap.html"
					title="interface in nuix"><span class="interfaceName">ItemCustomMetadataMap</span></a></li>
			<li><a href="nuix/ItemEventCallback.html"
					title="interface in nuix"><span class="interfaceName">ItemEventCallback</span></a></li>
			<li><a href="nuix/ItemEventInfo.html"
					title="interface in nuix"><span class="interfaceName">ItemEventInfo</span></a></li>
			<li><a href="nuix/ItemExistsException.html" title="class in nuix">ItemExistsException</a></li>
			<li><a href="nuix/ItemExpression.html"
					title="interface in nuix"><span class="interfaceName">ItemExpression</span></a></li>
			<li><a href="nuix/ItemInUseException.html" title="class in nuix">ItemInUseException</a></li>
			<li><a href="nuix/ItemKind.html" title="interface in nuix"><span class="interfaceName">ItemKind</span></a>
			</li>
			<li><a href="nuix/ItemMetadata.html"
					title="interface in nuix"><span class="interfaceName">ItemMetadata</span></a></li>
			<li><a href="nuix/ItemModifier.html"
					title="interface in nuix"><span class="interfaceName">ItemModifier</span></a></li>
			<li><a href="nuix/ItemModifierCallback.html"
					title="interface in nuix"><span class="interfaceName">ItemModifierCallback</span></a></li>
			<li><a href="nuix/ItemProcessedCallback.html"
					title="interface in nuix"><span class="interfaceName">ItemProcessedCallback</span></a></li>
			<li><a href="nuix/ItemSet.html" title="interface in nuix"><span class="interfaceName">ItemSet</span></a>
			</li>
			<li><a href="nuix/ItemSetBatch.html"
					title="interface in nuix"><span class="interfaceName">ItemSetBatch</span></a></li>
			<li><a href="nuix/ItemSorter.html"
					title="interface in nuix"><span class="interfaceName">ItemSorter</span></a></li>
			<li><a href="nuix/ItemSyncCallback.html"
					title="interface in nuix"><span class="interfaceName">ItemSyncCallback</span></a></li>
			<li><a href="nuix/ItemTreeNode.html"
					title="interface in nuix"><span class="interfaceName">ItemTreeNode</span></a></li>
			<li><a href="nuix/ItemType.html" title="interface in nuix"><span class="interfaceName">ItemType</span></a>
			</li>
			<li><a href="nuix/ItemTypeUtility.html"
					title="interface in nuix"><span class="interfaceName">ItemTypeUtility</span></a></li>
			<li><a href="nuix/ItemUtility.html"
					title="interface in nuix"><span class="interfaceName">ItemUtility</span></a></li>
			<li><a href="nuix/management/JobProgressCallback.html"
					title="interface in nuix.management"><span class="interfaceName">JobProgressCallback</span></a></li>
			<li><a href="nuix/management/JobProgressInfo.html"
					title="interface in nuix.management"><span class="interfaceName">JobProgressInfo</span></a></li>
			<li><a href="nuix/Licence.html" title="interface in nuix"><span class="interfaceName">Licence</span></a>
			</li>
			<li><a href="nuix/LicenceException.html" title="class in nuix">LicenceException</a></li>
			<li><a href="nuix/LicenceProperties.html"
					title="interface in nuix"><span class="interfaceName">LicenceProperties</span></a></li>
			<li><a href="nuix/engine/LicenceSource.html"
					title="interface in nuix.engine"><span class="interfaceName">LicenceSource</span></a></li>
			<li><a href="nuix/engine/LicenceSourceInformation.html"
					title="interface in nuix.engine"><span class="interfaceName">LicenceSourceInformation</span></a>
			</li>
			<li><a href="nuix/engine/Licensor.html"
					title="interface in nuix.engine"><span class="interfaceName">Licensor</span></a></li>
			<li><a href="nuix/LoadProcessingJob.html"
					title="interface in nuix"><span class="interfaceName">LoadProcessingJob</span></a></li>
			<li><a href="nuix/locations/Location.html"
					title="interface in nuix.locations"><span class="interfaceName">Location</span></a></li>
			<li><a href="nuix/locations/LocationFactory.html"
					title="interface in nuix.locations"><span class="interfaceName">LocationFactory</span></a></li>
			<li><a href="nuix/LocationValidationStatus.html"
					title="interface in nuix"><span class="interfaceName">LocationValidationStatus</span></a></li>
			<li><a href="nuix/LogicalImageExporter.html"
					title="interface in nuix"><span class="interfaceName">LogicalImageExporter</span></a></li>
			<li><a href="nuix/LogicalImageItem.html"
					title="interface in nuix"><span class="interfaceName">LogicalImageItem</span></a></li>
			<li><a href="nuix/locations/MailStoreLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">MailStoreLocation</span></a></li>
			<li><a href="nuix/Markup.html" title="interface in nuix"><span class="interfaceName">Markup</span></a></li>
			<li><a href="nuix/MarkupConfigurable.html"
					title="interface in nuix"><span class="interfaceName">MarkupConfigurable</span></a></li>
			<li><a href="nuix/MarkupSet.html" title="interface in nuix"><span class="interfaceName">MarkupSet</span></a>
			</li>
			<li><a href="nuix/MetadataExportProcessor.html"
					title="interface in nuix"><span class="interfaceName">MetadataExportProcessor</span></a></li>
			<li><a href="nuix/profile/MetadataExportProfile.html"
					title="interface in nuix.profile"><span class="interfaceName">MetadataExportProfile</span></a></li>
			<li><a href="nuix/profile/MetadataExportProfileBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">MetadataExportProfileBuilder</span></a>
			</li>
			<li><a href="nuix/profile/MetadataExportProfileRule.html"
					title="interface in nuix.profile"><span class="interfaceName">MetadataExportProfileRule</span></a>
			</li>
			<li><a href="nuix/profile/MetadataExportProfileRuleBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">MetadataExportProfileRuleBuilder</span></a>
			</li>
			<li><a href="nuix/profile/MetadataExportProfileStore.html"
					title="interface in nuix.profile"><span class="interfaceName">MetadataExportProfileStore</span></a>
			</li>
			<li><a href="nuix/MetadataImportExportDatabaseParameters.html"
					title="interface in nuix"><span class="interfaceName">MetadataImportExportDatabaseParameters</span></a>
			</li>
			<li><a href="nuix/MetadataImportExportDatabaseParametersBuilder.html"
					title="interface in nuix"><span class="interfaceName">MetadataImportExportDatabaseParametersBuilder</span></a>
			</li>
			<li><a href="nuix/MetadataImportProcessor.html"
					title="interface in nuix"><span class="interfaceName">MetadataImportProcessor</span></a></li>
			<li><a href="nuix/MetadataImportProfile.html"
					title="interface in nuix"><span class="interfaceName">MetadataImportProfile</span></a></li>
			<li><a href="nuix/MetadataImportProfileBuilder.html"
					title="interface in nuix"><span class="interfaceName">MetadataImportProfileBuilder</span></a></li>
			<li><a href="nuix/MetadataImportProfileStore.html"
					title="interface in nuix"><span class="interfaceName">MetadataImportProfileStore</span></a></li>
			<li><a href="nuix/MetadataItem.html"
					title="interface in nuix"><span class="interfaceName">MetadataItem</span></a></li>
			<li><a href="nuix/MetadataProfile.html"
					title="interface in nuix"><span class="interfaceName">MetadataProfile</span></a></li>
			<li><a href="nuix/MetadataProfileStore.html"
					title="interface in nuix"><span class="interfaceName">MetadataProfileStore</span></a></li>
			<li><a href="nuix/profile/MicrosoftExcelConversionOptions.html"
					title="interface in nuix.profile"><span class="interfaceName">MicrosoftExcelConversionOptions</span></a>
			</li>
			<li><a href="nuix/profile/MicrosoftExcelConversionOptionsBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">MicrosoftExcelConversionOptionsBuilder</span></a>
			</li>
			<li><a href="nuix/locations/MicrosoftGraphLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">MicrosoftGraphLocation</span></a>
			</li>
			<li><a href="nuix/profile/MicrosoftPowerPointConversionOptions.html"
					title="interface in nuix.profile"><span class="interfaceName">MicrosoftPowerPointConversionOptions</span></a>
			</li>
			<li><a href="nuix/profile/MicrosoftPowerPointConversionOptionsBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">MicrosoftPowerPointConversionOptionsBuilder</span></a>
			</li>
			<li><a href="nuix/profile/MicrosoftWordConversionOptions.html"
					title="interface in nuix.profile"><span class="interfaceName">MicrosoftWordConversionOptions</span></a>
			</li>
			<li><a href="nuix/profile/MicrosoftWordConversionOptionsBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">MicrosoftWordConversionOptionsBuilder</span></a>
			</li>
			<li><a href="nuix/MissingAccessTokenException.html" title="class in nuix">MissingAccessTokenException</a>
			</li>
			<li><a href="nuix/MultipleItemExporter.html"
					title="interface in nuix"><span class="interfaceName">MultipleItemExporter</span></a></li>
			<li><a href="nuix/MutablePrintedImage.html"
					title="interface in nuix"><span class="interfaceName">MutablePrintedImage</span></a></li>
			<li><a href="nuix/MutablePrintedPage.html"
					title="interface in nuix"><span class="interfaceName">MutablePrintedPage</span></a></li>
			<li><a href="nuix/profile/NamedEntity.html"
					title="interface in nuix.profile"><span class="interfaceName">NamedEntity</span></a></li>
			<li><a href="nuix/profile/NamedEntityProfile.html"
					title="interface in nuix.profile"><span class="interfaceName">NamedEntityProfile</span></a></li>
			<li><a href="nuix/profile/NamedEntityProfileStore.html"
					title="interface in nuix.profile"><span class="interfaceName">NamedEntityProfileStore</span></a>
			</li>
			<li><a href="nuix/NativeExportInfo.html"
					title="interface in nuix"><span class="interfaceName">NativeExportInfo</span></a></li>
			<li><a href="nuix/NetworkExporter.html"
					title="interface in nuix"><span class="interfaceName">NetworkExporter</span></a></li>
			<li><a href="nuix/NoItemException.html" title="class in nuix">NoItemException</a></li>
			<li><a href="nuix/profile/NumberingComponentDescriptor.html"
					title="interface in nuix.profile"><span class="interfaceName">NumberingComponentDescriptor</span></a>
			</li>
			<li><a href="nuix/profile/NumberingComponentDescriptorBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">NumberingComponentDescriptorBuilder</span></a>
			</li>
			<li><a href="nuix/NumberingConfigurable.html"
					title="interface in nuix"><span class="interfaceName">NumberingConfigurable</span></a></li>
			<li><a href="nuix/profile/NumberingStrategy.html"
					title="interface in nuix.profile"><span class="interfaceName">NumberingStrategy</span></a></li>
			<li><a href="nuix/OcrProcessor.html"
					title="interface in nuix"><span class="interfaceName">OcrProcessor</span></a></li>
			<li><a href="nuix/profile/OcrProfile.html"
					title="interface in nuix.profile"><span class="interfaceName">OcrProfile</span></a></li>
			<li><a href="nuix/profile/OcrProfileBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">OcrProfileBuilder</span></a></li>
			<li><a href="nuix/OcrProfileConfigurable.html"
					title="interface in nuix"><span class="interfaceName">OcrProfileConfigurable</span></a></li>
			<li><a href="nuix/profile/OcrProfileRule.html"
					title="interface in nuix.profile"><span class="interfaceName">OcrProfileRule</span></a></li>
			<li><a href="nuix/profile/OcrProfileRuleBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">OcrProfileRuleBuilder</span></a></li>
			<li><a href="nuix/profile/OcrProfileStore.html"
					title="interface in nuix.profile"><span class="interfaceName">OcrProfileStore</span></a></li>
			<li><a href="nuix/profile/OcrTemplate.html"
					title="interface in nuix.profile"><span class="interfaceName">OcrTemplate</span></a></li>
			<li><a href="nuix/profile/OcrTemplateBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">OcrTemplateBuilder</span></a></li>
			<li><a href="nuix/OperationFailedException.html" title="class in nuix">OperationFailedException</a></li>
			<li><a href="nuix/locations/OracleServerLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">OracleServerLocation</span></a></li>
			<li><a href="nuix/ParallelProcessingConfigurable.html"
					title="interface in nuix"><span class="interfaceName">ParallelProcessingConfigurable</span></a></li>
			<li><a href="nuix/annotation/ParametersLicenceChecked.html"
					title="annotation in nuix.annotation">ParametersLicenceChecked</a></li>
			<li><a href="nuix/PrintedImage.html"
					title="interface in nuix"><span class="interfaceName">PrintedImage</span></a></li>
			<li><a href="nuix/PrintedImageInfo.html"
					title="interface in nuix"><span class="interfaceName">PrintedImageInfo</span></a></li>
			<li><a href="nuix/PrintedPage.html"
					title="interface in nuix"><span class="interfaceName">PrintedPage</span></a></li>
			<li><a href="nuix/ProcessedItem.html"
					title="interface in nuix"><span class="interfaceName">ProcessedItem</span></a></li>
			<li><a href="nuix/ProcessingJob.html"
					title="interface in nuix"><span class="interfaceName">ProcessingJob</span></a></li>
			<li><a href="nuix/profile/ProcessingProfile.html"
					title="interface in nuix.profile"><span class="interfaceName">ProcessingProfile</span></a></li>
			<li><a href="nuix/profile/ProcessingProfileBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ProcessingProfileBuilder</span></a>
			</li>
			<li><a href="nuix/profile/ProcessingProfileStore.html"
					title="interface in nuix.profile"><span class="interfaceName">ProcessingProfileStore</span></a></li>
			<li><a href="nuix/ProcessingProgressInfo.html"
					title="interface in nuix"><span class="interfaceName">ProcessingProgressInfo</span></a></li>
			<li><a href="nuix/Processor.html" title="interface in nuix"><span class="interfaceName">Processor</span></a>
			</li>
			<li><a href="nuix/ProcessorCleaningUpCallback.html"
					title="interface in nuix"><span class="interfaceName">ProcessorCleaningUpCallback</span></a></li>
			<li><a href="nuix/profile/ProductionProfile.html"
					title="interface in nuix.profile"><span class="interfaceName">ProductionProfile</span></a></li>
			<li><a href="nuix/profile/ProductionProfileBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ProductionProfileBuilder</span></a>
			</li>
			<li><a href="nuix/ProductionProfileConfigurable.html"
					title="interface in nuix"><span class="interfaceName">ProductionProfileConfigurable</span></a></li>
			<li><a href="nuix/profile/ProductionProfileLoadFileSettings.html"
					title="interface in nuix.profile"><span class="interfaceName">ProductionProfileLoadFileSettings</span></a>
			</li>
			<li><a href="nuix/profile/ProductionProfileLoadFileSettingsBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ProductionProfileLoadFileSettingsBuilder</span></a>
			</li>
			<li><a href="nuix/profile/ProductionProfileRule.html"
					title="interface in nuix.profile"><span class="interfaceName">ProductionProfileRule</span></a></li>
			<li><a href="nuix/profile/ProductionProfileRuleBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ProductionProfileRuleBuilder</span></a>
			</li>
			<li><a href="nuix/profile/ProductionProfileStore.html"
					title="interface in nuix.profile"><span class="interfaceName">ProductionProfileStore</span></a></li>
			<li><a href="nuix/ProductionSet.html"
					title="interface in nuix"><span class="interfaceName">ProductionSet</span></a></li>
			<li><a href="nuix/ProductionSetItem.html"
					title="interface in nuix"><span class="interfaceName">ProductionSetItem</span></a></li>
			<li><a href="nuix/profile/Profile.html"
					title="interface in nuix.profile"><span class="interfaceName">Profile</span></a></li>
			<li><a href="nuix/profile/ProfileBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ProfileBuilder</span></a></li>
			<li><a href="nuix/profile/ProfileRule.html"
					title="interface in nuix.profile"><span class="interfaceName">ProfileRule</span></a></li>
			<li><a href="nuix/profile/ProfileRuleBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">ProfileRuleBuilder</span></a></li>
			<li><a href="nuix/profile/ProfileStore.html"
					title="interface in nuix.profile"><span class="interfaceName">ProfileStore</span></a></li>
			<li><a href="nuix/ProgressUpdatedCallback.html"
					title="interface in nuix"><span class="interfaceName">ProgressUpdatedCallback</span></a></li>
			<li><a href="nuix/graph/Property.html"
					title="interface in nuix.graph"><span class="interfaceName">Property</span></a></li>
			<li><a href="nuix/ReaderReadLogic.html"
					title="interface in nuix"><span class="interfaceName">ReaderReadLogic</span></a></li>
			<li><a href="nuix/report/ReportGenerator.html"
					title="interface in nuix.report"><span class="interfaceName">ReportGenerator</span></a></li>
			<li><a href="nuix/ReviewJob.html" title="interface in nuix"><span class="interfaceName">ReviewJob</span></a>
			</li>
			<li><a href="nuix/ReviewJobItem.html"
					title="interface in nuix"><span class="interfaceName">ReviewJobItem</span></a></li>
			<li><a href="nuix/profile/RuleBasedProfile.html"
					title="interface in nuix.profile"><span class="interfaceName">RuleBasedProfile</span></a></li>
			<li><a href="nuix/profile/RuleBasedProfileBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">RuleBasedProfileBuilder</span></a>
			</li>
			<li><a href="nuix/ScannedItem.html"
					title="interface in nuix"><span class="interfaceName">ScannedItem</span></a></li>
			<li><a href="nuix/SearchableItem.html"
					title="interface in nuix"><span class="interfaceName">SearchableItem</span></a></li>
			<li><a href="nuix/SearchCallback.html"
					title="interface in nuix"><span class="interfaceName">SearchCallback</span></a></li>
			<li><a href="nuix/SearchMacro.html"
					title="interface in nuix"><span class="interfaceName">SearchMacro</span></a></li>
			<li><a href="nuix/SearchMacroStore.html"
					title="interface in nuix"><span class="interfaceName">SearchMacroStore</span></a></li>
			<li><a href="nuix/Server.html" title="interface in nuix"><span class="interfaceName">Server</span></a></li>
			<li><a href="nuix/ServerGroup.html"
					title="interface in nuix"><span class="interfaceName">ServerGroup</span></a></li>
			<li><a href="nuix/ServerGroups.html"
					title="interface in nuix"><span class="interfaceName">ServerGroups</span></a></li>
			<li><a href="nuix/ServerRegistry.html"
					title="interface in nuix"><span class="interfaceName">ServerRegistry</span></a></li>
			<li><a href="nuix/ServerUser.html"
					title="interface in nuix"><span class="interfaceName">ServerUser</span></a></li>
			<li><a href="nuix/ServerUsers.html"
					title="interface in nuix"><span class="interfaceName">ServerUsers</span></a></li>
			<li><a href="nuix/engine/SharedLicence.html"
					title="interface in nuix.engine"><span class="interfaceName">SharedLicence</span></a></li>
			<li><a href="nuix/locations/SharePointLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">SharePointLocation</span></a></li>
			<li><a href="nuix/ShingleListStore.html"
					title="interface in nuix"><span class="interfaceName">ShingleListStore</span></a></li>
			<li><a href="nuix/SimpleCase.html"
					title="interface in nuix"><span class="interfaceName">SimpleCase</span></a></li>
			<li><a href="nuix/SingleItemExporter.html"
					title="interface in nuix"><span class="interfaceName">SingleItemExporter</span></a></li>
			<li><a href="nuix/SingleItemImporter.html"
					title="interface in nuix"><span class="interfaceName">SingleItemImporter</span></a></li>
			<li><a href="nuix/profile/SlipSheetTemplate.html"
					title="interface in nuix.profile"><span class="interfaceName">SlipSheetTemplate</span></a></li>
			<li><a href="nuix/profile/SlipSheetTemplateBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">SlipSheetTemplateBuilder</span></a>
			</li>
			<li><a href="nuix/SourceItem.html"
					title="interface in nuix"><span class="interfaceName">SourceItem</span></a></li>
			<li><a href="nuix/SourceItemFactory.html"
					title="interface in nuix"><span class="interfaceName">SourceItemFactory</span></a></li>
			<li><a href="nuix/SourceItemNotFoundException.html" title="class in nuix">SourceItemNotFoundException</a>
			</li>
			<li><a href="nuix/locations/SqlServerLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">SqlServerLocation</span></a></li>
			<li><a href="nuix/locations/SshLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">SshLocation</span></a></li>
			<li><a href="nuix/profile/Stamper.html"
					title="interface in nuix.profile"><span class="interfaceName">Stamper</span></a></li>
			<li><a href="nuix/profile/StamperBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">StamperBuilder</span></a></li>
			<li><a href="nuix/profile/StamperConfiguration.html"
					title="interface in nuix.profile"><span class="interfaceName">StamperConfiguration</span></a></li>
			<li><a href="nuix/profile/StamperConfigurationsBuilder.html"
					title="interface in nuix.profile"><span class="interfaceName">StamperConfigurationsBuilder</span></a>
			</li>
			<li><a href="nuix/StampingConfigurable.html"
					title="interface in nuix"><span class="interfaceName">StampingConfigurable</span></a></li>
			<li><a href="nuix/Text.html" title="interface in nuix"><span class="interfaceName">Text</span></a></li>
			<li><a href="nuix/ThirdPartyDependency.html"
					title="interface in nuix"><span class="interfaceName">ThirdPartyDependency</span></a></li>
			<li><a href="nuix/ThirdPartyDependencyStatus.html"
					title="interface in nuix"><span class="interfaceName">ThirdPartyDependencyStatus</span></a></li>
			<li><a href="nuix/TokenInfo.html" title="interface in nuix"><span class="interfaceName">TokenInfo</span></a>
			</li>
			<li><a href="nuix/Topic.html" title="interface in nuix"><span class="interfaceName">Topic</span></a></li>
			<li><a href="nuix/graph/Traversal.html"
					title="interface in nuix.graph"><span class="interfaceName">Traversal</span></a></li>
			<li><a href="nuix/TreePosition.html"
					title="interface in nuix"><span class="interfaceName">TreePosition</span></a></li>
			<li><a href="nuix/locations/TwitterHistoricalLocation.html"
					title="interface in nuix.locations"><span class="interfaceName">TwitterHistoricalLocation</span></a>
			</li>
			<li><a href="nuix/User.html" title="interface in nuix"><span class="interfaceName">User</span></a></li>
			<li><a href="nuix/UserDataStore.html"
					title="interface in nuix"><span class="interfaceName">UserDataStore</span></a></li>
			<li><a href="nuix/Utilities.html" title="interface in nuix"><span class="interfaceName">Utilities</span></a>
			</li>
			<li><a href="nuix/graph/Vertex.html"
					title="interface in nuix.graph"><span class="interfaceName">Vertex</span></a></li>
			<li><a href="nuix/Window.html" title="interface in nuix"><span class="interfaceName">Window</span></a></li>
			<li><a href="nuix/WordList.html" title="interface in nuix"><span class="interfaceName">WordList</span></a>
			</li>
			<li><a href="nuix/WordListStore.html"
					title="interface in nuix"><span class="interfaceName">WordListStore</span></a></li>
			<li><a href="nuix/WorkerAgent.html"
					title="interface in nuix"><span class="interfaceName">WorkerAgent</span></a></li>
			<li><a href="nuix/WorkerAgentStatus.html"
					title="interface in nuix"><span class="interfaceName">WorkerAgentStatus</span></a></li>
			<li><a href="nuix/WorkerBroker.html"
					title="interface in nuix"><span class="interfaceName">WorkerBroker</span></a></li>
			<li><a href="nuix/WorkerItem.html"
					title="interface in nuix"><span class="interfaceName">WorkerItem</span></a></li>
		</ul>
	</main>
</body>

</html>

Getting Started: Known Issues

Tue, 20 Apr 2021 00:00:00 +0000

Creating Item Sets

Creating an item set from a user-generated script where the query parameter is not defined automatically includes all items in the generated item set by default.

Workaround: To prevent all items from being included, ensure that the query parameter is defined with either a valid query or a null value to prevent all items from being included.

NTLM Authentication

The use of NTLM authentication is no longer supported by Nuix. If NTLM authentication is used, an authentication token is always acquired when calling the PUT /v1/authenticatedUsers/login endpoint.

Workaround: Nuix recommends using basic authentication with Nuix Management Server and Nuix RESTful Service.

Licence Description Parameter

The licenceDescription parameter used in conjunction with the /v1/authenticatedUsers/login endpoint has been deprecated because the description associated with this parameter is subject to change. The LicenseDescription parameter will be removed in a future release.

Workaround: The licenceShortName parameter should be used in its place along with the license’s short name.

Cookies2.dat

When a Nuix-generated cookies2.dat file is located in any userDataDirs folder set in nuix-restful-service.properties, an authentication token is always acquired when calling the PUT /v1/authenticatedUsers/login endpoint.

Workaround: Nuix recommends periodically checking to ensure that this folder does not contain a cookies2.dat file.

/v1/cases/{caseId}/keyStore Endpoint

The POST /v1/cases/{caseId}/keyStore endpoint is still under development and not intended for customer use in this release.

Case Title Migration Issues

Cases that contain a comma (,) or dollar sign ($) in the title will fail the migration process to version 7.0.

Workaround: Cases that have titles that include these symbols should be renamed prior to migration.