TweetFollow Us on Twitter

Building An AppleScript-Based Automator Action

Volume Number: 21 (2005)
Issue Number: 8
Column Tag: Programming

AppleScript Essentials

Building An AppleScript-Based Automator Action

by Benjamin S. Waldie

There has been a lot of excitement in the developer community around the release of Mac OS X 10.4. Unique technologies like Automator, Dashboard, and Spotlight are providing new opportunities for Mac developers to build unique tools that appeal to users everywhere. This month, we are going to walk through the process of developing for one of these great new technologies, Automator.

Automator is Apple's new technology that is helping users everywhere to begin automating repetitive and time consuming tasks in their own unique workflows, allowing them to become more efficient. By placing actions, which are single automated tasks, together in a sequence, users are able to construct a fully automated workflow, without the need to write a single line of code. How does this help us, as developers, you may be asking? Well, someone needs to create the actions that give users this power.

Automator actions are built in Xcode, and are typically developed using either Objective-C, AppleScript, or a combination of these, and possibly other languages. Objective-C may be used to develop actions that interact with core components of the OS, or applications with a public API. AppleScript may be used to develop actions that interact with any scriptable application or process on the Mac.

In this article, we will walk through the process of creating a basic Automator action with AppleScript. This brief overview should provide you with a basic understanding of the primary steps involved in creating a simple AppleScript-based action. Once you understand the basic concepts of building an action, then you can take additional steps on your own to begin expanding your knowledge through additional resources. Before long, you will be creating complex actions that interact with a variety of scriptable applications or processes, and sharing those actions with users. Obviously, it should go without saying that you will need Mac OS X 10.4 and Xcode 2 or higher to create an Automator action.

Getting Started

There are a number of steps involved in the creation of an AppleScript-based Automator action, and we will move through the process fairly quickly.

The first step in creating an action is to determine what the action will do. I've done this part for you already. Our action will accept a list of values as input, and then display a choose from list dialog to the user, allowing the user to make a selection. The value specified by the user will then be passed as output on to the next action in an Automator workflow sequence. An action such as this might be used to give a user the opportunity to process only a specified set of data during execution of a workflow.

  • The choose from list command is found in the User Interaction suite in the Standard Additions scripting addition, included with Mac OS X.

Create an Action Project

Once you have determined what your action will do, the next step is to create a new Xcode project. To do this, launch Xcode and select New Project... from the File menu. You will then be prompted to select from a list of pre-existing project templates. Apple has included a handful of Automator action templates with Xcode to get you started. Select the AppleScript Automator Action template, and click the Next button to proceed. See figure 1.


Figure 1. Choosing an Automator Action Project Template

  • If you are feeling adventurous, or if you prefer developing in other languages, be sure to check out the Cocoa Automator Action and Shell Script Automator Action (Xcode 2.1 or higher) templates, also included with Xcode. Also, be sure to check out the example Automator action projects, complete with sample code, located in the Developer > Examples > Automator folder.

Next, specify a name for your Automator action, in this case, Choose List Items. Specify a directory for the project, and click the Finish button to create the action project. See figure 2.


Figure 2. Specifying a Project Name and Directory

You should now have an Automator action project opened in front of you in Xcode. See figure 3. If you are new to Xcode, then the project may look a little overwhelming to you at first glance. However, there are really only a handful of components with which we, as AppleScript developers, will need to interact. These components are:

main.applescript - This is your action's main AppleScript file. It will contain the AppleScript code that will trigger when the action is run in an Automator workflow.

main.nib - This is your action's interface, as it will be displayed when the action is placed into the workflow view in Automator's interface.

info.plist - This is essentially a configuration file. It will indicate how your action should be handled within Automator, and within a workflow sequence.

  • An English instance of an InfoPlist.strings file is also present, and may be used to specify English translations of properties contained within the info.plist file. Optionally, additional versions of this file may be added for additional translations. For this sample action, we will not use the InfoPlist.strings file.

We will discuss each of these components in greater detail as we build our action project.


Figure 3. A New AppleScript-Based Automator Action Project

Update the Action's Properties

Once we have created our action project, we need to make some adjustments to the info.plist file within the action project. As previously mentioned, the info.plist file is an XML file, which provides information about the action to the Automator application. There are a number of properties and values included in the info.plist file. For the purposes of the action we are building, we will discuss only a handful. At this time, take care not to make changes to any properties included in this file, which are not specified below.

There are a number of ways that you can edit an action's info.plist file. For this project, we will edit the file's XML code directly. Click on the info.plist file in your action's project to view the file's contents within your Xcode window. Skim the info.plist file, paying special attention to the properties listed below, and making any adjustments indicated.

AMAccepts

This property provides Automator with information about the input that an action will accept. This property contains an XML dictionary, which specifies whether the input for the action is optional, and which types of input are acceptable. If an action is configured to accept a certain type of input, then Automator will generate an error if an incompatible input type is passed to the action.

An action may be configured to accept multiple input types, if desired, and each input type must be specified as a universal type identifier (UTI). A list of valid UTI's is included with the Automator developer documentation. For our action, we will simply make use of the default UTI for this property, com.apple.applescript.object, which indicates a generic AppleScript object. Because this is configured by default, you should not need to modify any aspects of this property. The property should appear as follows within your info.plist file:

<key>AMAccepts</key>
<dict>
   <key>Container</key>
   <string>List</string>
   <key>Optional</key>
   <false/>
   <key>Types</key>
   <array>
      <string>com.apple.applescript.object</string>
   </array>
</dict>

AMApplication

This property specifies the category in which the action will appear in the Library list within Automator's interface. For our action, set this property to a value of Automator. This will cause the action to appear within the Automator category.

<key>AMApplication</key>
<string>Automator</string>

AMCanShowSelectedItemsWhenRun and AMCanShowWhenRun

These properties indicate whether the user should be allowed to configure the action's interface to be displayed when run within a workflow. For our action, set the values of both of these properties to false, as we do not want the user to have the ability to display the action's interface during processing.

<key>AMCanShowSelectedItemsWhenRun</key>
<false/>
<key>AMCanShowWhenRun</key>
<false/>

AMCategory

This property is used to help Automator group similar actions together, internally. Currently, the value of this property is utilized by Automator only when the user performs a search via the search field in Automator's toolbar. For our action, set this property's value to Dialog.

<key>AMCategory</key>
<string>Dialog</string>

AMDefaultParameters

This property is used to link attributes of our action's interface to the action's code. We will revisit this property shortly, once we have created our action's interface, and we will specify its value at that time.

AMDescription

This property contains an XML dictionary, which contains the information that Automator displays in the description area when the action is selected. This value may be used to specify a variety of different types of information. For our action, we will use only a few. Configure this property in your action's info.plist file to match the following:

<key>AMDescription</key>
<dict>
   <key>AMDInput</key>
   <string>A list of values, which may be coerced to text format</string>
   <key>AMDOptions</key>
   <string>Allow multiple selections; allow empty selections</string>
   <key>AMDResult</key>
   <string>Specified list items</string>
   <key>AMDSummary</key>
   <string>This action will prompt the user to select from a list of values.</string>
</dict>

AMIconName

This property is used to specify the name of a graphic file that will serve as the action's icon in Automator's Action list, as well as in the action's description, when the action is selected. You may specify the name of a graphic file within your project, within Automator's bundle, or within the "CoreTypes" bundle (found in System > Library > CoreServices). For our action, we will specify a graphic that is included within Automator's bundle, a standard AppleScript icon:

<key>AMIconName</key>
<string>AppleScriptLarge</string>

AMKeywords

This property is used to specify keywords for an action. These keywords will be accessed by Automator when a user performs a search via the search field in Automator's toolbar. For our action, we will specify select and display as keywords. Feel free to assign other keywords as well, if you would like.

<key>AMKeywords</key>
<array>
   <string>select</string>
   <string>display</string>
</array>

AMName

This property contains the name of your action, as it will appear in the Action list within Automator. This property should already be populated for you, but it still bears mentioning. It should appear as follows within your action's info.plist file.

<key>AMName</key>
<string>Choose List Items</string>

AMProvides

This property is similar to the AMAccepts property. It contains an XML dictionary, and indicates the type of output that the action will provide to the next action in a workflow sequence. Like the AMAccepts property, the output type must be a valid UTI. By default, this property should already be configured to output a generic AppleScript object, so you should not need to adjust it. This property should appear as follows within your action's info.plist file.

<key>AMProvides</key>
<dict>
   <key>Container</key>
   <string>List</string>
   <key>Types</key>
   <array>
      <string>com.apple.applescript.object</string>
   </array>
</dict>

Localized Strings

As previously mentioned, you may use an InfoPlist.strings file to specify localized versions of strings within your action's info.plist file. However, for the purposes of this example action, we will not perform this task. Therefore, click on the InfoPlist.strings file in your action project, displaying its contents in Xcode. Next, delete the existing text from this file, leaving the InfoPlist.strings file blank.

Build the Action's Interface

The next step in building our Automator action is to create our action's interface. First, double click on the main.nib file in your action project to open the action's nib within Interface Builder. Once opened, double click on the nib's view instance, if it is not already displayed for you.

Assuming that you already have a basic understanding of how to use Interface Builder, then you may begin adding interface elements to your action's view. For our action, add two checkboxes, set their size to small, and title them Allow Multiple Selections and Allow Empty Selections, as shown in figure 4. These checkboxes will be the settings within our action's interface, which the user will be able to configure from within Automator.


Figure 4. Editing an Action's Interface

  • For more complex actions, you may add additional interface elements. However, be sure to adhere to Apple's Aqua human interface design guidelines, taking into account the limited amount of space within Automator's interface.

Bind The Interface to the Action's Code

Once an action's interface has been designed, the interface elements must be linked to the action's code. This will allow the action to detect changes made to the action's settings by the user, and trigger the appropriate processing code.

There are multiple ways of linking interface elements to the code of an action. However, the most straightforward is to make use of Cocoa bindings. This is the method that we will use for our action. The following steps will walk you through the process of creating these bindings.

Create Parameter Keys

The first step in binding interface elements to action code is to assign parameters. These parameters will later be attached to attributes of the interface elements, and inserted into our action's code. By doing this, changes made to the specified interface element attributes will automatically synchronize to the code of our action. Begin by clicking the Parameters instance in the action's nib. See figure 5.


Figure 5. Selecting the Parameters Instance

Next, type command + 1. This will open the Inspector panel, if not already opened, and display the Attributes pane for the selected Parameters instance. Next, click the Add button in the Attributes pane of the Inspector panel, and add two keys. As the new keys are created, double click on each of them, and re-name them allowEmptySelection and allowMultipleSelections, as shown in figure 6.


Figure 6. Interface Parameter Keys

Bind Parameter Keys to Interface Elements

Once you have created parameter keys, select each of the checkboxes in the action's window view, and perform the following steps. Type command + 4 to display the Bindings pane in the Inspector panel for the current checkbox. Click on value in the Bindings panes of the Inspector panel, and select the parameter key that corresponds to the current checkbox in the Model Key Path field. See figure 7 for an example of a properly configured parameter binding for the Allow Multiple Selections checkbox.


Figure 7. Binding Parameter Keys to Interface Element Attributes

Once parameter keys have been bound to the values of both checkboxes, save the action's interface in Interface Builder, and return to Xcode.

Specify Parameters in the info.plist File

Now that we have configured the bindings within our action's interface, we need to link them to our code, so that they will synchronize automatically when modified by the user. Click on the info.plist file again to display the list of properties for the action. Now, we will revisit the AMDefaultParameters property, which we mentioned briefly.

The AMDefaultParameters property should contain an XML dictionary, containing key/value combinations for the various parameter keys specified within your action's interface. Values specified for these keys will serve as default values for any bound interface elements. For our action, set the AMDefaultParameters property to contain a key for each of the parameter keys that we specified, along with a value of false for each. The properly configured property should appear as follows within your action's info.plist file:

<key>AMDefaultParameters</key>
<dict>
	<key>allowMultipleSelections</key>
	<false/>
	<key>allowEmptySelection</key>
	<false/>
</dict>

Write the Action's Code

Next, we are finally ready to begin writing the processing code for our action. We will be doing this entirely with AppleScript. Click on the main.applescript file to display the action's AppleScript code within Xcode. Next, specify the following code for the action:

on run {input, parameters}
   if (class of input) is not equal to list then set input to {input}
   if input = {} then return input
	
   set inputStrings to {}
   repeat with a from 1 to length of input
      set end of inputStrings to item a of input as string
   end repeat
	
   set allowMultipleSelections to |allowMultipleSelections| of parameters
   set allowEmptySelection to |allowEmptySelection| of parameters
	
   set outputStrings to choose from list inputStrings multiple selections 
      allowed allowMultipleSelections empty selection allowed allowEmptySelection
   if outputStrings = false then error number -128
	
   set output to {}
   repeat with a from 1 to length of inputStrings
      if outputStrings contains (item a of inputStrings) then set end of output to item a of input
   end repeat
	
   return output
end run

As you write processing code for an action, take care to add protection for scenarios that might cause the action to generate an error during processing. For example, our action expects a list of values to be provided as input. Therefore, I have added code to ensure that the specified value is a list, coercing it to a list if necessary.

Test the Action

Once the action's processing code has been written, you are ready to begin testing your action. You may do so by selecting Build and Run from the Build menu within Xcode. Doing so will launch a temporary instance of the Automator application, and your action should be accessible for testing.

To test our specific action, construct a sample workflow. This workflow may consist of a Run AppleScript action, our Choose List Items action, and a View Results action. See figure 8.


Figure 8. An Example of a Test Workflow

If all goes well, your action should display a list of passed input values when run within a workflow, and output the user-specified values. Inevitably, you may make a mistake, which could prevent your action from appearing within Automator, or from running properly within a workflow sequence. It happens to the best of us. To help resolve any issues that may occur during development of this action, you may download and consult the source code for this example action from the following URL:

http://www. automatedworkflows.com/files/demos/MacTECH.08.05.Example.zip.

In Closing

This article should serve as an initial guide to get you started with building your own AppleScript-based Automator actions. However, it is not meant to serve as a definitive guide to Automator development by any stretch of the imagination. For detailed information about creating Automator actions in AppleScript, as well as Objective-C, please refer to the developer documentation included with Xcode, and also available online via the Apple Developer Connection.

If you prefer a book on Automator, then be sure to check out my comprehensive Mac OS X Technology Guide to Automator, available from SpiderWorks http://www.spiderworks.com in both print and eBook formats. The first section of the book covers using Automator, and the second section covers developing your own custom actions. If you think that you need a refresher on AppleScript itself, be sure to check out Danny Goodman's AppleScript Handbook while you're there as well. Sample chapters of both books are available for download.

Until next time, keep scripting!


Benjamin Waldie, author of the best selling eBooks "AppleScripting the Finder" and "Mac OS X Technology Guide to Automator", available exclusively from www.spiderworks.com, is president of Automated Workflows, LLC, a firm specializing in AppleScript and workflow automation consulting. For years, Benjamin has developed professional AppleScript-based solutions for businesses including Adobe Systems, Apple Computer, NASA, PC World, and TV Guide. In addition to his role as a consultant, Benjamin is an evangelist of AppleScript, and can frequently be seen presenting at Macintosh User Groups, Macworld, and other events. For additional information about Benjamin, please visit www.automatedworkflows.com, or email Benjamin at applescriptguru@mac.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniFocus 3.12 - GTD task manager with i...
OmniFocus is an organizer app. It uses projects to organize tasks naturally, and then add tags to organize across projects. Easily enter tasks when you’re on the go, and process them when you have... Read more
Maintenance 2.8.1 - System maintenance u...
Maintenance is a system maintenance and cleaning utility. It allows you to run miscellaneous tasks of system maintenance: Check the the structure of the disk Repair permissions Run periodic scripts... Read more
Scrivener 3.2.3 - Project management and...
Scrivener is a project management and writing tool for writers of all kinds that stays with you from that first unformed idea all the way through to the first - or even final - draft. Outline and... Read more
OmniPlan 4.3 - Professional-grade projec...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
RetroArch 1.9.12 - Game emulator.
RetroArch is most popularly known for being a program with which you can play many emulators and games, which have all been customized and tailor-ported to the libretro API. It is designed to be fast... Read more
Affinity Photo 1.10.3 - Digital editing...
Affinity Photo - redefines the boundaries for professional photo editing software for the Mac. With a meticulous focus on workflow it offers sophisticated tools for enhancing, editing and retouching... Read more
Affinity Designer 1.10.3 - Vector graphi...
Affinity Designer is an incredibly accurate vector illustrator that feels fast and at home in the hands of creative professionals. It intuitively combines rock solid and crisp vector art with... Read more
BetterTouchTool 3.600 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom)... Read more
Backblaze 8.0.1.564 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac. With unlimited storage available for $6 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Day One 6.11 - Maintain a daily journal.
Day One is an easy, great-looking way to use a journal / diary / text-logging application. Day One is well designed and extremely focused to encourage you to write more through quick Menu Bar entry,... Read more

Latest Forum Discussions

See All

Best iPhone Game Updates: ‘Horizon Chase...
Hello everyone, and welcome to the week! It’s time once again for our look back at the noteworthy updates of the last seven days. Some big names in this week’s round-up, with a general theme that I would characterize as nostalgic. Not every game... | Read more »
‘Fantasy Life Online’ from Level-5 Is Ge...
Back in 2018, Level-5 released Fantasy Life Online for iOS and Android in Japan. Fantasy Life Online is a follow-up to the amazing Nintendo 3DS game Fantasy Life. Fantasy Life is one of my favourite and most-played games on that platform, so I was... | Read more »
This Podcast Must Stay Above 55mph – The...
In this week’s episode of The TouchArcade Show, we have to keep the podcast above 55mph or else it will explode! Like the movie Speed! Eli and I spend just about the whole episode talking about Apple’s Unleashed event from this past Monday where,... | Read more »
TouchArcade Game of the Week: ‘Pinstripe...
I know what you’re thinking: “Boy that Townscaper thing sure is neat!" Yes, it is, I love it too and we loved it in our review. BUT! As tempting as it is to gush about it some more here, I actually want to draw your attention to another excellent... | Read more »
The 10 Best Horror Games on Nintendo Swi...
2021 has been a packed year for games on all platforms across different genres. If you’ve noticed, a lot of games are getting into the spooky season with in-game events and the like, but nothing beats a horror game during this season. For this... | Read more »
SwitchArcade Round-Up: ‘Dying Light’ Rev...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for October 22nd, 2021. In today’s article, we have a rare Friday review from our pal Mikhail. He worked tirelessly through the night to bring us his thoughts on Dying Light: Platinum... | Read more »
Steam Link Spotlight - If On a Winter...
Steam Link Spotlight is a feature where we look at PC games that play exceptionally well using the Steam Link app. Our last entry looked at Ambition - A Minuet in Power. Read about how it plays using Steam Link over here. | Read more »
Adventure Puzzler ‘Rob Riches’ Gets a Ne...
Last month we wrote about a new game coming from developer Megapop called Rob Riches, a love letter to classic puzzle adventure games. In Rob Riches you’ll play as the titular man himself as you explore a temple collecting every coin you can find in... | Read more »
‘Grand Theft Auto: The Trilogy – The Def...
After Grand Theft Auto: The Trilogy – The Definitive Edition was officially announced recently following a rumour from a little while ago, a | Read more »
Apple Arcade October 22nd Update Roundup...
This week, NBA 2K22 Arcade Edition was the big new release and it actually arrived a few days ago instead of following the usual Thursday / Friday release pattern. Read more about it here. Barring that new release, Apple Arcade has had many big... | Read more »

Price Scanner via MacPrices.net

Apple restocks Apple Watch SE 40mm GPS + Cell...
Apple has restocked Certified Refurbished Apple Watch SE models (40mm GPS + Cellular, Aluminum Case/Black Sport Band) in their online store for $50 off MSRP, only $279. Each Watch includes Apple’s... Read more
Apple continues to offer 13″ M1 MacBook Pros,...
Apple has a full line of 2020 13″ M1 MacBook Pros available Certified Refurbished, starting at only $1099 and up to $230 off original MSRP. These are the cheapest M1 MacBook Pros for sale today at... Read more
256GB 8.3″ iPad mini on sale for $599, take $...
Amazon has the new 8.3″ 256GB WiFi iPad mini on sale today for $599 including free shipping. Delivery is expect around November 9th. Amazon’s price is $50 off Apple’s MSRP, and it’s the lowest price... Read more
A Look Back At ‘The gadget of the century,’ A...
FEATURE: 10.23.21 – It’s been two decades since a device that put 1,000 songs in our pockets would forever change the way we listened to music. The iPod — which Apple announced on October 23, 2001 —... Read more
Get Apple’s new AirPods Pro with MagSafe Case...
Amazon has Apple’s new 2021 AirPods Pro with MagSafe Case in stock and on sale for $219 shipped. Their price is $30 off Apple’s MSRP, and it’s the first discount we’ve seen on 2021 AirPods Pro. For... Read more
First discounts appear at Amazon with new 14″...
Amazon is offering $50 discounts on a couple of new 14″ M1 MacBook Pros and 16″ M1 MacBook Pros. Preorder today, and Amazon will ship once they receive stock. We expect Amazon’s $50 discount to... Read more
Expercom has the new 9th generation 10″ iPad...
Apple reseller Expercom has Apple’s new 2021 9th generation iPad and 8.3″ iPad mini on sale for up to $40 off MSRP. They are the first reseller to offer such discounts. Due to supply constraints,... Read more
Save $250 on the 12″ 2TB M1 iPad Pro, only $1...
Amazon has the new 12″ 2TB WiFi M1-powered iPad Pro, Space Gray, in stock and on sale today for $1949 shipped. Their price is $250 off Apple’s MSRP, and it’s the lowest price available for a 2TB iPad... Read more
These are the best AppleCare+ Plan deals toda...
Apple reseller Expercom is offering sale prices on Apple AppleCare+ plans ranging up to $94 off MSRP, depending on the product. Plans can be purchased individually and will extend your technical and... Read more
So… When Will All The NEW Products Apple Anno...
FEATURE: 10.20.21 – By now, you’ve probably heard everything there is to know about the products that were unveiled at Apple’s second Fall product announcement of the year, but when will they finally... Read more

Jobs Board

Sales Floor Associate - *Apple* Blossom Mal...
Sales Floor Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Seasonal Operations Associate - *Apple* Blo...
Seasonal Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Read more
Seasonal Cashier - *Apple* Blossom Mall - J...
Seasonal Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Geek Squad Advanced Repair *Apple* Professi...
**838870BR** **Job Title:** Geek Squad Advanced Repair Apple Professional **Job Category:** Store Associates **Store Number or Department:** 000056-Cedar Hill-Store Read more
Sales Floor Assistant - *Apple* Blossom Mal...
Sales Floor Assistant - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.