Volume Number: 22 (2006)
Issue Number: 4
Column Tag: Programming

AppleScript Essentials

Introduction to Scripting FileMaker Pro

by Benjamin S. Waldie

For the past couple of columns, we have discussed various ways to store and access data using AppleScript. One column provided an introduction to Database Events, a background application in Mac OS X 10.4 and higher, which allows AppleScripts to interact directly with SQLite databases for the purposes of storing and accessing data. Another column explored methods of storing and accessing data in script properties and property list files. This month, we are going to continue discussing data storage and access, this time, using FileMaker Pro, a third-party commercial database application.

For the purposes of following along with this month's column, if you do not own FileMaker Pro, you can download a fully functional 30-day trial from http://www.filemaker.com/

All AppleScript code covered in this month's column was written and tested with FileMaker Pro version 8.0.1. Therefore, some of the AppleScript terminology discussed, may not function with older versions of FileMaker.

A FileMaker Pro database, named Super Heroes, is referenced throughout this month's column. See figure 1. You may download a copy of this database from http://www.automatedworkflows.com/files/demos/MacTECH.03.06.Example.zip This example database is password protected with an account name of Admin and a password of heroes.

The first thing we will discuss, is general database interaction. When scripting FileMaker Pro, the first thing you will probably want to do, is make sure that your target database is opened. This can be done by first checking to see if the database exists, as demonstrated by the following example code.

tell application "FileMaker Pro"
   database "Super Heroes" exists
end tell
--> false

If the desired database is not opened, then you may need to write code to open it. This is done by using the open command, followed by the path to the database file that you want to open. When using the open command, you may optionally specify values for the Accounts and passwords parameters, if the database requires an account name and password. These parameters are pluralized because the open command may also be used to open one or more database files. If multiple databases are to be opened, then a list of databases, along with a list of account names and passwords, may be passed to the open command as parameters.

The following example code demonstrates how to open a single database with a specified account name and password.

set theDatabase to choose file with prompt "Please locate a 
FileMaker Pro database file to open:"

tell application "FileMaker Pro"
   open theDatabase for Accounts "Admin" with passwords "heroes"
end tell

In some cases, your database may already be opened, but may simply be hidden from view, or be behind another database. To show a database, or bring it to the front of any of other visible database windows, you may use the show command. For example:

tell application "FileMaker Pro"
   show database "Super Heroes"
end tell

While FileMaker Pro has a show command, it does not have a hide command. However, FileMaker Pro will allow AppleScript to interact with its menus, with the use of the do menu command. Using this method, you can hide a database by triggering the Hide Window menu item, which can be found under the Window menu. The following example code demonstrates how to do this.

tell application "FileMaker Pro"
   do menu menu item "Hide Window" of menu "Window"
end tell

A count command may be used to determine the number of currently opened databases. This includes any opened, but hidden databases. For example:

tell application "FileMaker Pro"
   count databases
end tell
--> 3

The following example code demonstrates how to retrieve the name of every opened database.

tell application "FileMaker Pro"
   name of every database
end tell
--> {"MyDB1.fp7", "MyDB2.fp7", "Super Heroes.fp7"}

In addition to supporting AppleScript interaction, FileMaker Pro also has its own internal scripting capabilities. Through FileMaker Pro's interface, you can create scripts, and attach them to a database. FileMaker Pro scripts can be triggered in a variety of ways, such as when a database is opened, when a user clicks a button, and so forth. These scripts are not to be confused with AppleScripts. Again, they are internal to FileMaker only, and cannot interact with external applications or processes. See figure 2 for an example of a FileMaker Pro script that will display a custom dialog message, using values from various fields in the database.

As you begin automating FileMaker Pro, you will lean that some tasks cannot be automated using AppleScript alone. For such tasks, utilizing a combination of AppleScripts, and FileMaker Pro scripts, can usually get the job done. FileMaker Pro scripts can be triggered from AppleScript with the use of a do script command. For example:

tell application "FileMaker Pro"
   activate
   tell database "Super Heroes"
      do script "Test"
   end tell
end tell

Figure 3 shows the result of using AppleScript to trigger the custom dialog FileMaker Pro script that was shown in Figure 2.

FileMaker Pro scripts can also be configured to trigger AppleScripts. This is done through the use of a Perform AppleScript FileMaker Pro script. See figure 4 for an example of a Perform AppleScript script that triggers AppleScript code to empty the trash in the Finder.

Prior to FileMaker Pro 7, a database file was comprised of a single table of data. FileMaker Pro 7 introduced the ability to include multiple tables within a single database file. Because of this, if you are scripting a database that contains multiple tables, you may need to specify the table, with which you want to interact in your database. This can be done with the following syntax.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      tell table "Super Heroes"
         -- Add code here
      end tell
   end tell
end tell

By default, if no table is specified, then any commands sent to the database will be directed to the first table in the database. This is demonstrated in the following example code.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      -- Add code here
   end tell
end tell

Therefore, if your database contains only a single table, then it is not necessary to specify a table in your AppleScript code. Rather, it is understood that all commands will be directed to the first table in this database.

Throughout this column, we will refer to our sample database without specifying a table. This is because, our sample database does not contain multiple tables.

Now that we have discussed database interaction, tables, and scripts, let's move on to the central focus of scripting FileMaker, interacting with the records of a database. When scripting FileMaker, you will most likely want to extract data from, or, populate data into the records of a database during execution of your script. Let's take a look at records.

To count the records of a database, you can use the count command in the same way that we counted opened databases. For example:

tell application "FileMaker Pro"
   tell database "Super Heroes"
      count records
   end tell
end tell
--> 3

Please note that the code above will return the total number of records within the entire specified database. That said, many times, you might not want to count the records of the entire database. In some situations, a find may have been performed in the database, and you might want to determine how many records are contained within the current found subset of records. To do this, rather than referring to the database class when counting records, you can refer to the document class. For example:

tell application "FileMaker Pro"
   tell document "Super Heroes"
      count records
   end tell
end tell
--> 1

Distinguishing between the document and database class, can sometimes seem a bit confusing, but here are some general rules for when you should use each construct. When you want to refer to records within the scope of the entire database, you should utilize the database class. When you want to refer to records within a found subset of records only, you should utilize the document class.

To navigate to a specific record in a database, you may use the show command. For example, the following code will locate and display the second record in the entire database.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      show record 2
   end tell
end tell

In the example code above, we specified an index number for the targeted record, in this case 2. An index number refers to the beginning to end positioning of a specified item. In this case, a record with an index number of 2 refers to the second record in the database. In many cases, locating a record by its index may meet your needs. However, keep in mind that a record's index number may change in certain situations, such as when a previous record is deleted. For example, if we were to delete the first record in my database, then record 2 would become record 1, and, therefore, it would have a new index number.

In FileMaker Pro, records also contain unique record ID numbers. These ID numbers are internal to FileMaker, and are assigned to records when they are created. Once an ID has been assigned to a record, it will not change. Therefore, a more accurate way of referring to a record would be to use its ID. To determine the ID of a given record, you may access the ID property of that record. For example, the following code will retrieve the ID number of the second record in the specified database.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      ID of record 2
   end tell
end tell
--> 3.0

Once you have the ID number for a record, then you may refer to that record by using its ID. For example, the following code will find and show a specified record, using its ID, rather than its index number.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      show record ID 3.0
   end tell
end tell

In some cases, rather than accessing an existing record, you may need to create a new record in a database. This is done by using the create command, and specifying in which database you would like to create the record. The following example code demonstrates the proper usage of this command.

tell application "FileMaker Pro"
   create new record at database "Super Heroes"
end tell
--> record id 4.0 of table "Super Heroes" of database "Super Heroes.fp7" 
of application "FileMaker Pro"

As you can see from the code above, the result of the create command, is a reference to the newly created record. This information could be placed into a variable for later usage in your script.

There may also be times when you need to delete records in your database. This can be done by using the delete command. The following code demonstrates how to delete a specific record of a specified database.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      delete record 3
   end tell
end tell

As another example of the delete command, the following code will delete every record in a found subset of records, within the specified database. Notice that, since we want to interact with a found subset of records, the document class is referenced, rather than the database class.

tell application "FileMaker Pro"
   tell document "Super Heroes"
      delete every record
   end tell
end tell

When manually creating a FileMaker Pro database, one of the first things you will do is add fields for the different types of data that your database will hold. For example, our sample database, Super Heroes, contains Name, Secret Identity, and Powers fields, among others. FileMaker Pro's AppleScript dictionary defines two classes for use when interacting with fields.

First, a field class pertains to the actual fields within the context of a database itself, and not within the context of a specific record within that database. This can be illustrated through the following two code examples.

This first example will count the fields within our sample database. Since there are 8 fields in this database, the result of this example code is a value of 8.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      count fields
   end tell
end tell
--> 8

This next example will attempt to count the fields within a specific record of our sample database. Since fields are not contained by records, this code results in a value of 0.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      tell record 1
         count fields
      end tell
   end tell
end tell
--> 0

The second class that is defined for interaction with fields in a database, is the cell class. In FileMaker Pro, databases contain fields and records. Records contain cells, which contain data and correspond to fields. The following example code shows that counting the number of cells within a specified record in our sample database returns a value of 8.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      tell record 1
         count cells
      end tell
   end tell
end tell
--> 8

Now that we have discussed different ways to refer to fields, let's discuss how to retrieve data from fields. To retrieve the contents of a field within the scope of a single record, refer to a specific cell class contained within that record. For example, the following code will retrieve the value of the Name field for the first record in our database.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      tell record 1
         cell "Name"
      end tell
   end tell
end tell
--> "Superman"

As you can see by the code above, it is not actually necessary to reference a parameter of a cell in order to retrieve the cell's value. Simply referring to the cell itself will result in the value of that cell. Other methods of requesting a cell's value include, using the get data command, as well as accessing the cellValue property of the cell class. For example:

get data cell "Name"

Or:

cellValue of cell "Name"

To retrieve a field value from multiple records at once, you may refer to the field class within the scope of a database itself, rather than a record. For example, the following code will return the value of the Name field for every record in the specified database.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      field "Name"
   end tell
end tell
--> {"Superman", "Spiderman", "Batman"}

Again, in this situation, referring to the document class rather than the database class would allow us to access records within the found subset of records, rather than within the entire database. The following example code will return the value of the Name field for every record in the found set of the specified database.

tell application "FileMaker Pro"
   tell document "Super Heroes"
      field "Name"
   end tell
end tell
--> {"Superman", "Spiderman"}

Fields also have properties, which may be of use to you as you script FileMaker Pro. For calculation fields, a formula property may be referenced to retrieve the calculation text for the field. For fields that have been assigned a value list, such as the Powers field in our sample database, the contents of that value list may be retrieved by referencing the choices property of the field. The following code demonstrates how to retrieve a value list for the Powers field in our sample database.

tell application "FileMaker Pro"
   tell document "Super Heroes"
      choices of field "Powers"
   end tell
end tell
--> {"Flight", "Martial Arts", "Peak Physical Condition", 
"Spider Sense", "Spider Webbing", "Super Breath", "Super Hearing", 
"Super Speed", "Super Strength", "X-Ray Vision"}

Now, let's discuss how to populate fields with data. The following example code demonstrates how to set the values of multiple fields within in a given record.

tell application "FileMaker Pro"
   set theRecord to create new record at database "Super Heroes"
   tell theRecord
      set cell "Name" to "Batman"
      set cell "Secret Identity" to "Bruce Wayne"
   end tell
end tell

AppleScript can also be used to populate container fields with images and other types of data using this same technique. To populate a container field with a file, set the value of the cell to the path of the desired file. For example, the following example code will prompt the user to select a photo of Wonder Woman. It will then create a record for Wonder Woman, populate some text fields, and insert the chosen photo into the Photo container field.

set thePhotoPath to choose file with prompt 
"Please select a photo of Wonder Woman:"
tell application "FileMaker Pro"
   set theRecord to create new record at database "Super Heroes"
   tell theRecord
      set cell "Name" to "Wonder Woman"
      set cell "Secret Identity" to "Diana Prince"
      set cell "Photo" to thePhotoPath
   end tell
end tell

Now that we have discussed basic record and field interaction, let's return to records again. Two primary tasks that you may want to automate in FileMaker Pro using AppleScript are, performing finds and sorting records.

There are two ways to find records in a database. The first is to make use of the show command. The following example code demonstrates how to use this command to find and display all of the records within the specified database.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      show every record
   end tell
end tell

To find and display records that match certain field values, you can still use the show command. However, you must specify the criteria for what you would like to find. This is done using the whose clause, and specifying the field you want to search, along with the value you want to locate within that field. For example, the following code will find and display every record in our sample database with a value of Superman in the Name field.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      show (every record whose cell "Name" = "Superman")
   end tell
end tell

A similar code variation can be used to search for records using multiple fields and values. The code below demonstrates this technique. This code will search our sample database for any record with a value of Superman in the Name field and a value of Clark Kent in the Secret Identity field.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      show (every record whose cell "Name" = "Superman" 
      and cell "Secret Identity" = "Clark Kent")
   end tell
end tell

Another method of finding records is to make use of FileMaker Pro's find requests. When you perform a find in FileMaker manually, by selecting Find Mode from the View menu, a new find request is created. You can then enter search values for any desired fields within the request. Additional find requests may also be added, if desired, and even omissions may be specified. This can allow you, for example, to perform a find for every record where field x contains a specific value and field y does not contain a specific value. See figure 5 for an example of a find request in a FileMaker Pro database.

Find requests may also be created using AppleScript, and are represented by the request class. To create a new find request, use the create command. Once a request has been created, much in the same way that you set field values for records, you may specify field values for the fields within find request. Once all field search values have been specified, you may then issue the find command to perform a find using any current find requests.

The following code will perform a find by creating a find request. Prior to creating the request, any existing requests will be deleted, ensuring that no previous requests are included in the search. Once this find request has been created, search criteria are specified by setting values for certain fields within the request. Next, the find command is issued.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      delete every request
      set theFindRequest to create new request
      tell theFindRequest
         set cell "Name" to "Superman"
         set cell "Secret Identity" to "Clark Kent"
      end tell
      find
   end tell
end tell

Like performing a find manually, AppleScript can create multiple requests prior to issuing a find command. The following example code will delete any existing find requests, and create a new request for any records with a value of Super Strength specified in the Powers field. Next, a second request will be created that will omit any records with a value of Flight in the Powers field. The find command will then be issued. So, in other words, this code will perform a find for any records in the database that have a value of Super Strength, but not a value of Flight specified in the Powers field.

tell application "FileMaker Pro"
   tell database "Super Heroes"
      delete every request
      set theFindRequest to create new request
      tell theFindRequest
         set cell "Powers" to {"Super Strength"}
      end tell
      set theFindRequest to create new request
      tell theFindRequest
         set cell "Powers" to {"Flight"}
         set omitted to true
      end tell
      find
   end tell
end tell

Using the techniques mentioned above, AppleScript can be used to perform virtually any type of find in FileMaker Pro, regardless of how complex.

Sorting records is another important task when working with databases in FileMaker Pro. At times, you may want to sort the records within your database, based on data within certain fields. This can be done by using the sort command, and specifying the fields and order that you would like to use for sorting. The following code demonstrates the proper syntax for performing a single field ascending sort of our sample database, using the values contained within the Name field.

tell application "FileMaker Pro"
   tell current layout of document "Super Heroes"
      sort by field "Name" in order ascending
   end tell
end tell

To sort the records of a database using multiple sort criteria, the sort command may be passed through a list of fields, as well as a list of values for the in order property. For example, the following code will sort the database first ascending by the Name field, and then descending by the Secret Identity field.

tell application "FileMaker Pro"
   tell current layout of document "Super Heroes"
      sort by {field "Name", field "Secret Identity"} in order {ascending, descending}
   end tell
end tell

You may have noticed that the sort examples above, reference the current layout of the document class. FileMaker Pro databases may contain multiple visual layouts, or designs, and the sort command requires a reference to a specific layout. Rather than referencing a specific layout by name, the code above simply references the current layout of the document. Please note that, when referencing a layout for sorting, the layout must display the fields that are referenced in the sort.

This month's column should give you a basic understanding of scripting FileMaker Pro. While there are other solutions available for data storage and access, FileMaker Pro provides a robust relational database system, along with a very user-friendly visual front end. FileMaker Pro makes it easy to design simple or complex databases, and writing scripts that interact with those databases is fairly easy too.

FileMaker Pro is a frequent choice by many users for storing and accessing data in their automated workflows. Workflows involving FileMaker Pro often include processes such as catalog automation, data archiving, desktop publishing, digital photograph storage and organization, and more. For complex processes such as these, the ability to write AppleScripts to help manage and streamline the workflow is essential, and can allow for great efficiency and processing power.

To further your knowledge of FileMaker Pro, be sure to visit the FileMaker Pro website at http://www.filemaker.com As mentioned earlier in this month's column, a fully functional 30-day trial of FileMaker Pro is available for download from this site. For additional information about AppleScripting FileMaker Pro, check out the Apple Events Reference database is installed with FileMaker Pro in the English Extras > Apple Events folder.

Until next time, keep scripting!

Ben Waldie is the 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 company 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