Workflows

Create and run automated workflows for your Filestack assets.

Workflows is a great way to automate your file ingest with business rules, automated transformations, and conditional logic. Ask our friendly support team to add it to your plan today! Contact support.

Overview

Workflows allow you to wire up conditional logic and image processing to enforce business processes, automate ingest, and save valuable development time. Once you’ve configured a workflow, it can be called with a single reference in your upload code (for example, using Filestack’s File Pickers).

Concepts

At a high level, workflow represent a unique collection of tasks and logic that orchestrates their execution. As you can build really complex solutions using this feature it is imperative to understand the following concepts, and vocabulary we will use in the documentation:

  • tasks - set of actions that will be executed when job starts
  • logic - some tasks end with specific output suitable to create logic that will orchestrate execution of other tasks
  • job - single run of the workflow. It is triggered by a file upload
  • webhooks - workflows are asynchronous by nature and therefore webhooks need to be configured in order to receive results of the job

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

Configuration

To create a workflow, log in to your Developer Portal with your email and password. Inside the Dev Portal, you’ll see a menu running down the left-hand side of the page. Click on “Workflows”, and you’ll be taken to the Workflows management page where you can see your existing workflows, edit them, remove them and create new ones.

You can learn more about creating new workflows from our tutorial.

Tasks

Workflows support three categories of tasks:

You can learn more about using tasks from our tutorial.

Logic

Configuring logical rules for your workflow requires an understanding of the structure of the data you’re dealing with. In this section, we’ll examine the values you can specify to configure these properly.

Path

The Path field specifies a path to an element in a JSON structure. Paths use the dot notation (element1.element2), for example in order to access the sky element in the following JSON the path would be tags.auto.sky:

{
  "tags": {
    "auto": {
      "aqua": 93,
      "azure": 82,
      "blue": 96,
      "moths and butterflies": 82,
      "sky": 76,
      "teal": 80,
      "turquoise": 78,
      "underwater": 85,
      "water": 93
    },
    "user": null
  },
  "metadata": {
    "filename": "example.jpg",
    "mimetype": "image/jpeg",
    "size": 206993,
    "uploaded": 1539306992437.26,
    "writeable": true
  }
}

Comparison Operators

The following operators will use the example JSON given above, using the following format: path operator value -> result

  • lt: “less than”

    tags.auto.aqua lt 93 -> false
    metadata.size lt 200000 -> true
    
  • lte: “less than or equal to”

    tags.auto.teal lte 80 -> true
    metadata.size lte 300000 -> false
    
  • gt: “greater than”

    tags.auto.aqua gt 93 -> false
    metadata.size gt 300000 -> true
    
  • gt: “greater than or equal to”

    tags.auto.teal gte 80 -> true
    metadata.size gte 200000 -> false
    
  • eq: “equal to”

    tags.auto.sky eq 80 -> false
    metadata.filename eq "image/jpeg" -> true
    
  • neq: “not equal to”

    tags.auto.sky neq 80 -> true
    metadata.filename neq "image/jpeg" -> false
    
  • incl: “does include”

    metadata.filename incl ".jpg" -> true
    metadata.mimetype incl "/png" -> false
    
  • nincl: “does not include”

    metadata.filename nincl ".jpg" -> false
    metadata.mimetype nincl "/png" -> true
    
  • kex: “key exists”

    tags.auto kex "sky" -> true
    tags.auto kex "red" -> false
    
  • knex: “key doesn’t exist”

    tags.auto knex "sky" -> false
    tags.auto knex "red" -> true
    

Usage

In order to trigger the workflow job for each upload in the File Picker you need to attach your workflow ID to the storeTo options like this:

const client = filestack.init('YOUR_API_KEY'); 
const options = {
  storeTo: {
    workflows: ["YOUR_WORKFLOW_ID"]
  }
};
picker = client.picker(options);
picker.open();

Webhooks

Workflows are asynchronous and therefore you need to configure a webhook with a “Workflow” type for your application where you will receive job results. You can configure webhooks in your Developer Portal

Example webhook response:

{
	"id": 61398533,
	"action": "fs.workflow",
	"timestamp": 1548235683,
	"text": {
		"workflow": "2c9b6198-b76r-451a-9755-e7f345d2f45d",
		"createdAt": "2018-10-15T21:57:08.830541141Z",
		"updatedAt": "2018-10-15T21:57:09.612782093Z",
		"sources": [
			"0ih46emUc5qJ1H8G08ag"
		],
		"results": {
			"filetype _ 1539287408985": {
				"data": {
					"filetype": "image",
					"mimetype": "image/png"
				}
			},
			"store _ 1539288700900": {
				"data": {
					"filename": "Publish-Png",
					"handle": "WeixbzAkS5iZhD0RTsTD",
					"size": 15834,
					"type": "image/png",
					"url": "https://cdn.filestackcontent.com/WeixbzAkS5iZhD0RTsT"
				},
				"url": "https://filestack-converse-production.s3.amazonaws.com/_wf/AcCAvMTSvRJ6e0i7eIqkjz/2c9b5749-b76e-453a-9756-e7f112d2f45d/0ih45emUS5eJ1H5G08ag/16d76a18-422f-4478-af77-b4c62e21e456/3bf255c1e548e4557c786a6b9ae14f0a?AWSAccessKeyId=AKIAINGKEZAPX6H5LB7Q&Expires=1339644229&Signature=b3y3RqnMS8gYZ0z3SOsPld7Rr3c%3D",
				"mimetype": "image/png",
				"size": 15834
			}
		},
		"status": "Finished"
	}
}

Read more about creating webhook for workflows in our tutorial.

Security

In order to run a workflow when app security is enabled, convert and runWorkflow policy calls are required. Policies including a call array should contain those calls. When calls are not explicitly set (call array is absent), the policy allows every call. You can read more about this here.

Example policy might look like this:

{
  "expiry": 1523595600,
  "call": ["runWorkflow", "convert", "store"],
}