Platform NL Flow API

Introduction

The Platform NL Flow API allows you to use Platform workflows programmatically.

The NL Flow API is a RESTful API whose resources correspond to 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/{{WORKFLOW ID}}/action/analyze

where you have to replace:

{{HOST}} with the host name or IP address of the Platform workflow runtime.
{{WORKFLOW ID}} with the workflow ID.

To get the actual endpoint, open the workflow settings in the NL Flow Web application and select the Information tab.

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 API request you must set the following headers:

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

where you have to replace {{API KEY}} 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.
The structure of the object varies based on the left-facing blocks of the workflow. A workflow can consist of one or more independent flows, as shown in the following figure.

The left-facing blocks are those that receive the request body so the JSON must be compatible with them. In the NL Flow application documentation you can find the description of the JSON expected by model blocks and by processor blocks.

Request options

In the case of a workflow starting with a thesaurus model, you can add an option to the request to obtain detailed information about extracted concepts. The request JSON must have this structure:

{
    "text": "{{TEXT}}",
    "options": {
        "custom": {
            "normalizeToConceptId": true
        }
    }
}

Read the article in the manual of the NL Flow application to have more information about this extra output.

Response

The response is a JSON corresponding to the workflow output. In case of single flow (see above), the output of the workflow is that of the last block, with multiple flows it is the concatenation of the outputs of the last block of each flow.

Workflow status

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

Endpoint

The API endpoint for workflow status is:

Workflow status:

https://{{HOST}}/api/v1/runtime/wokflow/{{WORKFLOW ID}}/action/status

where you have to replace:

{{HOST}} with the host name or IP address of the Platform workflow runtime.
{{WORKFLOW ID}} with the workflow ID.

To get the actual endpoint, open the workflow settings in the NL Flow Web application and select the Information tab.

HTTP verb

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

Request headers

In every API request you must set this header:

X-API-KEY: {{API KEY}}

where you have to replace {{API KEY}} with the API key associated with your workflow.

Response

The answer 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 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

Test the API

To test the API using Postman:

Go to the test page of the Workflow application.
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.
Save the request.
Set the request body.
Select Send to call the API.