Tips for Field Mapping Scripts
Overview
When you're editing the "Set XXXX Fields" scripts in GoZyncConnector or in your mobile file, you're mapping the data sent in a document to the real fields in your table.
We call these "Set XXXX Fields" scripts because you may have scripts called "Set Invoice Fields", "Set Customer Fields", etc.
The data you have to work with has, by this point, been unpacked into one $variable for every field name in your source table. Well not "every" field name, of course, just those included on the tabs of your source's Field Mapping layout. (If you're sending data up to your server form mobile, your source table is the table and field names in your mobile file.)
Watch a Video
Here is a short video showing how you can add a field to an existing mapping. Watch this after reading through this article and you'll see all the elements here in action: the field mapping layout, the data dictionary, and the Set Field script steps. Adding a field to a zynced file.
Set Fields
So if your mobile file has a field named "thing" on its Field Mapping layout, you'll have a variable named $thing as GoZync's scripts unpack the document in GoZyncConnector. Your job is now to make sure $thing gets sent to the right field in your solution.
You could do it like this:
Set Field [ MyTable::FirstName; $thing]
But GoZync actually does it like this...
Set Field [ MyTable::FirstName; zyncvariable ( "thing" ) ]
...so that we can trap for errors like misspelling "thing". That is why each SetField() statement in these scripts is followed by the same Perform Script line calling our Error Log script.
Thus, for every field you want to get from your mobile file, you'll have a "SetField / Perform Script Error Log:" pair of lines in your Set XXX Fields scripts in GoZyncConnector. (There are similar scripts in your mobile file to set the fields you get down from connector when pulling data into your mobile file.)
Using a Dictionary
Making your field mapping life easier
The trick to editing your Set XXXX field scripts is that you may not remember the field names in your source table, let alone spell them correctly.
So GoZync includes the ability to print a dictionary of the fields available in each document. You can get this by clicking "Validate..." at the bottom of any of your Field Mapping layouts (such as the layout "Invoice Map" in our sample Mobile file).
You can have this up while you're working on your Set XXXX Field scripts, copying and pasting variable names from the dictionary to your script. The dictionary also gives you instructions about which scripts to create and which branches to add to the script "Table Branches".
Here is an example of a data dictionary.
Tips & Tricks
"Transforming" Data
Remember that you don't have to simply send the $variable data from the mobile file into your database as is: you can perform calculations and transformation on the data in your "Set XXX Field" scripts. Here is a simple example..,
Transformations like these are one of the real strengths of GoZync in that they allow you to build mobile files that have a completely different structure from your served files. "Splitting Tables", below, is another popular transformation.
How and When to Split Records in Field Mapping
You have a a very simple mobile file with only one or two tables (something a database designer would call a fairly "flat" file), while your served solution may us many tables to represent the same data (it may be more "relational"). Go Zync provides a method for splitting the data from one table into many tables. Though this is most often done on the served side, you can split tables coming down onto the device as well.
For an example of how this works, check out the "Set Invoice Fields" script in a clean copy of GoZyncConnector. The scenario here is that our mobile file keeps the invoiced contact and their address IN the invoice table, while our sample served solution (Invoices.fp7) has a separate customer table. So you'll find a piece of GoZyncConnector's "Set Invoice Fields" script where we leave the invoice, create a customer record, and return to use the newly created customer ID in our invoice. This happens between the comment "Splitting Tables..." and "...End Splitting Tables".
Notice that we can create additional "Set XXXX Fields" scripts, for entities that don't exist in our mobile file: the Data Dictionary form our mobile file didn't mention a customers table, because the mobile file didn't have one, but we can still create a "Set Customer Fields" script in GoZyncConnector and split the invoice data into an invoice record and a related customer record.
Handling Related Records
> > Notes about saving the IDs of newly created parent records so you can make their children
Forcing Lookups
There may be times when lookup data doesn't fill in when you process records. This can happen when you're splitting records and the record (a customer, for example) hasn't been committed as FileMaker tries to lookup their information in a related record like an invoice.
This is a side effect of making all of GoZync transactional and you may want to back off this a bit, especially when it is the FileMaker-to-FileMaker communication of processing records in the InBox. "Backing off" in this case means adding a commit records script step to make sure you commit a record (like a customer) before using their information in a lookup.
To do this in any "Set XXXX Field" script, add the commit records script step right before the comment "Cleaning Up". In our customer-and-invoices example, where the customer data might not be getting looked up into the invoice, you'd add this in the "Set Customer Fields" script to commit the customer record.
Working with Photos
> > In serialize,
Am I a container field…
If it is a container
In the text, we put <attachment> attachment number </attachment> We then put these into the same repetition in inbox.
Repeating field has the container.
When unpacking
If there is <attachment> attachment number </attachment> in our document content we grab that rep from the repeytion in in box.
So as I'm building a mapping layout I do[n't need to worry about images.
It may be that what I did by hand is something we need to bring into unpack.
More
Coming Soon.
Troubleshooting Your Mapping
Common problems
Upload a single from Mobile to GoZyncConnector (you can even do this in FileMaker Pro, instead of Go) and then try to process that 1 record from the Inbox? in GoZyncConnector. If it fails, you'll see the first FIleMaker error reported right in the record's row in Inbox. Here are come common errors:
