Documentation

Your guide to everything Workflow.

Using the Workflow URL scheme

To expand the automation capabilities of Workflow, we’ve added a URL scheme that allows you to interact with the app directly via a series of links. Using the URL scheme, you can open a link on your device that takes you into Workflow and performs a certain task.

If you use another app that supports opening URLs like Launcher or Launch Center Pro, it’s helpful to learn about Workflow’s URL scheme capabilities so you can build your own custom automations.

The Workflow URL scheme allows you to open the app, create, run, or import a workflow, and interact with the Gallery.

Opening Workflow

The most straightforward version of the Workflow URL scheme is simply workflow://, which will open the app and leave it in the same state as when it was last used.

Creating a new workflow

Another simple URL is workflow://create-workflow, which will open My Workflows, create a new workflow, and place you in the workflow composer.

This is helpful if you want to jump straight into building a new workflow immediately, whether it’s setting up a new one on the spot or creating a recurring task to build a new workflow every day.

Running a workflow

The Workflow URL scheme also supports running a workflow saved in My Workflows. This functionality may be useful in automation systems that extend beyond Workflow itself, so other apps can run a workflow in your collection. Or, you could utilize this URL in a task manager like OmniFocus or Todoist for running a workflow as one step in a project.

A URL to run a workflow takes the following structure:

workflow://run-workflow?name=[name]&input=[input]

The following parameters can be provided in the URL:

  • name: The name of the workflow to run.
  • input (optional): Either the word text or clipboard. This value determines what will be provided as input to the beginning of the workflow. When set to clipboard, the contents of the clipboard is used.
  • text (optional): When input is set to text, this text is used as input to the workflow.

By setting the input to text, you can provide your own URL-encoded text as input to the workflow. For example, a URL to provide the text soup as input to a workflow named “Make PDF” would look like this:

workflow://run-workflow?name=Make%20PDF&input=text&text=soup

By setting the input to clipboard, the contents of the clipboard will be used as input to the workflow. For example, a URL to run a workflow named “Add to Instapaper” with the clipboard would look like this:

workflow://run-workflow?name=Add20%to20%Instapaper&input=clipboard

Pro Tip

If you would like to run one workflow from within another, we recommend using the “Run Workflow” action instead of opening this URL. You should only run workflows via URL if you’re integrating from another app outside of Workflow.

Importing a Workflow

Workflow also has the ability to accept .wflow files and import them into My Workflows. This is useful, for example, if you would like to share a workflow online and provide a link for others to instantly add it to their library.

A URL to import a workflow into My Workflows takes the following structure:

workflow://import-workflow?url=[url]&name=[name]

The following parameters can be provided in the URL:

  • url: A URL pointing to the .wflow file you want to import.
  • name (optional): What to name the new workflow. If not provided, the workflow filename is used.
  • silent (optional): By default, the imported workflow will be opened and displayed to the user. Set this parameter to true to import without opening the workflow.

Note

You will be prompted before running a workflow imported from another app for the first time. This prompt ensures that arbitrary workflows will not be run without your permission.

Workflow offers two URL scheme options for interacting with the Gallery: one for opening the Gallery, and one for searching the Gallery.

The URL to open the Gallery is workflow://gallery, taking you to the main page of the Gallery.

A URL to search the Gallery takes the following structure, where query determines the URL-encoded keywords to be searched in the Gallery:

workflow://gallery/search?query=[query]

For example, if you wanted to send someone a link to explore Evernote workflows available in the Gallery, you would have them open:

workflow://gallery/search?query=Evernote

X-Callback-URL

Workflow supports x-callback-url, allowing the calling app to receive a response (a callback) when a particular interaction has completed. You can import and run workflows from an x-callback-url using the same parameters as described above. Here’s an example:

workflow://x-callback-url/run-workflow?name=Calculate%20Tip&input=text&text=24.99&x-success=...&x-cancel=...

Per the x-callback-url standard, the following additional parameters can be provided:

  • x-success (optional): A URL to open when the interaction was successful, for example, after a workflow was imported or finished running. If a workflow was run, a parameter named result is appended to the URL and contains the textual output of the workflow.
  • x-cancel (optional): A URL to open when the interaction was cancelled by the user.
  • x-error (optional): A URL to open when the interaction failed because an error occurred. A parameter named errorMessage is appended to the URL and contains a description of the error.

With x-success, you can provide a URL to be opened after the workflow successfully finishes running. This could be used in conjunction with a multi-step checklist of tasks in OmniFocus, wherein you open the x-callback-url to run a workflow, return to the list, and move on to the next task via URL.

With x-cancel, you can provide a contingency URL to launch if the workflow is stopped before it finishes running. Because the workflow did not complete, no output from the workflow will be provided.

With x-error, you can provide a contingency URL to launch if the workflow encounters an error while running and fails to finish. In this case, you can kick off a different URL to handle the issue.

Using another app’s URL scheme

Workflow also has the ability to integrate with other apps via their URL scheme. If you want to use an app that has URL schemes but isn’t currently supported in a built-in action, you can construct the URLs manually using the URL action and launch them using Open URLs.

Note

Many URL schemes can be hard to implement and debug. Often they will include a variety of parameters and require text to be URL-encoded which can be difficult to read. That being said, exploring URL schemes does provide an even deeper range of customization beyond the built-in apps included in Workflow.

Contact the developers of your favorite apps to see if they currently utilize a URL scheme or ask them to implement URL schemes so you can automate their app in Workflow as well.


Next, we will learn about Taking advantage of web APIs.