Discovering Automator by Hanaan Rosenthal • Automator, A Mac OS X Tiger automation app for the rest of us
Chapter 7: Troubleshooting Workflows
As you build your workflows you are certain to encounter problems. Since Automator is so simple, these should be few and far and between.
It is important to recognize the two main types of problems you will encounter:
1. Workflow design issues; or your mistakes.
2. Workflow run-time issues; or user mistakes.
Design issues are actual bugs in your workflow. For instance, you tried to pass text to an action that requires an iTunes song as input. This is simply a bad design and can be discovered, most likely, the first time you try the workflow.
A run time problem is a bit trickier since it only crops up when the workflow runs if one of the required conditions is not met. For instance, the user ignored the dialogue box that asks him to select a photo in iPhoto. The following action will want to go to iPhoto and do something to the selected photo, but there is none.
In these cases, Automator has one course of action: it will stop the workflow and show an error message.
Users; could someone just make them all go away?
The difference is that design issues can be detected much easier than run time issues. In fact, whenever you leave anything up to the user, you leave the workflow wide-open for a failure. No matter how many alters and confirmations and explanations you will add, users will always out-dumb you, and find a way to misunderstand your instructions in a way that will cause your workflow to error.
The negative tone towards users, by the way, is not just letting out steam: it’s a state of mind that will help you create a better workflow with a higher chance for success. Thinking that anything you intend the user to do will be followed to the letter is nothing but delusional, even if you’re the sole user.
Another personality trait you want to assume about the users of your workflow, other than utter stupidity, is their inability to read any instructions longer than four words. That is a fact! When people use software they expect it to be so self-explanatory that any dialogue box containing long text is very likely to be promptly ignored by the user. Instead of reading the whole thing, they will read the first two orthree words and make up their mind as to the meaning of the OK and Cancel buttons you provided.
Name your buttons carefully
For the reasons mentioned above, it’s important to name the actual buttons in dialogue boxes in the most descriptive way instead of leaving them as OK and Cancel. Figure 1 and Figure 2 show two versions of the same dialogue box. The first one is short and to the point, and the second one is too long, and the button titles don’t explain much.
Figure 1. This dialogue text is short and to the point, and the buttons are descriptive.
Figure 2. The text in this dialogue box is too long and the buttons are too generic.
Keep the user in the loop
One problem you may have with users is that they get panicked when they can’t see progress. There area a few ways to help them out with that. First, estimate the time the workflow will take to finish and give the user a warning if the process is expected to last several minutes.
Another thing that can help the user know what’s happening is if you make sure that the application that the workflow uses is in front. While this may actually slow down things a smiget, it is well worth it. A user that sees a moving screen is a happy user.
To do that, use the “Launch Application” action, and specify the application you want to launch. Even if the application is already running, this action will bring it to the front for you, making whatever the application is doing visible to the user.
If the workflow is processing mail messages in Mail application, make sure that Mail is the front application, as seen in Figure 3.
Figure 3. This action will make the Mail application the front most application.
Let someone else test your workflows
It never ceases to amaze me how I can work of a short script or a workflow and try to extrapolate all the possible things a user can do wrong. Then I let an actual novice user use it and he manages to cause three problems in the first two steps.
The fact is, as the workflow designer, you subconsciously avoid doing these things that will cause your workflow to fail. It takes someone very talented, such as a complete novice, to bring the worst in a workflow.
So let a novice try it out. Don’t give him any directions or background; simply have him run the workflow. Watch him work, see where he gets confused, and make changes. I am not suggesting starting a nation-wide focus group operation for every workflow you want to write—simply ask someone in the vicinity to try it out: a spouse, a co-worker, etc. This just might teach you something about your workflow.
Debugging workflows
De-bug-what!? Debugging is the term programmers use to describe getting all the bugs out of a program. In our case it simply means making sure that the darn thing starts, finishes, and produces the intended result.
Bugs in your workflow are caused by you, can be discovered by you, and, well, should also probably be fixed by you.
There are three things that can help you find the bugs in your workflows:
1. Examine and match the input and output of adjacent actions.
2. The “Show Results” action.
3. The workflow log.
Matching input and output
Even if every action in your workflow does its job properly, the place where a lot of problems occur is in the way actions pass data from one to the other. Automator makes it easy to see when an action’s output is compatible with the following action’s input. It is up to you, however, to bridge the gap between what Automator shows you, and what you actually need.
The problem is that Automator can only show you the dry facts about how actions relate to each other, but Automator has no idea how you need them to interact in the context of your workflow. What I mean by that is that sometimes, even though one action seems to not like the output the previous action is giving it, the workflow will still work OK, since the workflow is not dependent on data flowing between the two actions. The other side is true as well: Actions that appear to pass data properly from one to the other are actually improperly placed in the workflow and will produce the wrong result.
Lets look at the workflow in Figure 4:
Figure 4. Automator gives only a part of the story regarding how the actions connect.
There are three actions: New Mail Message, Pause, and Add Attachment to Front Message. The connections between the actions all appear OK, however, they aren’t.
The first action’s result is a Mail message. The Pause action, which is next, doesn’t care what input it gets, it simply passes it along to the next action. That next action is the Add Attachment action. It requires a Files/Folders action, but seems to do OK with the Mail Message passed to it from the Pause action. When the workflow runs, it will not be so OK with it…
Using the “Show Results” action
The “Show Results” action, which I already discussed in detail in previous chapters, is one of the best tools you have for troubleshooting Automator workflows.
The function of this action is to show you the result of the previous action, which will be promptly passed to the following action. This makes the “Show Results” action completely unobtrusive—it sits there and shows you the data that passes from action to action.
Lets try and analyze a simple workflow. The workflow shown in Figure 5 is supposed to create a new TextEdit document with text from a webpage whose URL contains “Apple.” It produces a blank document. Lets see why.
Figure 5. This workflow produces a blank TextEdit document.
Now it may be obvious why this workflow does nothing, but lets pretend to be stumped for a second.
By looking at the red input of the first action, we see that it requires a URL or URLs. It gets nothing and therefore is red. Lets pretend we didn’t see this as well.
To troubleshoot the workflow lets stick a “Show Results” between the first and second action. You can quickly put together the workflow shown in Figure 5, or just follow the other screenshots to come.
After adding the “Show Results” action and running the workflow, the text in the “Show Results” action has empty parentheses, as shown in Figure 6. This shows us that the first action doesn’t actually generate any result.
Figure 6. The workflow after running with the “Show Results” action added.
The fact that the first action produces no result leads us to realize that it needs an input to have a result. Lets add the “Get Current Web Page from Safari” action to the start of the workflow.
After adding it, run the workflow again. Now, the workflow does create a filled TextEdit document containing text from the web page, and the text in the “Show Results” action shows us the URL to that page. See figure 7 for the final workflow.
Figure 7. The final workflow after running.
Now that the workflow works, you can remove the “Show Results” action.
Don’t discard the workflow from this part; it will be used in the next part.
Counting results
Sometimes, the results returned from an action is a list with hundreds or even thousands of items. You can use a simple AppleScript command with the Run AppleScript action in order to simply let you know how many items are there.
Here’s how you do that:
1. Add the Run AppleScript action.
Add it right after the Show Results action, or instead of it.
2. Type this text in the Run AppleScript action:
on run {input, parameters}
display alert (count input)
return input
end run
You can also make your message a bit fancier by making line 2 into this:
display alert "There are " & (count input) & " items in the input."
This will display the alert shown in figure 8.
Figure 8. The “count items” alert.
PDF actions
PDF actions work in a slightly different way: Instead of directly processing the file you pass to them, they will duplicate the file to some hidden directory in your startup disk and manipulate the copy.
This is done to protect your original file.
To see the path of the file these actions copy your PDF to, follow these steps:
1. Create a new workflow.
2. Add a PDF file for processing.
Drag any PDF file from your desktop directly to the Automator workflow window. This will add the “Specify Finder Items” action, and pass a reference to the PDF you dragged over to the next action.
3. Add the “Add Grid to PDF Files” action.
4. Add the “View Results” action.
5. Run the workflow.
As you can see in Figure 9, the file path of the PDF Automator duplicated is somewhere in a hidden folder named “tmp” in the hidden folder “private.”
Figure 9. The PDF action duplicates the PDF file passed to it to a hidden folder with some random name.
To get the file out, use the Move Finder Items action right after the PDF action.
Working with the log
The log is a simple table that shows you what Automator is doing. This does not include anything specific to the actions that run, only Automator’s part.
To show the log, choose Show Log (Command-Option-L). A drawer will open at the bottom of the workflow window and display the log.
If your Automator workflow window reaches all the way to the bottom of the screen, you will need to resize it in order to see the log.
Show the log in the workflow window from the previous workflow, and run the workflow to see the log builds.
The log will show you when every action starts, when it ends, and if it has errored-out. If there is an error, the log will show you the exact error message that describes the error that stopped the action.
The log will also describe any behind the scenes data conversion Automator does.
The log drawer can be seen in Figure 10.
Figure 10. The log drawer.
Looking at errors in the log
One of the benefits of looking at the log is when an action gets an error. Look at the log to see which action caused the error, although this is clear by the red X at the bottom left corner of the action pane. The log, however, will also show you the exact error message.
To force an error, start a new workflow, add the “Add Attachment to Front Message” action, and run the workflow. The log, shown in Figure 11, will display the error.
Figure 11. The log shows the error message.
Add a log button to the toolbar
If you’d like to be reminded to look at the log more often, it’s a good idea to add it to the Automator workflow window toolbar.
1. Choose “Customize Toolbar” from the View menu.
2. Drag the Log button from the Customize Toolbar panel to the window’s toolbar.
3. Click Done.
Figure 12 shows the Customize Toolbar panel.
Figure 12. The Customize Toolbar panel.To quickly remove the Log window from the toolbar, hold down the Command key and drag the Log button out.
The toolbar tips discussed above are useful for any application that has a standard Apple toolbar, which includes the Finder, Mail, Preview, and others.
You can control-click the toolbar to see a menu with toolbar-related items (seen in Figure 13), and command-drag any item from any application’s toolbar to remove it.
Figure 13. The toolbar popup menu.
Stopping workflows cold
In order to stop a workflow in the middle, while it is running, you can simply type Command-period. But what if while troubleshooting, you want to run the workflow halfway? This would usually require disabling a whole bunch of actions.
Unless, of course, you add this nifty little Run AppleScript action. Add it where you want to break, and put this code in iot:
on run {input, parameters}
error
end run
Easy enough?
Dealing with plug-in workflows that get stuck
Whenever you save workflows as plug-ins for other applications, they will run outside of Automator. When these workflows run, such as iCal alarms or Finder plug-ins, the name, status, or current action of the workflow will appear at the title bar of the Mac they run on.
The workflow has three items on the title bar: The name of the workflow, action or workflow status as text, the round progress indicator, and a stop sign.
To stop the workflow in the middle, you can click the stop sign.
Sometimes, however, a workflow gets stuck in the middle, and no matter how many times you click that Stop button, it will stay up there in some Limbaugh state. You can’t use Force Quit to stop it. Instead, you must stop a process called “Automator Launcher.” Here’s how you do that:
1. Launch Activity Monitor.
From the Utilities folder (Command-Shift-U), launch the Activity Monitor application, whose icon is showing in Figure 14.
Figure 14. The Activity Monitor icon.
2. Locate the Automator Launcher process.
In the search field at the top of the Activity Monitor window, type “Automator.” This will bring out the Automator application, as well as the Automator Launcher process.
3. Quit the process.
Click the Quit Process button at the toolbar to quit the Automator Launcher process. It will start up again next time it is needed.
Wrapping up
This chapter almost wraps up the how-to and what-is part of the book. Hopefully, after reading it, you feel more comfortable and competent with Automator.
In the next chapter we will look at some other workflow ideas you can try. These workflows don’t necessarily tie-down to a learned subject, but are simply cool.