Skip to content

Asynchronous workflows

A workflow published in asynchronous mode lends itself to analyzing a batch of documents in the background without blocking the client application which can do other things while waiting for the analysis results to be ready.
Typically the client application creates a new analysis task using the API—response time is fast—and is free to do anything else while the workflow performs the analysis and caches the results.
The client application then periodically checks the status of the task and, when the task is completed, requests the results.

An asynchronously published workflow corresponds to two macro resources: the single analysis task and all the submitted tasks not yet canceled. To operate on these macro-resources the API exposes these resources:

  • Single analysis task:

    1. Creation
    2. Status
    3. Results
    4. Cancellation

  • All tasks submitted and not yet deleted:

    1. Status
    2. Cancellation

Commonalities

All requests for resources of a workflow published in asynchronous mode must have these characteristics:

  1. The endpoint has to start with:

    https://host/api/v1/runtime/workflow/workflowId/task

    where you have to replace:

    • host with the host name or IP address of the NL Flow runtime.
    • workflowId with the workflow ID.

  2. In every request you must set the following headers:

    Content-type: application/json; charset=utf-8
X-API-KEY: APIKEY

    where you have to replace APIKEY with the API key associated with your workflow.

Single analysis task

Creation

Request this resource to submit a new analysis task to the workflow.

Endpoint

The endpoint coincides with the root common to all requests.

HTTP verb

The verb to use is POST.

Request headers

In addition to the common headers, it is optional to add the X-Correlation-Id header for troubleshooting purposes. Its value can be any string and must be unique for each call. You can mention this value when asking for support if you get unexpected errors. Support personnel can then track your calls based on this value when examining the NL Flow API logs.

Request body

The body of document analysis requests must be a UTF-8 encoded JSON object.

As with the synchronously published workflow analysis resource, in the JSON object there must be all the keys that the workflow needs to use. In the NL Flow application documentation you can find the description of the keys expected by model blocks and by processor blocks .

Each model or processor block, no matter how deep in the workflow, has access to the input JSON object keys by defining the input format, which also allows you to handle key name mismatch cases.

Response

The response body is a JSON object like this:

{
     "taskId": "a301ad0d-40d6-478a-a7a4-fd4a60aab8fd"
}

where taskId is the ID of the newly created task.

The HTTP status on success is 202 (Accepted).

Status

This resource represents the status of a previously submitted task.

Endpoint

To the common stem it is necessary to add:

/taskId/status

where taskId is the ID of the task obtained in response to the task creation request.

HTTP verb

The verb to use is GET.

Request headers

There are no headers additional to the common one.

Request body

No body is needed for the request.

Response

The response body is a JSON object like this:

{
     "status": "COMPLETED"
}

where status is the status of the task which can be:

  • SUBMITTED: the task was submitted and has been queued.
  • RUNNING: the task was popped from the queue and it's being executed.
  • COMPLETED: the task was completed.
  • ERROR: there was an error during task execution.
  • DROPPED: the task was dropped because the workflow was unpublished.

Results

Request this resource to obtain analysis results when a task is completed or error details when a task is in error.
The results can be requested multiple times as long as the task is not canceled.

Endpoint

To the common stem it is necessary to add:

/taskId/response

where taskId is the task ID obtained in response to the task creation request.

HTTP verb

The verb to use is GET.

Request headers

There are no headers additional to the common one.

Request body

No body is needed for the request.

Response

If the status of the task is COMPLETED, the response body is a JSON corresponding to the workflow output.

If the status of the task is ERROR, the response body is a JSON containing the detail of the error, for example:

{
    "message": "Cannot execute workflow 5941302d-c109-4b20-aa1a-3370e1d91ce6 for taskId 6c3bb18c-acdc-4407-b4f4-5a0f4701bd38 because workflow does not become ready",
    "details": {
        "stream": {
            "id": "benthos",
            "desired": 1,
            "actual": 1,
            "status": "GREEN"
        },
        "services": [
            {
                "id": "executor-5941302d",
                "desired": 1,
                "actual": 0,
                "status": "RED",
                "rolloutStatus": "InProgress",
                "rolloutStatusReason": "AwaitingNewReplicasToBeAvailable",
                "replicasDetail": [
                    {
                        "name": "depl-executor-5941302d-5e1d319e-ee7c-4070-a00e-0ffa5e854c7ld4ch",
                        "ready": false,
                        "available": false,
                        "startedAt": "2023-07-17T12:30:20Z",
                        "age": "1h33m34.372636619s",
                        "status": "Running",
                        "atLatestSpec": true
                    }
                ]
            },
            {
                "id": "knowledge-m-63fd8140",
                "desired": 1,
                "actual": 1,
                "status": "GREEN",
                "rolloutStatus": "Complete",
                "replicasDetail": [
                    {
                        "name": "depl-knowledge-m-63fd8140-da9b70cc-42f3-486e-9b34-30f85a1e9zhxd",
                        "ready": true,
                        "available": true,
                        "startedAt": "2023-07-17T12:30:19Z",
                        "age": "1h33m36.372707126s",
                        "status": "Running",
                        "atLatestSpec": true
                    }
                ]
            }
        ]
    }
}

In all cases of HTTP status 200, the response contains the additional header Workflow-Http-Status-Code whose value is the HTTP status returned by the analysis task.
For example, if the results of a task in ERROR status are requested to know the details of the problem, the resource is returned with status 200 OK, but the Workflow-Http-Status-Code header will probably have a different value, such as 500, to indicate the status that the asynchronous request handler got in response from the workflow.

Cancellation

Request this resource to cancel a task. Canceling tasks if a good practice but is not mandatory since tasks are automatically canceled after 24 hours.

Endpoint

To the common stem it is necessary to add:

/taskId

where taskId is the task ID obtained in response to the task creation request.

HTTP verb

The verb to use is DELETE.

Request headers

There are no headers additional to the common one.

Request body

No body is needed for the request.

Response

If successful, the response has no body and the HTTP status is 204 (No content).

All tasks not yet deleted

Status

This resource contains the lists of all the tasks or or only of those in certain statuses. For each task it's indicated its status.

Endpoint

To get the list of all the tasks, add:

/task/status

to the common stem.
To get the list of only the tasks in certain statuses, add:

/task?taskStatuses=status1[,status2[,...]]

where status1, status2, etc. are the statuses of the tasks to cancel (see above).

HTTP verb

The verb to use is GET.

Request headers

There are no headers additional to the common one.

Request body

No body is needed for the request.

Response

The response body is a JSON object like this:

{
    "taskStatusMap": {
        "e6a631df-020c-4ff0-bc2b-f48a8e6a5036": "COMPLETED",
        "a860f051-bd6e-40e7-baa0-115a3963da7c": "COMPLETED",
        "3c7840de-d0e3-446e-8e4d-d8771a8b4ade": "RUNNING",
        "3a3da5c6-4754-4c10-8f58-922322ef0aba": "SUBMITTED"
    }
}

where the taskStatusMap object has a property for each task. The property name is the task ID, the property value is the task status which can be one those listed above.

Cancellation

Request this resource to cancel all tasks or only those in certain statuses.

Endpoint

To cancel all the tasks, add:

/task

to the common stem.
To cancel only tasks in certain statuses, add:

/task?taskStatuses=status1[,status2[,...]]

where status1, status2, etc. are the statuses of the tasks to cancel (see above).

HTTP verb

The verb to use is DELETE.

Request headers

There are no headers additional to the common one.

Request body

No body is needed for the request.

Response

If successful, the response has no body and the HTTP status is 204 (No content).