TweetFollow Us on Twitter

Introduction to Scripting Address Book

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

AppleScript Essentials

Introduction to Scripting Address Book

by Benjamin S. Waldie

If you have a large number of contacts in your contact management application, then you are probably already aware that maintaining your existing contacts, adding new ones, removing outdated ones, etc., can quickly become a time consuming process. Yet again, AppleScript is ready to come to your rescue. Using AppleScript and Address Book in Mac OS X, you can begin to automate the process of adding and removing contacts, creating groups, and even more.

Throughout this article, we will discuss a number of techniques for automating aspects of Address Book in Mac OS X. Once you have an understanding of these basic techniques, you can begin combining them together, in order to automate your contact management workflow on a larger scale.

Figure 1 shows an example of an Address Book person, which has been created and added to a new group, all with AppleScript. The code that was used to create this entry and group was developed using the example code snippets that are provided throughout this article.

Please note that all code specified in this article was developed using Address Book version 4.0.2 in Mac OS X 10.4.x Tiger. Due to AppleScript terminology changes between versions of Address Book, some code may be slightly different, or may not function properly if you are using an older version of Address Book.

Working with People

Making a New Person

To create a new person in Address Book, use the make command, which can be found in the Standard Suite in Address Book's AppleScript dictionary. While using this command, you may also specify values for various properties of the person. This is demonstrated in the following code, which will create a new person, while assigning values to the first name, last name, organization, and job title properties.


Figure 1. A Person Created by a Script in a Specific Group

tell application "Address Book"		
   set thePerson to make new person with properties 
   {first name:"Ben", last name:"Waldie", organization:"Automated Workflows, 
   LLC", job title:"President"}
end tell
--> person id "778C4D8D-0A22-4918-A5B6-73361FFF8779:ABPerson" of application "Address Book"

The result of the make command is a reference to the newly created class. In the example code above, we have captured this reference in a variable named thePerson. This variable may now be referenced in future code, so that we may add email addresses, phone numbers, and more to the newly created person.

When writing code that interacts with Address Book, you might notice that Address Book's display is not immediately updated. Rather, it may take several seconds for the new person to appear. To force Address Book to update its display immediately, you may use the save addressbook command. For example:

save addressbook

It is good practice to use this command regularly in an Address Book script, in order to ensure that the display always shows the current information, as well as to prevent data loss in the unlikely event of an application crash.

Adding Email Addresses

In Address Book, email addresses, URL's, phone numbers, and addresses are not properties of a person. Rather, they are classes themselves, and are contained as elements of a person. The following example code demonstrates how to add an email address to a specified person.

make new email at end of emails of thePerson with properties 
{label:"Work", value:"applescriptguru@mac.com"}

In the example code above, the label property of the email address indicates the label text that will precede the email address in the person's address card in Address Book's interface. For example, an email address label might read "Work", "Home", "Other", etc. As you will see in some additional examples throughout this article, many other classes in Address Book also possess a label property.

Adding URL's

The method for adding a URL to a person is generally the same as that for adding an email address. The following example code demonstrates how to add a work URL to a specified person in Address Book.

make new url at end of urls of thePerson with properties 
{label:"Work", value:"http://www.automatedworkflows.com"}

Adding Phone Numbers

The following example code demonstrates how to add a work phone number to a specified person in Address Book. Again, as you can see, this code is generally the same as that for adding email addresses or URL's to a person.

make new phone at end of phones of thePerson with properties 
{label:"Work", value:"610.935.0652"}

Adding Addresses

Adding an address to a person is slightly different than the process of adding an email address, a URL, or a phone number. While you can still specify a label property for an address, addresses also possess many other properties. For example, in an address entry, you may specify a street, city, state, zip code, and more. The following example code demonstrates how to add a work address to a specified person in Address Book.

make new address at end of addresses of thePerson with properties 
{label:"Work", street:"123 Anystreet", city:"Anytown", state:"PA", zip:"99999"}

Finding a Person

In some cases, you may not actually want to create a person. Rather, you may want to locate an existing person. One way to access an existing person is by accessing the selection property of the Address Book application. This will return a list of any selected people. The following example code demonstrates how to retrieve the selection.

set thePeople to selection
--> {person id "778C4D8D-0A22-4918-A5B6-73361FFF8779:ABPerson" of application "Address Book"}

However, you may not always want to access the selected person or people. There may be times when you need to locate a person by name, or by another criteria. The following example code demonstrates how to search for specific people by retrieving a list of people matching a given last name.

set thePeople to every person whose last name = "Waldie"
--> {person id "778C4D8D-0A22-4918-A5B6-73361FFF8779:ABPerson" of application "Address Book"}

Retrieving Information for a Person

Once you have retrieved a list of people in Address Book, you will more than likely want to retrieve information about those people, such as their names, email addresses, etc. For starters, the following code demonstrates how you can retrieve a list of all properties of a specified person.

properties of (item 1 of thePeople)
--> {first name:"Ben", maiden name:missing value, 
id:"E9A1B78D-AE19-46D1-98A8-76ADB82E4C49:ABPerson", modification date:..

You may also retrieve the properties of specific elements of a person. For example, the following example code will retrieve properties of any email addresses of a specified person.

properties of emails of (item 1 of thePeople) -->
{{id:"9495797E-3942-4CA2-9EB7-A85CC1420A40", 
class:email, label:"work",value:"applescriptguru@mac.com"}}

Similar to the previous example code, the following example code demonstrates how to retrieve the properties of any phone numbers of a specified person.

properties of phones of (item 1 of thePeople) -->
{{id:"5D411959-09F0-4A65-82FA-01449FD50268", class:phone, label:"work", value:"610.935.0652"}}

Working with Groups

In Address Book, groups are also an important part of contact management. Groups allow you to organize your contacts into sets of contacts, all related in some manner of your choosing. Like people, groups in Address Book are also accessible via scripting.

Making a New Group

In a manner similar to that for creating a new person, the make command may be used to create a new group. For example:

set theGroup to make new group with properties {name:"My Group"} --> group id
"D988FC9B-62FC-4ABA-9C70-E5F5821D2724:ABGroup" of application "Address Book"

As mentioned previously, the result of the make command is a reference to the newly created class. In the case above, this reference is placed into a variable named theGroup, which may be accessed later in your code.

Adding a Person to a Group

To add a person to a group in Address Book, you may use the add command. The following example code demonstrates how to add a person to a group that is referenced through the variable theGroup.

add thePerson to theGroup

Alternatively, you may choose to add a person to a group directly, rather than through the use of a variable. For example:

add thePerson to group "My Group"

Removing a Person from a Group

Removing a person from a group is just as straightforward as adding a person to a group. To remove a person from a specified group, you may use the remove command. The following example code demonstrates the proper use of this code.

remove thePerson from group "My Group"

Again, as mentioned in a tech block earlier in this article, be sure to use the save addressbook command regularly throughout your code, in order to ensure that Address Book's display is immediately updated when creating groups, adding people to groups, or removing people from groups.

Retrieving a List of Groups

There may also be times when you need to retrieve a listing of groups in Address Book. The following example code demonstrates how to retrieve a list of references to any existing groups.

groups -->
{group id "D988FC9B-62FC-4ABA-9C70-E5F5821D2724:ABGroup" of application "Address Book"}

If you prefer to retrieve only the names of the groups in Address Book, the following example code may be used.

name of every group 
--> {"My Group"}

Pulling It Together

Using the sample code and techniques that were discussed thus far throughout this article, you should now be able to start building some basic Address Book scripts, which can be expanded and integrated into a larger workflow. For example, you could develop a script that will extract contact information from a database or from an email message, and then use that content to automatically add or update contacts in your Address Book.

The example code below provides a basic demonstration of how code elements and techniques specified in this article can be pulled together to form a single script. The following example will create a new person, complete with a work email address, URL, phone number, and address.

tell application "Address Book"
   set thePerson to make new person with properties 
      {first name:"Ben", last name:"Waldie", organization:"Automated Workflows, LLC", 
      job title:"President"}
   tell thePerson
      make new email at end of emails with properties {label:"Work", 
         value:"applescriptguru@mac.com"}
      make new url at end of urls with properties 
         {label:"Work", value:"http://www.automatedworkflows.com"}
      make new phone at end of phones with properties {label:"Work", value:"610.935.0652"}
      make new address at end of addresses with properties 
         {label:"Work", street:"123 Anystreet", city:"Anytown", state:"PA", zip:"99999"}
   end tell
   make new group with properties {name:"My Group"}
   add thePerson to group "My Group"
   save addressbook
end tell

Address Book Plug-Ins

When browsing the Address Book Script Suite in Address Book's AppleScript dictionary, you may notice the action property, action title, perform action, and should enable action commands. See figure 2.


Figure 2. Address Book Plug-In Handlers

These commands are actually handlers, which may be added to a script in order to create an Address Book plug-in script. An Address Book plug-in script is a script that may be triggered from a rollover button. Rollover buttons are popup buttons, which appear when a user drags the mouse pointer over and clicks on certain labels, including phone numbers, email addresses, addresses, and more, on a person's Address Book card.

The following is example code for an Address Book plug-in. This plug-in will add a new menu item, called "Speak Phone Number" to the rollover button popup menu for each phone number of a person in Address Book. See figure 3.


Figure 3. Accessing an Address Book Plug-In Script

Whenever the "Speak Phone Number" menu item is selected, the corresponding phone number's digits will be spoken, using the say command.

The say command may be found in the User Interaction Suite of the Standard Additions scripting addition.

using terms from application "Address Book"
   on action property
      return "phone"
   end action property

   on should enable action for thePerson with theEntry
      if theEntry <> missing value then
         return true
      else
         return false
      end if
   end should enable action

   on action title for thePerson with theEntry
      return "Speak Phone Number"
   end action title

   on perform action for thePerson with theEntry
      set thePhoneNumber to value of theEntry
      repeat with a from 1 to length of thePhoneNumber
         set theCharacter to character a of thePhoneNumber
         if "0123456789" contains theCharacter then say theCharacter
      end repeat
   end perform action
end using terms from

We will now take a few moments to walk through the different handlers in the code above.

action property Handler

This handler is called when the mouse pointer first rolls over a label that serves as a rollover button, after Address Book has been launched. When triggered, the handler should return a string indicating the type of rollover button under which the script should be displayed. Options may include phone, email, address, and more.

should enable action Handler

This handler is invoked when the user actually clicks on the rollover button on a person's card. Once triggered, this handler should return a boolean value indicating whether the plug-in script may be available for the currently selected rollover. The example code above uses this opportunity to verify that the value of the phone number is not a missing value. If it is a missing value, then the menu item will not be enabled in the rollover button popup menu.

action title Handler

This handler is also triggered when the user clicks on the rollover button, but after the should enable action handler is triggered, if present. This handler should return as its result the name of the menu item that should be displayed in the rollover button popup menu.

perform action Handler

This handler is triggered when the user selects the menu item from the rollover popup menu. A reference to the selected person, as well as the selected data on which the rollover button was clicked, are passed to the handler as parameters. Add your processing code to this handler to perform the desired function.

Installing an Address Book Plug-In Script

Once you have written your Address Book plug-in script, save it as a compiled script into the Library > Address Book Plug-Ins folder at the local or user level of your hard drive. Next, re-launch the Address Book application to load the plug-in script and begin using it.

In Closing

As you are probably aware, there are other applications available for the Macintosh that provide contact management capabilities, many of which are AppleScriptable. Microsoft Entourage, Eudora, Now Up-To-Date & Contact are a few of such programs. If you are not an Address Book user, you are encouraged to explore your favorite contact management application, in order to determine whether it is scriptable. If it is scriptable, while the AppleScript terminology will be different, many of the tasks discussed in this article may still be possible to automate.

Regarding Address Book, the examples shown throughout this article should help you to begin automating some basic Address Book functions. You are encouraged to begin integrating these examples into your own custom scripts, and exploring some of the other possibilities for automating Address Book, which may not have been discussed in this article.

Until next time, keep scripting!


Ben Waldie is author of the best selling books "AppleScripting the Finder" and the "Mac OS X Technology Guide to Automator", available from http://www.spiderworks.com. Ben is also president of Automated Workflows, LLC, a firm specializing in AppleScript and workflow automation consulting. For years, Ben has developed professional AppleScript-based solutions for businesses including Adobe, Apple, NASA, PC World, and TV Guide. For more information about Ben, please visit http://www.automatedworkflows.com, or email Ben at applescriptguru@mac.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

MacFamilyTree 8.2.7 - Create and explore...
MacFamilyTree gives genealogy a facelift: modern, interactive, convenient and fast. Explore your family tree and your family history in a way generations of chroniclers before you would have loved.... Read more
WhatsApp 0.2.8000 - Desktop client for W...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
TotalFinder 1.10.7 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Features... Read more
Box Sync 4.0.7886 - Online synchronizati...
Box Sync gives you a hard-drive in the Cloud for online storage. Note: You must first sign up to use Box. What if the files you need are on your laptop -- but you're on the road with your iPhone? No... Read more
Espresso 5.1 - Powerful HTML, XML, CSS,...
Note from the developer: For the new Espresso, we changed our versioning and licensing approach with more consistent pricing and a simpler development timeline: "X+1". Each new update would increase... Read more
VueScan 9.6.04 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Slack 3.0.5 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 3.0.5: Bug Fixes: An important security update. Security... Read more
VirtualBox 5.2.6 - x86 virtualization so...
VirtualBox is a family of powerful x86 virtualization products for enterprise as well as home use. Not only is VirtualBox an extremely feature rich, high performance product for enterprise customers... Read more
Vivaldi 1.13.1008.40 - An advanced brows...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more
WhatRoute 2.1.1 - Geographically trace o...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more

Latest Forum Discussions

See All

JYDGE (Games)
JYDGE 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: Build your JYDGE. Enter Edenbyrg. Get out alive. JYDGE is a lawful but awful roguehate top-down shooter where you get to build your... | Read more »
Tako Bubble guide - Tips and Tricks to S...
Tako Bubble is a pretty simple and fun puzzler, but the game can get downright devious with its puzzle design. If you insist on not paying for the game and want to manage your lives appropriately, check out these tips so you can avoid getting... | Read more »
Everything about Hero Academy 2 - The co...
It's fair to say we've spent a good deal of time on Hero Academy 2. So much so, that we think we're probably in a really good place to give you some advice about how to get the most out of the game. And in this guide, that's exactly what you're... | Read more »
Everything about Hero Academy 2: Part 3...
In the third part of our Hero Academy 2 guide we're going to take a look at the different modes you can play in the game. We'll explain what you need to do in each of them, and tell you why it's important that you do. [Read more] | Read more »
Everything about Hero Academy 2: Part 2...
In this second part of our guide to Hero Academy 2, we're going to have a look at the different card types that you're going to be using in the game. We'll split them up into different sections too, to make sure you're getting the most information... | Read more »
Everything about Hero Academy 2: Part 1...
So you've started playing Hero Academy 2, and you're feeling a little bit lost. Don't worry, we've got your back. So we've come up with a series of guides that are going to help you get to grips with everything that's going on in the game. [Read... | Read more »
What mobile gaming can learn from the Ni...
While Nintendo might not have had things all its own way since it began developing for mobile, one thing it has got right is the release of the Switch. After the disappointment of the WiiU, which I still can't really explain, the Switch felt a... | Read more »
Programmer of Sonic The Hedgehog launche...
Japanese programmer Yuji Naka is best known for leading the team that created the original Sonic The Hedgehog. He’s moved on from the speedy blue hero since then, launching his own company based in Tokyo – Prope Games. Legend of Coin is the... | Read more »
Why doesn't mobile gaming have its...
The Overwatch League is a pretty big deal. It's an attempt to really push eSports into the mainstream, by turning them into, well, regular sports. But slightly less sweaty. It's a lavish affair with teams from all around the world, and more... | Read more »
Give Webzen’s new billiard game PoolTime...
Best known for producing hugely popular MMO titles, South Korean publisher Webzen is now taking aim at a different genre altogether. PoolTime is a realistic eight ball pool simulator, allowing you to compete in real-time matches against players... | Read more »

Price Scanner via MacPrices.net

9.7-inch 2017 WiFi iPads on sale starting at...
B&H Photo has 9.7″ 2017 WiFi #Apple #iPads on sale for $30 off MSRP for a limited time. Shipping is free, and pay sales tax in NY & NJ only: – 32GB iPad WiFi: $299, $30 off – 128GB iPad WiFi... Read more
Wednesday deal: 13″ MacBook Pros for $100-$15...
B&H Photo has 13″ #Apple #MacBook Pros on sale for up to $100-$150 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13-inch 2.3GHz/128GB Space Gray... Read more
Apple now offering Certified Refurbished 2017...
Apple has Certified Refurbished 9.7″ WiFi iPads available for $50-$80 off the cost of new models. An Apple one-year warranty is included with each iPad, and shipping is free: – 9″ 32GB WiFi iPad: $... Read more
10″ iPad Pros on sale for $50-$75 off MSRP, n...
B&H Photo has 10″ and #Apple #iPad Pros on sale for up to $75 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only. Note that some sale prices are restricted to certain... Read more
Apple refurbished Mac minis available startin...
Apple has restocked Certified Refurbished Mac minis starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: – 1.4GHz Mac mini: $419 $80 off MSRP – 2.6GHz Mac... Read more
Amazon offers Silver 13″ Apple MacBook Pros f...
Amazon has new Silver 2017 13″ #Apple #MacBook Pros on sale today for up to $150 off MSRP, each including free shipping: – 13″ 2.3GHz/128GB Silver MacBook Pro (MPXR2LL/A): $1199.99 $100 off MSRP – 13... Read more
Sale: 12″ 1.3GHz MacBooks on sale for $1499,...
B&H Photo has Space Gray and Rose Gold 12″ 1.3GHz #Apple MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 12″ 1.3GHz Space... Read more
Apple offers Certified Refurbished 2017 iMacs...
Apple has a full line of Certified Refurbished iMacs available for up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: – 27... Read more
13″ MacBook Airs on sale for $120-$100 off MS...
B&H Photo has 2017 13″ 128GB MacBook Airs on sale for $120 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13″ 1.8GHz/128GB MacBook Air (MQD32LL/A): $... Read more
15″ Touch Bar MacBook Pros on sale for up to...
Adorama has Space Gray 15″ MacBook Pros on sale for $200 off MSRP. Shipping is free, and Adorama charges sales tax in NJ and NY only: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2199, $200 off... Read more

Jobs Board

*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 113384559 Brandon, Florida, United States Posted: 10-Jan-2018 Weekly Hours: 40.00 **Job Summary** Are you passionate about Read more
Art Director, *Apple* Music + Beats1 Market...
# Art Director, Apple Music + Beats1 Marketing Design Job Number: 113258081 Santa Clara Valley, California, United States Posted: 05-Jan-2018 Weekly Hours: 40.00 Read more
*Apple* Pay & Wallet Engineering Manager...
# Apple Pay & Wallet Engineering Manager, Apple Watch Job Number: 83769531 Santa Clara Valley, California, United States Posted: 06-Nov-2017 Weekly Hours: 40.00 Read more
UI Tools and Automation Engineer, *Apple* M...
# UI Tools and Automation Engineer, Apple Media Products Job Number: 113136387 Santa Clara Valley, California, United States Posted: 11-Jan-2018 Weekly Hours: 40.00 Read more
Senior Product Architect, *Apple* Pay - App...
# Senior Product Architect, Apple Pay Job Number: 58046427 Santa Clara Valley, California, United States Posted: 04-Jan-2018 Weekly Hours: **Job Summary** Apple , Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.