GoZync

Pulling Records Down To Go

Overview.

GoZync can bring records down from your server/host in addition to pushing data up.

If you have just a single table to bring down you can modify the items example in our sample code: that example brings items for sale down to the mobile device so they can be sold on invoices. This table is already set up in our example code. However, even if you're just modifying this one table, reading over the following notes will give you a good sense of how the whole process works and what you'll be modifying.

Parallelism.

Remember that the process for pulling records down is very parallel to sending records: so on your hosted file you'll have a field mapping layout in outbox and on the mobile file you'll have a field mapping script to set the fields in Mobile with the data received.

When sending records this is reversed: the outbox layout is in mobile and the script setting fields is in Connector. If that doesn't make sense, don't worry. The notes below will walk you through it.

This example.

Pulling tasks down to the mobile device.

In this example we'll be using a table of "Tasks" in your served/hosted file and pulling this down to the local file so tasks can be marked done. We'll assume your task table already exists in your served/hosted file, but doesn't yet exist in the file on the mobile device. Further, we assume you're either working with our mobile example file (Mobile.fp7) or have added our code to your mobile file; that is, you've integrated GoZync.

Preparing to work.

Grab a copy of your Mobile file and open it in FileMaker Pro. If you've already added file references for your hosted versions of GoZyncConnector.fp7, you can continue to use those: open GoZyncConnector.fp7 from your host/server. Open your hosted solution from your server/host as well.

If you haven't deployed yet, open Mobile.fp7 from inside the Local folder it came in: then open GoZyncConnector.fp7 from within the Hosts folder beside Local. Place a copy of your solution inside the Host folder and open it as well.

At this point you should have Mobile.fp7 (or your mobile file), GoZyncConnector.fp7 and your solution open.

Packaging your data

In GoZyncConnector: Relationships

Open the relationship graph in GoZyncConnector.fp7 and add a new table occurrence for the tasks table in your solution. Preface the table occurrence name with "GoZync" so that it is named "GoZyncTasks".

Now, make a relationship between GoZync and GoZyncTasks so that GoZync::PrimaryIDGlob = GoZyncTasks::TaskID where "TaskID" is the primary key (unique ID) in your table. Make sure the GoZyncTasks side of this relationship has "Allow creation of records..." turned on.

In GoZyncConnector: Layout

Find the Products layout in GoZyncConnector.fp7 and duplicate it. In Layout Setup, name this layout "Tasks" and switch it to show records from "GoZyncTasks". For clarity's sake, move this into the Outbox folder in GoZyncConnector.fp7.

Now edit this layout, making the following changes:

Change the headline of the layout to "Mapping Layout: Tasks"

Double click on the tab control and change the name of the tab to "Tasks".

With the tab control still selected, change the object name of the tab in the inspector to "tasks" this is the first field on the Position tab of the inspector).

Replace the fields shown on the layout with the fields from Tasks that you'd like brought down to Mobile. Remember you don't need to bring down all the fields, but any fields you add to this layout will be brought down. For clarity's sake, make sure the first field (in tab order) is the unique ID from your table. Make sure that none of these fields have object names or script triggers on them.

In GoZyncConnector: Scripts

In GoZyncConnector.fp7, open the folder of scripts named "Geting Data Down To Mobile". Duplicate the script "Package up Products" and name the newly created script "Package Up Tasks".

Edit the script "Package Up Tasks" and make the following changes:

Change the GoToLayout step at the start of the script to use your Tasks layout from the GoZyncTasks table occurrence.

If you want to bring down a separate found set for each user you can return and do that later, but for now just leave the "Show All Records" step there. Return here once you have this working with all records: Downloading Found Sets. For example, you may want to only find "undone" tasks, or better yet, "undone tasks for the logged in user" but again, you can return here and add this refinement once you have the basics up and running.

Now edit the script "Get Records From Server ( RecordType )" and make the following changes:

Find the comment "------------- Add branches following the comments below ------------- " and the first "Else If.." step below it. Change this Else test to be...

$RecordType = "Tasks"

...where "Tasks" is the object name you assigned to the tasks tab on the Tasks layout in the "GoZyncConnector: Layout" section above.

Then, after the next comment "Call the correct "Package..." script for this table." following your Else If.. statement, change the Perform Script step to call the scrip "Package Up Tasks" you edited above.

That's it in GoZyncConnector.

Unpacking your data

In Mobile: Adding the Tasks table and layout

Create a new table for tasks in your mobile file. This doesn't have to have the same table name or field names as in your sever file, but it can. Create a new layout for working with these tasks in your mobile file: you can refine this later, but for now just make a straight froward layout so you can see your data.

In Mobile: Relationships

Open the relationship graph in Mobile.fp7 and find the new table occurrence for the tasks table in Mobile: one will have been created for you automatically when you made your table, and that is the one you should use for your data entry layout in Mobile. So find this new occurrence of "tasks" on the graph and rename it, prefacing the table occurrence name with "GoZync" so that it is named "GoZyncMobileTasks".

(The "Mobile" in this name is just for clarity: remember this is the tasks table IN mobile.fp7)

Now, make a relationship between GoZync and GoZyncMobileTasks so that GoZync::PrimaryIDGlob = GoZyncMobileTasks::MobileTaskID where "MobileTaskID" is the primary key (unique ID) in the tasks table on Mobile. Make sure the GoZyncMobileTasks side of this relationship has "Allow creation of records..." turned on.

In Mobile: Scripts

Note that in what follows you may want to refer to the data dictionary you can print by clicking "Validate..." at the bottom of the layout you created in GoZyncConnector above.

In Mobile.fp7, open the folder of scripts named "Field Mapping: Items". Duplicate that folder and the script within it: "Item Set Fields". Name the folder "Field Mapping: Tasks" and name the newly created script "Task Set Fields".

Edit the script "Task Set Fields" and make the following changes:

After the comment "Editing Records or Making New Ones?" set into GoZync::PrimaryIDGlob the primary key of your task table if you wish to edit existing task records in mobile. In this example we will be editing existing tasks if there are any, so we're going to set this to...

zyncVariable ( "TaskID" )

...where "TaskID" is the unique ID of the task record in your file: you can get the exact spelling of this field from the data dictionary.

After the comment "Begin editing your setting fields below" you'll see several Set Field statements, replace each one with the field and variable name needed to set the fields in your Mobile task record with their equivalent from your served file. These names may be very similar, but we've prefaced the field names in Mobile.fp7 with "mobile" in this example to keep things clear. So for example where our script used to say...

Set Field [GoZyncItem::_id; zyncVariable ( "Product ID")

...right after the comment "Error trap the first set field to make sure the record is editable", we switched that to read:

Set Field [GoZyncMobileTasks::MobileTaskName; zyncVariable ( "TaskName")

Do this with each of the other Set Field statements in this script, adding new Set Field pairs if you need them. Remember to follow each with that same Perform Script step calking our "Log Error..." script.

Note that your may not want to add Set Field steps for every field in your table. For example, we may want someone to be able to pull down a revised task description from the server even if they have marked the task "done". So we won't write the "done"-ness from the server and won't create a SetField step for that field. On the other hand, we may want to erase the "done"-ness of that task in some cases, so you can see that this is a place where the unique business logic of your situation can find expression.

In Mobile: Scripts, Part 2

Now edit the script "Table Branches" and find the comment "Add branches following the comments below". You'll see an Else If statement following that comment that currently reads...

$$gz_SourceTable = "AnotherTable"

...change this to read...

$$gz_SourceTable = "Tasks"

...as instructed in your data dictionary. Make sure the script parameter passed to this script is $data as it is in the earlier Perform Script step in this script.

Next, in the Perform Script step that follows, call the script "Task Set Fields" created above.

Continuing in Mobile, find the script "Get Products from Server" and duplicate it, renaming it to "Get Tasks from Server". Find the comment "Pass to GoZyncConnector the name of the source table you want to retrieve" and replace the parameter in the next line with "Tasks" where "Tasks" is one of the possible branches in the script "Get Records From Server ( RecordType )" in GoZyncConnector.fp7 (i.e. the line $RecordType = "Tasks" exists in that script).

Continue in "Get Tasks from Server" finding the comment "Delete any local records from the table if necessary". In the next three lines you can decide what to do with tasks that are already in the mobile file. You may wish to delete them--as the lines are currently written--or to leave them alone. In our example we'll leave the existing records there because we want to update them: so we'll leave the GoToLayout line, changing it to go to our Tasks layout, and delete the Show all and Delete All lines.

Note that if you're mapping this data to be posted back to the server, our instructions will have you create a field here to note that the item was sent back. You could return here and amend this to delete any records that have been sent.

Finally, find the comment "Perform any interface cleanup you need to in order to show the records just retrieved." and add any lines you may need to do to make your task layout look good after the script has run, the most common use case here is to bring a certain tab forward, but you can return to this later to polish up the behavior here after you have this working.

There is just one more script to edit in Mobile.fp7.

Edit the script "Get Records From Server ( RecordType )" in Movile.fp7 and find the comment "Add a new branch...". An Else if statement follows: replace "SomeOtherType" with "Tasks" so this reads:

$RecordType = "Tasks"

You'll have done something very similar in the script "Table Branches, so this should seem familiar. In the next Perform Script step, call the script "Get Tasks from Server."

That's it for editing scripts.

Testing Your Work

Run your script from Mobile.fp7

If you haven't done so yet, make a few Task records in your hosted solution.

Open Mobile.fp7 in FileMaker pro and go to the layout you made in the first if the "In Mobile" scripts above. Now create a button on this layout that runs the script "Get Records From Server ( Record Type )" from the file Mobile.fp7 with the script parameter "Tasks".

Enter browse mode and click your button.

If you didn't mistype any names you should see task records in your mobile file: Congratulations! You can now work on making this task layout sexy or follow our integration instructions to learn how to post edited tasks back to your served / hosted files. (Note that our instructions take "invoices" as an example, but you can follow the same instructions for tasks.)

If you don't see new records, one if a few things happened...

Troubleshooting

If you didn't see an error message it is likely that your button on tasks is trying to call the "Get Records From Server..." script n Connector instead of Mobile: the button should call the one in Mobile.

If you did get an error and it told you one of the Set Field steps had a problem, that error is probably accurate: edit the script and Set Field step mentioned in the error.