Developer»Integration Instructions

Integration Instructions

Integrating fmSpark in 10 minutes or less.


For fmSpark to work correctly, it must be 'stitched' to your solution using the relationship graph in fmSpark.fp7.

Note that you can't integrate the fmSpark demo; you'll need the purchased version in order to get in under the hood and attach this to your files. If you'd like a preview of what's involved, check out this short video where we integrate a copy for you: integrating fmSpark live.

fmSpark ships with an example Contacts database that is already integrated attached to it, but the quickest way to get fmSpark working with your solution is to repoint the table occurrence away from the example database and point it at your own contacts database.

Step 1. Copy files into correct location.

Copy fmSpark.fp7, fmSparkUtil.fp7, fmSparkData.fp7 and SampleContacts.fp7 to the same location as the database to which they are being stitched. All files should be next to each other and in the same folder as your solution. (You'll get rid of SampleContacts.fp7 eventually, but it helps to have that file there for now.) For instance, it might look like this:

Step 2. Setup fmSpark

1. Double click on fmSpark.fp7: the plugins were probably installed for you automatically, but you may need to close and re-open FileMaker for them to become active.

2. Click the Settings button the top right corner of the Welcome screen and fill in your user and email server information. You can skip this for now if you just want to play with letters instead of emails.

Step 3. Modify the CONTACTS file reference in fmSpark

In fmSpark.fp7, select Manage > External Data Sources from the File menu. (In FileMaker 8.5 this would be Define > File References...)

1. Repoint the SampleContacts data source to your database file containing contact records (names, email addresses, etc). You can rename it if you'd like.
2. Next, go to the Relationship Graph and double click on the CONTACS table occurrence, pointing it at the contacts table in your file. Make sure you keep “CONTACTS” as the name of this table occurrence, regardless of what the name of your contacts table may be.

Attach:contactgraphnew.png Δ

3. Now, double click on the relationships between CONTACTS and "_ Merge Message" making sure the right hand side of these relationships (the CONTACTS side) uses your contact table's primary key, e.g. Contact_ID, People_ID, Student_id, etc.
4. Follow the same steps for the “_CONTACTS Recipients” table occurrente: keeping its name the same, double click it and point it at your contacts file, then edit the relationship to “_Merge Batch”, making sure it uses your Contact ID on the “_CONTACTS Recipients” side.
5. Don’t worry about the Contacts Log table for now. If you wish to track all your correspondence in a portal on the contact’s record, check out our entry on “Journaling” to learn about this feature.

Step 4. Rebuild Merge Fields

Since your contacts table likely has different fields and field names than fmSpark’s sample file, the merge fields and templates in fmSpark won’t line up with your fields.

From the fmSpark menu select “Settings” and then click the “Developer” icon in the upper right of the screen. Select the “Fields and Functions” tab and then, making sure that the “CONTACTS” table is selected, click the “Rebuild” button.

This will add all of your fields as possible merge fields in fmSpark. Down the road you can search the built in documentation for “Merge Fields” to find out how to exclude fields from this list, but this quick rebuild will get you going.

Note: The templates that come with fmSpark also use the field names from the sample Contacts file. You may need to modify these after rebuilding fmSpark with your field names.

Step 5. Modify the “Manage Recipients” layout (optional)

You will need to modify the “Manage Recipients (Contact)” layout if you want to be able to deselect recipients from within fmSpark. There are five simple steps involved:

1. From the Welcome screen enter Layout Mode, toggle the status area open, and switch to the “Manage Recipients (Contacts)” layout
2. Select the field now reading <<Field Missing>> and choose Field/Control... > Setup from the Format menu. Select the appropriate name field from the list of fields in your solution. This is likely your contact’s name.
3. Select the field and choose Button Setup... from the Format menu. Click the “Specify” button and ensure the Script Parameter at the bottom is the primary key you selected in Step 3 above.
4. Next, select the field and choose Conditional... from the Format menu. Ensure the contact ID field in the “Condition” is the primary key you selected in Step 3 above. So the calc might now read: not MemberOf ( _Merge Batch::entityIDs ; _CONTACTS Recipients::My Contact ID). (Conditional formatting requires FileMaker Pro 9 or higher, so don't worry about this if you're in 8.5.)
5. Double-click on the portal to bring up the Portal Setup dialog. Click on “Specify” to change the Sort Order for the portal to one using your fields.

Step 6. Add scripts

The easiest way to get started here is to go to the SampleContacts.fp7 file and copy the four example scripts from SampleContact.fp7, and then paste them (or import them) into your own contacts database. Add the following scripts:

Open fmSpark
Create Letters Foundset
Create Emails Foundset
Create Labels Foundset

Tick off the checkbox to display these scripts in your menu.

Step 7. Edit scripts

You'll need to make a small change to each of the “Create...” scripts you just added to your file. Edit the script "Create Letters Foundset" and you'll see a comment “NOTE: change to use your primary key (ID) in the following line” shown below:

Attach:editscriptnew.png Δ

Edit the Set Variable following “NOTE” and remove the comments (the /* at the beginning of the calculation and the */ at the end). Then replace Contacts::Contact ID with the field which is the primary ID in your table: the same primary key you used in step 3 above.

Remember, you'll make this same change in each of the “Create...” scripts you brought in from Sample Contacts.

Step 8. Change Merge Group Settings.

From the fmSpark menu, select “Settings...” and then click the Developer button in the upper right, the second portal you see on the Media and Groups tab is called “Merge Groups.” There are two settings here where you’ll need to enter the name of the field you use for your contact’s full name:

Attach:mergegroup.png Δ

Remember that you kept the table occurrence names (things like “_CONTACTS Recepients”) the same in step 3 above, so you just need to change the text to the right of the “::”. Be sure to change both field names above, leaving the table occurrence name alone.

Step 9. Spark away...

1. Start with a small found set of your contact records.
2. Run one of the "Create..." scripts, remembering that you’ll likely need to edit any templates so they use your new merge fields.
3. Now, grab a nice cold drink and read the rest of this documentation!

Page URL: