Embedding the fmSMS file into your existing FileMaker solution is the more complex and time consuming type of integration and involves copying all of the elements from fmSMS into your existing file, so that you end up with your existing file with the functionality of fmSMS embedded into it. We’re going to use the FileMaker Pro v12 Contacts Starter Solution as our example solution file we wish to embed fmSMS into.

Step 1: Backup Files and Create Fields

Before proceeding with the integration please backup your existing solution file/s – you want to have a stable version you can revert to in case something goes wrong. We also recommend making a backup of the fmSMS file so you can refer to this to see how it was originally (particularly when updating layouts).

Once you’ve made a backup of your solution files copy the fmSMS file into the same folder as your solution file/s.

Files in Folder

Your solution file is going to need a few existing fields in your Contacts table (we’re assuming your already have a Contacts table that stores Contact names/numbers etc) that we will reference:

ContactID – the primary key field for your Contacts table, typically this is an auto-enter serial number field

Contact Name – typically a field for First Name and another field for Last Name

Mobile/Cell Number – the field that stores the Contact’s mobile/cell number as you would normally dial it (no country codes)

Country – this is required to we can generate the recipient’s number in the international format with the country code (e.g. 61412345678). If you will only ever be sending messages to recipients in the one country you can hard code the country code instead, but we will be using a Country field in these instructions)

Mobile/Cell Number International Format – stores the international formatted version of the Contact’s mobile/cell number. You can copy the field PhoneMobileIntFormat from the fmSMS Contacts table to use here.

If you will be using fmSMS with FileMaker Go for the iPad or iPhone there are a number of fields that we use for the FileMaker Go layouts (you can copy/paste these from fmSMS as well):

SortField_c

zv_SortOrder_gt

zv_QuickFind_g

Step 2: Custom Functions – Copy and Paste or Import

This requires FileMaker Pro Advanced – you can either copy the Custom Functions from the fmSMS file or you can import them from your solution file. If you already have any of these custom functions installed you can skip those:

fmSMS Custom Functions

fmSMS Custom Functions to Copy

 

Contacts Custom Functions after importing

Contacts Custom Functions after importing

 

Step 3: Tables – Copy and Paste or Import

This requires FileMaker Pro Advanced – you can either copy the Tables from the fmSMS file or you can import them from your solution file.

fmSMS Tables List

fmSMS Tables List

 

You most likely won’t need to import the Contacts table as you already an existing Contacts table (if you don’t then you will need to import that). Some other tables might not be required:

Interface: this is part of the fmSMS demo file and usually will not be required

Navigation: this is part of the fmSMS demo file and usually will not be required

Plugins: if you already have a table for plug-ins you won’t need to import this

Preferences: if you already have a single record preferences table you won’t need to import this

Replies: if you will only be sending messages from fmSMS and not receiving incoming messages/replies you won’t need to import this

DeliveryReceipts: if you will not be receiving delivery receipts/status updates automatically from your SMS Gateway you will not need to import this

Senders: if you already have a users table (e.g. all Staff records) you won’t need to import this

ServerSideErrors: if you will not be using FileMaker Server to perform server side scripts you won’t need to import this

In our example integration with the Contacts starter solution we are going to import all tables except for the Contacts, Interface and Navigation tables:

Contacts Table List after importing

Contacts Table List after importing

Step 4: Relationship Graph – Table Occurrences and Relationships

You will need to recreate the Table Occurrences and Relationships from the fmSMS file in your solution file. Unfortunately FileMaker Pro/Advanced does not currently support copy/pasting or importing of table occurrences and relationships so these will need to be recreated manually. As with importing tables if you did not import certain tables you will not need to recreate table occurrences/relationships associated with those tables you did not import.

fmSMS Relationship Graph

fmSMS Relationship Graph

 

Step 5: Update fields that referenced Relationships

Some fields that referenced relationships will now need to be updated (e.g. calculation fields, auto-enter calculations etc). Here’s a list of fields that you should update to make sure the calculations are not commented out:

Accounts

DefaultAccount_c

GatewayAccountNotes

BulkSessions

MessageBodyPreview_c

SenderCountry

SenderIDType

SenderPhoneMobile

SenderPhoneMobileIntFormat

TotalContacts

Messages

RecipientCountry

RecipientPhoneMobile

RecipientPhoneMobileIntFormat

SenderCountry

SenderIDType

SenderPhoneMobile

SenderPhoneMobileIntFormat

SortField_c

Replies

DisplayFromName_c

Senders

PhoneMobileIntFormat_c

N.B. fmSMS references some of these relationships in the calculation fields in the Gateways table to generate the appropriate HTTP POST URL and POST Data for different SMS Gateways. We encourage you to keep the same table occurrence names as fmSMS, otherwise you will need to update the calculation formulas in the Gateways table.

Step 6: Create Layouts

You will need to create any necessary layouts in your solution file with the same names as the fmSMS file. If you did not import certain tables then you will not need to create layouts for those tables. At this step you are only creating the blank Layouts with the same name as in fmSMS. You will be copy/pasting the layout objects/content at a later step. As we have not imported any scripts yet copy/pasting layout content would mean any buttons that reference scripts will be broken.

As you will be recreating layouts in your existing solution file we will be assuming that you will with to recreate the layouts using the same theme/style as your existing solution and not necessarily keep the layouts the same as they are in the fmSMS file. The layouts in the fmSMS file use the Cool Gray theme.

The “DEV” layouts are layouts designed for the developer and are kept hidden from users.

We find having the Manage Layouts window open for both the fmSMS file and your solution file side by side is the quickest way to create new layouts in your solution file. You can quickly copy the Layout Name from the fmSMS file, create a new Layout in your solution file and paste in the name and then select the correct table occurrence to use in the Show Records from menu:

Manage Layouts for fmSMS and your solution file

Manage Layouts for fmSMS and your solution file

Step 7: Scripts – Copy and Paste or Import

You can use FileMaker Pro/Pro Advanced to either copy/paste or import the scripts from the fmSMS file. Once again if you did not import certain tables you will not need to import scripts associated with those tables you did not import. You can generally not import scripts in the following folders as they are used in the fmSMS demo file and usually not required for your solution file:

Utility Scripts

System

Do import these:

System View Selected Related Record

System Create New Blank Record

System Install Solution Plugins

Developer

Do import these:

Set Default Country

Bullet Control [StoreField]

Toggle Debug Mode

Step 8: Value Lists

You will need to recreate the Value Lists from the fmSMS file in your solution file. Unfortunately FileMaker Pro/Advanced does not currently support copy/pasting or importing of Value Lists so these will need to be recreated manually:

fmSMS Value Lists

Step 9: Layout Contents – Copy and Paste Layout Objects/Content

Now that we have the necessary value lists and scripts in your solution file you can now copy/paste the Layout objects/content from the layouts in the fmSMS file. You will first need to size the layouts and layout parts to the correct sizes, or you can customise these to suit your requirements. We are assuming that you will be changing the layouts to match your existing theme and styles, but whilst you are testing the integration you can copy/paste these “as is” and once everything is working you can then come back and restyle the layouts to suit your requirements.

Step 10: Layout Script Triggers

Some of the fmSMS layouts have Script Triggers attached to them. You will need to manually reset these Script Triggers for the following layouts (all of these layouts are for use with FileMaker Go on the iPhone and iPad – if you did not recreate these layouts as your solution won’t be accessed by FileMaker Go users you can skip this step):

Contacts List – iPad

Contacts List – iPhone

Messages List – iPad

Messages List – iPhone

Step 11: Security/Privilege Set Changes

This is an optional step and depends on your particular requirements, but you may wish to make any necessary changes to your existing Privilege Sets to allow certain users access to the fmSMS functionality etc.

If you will be working with an SMS Gateway that sends incoming messages/delivery receipts to your FileMaker Server using the FileMaker PHP API then you will also need to create the required Accounts/Privilege Sets as follows:

Web Privilege Set:

Web Privilege Set

Web Account:

Web Account

fmphp Extended Privileges:

fmphp Extended Privileges

If you will be using FileMaker Server to perform server side scripts (e.g. sending bulk messages, sending messages for FileMaker Go users) you will also need to create the required Accounts/Privilege Sets as follows:

Server Side Script Privilege Set:

Server Side Script Privilege Set

Server Side Script Account:

Server Side Script Account

Step 12: Custom Menus

This is an optional step and depends on your particular requirements, but you may wish to recreate the Custom Menus used in the fmSMS file or modify them to suit your requirements. Unfortunately FileMaker Pro/Advanced does not currently support copy/pasting or importing of Custom Menus so these will need to be recreated manually.

Step 13: OnFirstWindowOpen Script Trigger

The fmSMS file has a OnFirstWindowOpen Script Trigger set via the File Menu>File Options:

File Options

 

The OnFirstWindowOpen Script script performs a number of functions that are specific to the fmSMS file, but you may need to replicate some of this functionality in your existing OnFirstWindowOpen Script Trigger in your solution file (or set a OnFirstWindowOpen Script Trigger if you do not currently have one set). The most likely features you will need to recreate in your OnFirstWindowOpen Script Trigger include:

Ensure the BaseElements Plug-in is installed: this is handled by performing the System Install Solution Plugins script as part of the OnFirstWindowOpen Script Trigger:

Install Plugins

 

Branch by FileMaker client: this is handled at the start of the OnFirstWindowOpen Script Trigger by checking the type of FileMaker Pro client:

Branch By Client

Step 14: Import Records

You will need to import all the records from the fmSMS file from the following tables into your solution files tables:

Gateways

GatewayCodes

Plugins

Templates

When importing make sure you do NOT select the “Perform auto-enter options while importing” in the Import Options dialog. Make sure you reset the zz_Serial# field in each of these to the next serial number.

You will also need to manually create a single record in the Preferences table if you imported that table.

Step 15: Create buttons on your Contacts layouts to Send Single/Bulk SMS

You will need to create some buttons in your existing Contacts layouts to send a Single and Bulk SMS. You can copy/paste these buttons from the Contacts Form layout in the fmSMS file:

Create Bulk SMS

New SMS

Step 16: Update PHP Files

If you will be working with an SMS Gateway that sends incoming messages/delivery receipts to your FileMaker Server using the FileMaker PHP API then you will also need to update the PHP files to reference your solution file and Web Account Name/Password that you created earlier. You need to update the following lines in the PHP files for the SMS Gateway you will be working with:

$hostname = ‘127.0.0.1’;
$database = ‘yourSolutionName’;
$username = ‘yourWebAccountName’;
$password = ‘yourWebAccountPassword’;

Step 17: Update Merge Fields Script

The script Update All Contacts Merge Fields is used to generate a list of merge fields that you can insert into Templates. You will need to update this script so that it works with your existing Contacts table. You only need to update the Set Variable $contactsMergeFields step at the top of this script. It uses the ExecuteSQL function to get a list of fields from your Contacts table:

ExecuteSQL ( “SELECT FieldName FROM FileMaker_Fields WHERE TableName=’Contacts’ ORDER BY FieldName” ; “” ; “” )

You just need to replace ‘Contacts’ with the table occurrence name for your Contacts table. For example if your Contacts table name is Customers and you have a table occurrence on your relationship graph called Customers you would change this to:

ExecuteSQL ( “SELECT FieldName FROM FileMaker_Fields WHERE TableName=’Customers’ ORDER BY FieldName” ; “” ; “” )

Step 18: Testing/Check for Errors

You are now ready to start testing by sending a test message to yourself. You will need to follow the instructions in our Getting Started guide to create the necessary Contact, Sender and Account records first before attempting to send a message. We also recommend that you use a tool like BaseElements to check for any errors that were introduced as part of the integration first (typically you will find some calculations that are still commented out due to missing relationships/table occurrences).