Integration
Overview
Before you add GoZync to your solution we strongly recommend you play with our sample files and see a real "zync" of data before you get to work. If at all possible do this on your iPad and FileMaker Server / Host so you can see how this will work when you're done. This will also ensure you can see your server / host from your iPad. Something you'll want to know before you needlessly tear into some scripts.
Step by step instructions for uploading and playing with the sample files can be found here Getting Started.
How this page is organized
In order to add GoZync to your solution you'll be working in both the local (the mobile) file, and in the served files that are part of GoZync. The work done on both sides of this (the served side and the local side) is very similar and involves teaching GoZync how to translate the information passed in as a document into the tables and fields of your files.
The first part of this page describes the work to be done in the hosted file (GoZyncConnector) and the second half gets into the changes to be made to your local / mobile file (Mobile.fp7 or your own file).
Which to do first: local files or served files?
You'll need to do the file that "packages" the data before you do the file that unpacks it. So if you're working on getting data from your local file, you'll get the local file straightened out first before moving to the served files (GoZyncConnector is the only served file you'll be editing).
In this documentation we assume you're leaving our mobile file alone and connecting it to your served invoicing file. So we'll work with GoZyncConnector first. If plan on making a lot of changes to our mobile file--or plan to use your own-- jump to the "In the Local File/Mobile File" section first before working in GoZyncConnector.
Note that in our demo, you can't teach GoZync about your own solution, but you can test the demo on your own server and your iPads. More here: Hosting the Demo
In GoZyncConnector
Background
GoZyncConnector is the served file your mobile/remote file will be communicating with. As part of adding GoZync to your solution you'll be teaching GoZyncConnector how to talk to the served file(s) of your solution: you'll teach it how to translate the records (the documents) sent to it from you mobile file into new or edited records in your served solution.
GoZyncConnector ships already connected to a simple served solution of our own called "Invoices". The instructions below show how to replace this connection with a connection to your own file.
The Work
1. Back Up Your Files.
Seriously. If you're doing all this on the server, download one of your server's backups and verify that you can open it without issue. If you're working locally, save a compacted copy of all the files you'll be working with.
We also strongly recommend you do this work on local files (off the server) as you'll be modifying scripts and table occurrences. Take your files down, work on them, and then load them back to your server: at least for anything that involved importing or pasting scripts, and modifying the graph. Layout work and script edits are safer to do live.
2. File References.
Add a file reference for your solution to GoZyncConnector.
if you're working locally, make sure your solution and GoZyncConnector are in the same place relative to each other as they'll be on the server. (Once you're all done you can delete references for the sample Invoice file that ships with GoZync if you won't be using it: elect to remove its occurrences from the graph as well.)
From FileMaker's menus, select File / Manage / External Data Sources... and click "New" to create a reference for your served file.
3. Edit the Relationship Graph.
In the Relationships tab of Manage Database, find "GoZync" in the section "Packing and UnPacking...". Create one table occurrence here for each table you'll be working with in GoZyn: this includes tables you're pulling down to your mobile file, and tables for which you're getting data from mobile. Preface the table occurrence name of each with "GoZync" as we did with the name "GoZyncInvoices"
Next make a relationship between each of these table occurrences and GoZync, connecting "PrimaryIDGLOB" in GoZync with the primary key field in each of your tables. If your tables don't have a primary key field, make one. =)
Make sure the right hand side of this relationship (your table's side) has "Allow creation of records in this table.." turned ON as shown below:
Repeat this with each table you want to add or edit records for in you file, prefacing each table occurrence with "GoZync".
Revisit each relationship and, in each case, make sure the right hand side of the relationship uses the primary key for that table (it's unique ID). When you're done, this section of the graph should look something like this (using our Invoices sample file as an example):
4. Edit Scripts. Field Mapping
Find the "Field Mapping..." folder inside the script folders named "GoZync Connections... / Parsing Data Into Host / Table Mapping" and edit the first script, named "Set InvoiceLines Fields".
Edit each SetField statement in this script to that it is setting the correct field in your invoices lines table, following the comments in this script for guidance. You can also look here for more tips on field mapping.
If you've left our mobile file alone, you'll already have one SetField step for each field coming from our mobile file. But if you've added field to our mobile file, or if you're using your own, you'll want to refer to the "dictionary" of the fields available to be mapped. Learn how to generate a data dictionary to help you out here: Field Mapping Tips.
Be sure to edit the Perform Script step in the section "Cleaning Up...", replacing the field used at the end of the script parameter, with your invoice lines ID field (or the primary key / unique id of the table you're working in).
If you're using your own Mobile file, these scripts may not have anything do do with invoices any more. That is fine: rename the scripts so the make sense for you, deleting the scripts you don't need, and duplicating the ones here to create one "Set XXXX Fields" script for each table you receive from your mobile file.
5. Edit Scripts. Field Mapping Contd.
Continue editing each of the field mapping scripts, deleting those you don't need and creating new ones for additional tables you may have.
When you get to the script "Set Invoice Fields" you'll see a new section in this script for splitting records: we do this when we have a record (like the invoice in our sample Mobile file) that really has two records in it: our invoice contains information that properly belongs in the customer's record. So you'll see that we leave the invoice "Set Invoice Fields" script to go make the customer's record and then return.
If your hosted file contains a separate customer (or contacts) table, you may want to do what we're doing as well and create/edit a customer record from the invoice. If not, you can create additional Set Field steps to add the customer information to the invoice itself: feel free to copy the SetField steps and Log Error script steps from the scrip "Set Customer Fields" as these are already mapped to the fields coming from your mobile file.
Again, continue editing each of the field mapping scripts, deleting those you don't need and creating new ones for additional tables you may have. Refer here for Field Mapping Tips.
6. Edit Scripts Part 2: Table Mapping.
Note that if you didn't create or delete any "Set XXXX Fields" scripts in steps 4 and 5 above you can leave this section alone: this is where we tell GoZync which of your "Set XXXX Fields" scripts to run. But if you simply edited the 4 scripts that come with GoZync, our "Table Map" script already knows about them.
The last script you have to edit is inside the folder "Table Mapping". Edit the script "Table Map" adding a "branch" for each table that has one of the "Set XXXX Fields" script steps you were just editing.
A "branch" is an IF or Else IF statement that forks this script into calling the correct Set Field script for the kind of data being worked with.
Follow the instructions within this "Table Branches" script's comments for details on how to change it.
7. Getting data down to Mobile: Layouts.
Here is where we'll tell GoZync which fields from your hosted file should be packaged into the document we sent to your mobile files. (If your mobile is only making records and doesn't need anything from the host, you can skip this section.)
This packaging is done on a "Products Field Mapping" layout in the layout folder "Outbox" (get it? records on their way out), though you can now rename that to something more relevant, like "Contacts".
There are two things you need to change on this layout: the tabs, and the fields.
Tabs.
GoZyncConnector comes with a single tab for the products table. A single tab is all you need if you're sending flat records to mobile. But if you need to send something related (like a contact and their phone numbers) you need one tab for each table in the entity: in this example the "entity" is a contact and it has two tables: contacts and phones. Read section 4 in the Mobile File half of this article for more on tabs.
Fields.
Now double click on the fields on each tab and point these to the fields you'd like included in this document when we sent it to your hosted files. Here are a few tips:
The first field (in tab order) on each tab should be the primary key of the table. The first 4 fields show up in the InBox of GoZyncConnector and should be used to identify the record (things like the contact's name, for example). Aside from that, field order doesn't matter.
If you include related data on one of your tabs, you'll want to include that in a portal as we do in our example mobile file's Invoice Field Mapping layout. on the Invoice Lines tab.
GoZync doesn't use the field labels so do what you'd like with those.
When you're done, enter browse mode and click "Validate & Export..." to create a data dictionary for this layout. This document contains customized instructions based on the fields and portals you've added to your layout: you'll refer to this when you'e editing scripts in your mobile to teach mobile how to unpack your document into new or modified records.
8. Getting data down to Mobile: Scripts.
There are two scripts to edit in GoZyncConnector to get your data down to your mobile file. Begin by editing the script "Package Up Products." You'll have one of these scripts for each entity you wish to send to your mobile file. Rename and edit "Package Up Products," following the script comments for guidance, then duplicate this for each entity you're sending to mobile.
Next edit the script "Get Records From Host ( RecordType )" following the comments in that script for instructions on how to create a "branch" in the script for each record type you're processing.
9. Test It.
If you already have a document in the InBox of GoZyncConnector you can now send it to your hosted file. (If the document has already been processed, select it anyway and hold down the shift key when you click "Process Selected Items".) If you don't have anything in your InBox, head over to your mobile file, create a new record, and upload it. Remember, you can do this in Pro so you don't have to use FMGo to test your field mappings.
Take a look at the record you've created in your file and see if the data ended up in the right place. Often you'll want to make some changes to where the data is being set, so edit your "Set XXXX Fields" scripts, re-processing your test records until the data is ending up where you like.
That's it.
In the Local / Mobile File
Background
Many people will modify our example files in order to get started with GoZync though some folks will want to add Zync to mobile files they already have. This section talks about how to do that: if you're just modifying one of our example files, you won't need to add the GoZync tables and scripts, etc but can jump right in at step 8 where we teach the file how to translate the records your created in your mobile file into (the documents) we'll send to your served solution.
Note that in our demo, you can't teach GoZync about your own solution, but you can test the demo on your own server and your iPads. More here: Hosting the Demo
The Work
1. Back Up Your Files.
Seriously. And you'll probably want to pull everything off the server and do this work locally as importing scripts from local files into hosted files is a good way to mess up your database.
You'll also be copying things from our Mobile example file, so make sure you have a nice clean copy of that file. Now place the file you're working with (what will become your new mobile file) in the Local folder of GoZync on your desktop, beside Mobile.fp7.
2. Add a Custom Function.
Our mobile example file contains one custom function you'll want to add to your mobile file. Select Manage / Custom Functions from FileMaker's File menu and copy the function "zyncVariable". Select the same menus in your mobile file and past the function in: you don't have to modify it at all.
Note that moving custom functions requires FileMaker Advanced. If you don't have a copy of Advanced you'll have trouble with a number of steps that follow as well. Please get in touch and we'll get you a quote for moving all of this into your mobile file.
3. Import Tables.
Copy the tables "GoZync" and "Interface" from our mobile file and paste them into yours. If you already have a table named "Interface" please rename yours before pasting ours in. If you already have a table named GoZync, well then you must be Todd Geist ;-)
When you pasted in those tables a blank layout was created for each one. Visit each of these and import the data from the same table in our sample mobile file. (Or do all this in one step by importing these two table from our sample mobile file into yours.)
3.1 Relationship Graph.
Create a Table Occurrence for each local table you want to send up to your hosted file, prefacing each table occurrence with "GoZync" similar to the example mobile file e.g. GoZyncInvoices, GoZyncInvoiceLines, etc. Wire these together only as much as the natural relationships between them warrants. For example, we connect GoZyncInvoices to GoZyncInvoice lines in our example file. Where the actual relationships in the lower half of the graph are a little more complicated. This "GoZync" graph should be nice and simple.
Make sure all these relationships between your tables have Allow Creation of Related Records turned "on" for the child side of the relationship: in our example this is on the GoZyncInvoiceLines side and the GoZyncInvoicePhotos side. (We don't use this to create records, but we need this on so we can "walk" into these portals and grab their field names.)
Create a relationship between your recently created GoZync table in your mobile file and each new table occurrence. The left hand side of your relationship should be GoZync::PrimaryIDGLOB and the right hand side YourNewTableOccurrence::PrimaryID as shown in the highlighted table occurrences here:
Ensure Allow Creation of Records in this table via this relationship is checked on the right hand side of the relationship (the your table's side).
Note that if you were modifying our mobile file, you'd double click on the Table Occurrences in the section "Packing and UnPacking" which are related to GoZync. For example,double click on "GoZyncInvoice" and now click where it says "data source" and select the any other table in your mobile file which you'd like to Zync, pasting the prefix "GoZync" back in there in front of your table name before you click OK. Next double click on the line between GoZyncInvoice and GoZync, make sure the right hand side of this relationship (the GoZyncInvoice side) uses the primary key (probably the invoice ID) from your table.
Repeat this for each table you want to send to (or get from) your hosted file, prefacing each table occurrence with "GoZync".
Revisit each relationship and, in each case, make sure the right hand side of the relationship uses the primary key for that table (it's unique ID).
3.2 One More Relationship.
Add one more Table Occurrence to your graph; from the file GoZyncConnector.fp7, add an instance of Inbox named "GoZyncInbox". To do this you'll make a new External Data source for
GoZyncConnector: from FileMaker's File menus select Manage / External Data Sources...
While you're at it, make a reference GoZync.fp7 as well. Name that reference "GoZync" and name the other "GoZyncConnector". Use these names even if you plan to rename these files later.
Now return to the relationship graph create a relationship between GoZyncInbox and GoZync in your mobile file where GoZync::NewDocumentID in the new mobile file and GoZyncInbox::InboxID.
This relationship must have Allow Creation of Records turned on for the GoZyncInbox side of the relationship.
4. Layouts Part 1: blank layouts.
Return to the two layouts created above. Leave the one named Interface alone, and head over to the one named GoZync. Name this layout "New File Prep", delete everything on it, and then duplicate it; name this newly created one "GoZync Packing-UnPacking" (make sure you get the name exactly right). Now duplicate this one and name the new one "Transition".
Duplicate the transition layout and name it "Progress".
Now create one new blank layout called "Invoice Field Mapping" and base it on the table occurrence for the main entity you're sending up to your hosted solution. This is the occurrence created in 3.1 and it's name begins GoZync. For example, if you were sending contacts up, you'd base this layout on your GoZyncContacts table occurrence created in 3.1 above. You can have many of these field mapping layouts, but focus on one entity for now to get this working. Then you can come back here and add additional field mapping layouts.
We'll change the name of that layout on step 7 below. And don't put anything on these layouts yet: we'll come back to that in step 7 as well.
Back up your mobile file now that you've gotten all this done, and feel free to back it up frequently, never deleting a previous backup, as you move through the steps below.
5. Fields
Copy two fields form the Invoices table of our mobile sample file...
zync_Uploaded
zync_UploadTimestamp
...and paste them into the main table you'll be sending to your hosted files. In this article's example, this table is called "Contacts".
6. Scripts Part 1
From the FileMaker menu in our mobile file select "Scripts" and then "Manage Scripts"; you'll see three top level script folder:
Scripts Specific to the Local File...
GoZync Core
GoZync Connections -- Edit these scripts as necessary --
Copy the last two folders and paste them into your mobile file. In GoZync Core / House Keeping you'll se a script called SetUp. Depending on how your mobile / local file is set up, this script may or may not apply to you. This script manages the resizing of layouts and checks for the records our example file needs for its virtual list. If you think these scripts would make sense in your solution, also add the following scripts to your file from the folder "Scripts Specific to the Local File"...
Simulate Rotate to Horizontal
Simulate Rotate to Vertical
Recreate Portal Row Records
... and then repair the script "Setup" by pointing it to these scripts as it does in our example file.
If you don't need these things in your mobile file, just delete the Perform Script <missing> lines from the "Setup" script in your file. If your file has a start up script, be sure to add a step to call this script "Setup" from yours; if you don't have a start up script, make "Setup" your startup script.
Now edit the script "Where Is My Home Layout" changing the first line to what you consider to be the main layout of your solution.
7. Layouts Part 2: layout contents.
Now that your scripts are in place, you can paste in the contents of the 5 layouts you created in step 4 above. Visit each layout in turn, copying all the layout content from the same layout in our mobile file and adding it to yours. You can delete things like the Home and Back buttons in some of these headers unless you have your own navigation scripts you'd like to hook them to.
When you get to the layout "Transition", be sure to give it a fill color in the body as we've done in our file.
The most important layout, of course is "Invoice Field Mapping" there is where you'll be doing the rest of the work to hook this up. Probably want to make another backup copy of the file now.
8. Field Mapping.
Here is where we'll tell GoZync which fields from your mobile file should be packaged into the document we sent to your hosted files. This is done on the "Invoice Field Mapping" layout, though you can now rename that to something more relevant, like "Contact Field Mapping" in this example.
There are two things you need to change on this layout: the tabs, and the fields.
Tabs.
Our sample mobile file comes with three tabs, one for each related table we need to include in our document. Add or remove tabs to represent the tables related to your primary entity (contacts in this example). So if you have a related table of notes, you may create a tab for notes. Delete any tabs you don't need: you'll have at least one (contacts in this example).
Now revisit each tab and give it an object name like "Tab1". If you haven't created object names before, you do this in the Inspector:
- Note that these tabs can be the only named objects on the layout.Fields.Now double click on the (currently blank) fields on each tab and point these to the fields you'd like included in this document when we sent it to your hosted files. Here are a few tips:The first field (in tab order) on each tab should be the primary key of the table. The first 4 fields show up in the InBox of GoZyncConnector and should be used to identify the record (things like the contact's name, for example). Aside from that, field order doesn't matter.If you include related data on one of your tabs, you'll want to include that in a portal as we do in our example file on the Invoice Lines tab.GoZync doesn't use the field labels so do what you'd like with those.When you're done, enter browse mode and click "Validate & Export..." to create a data dictionary for this layout. This document contains customized instructions based on the fields and portals you've added to your layout: you'll refer to this when you'e working in GoZyncConnector as you edit the scripts teach Connector how to unpack your document.
9. Scripts Part 2: Pull from Host
If you're not pulling data down from your host you can skip this section.
Field Mapping.
Inside the script folder Pull from Host, you'll find a folder called Field Mapping inside a folder named Table Mapping. We'll work with the Field Mapping scripts first. Here you'll find one "Set XXX Fields..." script for each table (not each entity) for which you pull data down from the host. This script moves the data from the host into the correct fields. Edit this script following the comments inside the script and using your data dictionary for reference. You can also find help here: field mapping.
In our sample file we only pull down items for sale so you'll see a single script "Set Item Fields ( $data ). Duplicate and modify this if you're pulling data down for additional tables.
Table Map.
Find the script called "Table Map" and add "branches" as described in the script's comments. These branches call one of the field mapping scripts (the "Set XXX Fields.." scripts) you worked on above.
Pull... Scripts.
Inside the Pull from Host folder you'll see two scripts beginning "Pull..." the second one looks like this in our sample file "Pull from 'Products' into Local 'Items'". This is the script you'll edit first and you'll duplicate this script to create one for each entity (not each table) you're pulling down from server. In our example file we're only pulling Items down, so you'll see only the one script. Edit this script, following the comments as you go.
Now move on to the script "Pull Records From Host". Find the comment "Begin Editing" and add one Perform Script step for each of the "Pull..." scripts you worked on above. You may want to create duplicates of this script so you can pull different data sets down at differrent times, sometimes getting all your entities down, other times getting down just others, but you can come back and do that later.
10. Scripts Part 3: Push to Host
Almost done. Now we can edit the scripts which actually move our data up to the server. These scripts are in the GoZyncConnections folder of scripts, in the Push to Host folder. Inside that Push... folder you'll have one folder for each entity you're sending up. In our sample file we only send up Invoices, so you'll see a folder called "Invoices".
You'll modify the contents of this "Invoices" folder and then duplicate it for each additional entity in your mobile file. (If you're only sending up invoices from our mobile file, read through this but you may not need to modify anything.)
Each entity (Invoices in our example) requires three scripts and you'll make small changes to each of these three scripts by following the comments in each of the following scripts (when you duplicate the Invoices folder, replace "invoices" in the script names below with your own entity name):
Upload All Invoices To Server
Upload One Invoice To Server
Prep One Invoice for the Server
In the two "Upload..." scripts you'll edit a few lines at the beginning of each script AND a Perform Script line toward the end. The "Prep..." script has a single line you need to edit.
12. Scripts Part 4: Misc Configurations
Open the script folder "Edit Some Configurations Here" and edit each of the scripts within it (and those inside any subfolders), following the comments in the scripts for instructions. These are simpler than the scripts you've edited so far, but are still important.
13. Cleaning Up and Testing
At this point you're pretty much done and just need to tidy up a few things before you can move on to testing this and then teaching GoZyncConnector how to unpack your document into records in your hosted file.
File References.
You'll need to change the file references to the hosted versions of you GoZync files. The External Data Sources you created in 3.2 above were likely to instances of GoZync and GoZyncConnector on you local machine: you'll need to teach your mobile file how to find the hosted versions of these files.
From FileMaker's menus, select File / Manage / External Data Sources... and you'll see two file references, one for GoZyncConnectpor and one for GoZync. Edit both of these and you'll add a second line: the first line contains a reference to the local version of the GoZync files in your "Host" folder. Edit the second line of each file reference should point to the hosted versions of these files on your server. You can see an example of this in the External Data Sources of our mobile example file. You'll be replacing "yourserver.com" with the name or IP address of your FileMaker Server or host.
Remember to edit both the External Data Sources in Mobile: the ones for Connector and for GoZync.
Upload Button.
You'll need some way to run the scripts which will upload your data to the server, so create an upload button on one of your layouts and tell it to run the script "Upload One Record to Server". There is a also a script called "Upload Found Set To Server" if you're feeling ambitious.
You'll also want to edit these two scripts as they contain references to the word "invoice" and to the "sent" field you added to your table. Point the If statements in each script at your sent field (the one in contacts in this example).
That's it. You're ready for testing. Enter browse mode, make some records and then click your new upload button. You'll see a record for each document you sent in the InBox of GoZyncConnector. Eventually you'll want to read some of our additional notes about refining the behavior of your mobile file.
