Ch2

Discovering Automator by Hanaan Rosenthal • Automator, A Mac OS X Tiger automation app for the rest of us

Chapter 2: The Anatomy of an Automator Action
Automator Actions come loaded with many little nuggets of information about the applications they control, the functions they perform, their requirements, warnings, and info about which other Actions they get along with. This chapter examines these properties, and looks at how understanding the information that comes with the Actions can help you in building your workflows.
Where Do I Find Information?
Automator makes it very easy to find information about actions. All you have to do is click the Action—either in the Action column or in your workflow—and look at the information area, seen in Figure 1.

Figure 1. The Action’s info area provides you with useful nuggets of information about what the Action does.
In Figure 1, you can see that the “Download URLs” Action is selected, and the information about that Action is displayed in the Info area at the bottom-left of the Automator document window. But what does that information actually tell you? Let’s find out.
The basic information
While Action developers can include many bits of information about an Action, there are a few basic pieces of information that are available for every action.
The first ones are the Action’s icon, name, and general description; something that tells you what the Action actually does. In Figure 1,you can see that the name of the Action is “Download URLs” and its description is: “This action downloads the specified files from the Internet.” What this tells you is that the Action, when coupled with another Action that actually goes to a URL (hint, try placing the “Get Specified URLs” Action before this one) and download any files it finds there to a specific location on your Mac’s hard drive.
Input and output
Two more important pieces of information are an Action’s input and output. The Info window shows you the type of object (or objects) that the Action expects as input, and the type of object (or objects) that the Action returns as a result. If the Action does not mention a type for input, it means that the Action does not make use of the result of the previous Action. If the Action’s information does not mention the Action’s output (its result), it means that the Action does not return any result.
Pay close attention to an Action’s input and result different actions accept or provide because that can help you to create usable workflows.
More (about) information
Instead of talking about the information Actions may give you, let’s create another cool workflow. The workflow you’ll create takes some Address Book contacts and creates a text document containing the information from these records. While creating this workflow, we’ll take some time out to examine the information that the different Actions provide in the Info pane.
Start by creating a new workflow and save it.
Create a new workflow by choosing New from the File menu (-N), and then save the workflow by choosing Save or Save As from the File menu (-S). Set the workflow’s File Format pop-up to Workflow, and name it “Test workflow.”
We start by saving the workflow right away because it makes it easy to make subsequent saves.
It is too easy to get caught up with Automator fun, forget yourself, and then lose work because you never saved…
Start by locating and adding to the workflow the Action, “Get Selected Address Book Items.”
To do that, clear the Search field by clicking the X to the right of the Search field (see Error! Cannot open file.). Then in the Library, select the Address Book; if you can’t see it, make sure to expand the Applications folder, as seen in Figure 2.

Figure 2. The Applications folder in the Library is expanded, allowing you to click the Address Book application.
Once the Address Book actions are listed, drag the “Get Selected Address Book Items” Action to the blank workflow area on the right. After the Action is in the workflow, click it either in the Actions column or click its title in the workflow area on the left to reveal the Action’s information. Figure shows the selected action in the workflow and the action information in the info area.

Figure 3. The Selected action in the workflow and the action’s information in the info area.
Now let’s see what kind of details the Action’s information box reveals. First it says that the “Get Selected Address Book Items” Action gets the selected items and passes them to the next Action. We can also see that in the Input:
Input: The selected items.
This tells us that this first Action in the workflow requires something to be selected in the Address Book. To help with that, you’ll need to make sure that the person running this workflow knows that they’ll first have to do something with their Address Book. Lets add a “Wait for User Action” item before this Action. This action displays a dialogue box with a message, giving the user time to select items in their Address Book before the workflow continues to run.
Add a user-interaction action.
To do that, click the Applications folder in the Library column, and then go to the Search field, type in “wait.” You’ll see two items appear in the Actions column, “Wait for User Action” and “Pause;” you’ll want the first one. Double-click the “Wait for User Action” item to add it to the workflow. As you can see from Figure , this Action now appears second in line, but you need it to appear at the start of the workflow. The best way to do that is to click and hold on the Action’s number at the top-left of the Action’s panel in the workflow. Clicking the number, in this case number 2, displays a pop-up menu. From that pop-up, choose “Move Before ‘Get Selected Address Book Items,’” as shown in Figure .

Figure 4. Moving the second action to the beginning of the workflow.
Give the user some direction in the Message field.
Once you’ve successfully moved the “Wait for User Action” action to the start of the workflow, your next step is to enter a Message that the user will see when they run this workflow. You’ll want to be as descriptive and succinct as possible since you don’t have a lot of space to work with. For example, you could enter the following text in the message field:
Select some items in the Address Book and then click “Continue.”
You can also increase the time you give the user to do that from 1 minute up to 59 minutes, which would be plenty of time for the user to make their Address Book selections, and also go out and grab a latte. When you’re done, your workflow should look like the one in Figure .

Figure 5. Our workflow with the two actions so far.
Finish the workflow.
To finish this workflow, you’ll need to add two more Actions.
Continue by locating and adding the Address Book’s “Get Contact Information” Action to the end of the workflow. There’s a lot to do in this Action, so feel free to customize it as you see fit.
As an example, you can pretend that this workflow will be used to create a list for distributing to your buddies at basketball pick-up games. For that, you can select to include the first and last names, as well as the email and mobile phone number.
Once you’re done playing with that Action, collapse it by clicking the disclosure triangle next to the Action number at the top-left of the Action panel, as shown in Figure . Doing so allows you to see more of your workflow at the same time and hides the clutter.

Figure 6. Click the disclosure triangle to collapse the action panel and make it take substantially less space in the workflow window.
Locate and add the New TextEdit Document action to the end of the workflow.
The final action is TextEdit’s “New TextEdit Document.” This Action takes the text passed from the “Get Contact Information” Action and creates a new TextEdit document containing that text.
After adding all the Actions and collapsing the “Get Contact Information” Action, your workflow should look like the one in figure 7.

Figure 7. The “Contact Grabber” workflow in its final form.
After you verified that the workflow is complete, run it to see it work!
Your last and final step is to save the workflow (File Save, or -S) and close the workflow window (-W).
Mail attachment workflow
The next workflow you’ll create takes an item you’ve selected in the Finder and attaches it to a Mail message. (I think you can see where we’re going with this, but for now, just think about these example workflows as independent from one another.)
Create a new workflow.
To start out, you’ll need to create a new Workflow (File New, or -N) and save it under the name “New mail with attachment.”
2. Start building the Workflow.
After you have a new blank workflow document, add Mail’s “Add Attachments to Front Message” action to the Workflow area.
3. Read the Action’s Info box.
After adding the Action to the workflow, click the Action’s title bar; this allows you to examine the Action’s info at the lower-left of Automator’s window. Aside from the normal description, Input, and Output, the Info area contains some concisely-stated requirements for the Action as follows:
Requires: The Mail application must be running and there must be an outgoing message.
By looking at the Input part of the Action’s information, you’ll see that the Action requires a file or folder to be passed to it from the previous Action, and that that file/folder then gets attached to a new email message.
You can also tell that the action requires an input by the color of the text describing the input. The input is displayed in the gray title bar at the top of the action pane, while the result type is indicated at the bottom.
As you can see in figure 8, the input indicator of the ‘Add Attachments to Front Message’ action is red, indicating that the action will fail if the correct type of data isn’t passed to it.
This makes sense, since the action can’t attach a file to the mail message if no file was passed to it from the previous action.

Figure 8: The red text showing the input data type required by the action tells you that the action won’t work unless the correct type of input is passed to it.

4. Conform to the Action’s requirements.
First, we must make sure that when the Action runs, Mail will have an open outgoing message. The best way to ensure that is to create a new message.
In the Library column, select Mail (if not already selected) and drag the “New Mail Message” Action to the beginning of the workflow, above the “Add Attachments to Front Message” Action.
Fill in the information for the New Mail Message action and collapse the Action by clicking the disclosure triangle at the top-left of the Action’s panel.
If you open that one up, you’ll notice a Rolodex card icon/button in the upper-right corner of the Action. If you click on that, it opens an “Addresses” window that contains all of your Address Book contacts. You can then select the names of the people you want to add to the distribution of the email, and click either the To, CC, or BCC buttons along the top of that window to insert their addresses) in the appropriate field.
Figure 9 shows the address book button, and figure 10 shows the window that allows you to add addresses to the action’s To, CC, and BCC fields.

Figure 9: The New Mail Message action. Note the Address Book button.

Figure 10: The address book window allows you to easily add email addresses to the New Mail Message address fields.
5. Pass the Action to the right input
While in Step 4 you made sure that there’s going to be an open message to attach the file to; you still need to attach the file. What you’ll want to do here is attach the item that happens to be selected in the Finder. To do that, you’ll want to add the “Get Selected Finder Items” Action to the workflow.
In the Library column, select the Finder and drag the “Get Selected Finder Items” action and place it between the “New Mail Message” and “Add Attachment to Front Message” Actions.
After doing so, your workflow should look like the one in Figure .

Figure 11. The workflow with the three actions so far, and the first action collapsed to save screen space.
6. Finishing touches.
While we’re done with the workflow for this chapter’s purpose, here’s a nice touch you can add:
Locate the “Create Archive” Action and add it between the “Get Selected Finder Items” and the “Add Attachment to Front Document” actions. This creates a ZIP archive from the selected files, and attaches that ZIP archive to the email instead of the individual files themselves.
7. Give it a run.
Now that the workflow is complete, press the Run button at the top right of the window to see it execute.
See how every action that executes in the workflow gets a round progress indicator as it runs, and a green checkbox after it has completed successfully. I will tell you more about that in chapter 3 which is dedicated to running workflows.
8. To finish up, save and close the workflow.
Alerts and Warnings
As much as it is fun to create Automator workflows and watch them run, the damage that can be done by the “wrong Action at the wrong time” cannot be underestimated. Fortunately, Automator has a built-in warning system for Actions that have the potential to permanently alter files or other elements affected by your workflow.
To experience Automator’s warning system, you’ll create a simple workflow that asks the user to choose a folder, pass the contents of that folder over to the next Action, and have the final Action rename all of items in the original folder.
Creating the workflow.
Start by creating a new workflow document (File New, or -N).
2. Give it an Action.
Locate the Finder-related action “Ask for Finder Items” and add it to the workflow. After that, change the settings to match those shown in Figure . The type must be changed to Folders, and the message should better describe what we want the workflow to do, which is to “Choose a folder whose contents you want to rename.”

Figure 12. The first action in the workflow customized to match the workflow needs.
3. Pass on the Action to another Action.
Next, add the “Get Folder Contents” Action to the end of the workflow. This Action takes the folder (or folders) from the previous Action and passes it to the following Action, giving it something to do.
4. Add the Rename Finder Items action.
This action, however, is a bit different. Automator won’t just allow you to add it without making sure you understand the consequences.
As you try to add the Action, Automator pops up the warning message shown in Figure 12.

Figure 13. The warning that pops up when you try to add the Rename Finder Items action.
What Automator is telling you, essentially, is that simply adding the action as-is will permanently alter the files in the folder. Automator, following the directions supplied by the Action itself, suggests adding the “Copy Finder Items” before the “Rename Finder Items” Action. This way, you’ll only alter the copies and not the original files. The buttons you see in this warning dialogue can be a bit confusing, so here’s a little explanation to help you figure this out:
The Add and Don’t Add buttons are a bit misleading. They do not refer to the Action you are trying to add, but rather, they refer to the Action Automator suggests adding to your workflow. If you click the Add button in the warning dialogue (Figure 13), Automator adds the suggested Action, in this case the “Copy Finder Items” action.
Clicking Don’t Add adds the original Action you were trying to add, and won’t add the action suggested by Automator.
Clicking Cancel leaves your workflow unchanged by not adding any Action at all. This lets you take a deep breath, collect yourself, and make another attempt.
Click the Add button and see what happens. If you did, your workflow looks like the one if Figure 6, where action number 3, “Copy Finder Items,” is the action Automator added for you.

Figure 14. The finished workflow.
5. Run your workflow.
Each time you run a workflow, there should be a way to tell if it ran properly. The green checkboxes we discussed earlier in this chapter, and the chime that Automator sounds at the end of the workflow, are indicators that the workflow was completed, but did it actually achieve what you wanted?
In this case, you should have a few items on the desktop renamed with a date stuck at the end of their names.
6. Save and close the workflow window.
What’s coming up next?
So far you were introduced to the Automator interface, and learned quite a bit about how individual actions work. In the next chapter you will learn more about putting actions together into workflows. You will create more sophisticated workflow and see the different ways in which actions pass data from one to the other.

<-- Previous Chapter - Next Chapter -->