Skip to content

Platform Workflow API

Introduction

The Platform Workflow API allows you to use Platform workflows programmatically.

The Workflow 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.

API endpoints

The API endpoints for a workflow are:

  1. Document analysis:

    https://{{HOST}}/api/v1/workflow/{{WORKFLOW ID}}/action/analyze
    

  2. Workflow status:

    https://{{HOST}}/api/v1/workflow/{{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 endpoints for your workflow, open the workflow settings in the Workflow application and select the Information tab.

Document analysis

Request this resource to analyze a document with the workflow.

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.

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 first block of the workflow.

If the first block is a ML model, use this structure:

{
    "text": "{{TEXT}}"
}

where {{TEXT}} must be replaced with the plain text to process.
If the first block is a symbolic model that is not configured to accept a sectioned text, use the structure above, otherwise use the following:

or this:

{
    "text": "{{TEXT}}"
    "sections": {{SECTIONS}}
}

where {{TEXT}} must be replaced with the plain text to process and {{SECTIONS}} must be specified to define the boundaries of text sections. In the latter case, sections must be an array of unnamed objects with these properties:

  • name (string): name of the section
  • start (integer): zero-based position of the first character in the section
  • end (integer): zero-based position of the first character after the section

for example:

"sections": [
    {
        "name": "TITLE",
        "start": 0,
        "end": 61
    },
    {
        "name": "BODY",
        "start": 62,
        "end": 2407
    }
]

If the first block of the workflow is the Tika Converter processor, use this structure:

{
    "path": "{{FILE PATH}}",
    "base64": "{{BASE64}}"
}

where {{FILE PATH}} must be replaced with the name of the file to process—or its path—and {{BASE64}} with the Base64 encoding of the file.

If the first block is the URL Converter processor, use this structure:

{
    "url": "{{URL}}"
}

where {{URL}} must be replaced with the URL of the page to process.

Response

The structure of the response reflects the inner working and the layout of the workflow.
The format of the response body, therefore, depends on how the workflow is made and what it does: typically it is a JSON object containing the results of the process in terms of categories and/or extractions, but, in fact, it can be something very different in the case of JavaScript post-processing or custom-type models.
Test the workflow in the management Web application to examine the output and so be able to parse API responses in your program.

The output of your workflow, except when a test block is present, is that of the last block of the flow.
Learn more about the output of the different block types in the reference documentation.
In the case of the presence of the test block within the workflow, the output is always that of that block, regardless of which is the last block of the flow.

Workflow status

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

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:

  1. Go to the test page of the Workflow application.
  2. Download the sample collection.
  3. Import the collection in Postman.
  4. Inside the collection, open the Analyze request and set the X-API-KEY header to the API key associated with the workflow.
  5. Save the request.
  6. Set the request body.
  7. Select Send to call the API.