Developer»Adding Groups Support

Adding Groups Support


Creating a new Merge Group is one way to link fmSpark to tables in your own file. You may not need to do this, however, as most integration can be handled by pointing fmSpark at your file and perhaps attaching new Table Occurrences (TOs) to the TOs already there. Read the section on LinkingToOtherTables for an overview of when creating a new merge group might be necessary.

If you know that you need to create one, the instructions below will show you how.

In this example we'll create a new Merge Group for an Invoices table so that we can send fmSpark a found set of Invoices instead of a found set of contacts; fmSpark will then use the contact information for the contact associated with each invoice we send.

1. File References. Before you begin this be sure your file is in the same relative location to fmSpark (in the same folder) as it will be when the files are deployed. Then, if you haven't yet made use of your file in fmSpark, create a new file reference ("data source" in FM9) for your file in fmSpark.fp7 by selecting "Manage External Data Sources..." from FileMaker's File menu and click "New" to create a reference to your file containing invoices.

2. Relationship Graph Changes. Open the relationship graph in fmSpark and notice how there is a CONTACTS table occurrence (TO) and a _CONTACTS Recipients TO. (You may also have one called "_Contacts LogTable") These are the instances of your data in fmSpark: you'll create one of each of these for the table you'll be sending to fmSpark in this new merge group. In our example, this will be the invoices table:

Notice how we've created one called "INVOICES" and a second called "_INVOICES Recipients". You can substitute whatever you'd like for the word "invoices" but you'll want to keep the underscore in the second TO name, and I think keeping the capitalization and syntax the same makes it easier to keep things straight.

In both TOs we've use the primary key from the Invoices table in the right hand side of our relationship and on the left hand side we've used the fields "EntityID" and "entityIDs_backup" already in use in the CONTACTS... relationships.

3. Linking Contacts to the New Merge Group. Now we need to know about the contacts associated with each invoice. If your new merge group represents "people" you won't need to perform this step, but if you new group represents something else, like invoices in our example, you'll need to teach the relationship graph about who should be contacted about a given invoice. Do this by adding a TO for your contact's table to the right of each of the new Merge Group TOs as shown below:

Note that in both cases we link to invoices using the Contact's ID and that in the case of the "..._recipients" layout we keep the leading underscore in the name.

4. Duplicate the Manage Recipients Layout. Note that when working with layouts in fmSpark you may find the menus reverting to the custom fmSpark menus we use when the file is doing its work. If that happens you'll see things like the "Layout" menu disappear. Simply use the Tools menu in FileMaker Advanced to select the "Standard FileMaker Menus" from Tools / Custom Menus and you'll be back to work.)

Duplicate the "manage recipients (CONTACTS)" layout, renaming it with the name of your new group ("Invoices" in this example).Next, double click on the portal on this layout and change the target of the portal to match the new "..._recipients" TO created in step 2 above ("_INVOICES Recipients" in our example). You'll now double click on the field in this portal and select the field which best represents your contact's name: on our example this field is in the TO "_INVOICES Recipients Contacts". You may want to add other fields to this portal: for example, if your Merge Group, like our invoices group, doesn't represent people, you may want to include some fact about the entity itself (the invoice in our example) in the portal. We've chosen to include the invoice number, but it is easiest to do this at the end of step 4 after you've already gotten the field's conditional formatting and script parameter fixed.

Continue editing this layout by right clicking on this field in the portal again and selecting "Conditional Formatting..."Change the conditional calculation for the field to include the primary key of your table:

not MemberOf ( _Merge Batch::entityIDs ; _YOUR Table::YourKeyField )

In this case "_YOUR Table::YourKeyField" above refers to the field linked to the "_Merge Batch" TO in step 2 above, not the primary field in your contact's TO which may be to the right of it.

Finally, double click on this field in the portal again and you'll see it is formatted as a button to call a script. Change the parameter of the button attached to the field to use your key field. In our example, replacing the parameter of "_CONTACTS Recipients::Contact ID" with the "_YOUR Table::YourKeyField" we just used above: _INVOICES Recipients::InvoiceID_kprime

5. In Developer Settings, Create the MergeGroup Record Select "Settings..." from the fmSpark menu and then click the "Developer" icon in the upper right to arrive at the Developer screen. Once there, create a new MergeGroup with the name that you encoded above (e.g. "Invoices" in our example). Put the layout name in, from step 4 above. And add a Tool Tip format calculation if you'd like:

7. Add records for your tables in the developer settings. Navigate to the "Fields and Functions" tab and the select the "Table List" tab. Click "New Table" in the bottom right and add entries for each of the new table occurrences you added to the graph. Be sure to enter the table name exactly as you did in the relationship graph. You won't be adding the "..._recipients" tables, just those to the right of "_Merge Message": "INVOICES" and "INVOICES Contacts" in our example. Mark these new tables as belonging to the merge group you names n step 5 above: they likely won't belong to the Contacts group in addition to the new group ("Invoices" in our example).

8. Rebuild the field list. Now switch to the "Field List" tab and click "Rebuild". You'll see that you now have access to all the fields in your newly created table occurrences hanging off CONTACTS.

9. Link One or More Templates to the New Group. Switch back to the "Settings" screen and you'll likely want to link the "Blank" templates to the new group. That way, your users at least have a blank template to select when they come in with the new group. You may also want to add additional templates specifically for the new group, but you can do that later.

Note that fmSpark determines which merge fields you can see by which Merge Groups your selected template is linked to. So linking a template to both Contacts and Invoices (for example) may make sense for a blank template, you'll want most of your templates associated with only one merge group. With templates that are only linked to Invoices so you only see the INVOICES Contacts merge fields instead of those and merge fields from CONTACTS (which wouldn't apply to records you created from Invoices). (The template's merge group is also what determines which "manage recipient" layout is used, so if you don't see the layout you expect, check to see if your template isn't linked to more than one group.)

10. Import the fmSpark Scripts Into Your File. If this new mere group is the first one to link fmSpark to your file, you'll need to add the fmSpark scripts to your file. If you already have the scripts in your file, you'll duplicate them and edit them to use the Primary Key of your new merge group instead of the ID of your contacts.

Follow steps 6 and 7 of our Integration/QuickStartGuide. In our example you'd use the field "Invoices::InvoiceID_kprime" in the Set Variable line in step 7. You'll need to further edit the three imported "Create..." scripts to indicate the new media group you've created. You'll find a statement for this near the beginning of each script, highlighted in blue below:

That's It. You can now call these newly imported scripts from your file and send mailings to found sets of invoices. Enjoy!

Going Further: Add Group Specific External API scripts There's an "encode Group ( Group* )" script that is performed in the "Open Spark ( IDList* )" script. Currently, it encodes "_app::gDefaultGroup" (a calculated Global set to "Contacts"). After duplicating, you can encode whatever you want to call your Groups -> "Students", "Parents", "Gifts", "Contacts", etc.

Journaling Your New Merge Group: Additional Changes May be Necessary You may need to modify the "create journal entry" script to accommodate the additional group(s). TOs may have to be added to support the additional journal record create.

Original source (login required):

Page URL: