Workflows

Learn how to create and execute workflows for your Filestack assets.

The Workflows API is currently in a private beta. Please contact support if you are interested in using the Workflows API.

Workflows API

The current beta for the Workflows API is available at: https://workflows-beta.filestackapi.com.

Authentication is required via HTTP basic authentication using your Filestack application key and secret key, as user and password respectively. The API is only available over HTTPS so your credentials are never exposed.

Swagger documentation is available at:

https://workflows-beta.filestackapi.com/docs.

Workflow Model

At a high level, a workflow represents a unique collection of tasks. A task is identified by its id and is associated with a single action it will execute.

When you create a workflow you can specify three properties:

  • name - A descriptive name for the workflow (required field).
  • tasks - The array of tasks that will be executed when a job starts (required field).
  • webhook - A URL that will be sent job results via a POST request.

Each workflow will get its own UUID, which can be used to start jobs. You can think of a workflow like a template for a job, where a job is a concrete instance of the workflow for a particular file.

Define Tasks

A task is comprised of the following properties:

  • id - An optional string id. Defaults to the value of the task’s action.
  • action - The built-in function to execute during a job.
  • params - An object containing parameters for the specified action.
  • requires - An array of task dependencies, where a dependency specifies a task id (which can be another task in the tasks array, or a built-in action id) and a condition that the dependent task output must satisfy.

If a workflow requires two tasks with the same action, then you must give each task a unique id.

Task Actions

All available task actions and their contracts are provided in the JSON response from the /tasks endpoint:

https://workflows-beta.filestackapi.com/tasks

These currently include:

  • ocr - An action that runs optical character recognition on an image and returns the text results.
  • tags - Runs object classification on the provided image and returns a dictionary of confidence levels for each label detected.
  • sfw - Runs a model that returns confidence levels for an image being not safe for work.
  • process - Runs requests to the Processing API. Allows users to define a chain of the available file processing tasks as a single workflow task.
  • delete - This action removes the file from Filestack and its underlying storage.
  • copyright - Runs copyright detection on a provided image, and returns a list of any detected licenses associated with the image.

Task Dependencies

Tasks can have dependencies on other tasks, and this allows users to construct powerful logic for running jobs on assets that only meet specific conditions. The requires array on the task object defines a list of task dependencies and their conditions.

A requirement consists of a single task id and a condition of its output. The task id can reference a built-in action or another task defined in the tasks array for that workflow.

A condition has the following properties:

  • type: a string referencing a built-in binary predicate. The first argument to the predicate is the result of the task defined on the requirement.
    • gt (Greater Than)
    • lt (Less Than)
    • equals (Equality)
    • includes (Check for existence of value in array)
  • value: the value to compare against (the second argument to the predicate)
  • path: an optional array of strings and integers specifying a path through the task result object. Integers will index arrays, and strings refer to object keys. For example: path: ['x', 0, 'y'] on result object {x: [{y: 2, z: 3}, {y: 4, z: 5}]} will result in value being 2.

For example, if I want to run the built-in “delete” action only when the results from the built-in “sfw” action are above a certain confidence threshold:

{
  "name": "deleteNSFW",
  "tasks": [
    {
      "action": "delete",
      "requires": [
        {
          "task": "sfw",
          "condition": {
            "type": "gt",
            "value": 50,
            "path": ["nsfw"]
          }
        }
      ]
    }
  ]
} 

Start Jobs

The workflow UUID given back in the /workflows POST response can be used to start jobs on Filestack handles. To start a job, POST the following JSON body to /jobs:

{
  "workflow": "workflow_uuid",
  "handle": "file_handle"
}

You should receive a JSON response containing a “pending” status type. Jobs are run asynchronously, so webhooks are highly recommended in order to avoid polling the API for status changes. Your webhook endpoint is expected to be able to receive POST requests with a request body schema as follows:

{
  "handle": "YOUR_FILE_HANDLE",
  "results": {
    "task_id": {
       // results of task
     }
  },
  "status": {
    "type": "done",
    "text": "" 
  },
  "createdAt": "2018-01-02T14:56:05.000Z",
  "startedAt": "2018-01-02T14:56:05.000Z",
  "updatedAt": "2018-01-02T14:56:17.000Z",
  "uuid": "JOB_UUID",
  "workflow": "WORKFLOW_RESOURCE_JSON"
}

Note that results is a mapping of task ids to their respective result values. The results field will be populated once a job has completed successfully. Failed jobs, where the status type is "failed", will not populate results but will instead provide a status text containing the reason for failure.

Roadmap

Right now the Workflows API offers only a subset of the actions we plan to support. Eventually we would like to offer built-in actions such as virus scanning, more object detection models, and file quarantine. Added to this would be the possibility for piping task outputs into other tasks.

We are also planning on adding triggers and constraints to the workflow model. This will enable automated jobs for files based on various triggers, such as upload events. Constraints would restrict automatic job creation to specific criteria derived from the file being processed.

If you have a use case that you think is in scope, please let us know and we would love to talk about it.