Promote to Nuix Discover

Learn how to promote items from a case to Nuix Discover.

  5 minute read  

Promote to Nuix Discover

After you import items into a case, you can optionally promote those items to an existing Nuix Discover SaaS case using the POST /cases/{caseId}/promoteToDiscover/{discoverCaseId} endpoint.

Before you begin

Before you begin promoting items to Nuix Discover, you must:

  • Ingest items into a Nuix case
  • Copy your API access token from Nuix Discover
    • For more information on accessing the Discover Connect API Explorer and retrieving your API access token, see the Manage Security of the Connect Graph API documentation.
  • Copy your Discover case ID from Nuix Discover
  • Add your Nuix Discover account in Nuix Workstation

Example cURL request

curl --location --request POST '/cases/34625454770746279e0e21459d99d992/promoteToDiscover/1036?query=*&deduplicated=false&discoverDeduplication=false&apiAccessToken=3d7c813a-9be0-4284-9e28-5c111a781ee' \
--header 'Nuix-auth-token: <auth-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

{
  "functionKey": "e0319b96-5c84-40f4-adce-2f3d6aa0465a",
  "location": "http://localhost:8080/svc/v1/asyncFunctions/e0319b96-5c84-40f4-adce-2f3d6aa0465a"
}

Parameters

The example above used the following parameters in the request body.

Parameter Type Description
query String Identifies which items will be promoted. When no query is provided, all items are promoted.
dedeuplicated Boolean Deduplicates items before promotion.
discoverDeduplication Boolean After promotion, deduplicates items in Nuix Discover.
apiAccessToken String Required. A valid Discover API Access token that authorizes the request.

Check the request’s status

Using the function key from the cURL response above, check the status of your request.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/e0319b96-5c84-40f4-adce-2f3d6aa0465a' \
--header 'nuix-auth-token: <your-auth-token>'

{
  "done": true,
  "cancelled": false,
  "result": {
    "totalItems": 1,
    "processedItems": 1,
    "processedBytes": 25893,
    "failedItems": 0
  },
  "token": "3d7c813a-9be0-4284-9e28-5c111a781ee6",
  "functionKey": "e0319b96-5c84-40f4-adce-2f3d6aa0465a",
  "progress": 1,
  "total": 1,
  "percentComplete": 100,
  "updatedOn": 1606337690126,
  "requestTime": 1606337664447,
  "startTime": 1606337671715,
  "finishTime": 1606337692602,
  "caseId": "34625454770746279e0e21459d99d992",
  "caseName": "MyDiscoverCase",
  "action": "PromoteToDiscoverFunction",
  "options": {
    "deduplicated": false,
    "discoverCaseId": 1036,
    "discoverDeduplication": false,
    "query": "*",
    "caseId": "34625454770746279e0e21459d99d992"
  },
  "participatingInCaseFunctionQueue": true,
  "processedBy": "rest-server-2"
}

Additional example requests

discoverApiToken='YOURTOKEN'
discoverCaseId='1036'
deduplication=false
query='guid:fc13d1d4-6a09-47a4-9e58-87dff113c93b'
items=current_case.searchUnsorted(query)
​
​
var options = {
	"token": discoverApiToken,
	"caseId": discoverCaseId,
	"deduplication": deduplication
}
​
discoverExporter = utilities.createBatchExporter("/tmp/export1")
discoverExporter.setPromoteToDiscoverOptions(options)
​
discoverExporter.whenItemEventOccurs(function(callback) {
	try {
		print("Processing item: " + callback.getItem().getGuid() + ", Stage: " + callback.getStage())
	} catch(err) {
		print(err)
	}
})
​
discoverExporter.beforeExport(function(info) {
	try {
		print("Exporting " + info.getItems().length + " items.")
		return true
	} catch(err) {
		print(err)
		return false
	}
})
​
discoverExporter.afterExport(function(info) {
	try {
		print("Failed items: " + info.getFailedItems().length)
	} catch(err) {
		print(err)
	}
})
​
discoverExporter.exportItems(items)
​

discoverApiToken='YOURTOKEN'
discoverCaseId='1036'
deduplication=False
query='guid:fc13d1d4-6a09-47a4-9e58-87dff113c93b'
items=current_case.searchUnsorted(query)
​
​
options = {
	"token": discoverApiToken,
	"caseId":  discoverCaseId,
	"deduplication": deduplication
}
​
discoverExporter = utilities.createBatchExporter("/tmp/export1")
discoverExporter.setPromoteToDiscoverOptions(options)
​
​
def when_item_event_occurs(callback):
	try:
		print("Processing item: {}, Stage: {}".format(callback.getItem().getGuid(), callback.getStage()))
	except Exception, e:
		print(e)
​
def before_export(info):
	try:
		print("Exporting {} items.".format(info.getItems().size()))
		return True
	except Exception, e:
		print(e)
		return False
		
def after_export(info):
	try:
		print("Failed items: {}".format(info.getFailedItems().size()))
	except Exception, e:
		print(e)
​
discoverExporter.whenItemEventOccurs(when_item_event_occurs) 
discoverExporter.beforeExport(before_export)
discoverExporter.afterExport(after_export) 
​
discoverExporter.exportItems(items)



discoverApiToken='YOURTOKEN'
discoverCaseId='1036'
deduplication=false
query='guid:fc13d1d4-6a09-47a4-9e58-87dff113c93b'
items=$current_case.searchUnsorted(query)
​
​
options = {
	"token" => discoverApiToken,
	"caseId" => discoverCaseId,
	"deduplication" => deduplication
}
​
discoverExporter = $utilities.createBatchExporter("/tmp/export1")
discoverExporter.setPromoteToDiscoverOptions(options)
​
​
discoverExporter.when_item_event_occurs do | callback |
	begin
		puts "Processing item: #{callback.getItem().getGuid()}, Stage: #{callback.getStage()}"
	rescue => exception
		puts exception
	end
end
​
discoverExporter.before_export do | info |
	begin
		puts "Exporting #{info.getItems().size()} items."
		true
	rescue => exception
		puts exception
		false
	end
	
end
​
discoverExporter.after_export do | info |
	begin
		puts "Failed items: #{info.getFailedItems().size()}"
	rescue => exception
		puts exception
	end
end
​
discoverExporter.exportItems(items)


package com.nuix.us.ws;

import java.io.File;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;

import nuix.BatchExporter;
import nuix.Case;
import nuix.Item;
import nuix.Utilities;
import nuix.engine.AvailableLicence;
import nuix.engine.Engine;
import nuix.engine.GlobalContainer;
import nuix.engine.GlobalContainerFactory;
import nuix.engine.LicenceSource;
import nuix.engine.Licensor;

public class NuixDiscover {
    public void promoteItems() throws IOException {

        //Define our engine configuration settings
        //This example assumes an engine in /engines/9.10.0.58
        final File userDataDirs = new File("/engines/9.10.0.58/user-data");
        final String username = "username";
        final String password = "password";
        final String nuixRegistryServers = "127.0.0.1";
        final File casePath = new File("/cases/mycase");
        final String discoverApiToken = "YOURTOKEN";
        final String discoverCaseId = "1036";
        final boolean discoverDeduplication = false;
        final String query = "guid:fc13d1d4-6a09-47a4-9e58-87dff113c93b";

        System.setProperty("nuix.registry.servers", nuixRegistryServers);

        GlobalContainer container = GlobalContainerFactory.newContainer();
        Map<Object, Object> engineConfiguration = new HashMap<>();
        engineConfiguration.put("user", username);
        engineConfiguration.put("userDataDirs", userDataDirs);

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

        // 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(info -> {
            System.out.println("Trusting certificate blindly!");
            info.setTrusted(true);
        });

        // We provide credentials for authenticating with the license server
        // through this callback.
        engine.whenAskedForCredentials(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<>();
        licenseOptions.put("sources", "server");

        // Ask licensor to see what available licenses it can find
        LicenceSource licenceSource = engine.getLicensor().findLicenceSourcesStream(licenseOptions)
                .findFirst()
                .orElseThrow(() -> new RuntimeException("Could not find licence server."));

        // 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 licence : licenceSource.findAvailableLicences()) {
           licence.acquire();
           break;
        }

        Utilities utilities = engine.getUtilities();
        File exportPath = new File("/exports");
        BatchExporter discoverExporter = utilities.createBatchExporter(exportPath);

        Map<String, String> options = Map.of(
                "token", discoverApiToken,
                "caseId", discoverCaseId,
                "deduplication", String.valueOf(discoverDeduplication));
        discoverExporter.setPromoteToDiscoverOptions(options);

        discoverExporter.whenItemEventOccurs(itemEventInfo -> {
            System.out.println("Processing item:" + itemEventInfo.getItem().getGuid() + ", Stage:" + itemEventInfo.getStage());
        });

        discoverExporter.beforeExport(info -> {
            System.out.println("Exporting " + info.getItems().size() + " items.");
            return true;
        });

        discoverExporter.afterExport(info -> {
            System.out.println("Failed items: " + info.getFailedItems().size());
        });

        try (Case caze = utilities.getCaseFactory().open(casePath)) {
            Set<Item> items = caze.searchUnsorted(query);
            discoverExporter.exportItems(items);
        }

        container.close();
    }
}