Documentation

Your guide to everything Workflow.

How workflows work

Now that you’ve had an introduction to workflows and actions and learned how to run workflows, you’re ready to dig into the nitty gritty details of how workflows, well, work.

When you run a workflow, each action inside runs in order from top to bottom. Each action plays a role in the task or goal you want to accomplish, much like individual steps in a factory assembly line. For example, some actions fetch information, either from your device or the Internet. Some actions transform information, say, for resizing an image. Other actions share information to services like Facebook or Twitter.

Once the last action finishes running, the workflow completes.

Let’s dive deeper into what happens at each step.

The flow of content

While running a workflow, information is passed from action to action and transformed along the way. We refer to this information as “content”, which can be any type of data. From a simple piece of text, to photos and videos, URLs, calendar events, songs, contacts, Health data, Maps locations, and much more, workflows handle a wide variety of content.

Any number of items can be passed from one action to the next. Content is mostly invisible in the workflow as it’s handed from action to action. And when a workflow finishes, the content is discarded and the workflow reset for the next time you run it.

Consider the following workflow, which contains a Get Latest Photos action followed by a Tweet action. When run, the workflow prompts you to tweet the latest photos from your Camera Roll.

The Get Latest Photos action retrieves and outputs the photos most recently saved to the Camera Roll. While you can’t directly see it, three photos will be passed from the first action to the second when the workflow runs.

Multiple items passed between actions will take the form of an ordered list. In this example, the Get Latest Photos action produces three images sorted in order from most recent to oldest.

Action connections

When one action uses content provided by the action before it, a line forms down the center, connecting the actions together. This line indicates that the output of the one action will be used as input to the following action.

Across the actions available in Workflow, there is a variety of input/output possibilites; many actions can both accept input and create output, whereas some only accept input, others only create output, and a few pass input through as output without changing it.

To check an action’s behavior, tap on its icon and you’ll see a popover that describes the types of input it accepts and what types of output it provides.

Some actions only can accept specific types of content as input. If you were to place an action before an action that isn’t compatible, the actions would not connect and instead would be spaced apart. For example, the Create Playlist action, which creates a new playlist in Apple Music, can only take iTunes songs as input.

The actions are spaced apart because the first action outputs a location and the second action expects to receive iTunes songs. Intuitively, you can see why this doesn’t make sense; you can’t create a playlist of music from a Maps location.

Some actions don’t take input and only produce output. These are typically your “getter” actions, like Get Upcoming Events, Get Current Song, or Select Photos, all of which simply retrieve data. An action that doesn’t take input will be spaced apart from the action before it.

Some actions accept content as input but don’t change it, passing the same content as output. For example, the Vibrate Device action shake your device in between actions while still pass the input along. Similarly, passing a phone number as input to the Call action will place a phone call to that number, and, when the call finishes, will produce the same phone number as output.

The Content Graph

Much of the magic of Workflow comes from the Content Graph, a technology that intelligently converts between different types of content on your behalf. When an action expects one type of content, and you pass in another type, the Content Graph will automatically coerce to the desired type.

For example, consider a workflow with a Get Upcoming Events action followed by a Show Directions action. When run, this workflow will show navigation directions to the next event on your calendar.

The Content Graph knows that the first action outputs a calendar event, and the second action expects a Maps location as input. As such, Workflow automatically grabs the location where the event will take place, and passes that location to the second action to get directions.

More advanced, multi-step coercions are also possible. For example, consider a workflow with a Get Upcoming Events action followed by a Post on Instagram action.

A lot is accomplished with just these two actions. It’s not immediately obvious what would happen when you run this workflow, but the Content Graph figures it out. Since the Content Graph knows that the first action outputs a calendar event and that Instagram action expects an image as input, Workflow can automatically take the location of the event, generate a map image, and pass that on to Instagram.

With the Content Graph, you rarely have to consider whether you’re passing the right type of content from one action to another. Workflow assumes what you want to accomplish, and figures out how to get there.

Jumps in the flow

Once you move into more complex workflows, you’ll run into some special cases where groups of actions may be skipped or separated. Here’s a few examples of unusual flow.

Variables

Variables allow you to temporarily save some content for usage later in a workflow. Often, actions used in conjunction with variables will not connect to any other actions, but their output will be taken advantage of later in the workflow. Learn more in Using variables.

If conditionals

With the If action, a workflow can decide to only run a group of actions if a certain condition is true. Otherwise, it can run an entirely separate group of actions.

When the workflow is run and reaches If, the content will follow the path that fits the conditional requirements. The final action inside an If block will produce the output of the If block as a whole. Learn more in Using If conditionals.

Repeat loops

Repeat actions are used to perform the same actions repeatedly. Actions within a repeat loop run from top to bottom and then jump back to the top, repeating the series as many times as necessary. The input and output for loops works a little differently, which you can learn more about in Using Repeat loops.

Choose from Menu

Choose from Menu actions present a menu to the user for deciding which direction a workflow should head. You can run entirely different series of actions based on which option the user chooses. Learn more in Using Choose from Menu.

Reaching the end

When we reach the end of our metaphorical assembly line, and content has finished being passed down the chain, the workflow reaches the last action and completes. If the last action produces output, the output will appear in a small window below the workflow. You can tap the expand button to bring the content full screen, or tap the share button to send it elsewhere.

Note

If you run a workflow from the Today Widget or Action Extension, no preview of the output will be shown. Instead, the workflow will dismiss immediately and you’ll be brought back to where you left off.

Now you’ve reached your goal, and now you can move on with whatever you were doing.

Whew.


At this point, you may be interested in Discovering useful workflows to play around with. Or, skip ahead to Identifying opportunities for automation to brainstorm potential ideas for workflows. If you have an idea in mind, move on to Creating a new workflow.