Integration
Overview
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.
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 done you can delete references for the sample Invoice file that ships with GoZync if you won't be using it.)
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.
Double clicking on the Table Occurrences in the section "Packing and UnPacking" which are related to GoZync. For example,double click on "GoZyncInvoice" and copy the name (GoZyncInvoice) to your clipboard, now click where it says "data source" and select the invoices table in your file, pasting the name "GoZyncInvoice" back in there 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 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).
4. Edit Scripts. Field Mapping
Find the "Field Mapping..." folder inside the folder named "GoZync Connections..." 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: you want to find the field that most closely matches the contents of the variable in the SetField step.
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 need a "dictionary" of the fields available to be mapped. Learn how to generate a 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).
For help with field mapping, read mode here: Field Mapping Tips.
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. Table Configuration.
Note that is you didn't create or delete any "Set XXXX Fields" scripts in steps 4 and 5 above you can leave this section along: 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 Branches" script already knows about them.
The last script you have to edit is inside the folder "Table Configuration". Edit the script "Table Branches" 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. 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 to your hosted file, prefacing each table occurrence with "GoZync" similar to the example mobile file e.g. GoZyncInvoices.
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
Ensure Allow Creation of Records in this table via this relationship is checked.
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, add an instance of Inbox named "GoZyncInbox". Now 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 Checked.
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 primary table occurrence whose data you'd like to send to your hosted files. For example, if you were sending contacts up, you'd base this layout on your contacts table occurrence.
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
From the FileMaker menu in our mobile file select "Scripts" and then "Manage Scripts"; you'll see three top level script folder:
GoZync Core
GoZync Connections -- Edit these scripts as necessary --
Scripts Specific to the Local File...
Copy the first two folders and paste them into your mobile file.
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: this is the name we'll use to refer to this "table" when we unpack the document in GoZyncConnector. (As described in step 6 in the Connector instructions at the top of this page.)
In our example, the "tables" we're dealing with are Contacts and Notes, so those should be your tab's object names. Note that object names are different from the tab's display name. In the screen shot below, "Some Name" is the display name, but "Contacts" is the object name we care about:
- Note that these tabs can be the only named objects on the layout. And these object names should be unique among the files you're processing in GoZyncConnector. So if you have one mobile file sending the object names "invoices" and "customers", you'll want to use something besides "customer" in your second mobile file (we're using "contacts" in this example).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 is the document you'll use in GoZyncConnector when you edit the scripts teach it how to unpack your document.
9. 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.
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 see each is two lines long: 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 to point to the hosted versions of these files on your server, 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.
