Part 6: Asynchronous Functions

Learn how to poll the status for asynchronous functions.

  3 minute read  

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 function 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"
}

Poll for function status

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

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"
}