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.
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):
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:
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.
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: if you already have a single record preferences table you won’t need to import this
Navigation: this is part of the fmSMS demo file and usually will not be required
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 and Navigation tables:
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.
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:
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:
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.
If you are only going to be working with a single SMS Gateway (e.g. Twilio) then you can just import the scripts for your SMS Gateway. There are scripts for each SMS Gateway in the following script folders (not all Gateways support all fmSMS features so you may not find a script for your selected SMS Gateway in each of these);
Send Message Gateway Subscripts
Get Incoming Messages Gateway Subscripts
Check Account Balance Gateway Subscripts
If you find a script in these folders for your selected SMS Gateway then you could just import these. For example if you are only going to be working with Twilio you would import the following scripts:
Get Replies - Twilio
Get Replies - Twilio API for WhatsApp
Send SMS - Twilio
Send SMS - Twilio API for WhatsApp
Get Message Status - Twilio
If you do import just the scripts for your selected Gateway you will then need to update the following scripts which branch for each supported Gateway:
Check Account Balance
Send SMS from Selected Gateway
Query Status of Current Message
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:
Do import these:
System View Selected Related Record
System Create New Blank Record
Do import these:
Set Default Country
Toggle Debug Mode
Step 8: Value Lists
You will need to recreate the Value Lists from the fmSMS file in your solution file. You can use FileMaker Pro Advanced to copy and paste these from the fmSMS file:
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 or Data API then you will also need to create the required Accounts/Privilege Sets as follows:
Web Privilege Set:
fmphp Extended Privileges:
fmrest Extended Privileges (requires FileMaker Server 17 or later):
If you will be using FileMaker Server to perform server side scripts (e.g. sending bulk messages) you will also need to create the required Accounts/Privilege Sets as follows:
Server Side Script Account:
If you don’t wish to assign this the Full Access Privilege Set you can create your own Privilege Set here with the appropriate permissions and assign that to this 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. Using FileMaker Pro 17 Advanced or later you can copy and paste custom menus from one FileMaker solution to another.
Step 13: OnFirstWindowOpen Script Trigger
The fmSMS file has a OnFirstWindowOpen Script Trigger set via the File Menu>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:
Branch by FileMaker client: this is handled at the start of the OnFirstWindowOpen Script Trigger by checking the type of FileMaker Pro 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:
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
Interface 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
Step 16: Update PHP API 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 Data API PHP Files
If you will be working with an SMS Gateway that sends incoming messages/delivery receipts to your FileMaker Server using the Data API then you will also need to update the Data API 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 = 'your FileMaker Server DNS Name';
$database = 'fmSMS';
$username = 'Web';
$password = 'Web';
$layout = 'WebReplies';
Step 18: 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 19: 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).