Asynchronous workflows

Usage modes

An asynchronous workflow can be used programmatically in these modes:

Classic
All-in-one

Classic mode

In classic mode the user:

Makes a call to create a new task. This call must contain, in the request body, the input for the workflow. Response time is typically very low. The response contains the ID of the new task.
After this call, the task gets queued then executed as soon as workflow's computing resources become available.
Makes one or more calls to get the current status of the task until the task is finished (COMPLETED or ERROR status).
When the task is finished, makes a call to retrieve its outcome. The response body is the output of the workflow.

Note

Retrieving the outcome of the task is not when is enough to know that the task finished successfully.
An example is a workflow that saves results in an external storage or a workflow that indexes documents: status COMPLETED means success and the output of the workflow is of no interest.

The traces of a task, for example its outcome, are kept for 24 hours after creation, then they are deleted automatically. The good practice however is to delete task traces after the task is finished and, if needed, its outcome has been retrieved. This frees up memory and keeps the workflow efficient.

All-in-one mode

In all-in-one mode the user calls the workflow as it was synchronous. In response to the call, a server-side agent uses the workflow in classic mode with a high frequency polling of the task status and responds to the user's call with the workflow outcome when ready. After responding to the user, the agent deletes the task.
The response time corresponds to the sum of four phases: task submission, status polling until the task finishes, outcome retrieval and task deletion.

Additional functionalities

An asynchronous workflow also provides API endpoints to:

Get the status of all the tasks.
Get the status of multiple tasks.
Get a list of tasks in given statuses.
Delete the tasks in given statuses.
Delete all the tasks.
Retrieve the input JSON, that is the JSON passed as the body of the task creation request.

All the possible API endpoints for an asynchronous workflow are described below.

Create a task

This call creates a new task for an asynchronous workflow.

Request:
- Verb: POST
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task[?verboseErrorOutput=true]
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - verboseErrorOutput=true is an optional query string parameter that makes the workflow produce a verbose output in case of errors.
- HTTP headers:
  
  Mandatory:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
  - Content-type: application/json; charset=utf-8
  Optional:
  - X-Correlation-Id: Correlation ID
    
    For troubleshooting purposes. Correlation ID can be any unique string. It can be mentioned when asking for support in case of unexpected errors because support personnel can then track API calls based on this value when examining system logs.
- Body: the substance of what needs to be processed by the workflow for this task, that is an UTF-8 encoded JSON object compatible with the format of the workflow's input.
Response:
- HTTP status code: the HTTP status code upon success is 202 (Accepted).
- Body: the response body is a JSON object like this:
```
{
    "taskId": "taskId"
}
```
  where taskId is the ID of the newly created task. This value must be used in all the subsequent requests about the task.

Get the status of a task

This call gets the status of a given task of an asynchronous workflow.

Request:
- Verb: GET
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task/taskId/status
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - taskId is the ID of the task obtained when creating the task
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 200 (OK).
- Body: the response body is a JSON object like this:
```
{
    "status": "taskStatus"
}
```
  where taskStatus is the status of the task.

Get the list and status of all tasks

This call gets the list and the status for all the tasks of an asynchronous workflow.

Request:
- Verb: GET
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task/status
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 200 (OK).
- Body: the response body is a JSON object like this:
```
{
    "taskStatusMap": {
        "task1Id": "task1Status",
        "task2Id": "task2Status"
    }
}
```
  where the taskStatusMap object has a property for each task of the workflow; task1Status is the status of task with ID task1Id and task2Status is the status of task with ID task2Id.

Get the status of multiple tasks

This call gets the status of multiple tasks of an asynchronous workflow.

Request:
- Verb: GET
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task/status?taskIds=task1Id[,task2Id[,...]]
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - task1Id, task2Id, etc. are the IDs of the tasks
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 200 (OK).
- Body: the response body is a JSON object like this:
```
{
    "taskStatusMap": {
        "task1Id": "task1Status",
        "task2Id": "task2Status"
    }
}
```
  where task1Status is the status of task with ID task1Id and task2Status is the status of task with ID task2Id.

List the tasks in given statuses

This call gets the list of the tasks of an asynchronous workflow that are in given statuses.

Request:
- Verb: GET
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task/status?taskStatuses=status1[,status2[,...]]
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - status1, status2, etc. are possible task statuses
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 200 (OK).
- Body: the response body is a JSON object like this:
```
{
    "taskStatusMap": {
        "task1Id": "task1Status",
        "task2Id": "task2Status"
    }
}
```
  where the taskStatusMap object has a property for each task in one of the specified statuses; task1Status is the status of task with ID task1Id and task2Status is the status of task with ID task2Id.

Get the outcome of a task

This call gets the outcome of a finished task of an asynchronous workflow, that is the output of the workflow in case of success or the description of the problem in case of error.

Request:
- Verb: GET
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task/taskId/response
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - taskId is the ID of the task obtained when creating the task
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 200 (OK).
- Body: if the status of the task is COMPLETED, the response body is a JSON corresponding to the workflow output for that task.
  
  If the status of the task is ERROR, the response body is a JSON containing the description of the error.

Delete a task

This call deletes any trace of given task of an asynchronous workflow.

Request:
- Verb: DELETE
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task/taskId
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - taskId is the ID of the task obtained when creating the task
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 204 (No content).
- Body: none

Delete all the tasks in given statuses

This call deletes any trace of all the tasks of an asynchronous workflow that are in given statuses.

Request:
- Verb: DELETE
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task?taskStatuses=status1[,status2[,...]]
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - status1, status2, etc. are possible task statuses
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 204 (No content).
- Body: none

Delete all the tasks

This call deletes any trace of all the tasks of an asynchronous workflow.

Request:
- Verb: DELETE
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 204 (No content).
- Body: none

Get the workflow input for a given task

This resource returns the workflow input of a given task, that is the body of the task creation request.

Request:
- Verb: GET
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/task/taskId/request
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - taskId is the ID of the task obtained when creating the task
- HTTP headers:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
- Body: not required
Response:
- HTTP status code: the HTTP status code upon success is 200 (OK).
- Body: the response body is the JSON that was used as the request body when creating the task.

All-in-one

This call uses an asynchronous workflow in the all-in-one mode.

Request:
- Verb: POST
- Endpoint:
  
  https://host/api/v1/runtime/workflow/workflowId/sync[?verboseErrorOutput=true]
  
  where:
  - host is host name or IP address of the NL Flow runtime
  - workflowId is the workflow ID
  - verboseErrorOutput=true is an optional query string parameter that makes the workflow produce a verbose output in case of errors.
- HTTP headers:
  
  Mandatory:
  - X-API-KEY: API key
    
    where API key is one of the API keys associated with the workflow.
  - Content-type: application/json; charset=utf-8
  Optional:
  - X-Correlation-Id: Correlation ID
    
    For troubleshooting purposes. Correlation ID can be any unique string. It can be mentioned when asking for support in case of unexpected errors because support personnel can then track API calls based on this value when examining system logs.
- Body: the substance of what needs to be processed by the workflow for this task, that is an UTF-8 encoded JSON object compatible with the format of the workflow's input.
Response:
- HTTP status code: the HTTP status code upon success is 200 (OK).
- Body: a JSON corresponding to the workflow output.

Possible statuses of a task

The status of a task can be:

SUBMITTED: the task was submitted and is going to be queued.
RUNNING: the task is either waiting in the queue or being executed.
COMPLETED: the task finished successfully, its outcome is available and can be retrieved.
ERROR: the task finished with an error. The outcome, which typically contains details about the error, can be retrieved.
DROPPED: the task was dropped because:
- The sum of the queue time and the execution time exceeded the workflow timeout.
Or:
- The workflow was unpublished.

How to know a workflow's ID

To get the ID of a workflow to use in endpoints access the NL Flow application and: