Platform NL Flow API

Introduction

The NL Flow API allows you to use NL Flow workflows programmatically. It is a RESTful API whose resources correspond to two functionalities—document analysis and workflow status—of published workflows.

Requirements

A workflow can be accessed through the REST API if it has been published and associated to a API key.

Document analysis

Request this resource to analyze a document with the workflow.

Endpoint

The API endpoint for document analysis is:

https://host/api/v1/runtime/workflow/workflowId/action/analyze

where you have to replace:

host with the host name or IP address of the Platform workflow runtime.
workflowId with the workflow ID.

To get the actual endpoint for a workflow, access the NL Flow application and:

Open the workflow in the Workflows view of the dashboard.
Display identifying information.
Copy the value of the Document analysis endpoint.

To get a verbose output in case of errors add this query string parameter to the URL:

verboseErrorOutput=true

HTTP verb

The document analysis resource must be requested with the POST verb.

Request headers

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.

Warning

You have to take note of the API key when you generate it, because it's not possible to retrieve it afterwards, even if there's always the possibility to re-generate it.

The X-Correlation-Id header is optional and used 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 an UTF-8 encoded JSON object.

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 corresponding to the workflow output.

Workflow status

Request this resource to know about the status of a workflow.

Endpoint

The API endpoint for workflow status is:

https://host/api/v1/runtime/workflow/workflowId/action/status

where you have to replace:

host with the host name or IP address of the Platform workflow runtime.
workflowId with the workflow ID.

To get the actual endpoint for a workflow, access the NL Flow application and:

Open the workflow in the Workflows view of the dashboard.
Display identifying information.
Copy the value of the Workflow status endpoint.

HTTP verb

The workflow status resource must be requested with the GET verb.

Request headers

In every request you must set the following header:

X-API-KEY: APIKEY

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

Response

The response body is a JSON object like this:

{
    "desiredStatus": "PUBLISHED",
    "actualStatus": "ORANGE",
    "details": {
        "stream": {
            "id": "benthos",
            "desired": 1,
            "actual": 1,
            "status": "GREEN"
        },
        "services": [
            {
                "id": "cogito-1-0--9ccf18ea",
                "desired": 1,
                "actual": 0,
                "status": "RED"
            }
        ]
    }
}

Its properties are:

desiredStatus: target workflow status of the workflow, e.g. PUBLISHED
actualStatus: current workflow status with respect to the color-code used in the Workflow Web application, namely:
- GREEN: workflow is fully published and usable
- YELLOW: workflow is partially published, but already usable: instances of multi-instance blocks have not been activated yet
- ORANGE: workflow is being published, some necessary parts are not active, so the workflow is not usable
details: details on the publication status of the workflow components. Contains:
- stream: information on the data stream, i.e. the service that deals with the passage of data from one block to another. Its properties are:
  - id: data stream ID
  - desired: number of target instances
  - actual: number of currently active instances
  - status current status of the service with respect to the color-code used in the Workflow Web application, namely:
    - GREEN: all target instances are active
    - ORANGE: some instances are active, some other are not active yet
    - RED: no active instance
- services: information about the services corresponding to the workflow blocks. It is an array, each item of which corresponds to a service and has these properties:
  - id: service ID
  - desired: number of target instances
  - actual: number of currently active instances
  - actual current status of the service with respect to the color-code used in the NL Flow Web application, namely:
    - GREEN: all target instances are active
    - ORANGE: some instances are active, some other are not active yet
    - RED: no active instance

Test the API

To test the API using Postman:

Open the workflow in the Workflows view of the dashboard.
Select the Test tab.
Download the sample collection.
Import the collection in Postman.
Inside the collection, open the Analyze request and set the X-API-KEY header to the API key associated with the workflow.
Set the request body.
Select Send to call the API.