Filemaker and the Mac OS X Addressbook
Using MBS Plugin 3.2pr7 and newer you can access the address book on Mac OS X from Filemaker. You can query, create and edit records, both groups and people. So in this article we show you how to do certain tasks.We'd like to explain you a few basic tasks, so you can easily get started and add addressbook features to your solution. Especially doing some level of synchronization, so users can change an address on their iPhone in the contacts app and your solution notices that change.
1. Me
One person record in the address book is blessed as it represents the user logged in to the computer. So the Addressbook.me function returns you the ID of this person. All functions returning records give you a list of IDs. With the ID, you can query values like the name of the record. For that we have the convenience function Addressbook.record.displayname.
So you can use script steps like this:
Set Variable [ $userID; MBS("Addressbook.me") ]
Set Variable [ $name; MBS("Addressbook.record.displayname"; $userID) ]
This will get you the user name of the user of the computer your Filemaker solution runs on.
2. Find people and groups.
For getting a list of all people, you can call Addressbook.people to get a list of the people. And if you call Addressbook.groups, you get the list of groups. You can write a loop and pick an ID at a time and pass it to the Addressbook.record.displayname function to learn all the display names for the people or groups.
Also we have some search functions: Addressbook.searchPeopleWithEmail finds you all peoples with a given email address. Also you can search by name with Addressbook.searchPeopleWithName by first name, last name or both. If you need a specific other search, we can help you by adding it.
3. Reading values
To query a value of a record, you use the Addressbook.record.valueForProperty function. It takes a property name. You can pass FirstNameProperty to get the first name of a person. Some properties are text, some are dates and some are numbers. You can simply query them. But some values are really multi values. That means you have not simply a phone number, but a list of phone numbers which also have labels (like work or home) and one is the primary one. In case of a multi value property, you have to use our multi value functions. So here some example script steps:
Set Variable [ $userID; MBS("Addressbook.me") ]
Set Variable [ $FirstName; MBS("Addressbook.record.valueForProperty"; $userID; "LastNameProperty") ]
Set Variable [ $ModificationDate; MBS("Addressbook.record.valueForProperty"; $userID; "ModificationDateProperty") ]
Set Variable [ $PhoneNumbers; MBS("Addressbook.record.valueForProperty"; $userID; "PhoneProperty") ]
Set Variable [ $PhoneCount; MBS("Addressbook.multivalue.count") ]
Set Variable [ $FirstPhoneNumber; MBS("Addressbook.multivalue.valueAtIndex"; 0) ]
As you see we query the phone property. This will give a multi value which is stored by the plugin as the current one. All multi value functions work on that one, so the Addressbook.multivalue.count function gives you the number of phone numbers. In a loop you can use Addressbook.multivalue.valueAtIndex to get each of the phone numbers by counting the index from 0 to count-1.
To find the primary phone number, you can use Addressbook.multivalue.primaryIdentifier to get an ID and use Addressbook.multivalue.valueForIdentifier to get the actual value.
The current list of supported properties is here:
Possible property names are UIDProperty, CreationDateProperty, ModificationDateProperty, FirstNameProperty, LastNameProperty, FirstNamePhoneticProperty, LastNamePhoneticProperty, NicknameProperty, MaidenNameProperty, BirthdayProperty, BirthdayComponentsProperty, OrganizationProperty, JobTitleProperty, HomePageProperty, URLsProperty, CalendarURIsProperty, EmailProperty, AddressProperty, OtherDatesProperty, OtherDateComponentsProperty, RelatedNamesProperty, DepartmentProperty, PhoneProperty, AIMInstantProperty, JabberInstantProperty, MSNInstantProperty, YahooInstantProperty, ICQInstantProperty, InstantMessageProperty, SocialProfileProperty, NoteProperty, MiddleNameProperty, MiddleNamePhoneticProperty, TitleProperty, SuffixProperty and GroupNameProperty.
4. Creating a record
To create a person or a group use our functions for that: Addressbook.NewGroup and Addressbook.NewPerson. You get back a special ID which you pass to other functions like Addressbook.record.SetValueForProperty to set properties. For multi values like phone numbers, emails or related names, you use Addressbook.multivalue.New to create a new multi value. Than you fill in values with Addressbook.multivalue.addValue and than you can call Addressbook.record.SetValueForProperty. Simply pass multi value as text to the value, so the plugin knows you want to set the new multi value for the property.
Once you created the person, you need to add it to the database with Addressbook.addRecord. But that doesn't commit the change unless you call Addressbook.save, too. After the save was successful, you can use Addressbook.record.UniqueID to get the permanent ID for the special ID from Addressbook.NewPerson.
5. Utility functions
We have a couple of utility functions. Like for example Addressbook.person.ShowInAddressbook and Addressbook.person.EditInAddressbook functions are handy to launch Contacts app and show the person to the user.
For addresses, we have the function Addressbook.formattedAddress to format an address in the multi value for the address property. This way you can format the addresses for displaying to user in the localized format for the address.
For a person you can query the data as a VCard file and export it or email it. And when your solution has an VCard as file or in a container, the plugin can create you a person from it which you can add to the database or simply query values from it.
6. Use in Solutions
Well, most solutions have some address book feature and you can build scripts to sync the addresses. But it may be worth to decide to actually make the decision to say: We keep contacts in Contacts app on Mac and just store additional values in Filemaker. So in Filemaker you store the ID for the person record and any additional value. You should cache values you need like phone numbers, but you also should regularly check the modification dates of your record and the address book record. This way you can quickly check and update your cache.
Be sure to also check the example project for sample script code.
