Automator Actions

Automator lets people automate time consuming and repetitive tasks by constructing workflows. A workflow consists of one or more actions, each of which performs a single, specialized task in the system or an app—such as opening a file, resizing an image, or opening a webpage. When a workflow runs, its actions execute sequentially, working together toward a common goal. For example, a workflow might include several actions that work together to download images from a webpage, resize them, and import them into Photos.

Within a workflow, information can flow from one action to the next like an assembly line. Most actions accept information as input, and then pass information as output (result) to the next action in the workflow. Actions also often include settings, which the user can adjust to refine the action’s behavior.

The system includes actions for performing tasks in most Apple apps, including Mail, iTunes, Photos, and Safari. Your app can extend the capabilities of Automator by providing actions of its own.

Consider offering at least a basic set of automator actions. Every additional action extends the power of Automator by letting people build a wider range of useful workflows. By providing actions, you enable users to streamline their processes and integrate your app with the system and other apps in new, unique ways.

Create narrowly-defined actions. Keeping actions simple ensures they can be combined in a variety of useful ways.

Make actions configurable. You can’t always predict how people want to use your app. By letting people configure actions to meet their specific needs, you magnify the usefulness of your actions.

Consider letting people configure settings at runtime. Even well-defined workflows often require flexibility. For example, a user might not want a workflow that resizes images to use the same output folder every time the workflow runs. To provide versatility, many actions can be configured to appear onscreen at runtime to allow on-the-fly adjustments.

Allow an action to ignore its input whenever possible. Passing information between actions in a sequential workflow isn’t always possible or desirable. To offer flexibility, many actions can be configured to ignore any input they receive. When an action is set to ignore its input, the action should still be operable. If the action requires information to proceed, it should try and gather that information on its own. For example, if a document isn’t received as input, an action might instead process the currently opened document in your app.

Provide a conversion action when one of your actions produces nonstandard output. Most actions accept and produce common types of information, such as files, images, PDFs, and text. Automator tries to ensure compatibility between actions by performing automatic data conversions whenever possible. For example, when one action outputs files and the next inputs text, Automator automatically converts the files to text-based file paths so the workflow can proceed without fail. Some actions, however, produce more specialized content that Automator doesn’t understand, such as app-specific documents or objects. If your actions do this, you can provide a conversion action that doesn’t appear in a workflow, but runs behind the scenes whenever necessary to ensure compatibility between actions.

Communicate progress when it takes time to populate an action’s interface. Sometimes, an action must gather data to populate its interface. For example, the Get New Mail action gets a list of email accounts and displays them in a pop-up button. If it takes more than a second or two to gather necessary information, your action should show a progress indicator so the user knows that data is loading. See Progress Indicators. It’s also a good idea to disable interface elements while data loads so the user doesn’t try to interact with them.

Action Design

Provide a clear action title. Action titles should be short, verb phrases that use title-style capitalization. They should clearly describe the action’s purpose so it’s easy to locate at a glance. To avoid truncation, limit titles to between two and five words. For example, Eject Disk, New Mail Message, and Get Definition of Word. Include your app name if it adds context. For example, Get Specified iTunes Items, Get Specified Finder Items, and Get Specified Calendar Items.

Provide sufficient descriptive information about an action. Automator includes a description area that shows detailed information about a selected action. People often use this area to learn about an action and decide whether to include it in a workflow. Each action should provide a detailed description consisting of one or more sentences that clearly describe the purpose of the action. In addition, each action should detail its input and result types, requirements, options, notes, warnings, related actions, version, and copyright information.

Minimize action height. Actions are stacked within a workflow. Since screen sizes are wider than tall, you should consider ways to minimize an action’s use of vertical space. For example, you could use a pop-up button instead of a series of radio buttons, even if there are only two choices. In general, use small sized controls and 10pt margins. Make sure your entire action fits onscreen without requiring scrolling.

Don’t include labels that repeat the action’s title or description. Labels that repeat information available elsewhere take up space without providing value.

Don’t use boxes. An action doesn’t need to separate or group controls within boxes.

Avoid visible tab views. Instead, use hidden tab views to alternate between different sets of controls.

For developer guidance, see Automator and macosxautomation.com.