Okay, enough fluff... you came here to get some meat (or veggies if you're not into meat)!  Here's a real example using FacetPhone to dial out of the popular Mac database software, FileMaker Pro, using simple FacetPhone UTAPI commands in AppleScript.  FacetPhone UTAPI is part of the FacetPhone package, but is designed as a set of utilities that can be installed on a separate server or Mac desktop that is not running the FacetPhone PBX software.  The FacetPhone UTAPI utilities understand how to talk to the FacetPhone PBX and can issue dial commands or fetch caller ID of incoming calls so another application can use the information to do lookups, or special logging, etc.  The FacetPhone UTAPI package can be copied off the FacetPhone server or contact FacetCorp Support (support@facetcorp.com) to get the latest copy.  It should be installed and configured on any Mac desktop for which you wish to implement this Dialing Out and Caller ID Lookup scheme.

Dialing Out

Telling a FacetPhone user's phone to dial a number is super easy.  The FacetPhone UTAPI command for doing this is "fp_dial".  You just tell "fp_dial" the phone number to dial and a FacetPhone username.  Nada más.  If your Mac username is the same as your FacetPhone username, then this can be something simple like this:

   fp_dial -n 9,972-985-9901 -u $USER

      -n NUMBER_TO_DIAL
      -u FACETPHONE_USER

Fetching Caller ID

Getting the Caller ID information for your current (or last) call with FacetPhone UTAPI is even easier than dialing!  The FacetPhone UTAPI command for doing this is "fp_cid".  Just tell "fp_cid" the FacetPhone username whose Caller ID information you wish to fetch.  If you want extended information you can also get DNIS and call status, for example:

   fp_cid -u $USER

      -u FACETPHONE_USER

   fp_cid -u $USER -n
   fp_cid -u $USER -n -s

      -n  (return DNIS info)
      -s  (return call state)

   <number=9729859901><name=FACETCORP>
   <number=9729859901><name=FACETCORP><dnis=6920>
   <number=9729859901><name=FACETCORP><state=active>
   <number=9729859901><name=FACETCORP><dnis=6920><state=completed>

   <number=No caller id>

FileMaker Pro Implementation

FileMaker Pro by FileMaker, Inc. (a subsidary of Apple) is powerful and easy to use database software.  FileMaker Pro databases are easily customized and extending functionality to include FacetPhone UTAPI support is a breeze.  FacetPhone is all about communicating with folks and in FileMaker, those folks are in your Contacts database.  Imagine a pretty Contacts database with all the regular stuff you keep about your Contacts including Work Phone, Mobile Phone, and Home Phone fields.  Add some buttons to Dial and a button to Find Callers and you have a very slick FileMaker/FacetPhone UTAPI solution for calling out of your database.  Mama would be proud!

FileMaker Dial Buttons

Dialing out of a database is a little easier than searching fields for Caller ID information.  Let's start by setting up to dial out...  In this tutorial, we'll use a Contacts database with phone number fields called, "Work Phone", "Mobile Phone", and "Home Phone".

An easy approach (remember our theme word!) is to create separate buttons for dialing each of the phone number fields.  This allows the database user to pick which number to dial with minimal effort.  So, let's clone the "Contact List" button into 3 new buttons: "Dial Work", "Dial Mobile", and "Dial Home" buttons.  To clone buttons in FileMaker Pro, in "Edit Layout" mode, copy an existing button and then paste it in its new location.

To define a button's functionality in FileMaker, click "Edit Layout", right-click the button, and select "Button Setup".  In this case we want to Specify Calculated AppleScript so we can get the phone number field contents for our dial command.  So select "Perform AppleScript", "Specify...", then "Calculated AppleScript", and "Specify...".

In the Calculated AppleScript area, enter this snippet of code, including each of the double-quote marks and everything else exactly as shown:

"do shell script \"/usr/facetphone_mac_utapi/bin/fp_dial -u $USER -n 9" & GetField( "Work Phone" ) & "\""

Repeat Button Setup for each button, changing only the "GetField" parameter to match corresponding phone number field names (Mobile Phone, Home Phone). That wraps up the Dialing Out part of this.  Pretty easy, huh?  Be sure to test each button...

FileMaker Find Caller Button

Fetching Caller ID and doing a database lookup with the parsed data is a little more involved that dialing out, but it is pretty easy too.  Start by cloning a button, let's call it "Find Caller".

To define the Find Caller button functionality, click "Edit Layout", right-click the Find Caller button, and select "Button Setup".  This time we want to Specify Native AppleScript so we can enter more involved AppleScript code to fetch the Caller ID information, parse it, and then tell FileMaker Pro to search the phone number fields for the Caller ID phone number.  So select "Perform AppleScript", "Specify...", then "Native AppleScript".

In the Native AppleScript area, enter this AppleScript code below, or download "fp_cid_search.applescript" and paste it in:

-- -- $Date: 2012/06/12 -- $Revision: 1.0.a -- -- fp_cid_search.scpt -- -- Searches for Caller ID Number of incoming FacetPhone call in Filemaker -- Contacts database. If Caller ID Number is not found then a new Record -- can be created. FacetPhone's "fp_cid" program used to retrieve Caller ID -- of the current or last call for logged in user sends back a reply like this: -- -- <number=2817318429><name=WIRELESS CALLER> -- -- Assumes 10-digit phone numbers w/hyphens stored in contact records: -- -- Work Phone, Mobile Phone, and Home Phone -- -- For example: -- -- Work Phone: 972-985-9901 -- -- Tested on Mac OS X 10.7.4 with: -- -- FacetPhone v5.0, Build 715 -- AppleScript 2.2.1 -- FileMaker Pro 12.0v1 -- -- -- 2012/06/12 Eric Yundt - FacetCorp Support, support@facetcorp.com -- -- --------------------------------------------------------------------------- -- set cidLine to do shell script "/usr/facetphone_mac_utapi/bin/fp_cid -u $USER" set cidNum to text 9 thru ((offset of ">" in cidLine) - 1) of cidLine -- set cidNum to "1234567890" -- set cidNum to "No caller id" -- set cidNum to "103" if length of cidNum is 10 then set cidNum2 to text 1 thru 3 of cidNum & "-" & text 4 thru 6 of cidNum & "-" & text 7 thru -1 of cidNum else set cidNum2 to cidNum end if tell application "FileMaker Pro" tell database "Contacts" try show (every record whose cell "Work Phone" = cidNum2 or cell "Mobile Phone" = cidNum2 or cell "Home Phone" = cidNum2) on error try display dialog "Caller ID not found. [" & cidNum & "]" buttons {"Cancel", "Create New Record"} if result = {button returned:"Create New Record"} then set newRecord to create new record try if cidNum mod 1 is 0 then tell newRecord set cell "Work Phone" to cidNum2 end tell end if end try show newRecord end if end try end try end tell end tell

That is pretty much all there's to it!  Congratulations, your FileMaker Pro Contacts database now has FacetPhone UTAPI support and is dial-enabled.

For you curious engineering-types... (as if you didn't already know) the above AppleScript code works like this:

1. Call "fp_cid" to get Caller ID information
2. Parse reply to extract Caller ID number part
3. Insert hyphens to convert number into pretty phone format
4. Search database phone number fields for Caller ID number
5. If no match is found, offer to create a new record
6. Fill Work Phone field of new record with Caller ID number

Contact support@facetcorp.com if you have any questions about how to implement this with your FacetPhone system.
Please contact sales@facetcorp.com if you don't have a FacetPhone system.  You know you want one!