Workflow
There is a lot of flexibility in how you interact with Fizz, but typically it is used to sync the data between Coolfront Mobile and an external system. This synchronization usually occurs on a regular interval (e.g. once per hour), and we recommend using the following workflow. It will make your life easier, and it will give the user the best experience.
If you are using Fizz to fetch or update data in "real time", you won't need to use this workflow for those on-demand transactions. However, you will want to have a separate process that does a full sync (as described below). Otherwise the data in your system and the data in Coolfront Mobile will start to drift apart as it is modified by other people and systems.
Step #1: Get the Last Sync
Before starting a new sync it is best to grab the most recent sync and check to see when it ran, and to make sure that it isn't still running. You may not need to do this if you are keeping track of the state of each sync locally, but it is especially important if your sync is initiated by a scheduled task (or cron job), since the the previous sync may still be running.
So, using a reverse sort on the created-at field, let's grab the latest sync and check the in-progress flag:
GET /fizz/syncs.xml?token=TOKEN&page=1&sort=-created-atThe first one (with an id of 7) is the most recent sync:
<syncs> <sync> <id>7</id> <in-progress>false</in-progress> <issues></issues> <log></log> <percent-complete>100</percent-complete> <created-at>2011-04-11T01:18:25Z</created-at> <updated-at>2011-04-11T01:22:51Z</updated-at> </sync> <sync> ... </sync> </syncs>The in-progress value was false, so we can safely start a new sync. If the in-progress value had been true, we would stop and try again later. This last sync (with an id of 7) was created at 2011-04-11T01:18:25Z, so this will be the timestamp we will use when searching for updated data.
If the response had been an empty (<syncs/>
), then we
know that this is the first sync, and we update all the data in both systems.
Step #2: Create a Sync Object
The Sync object (see API reference for details), represents an attempt to update Coolfront Mobile and another system so they both have the most recent data. Getting the data updated in both systems will take a series of Fizz requests, so the Sync object is a way to capture the high-level status of those transactions to make it clear to the user what is happening.
Let's create a new sync object:
#POST this to /fizz/syncs.xml?token=TOKEN <sync> <percent-complete>0</percent-complete> </sync>
Fizz will respond with the xml for the newly created sync, and we'll grab the id (8) so we can update the sync object as we go.
Step #3: Pull Data from Coolfront Mobile
Next we want to start pulling data from Coolfront Mobile. Let's start with the customers.
We only need to get the data that has been updated in Coolfront Mobile since our last sync, so we'll use the created-at date from the last sync to filter the data to only include customers that have been updated since then.
All dates and times in Fizz are in UTC. If your system does not store its dates in UTC, make sure that you convert all of the dates and times when: filtering, reading, or updating data. Also, if you store your data using the local timezone, make sure that you account for daylight saving time during your conversions.
GET /fizz/customers.xml?token=TOKEN&page=1&since=2011-04-11T01:18:25Z
If that request comes back with less than 10 customers, then we are done. If not, then we need to make the same request, but with the page parameter of 2:
GET /fizz/customers.xml?page=2&token=TOKEN&since=2011-04-11T01:18:25Z
Then after you have the customers, you would make similar requests for any of the other data that your system needs, like: invoices, and addresses.
You can take all those records and update them in your system. If the record has a fizzid, then you can use that fizzid to match the record from Coolfront Mobile to the existing record in your system. If there is no fizzid, it is a new record and you need to:
- create a new record in your system
- insert the data from the record pulled from Coolfront Mobile
- generate a fizzid (if the system doesn't generate a stable id for you)
- update the record on Coolfront Mobile to give it the new fizzid
As you are updating the data in your system don't forget to update the sync object to give the current percent-complete. Updating the sync object is important for two reasons: it gives the user an indication of the progress, and it prevents Coolfront Mobile from assuming that the Sync has stalled.
Since the pull is only half of the sync process, this will only account for 50% of the completion. You can use a formula like this to calculate the completion:
completion = (recordNumber * 100 / totalRecordCount) / 2
If you are on the 10th record of 20, you are 50% done with pulling data from Coolfront Mobile, but you are only 25% complete with the entire sync. So, you would get this:
completion = (10 * 100 / 20) / 2 completion = 25Then you can update the sync status by doing a PUT request to
/fizz/syncs/8.xml&token=TOKEN
with this XML:
<sync> <percent-complete>25</percent-complete> </sync>
You could also update the issues or log on the sync, but you can wait until the end of the sync (step #5) to do this instead.
Step #4: Push Data to Coolfront Mobile
Now you can grab all the data that has been recently updated in your system, and push the data up into Coolfront Mobile. Each update will require two requests, one to fetch the current record data (to get the id), and the second request to update the record.
GET /fizz/customers.xml?token=TOKEN&page=1&fizzid=UNIQUE-ID # response is... <?xml version="1.0" encoding="UTF-8"?> <customers> <customer> <account-number>123</account-number> <company-name></company-name> <email></email> <fizzid>UNIQUE-ID</fizzid> <first-name>John</first-name> <phone-1>5551114444</phone-1> <phone-2>5553334444</phone-2> <phone-3></phone-3> <phone-1-label>home</phone-1-label> <phone-2-label>cell</phone-2-label> <phone-3-label>work</phone-3-label> <id>74</id> <last-name>Doe</last-name> </customer> </customers>
When the response comes back, grab the id (74) and use it in the URI for the PUT request to update the data.
PUT /fizz/customers/74.xml?token=TOKEN # send the following data to update the phone number... <?xml version=\"1.0\" encoding=\"UTF-8\"?> <customer> <phone-1>5553338888</phone-1> </customer>
As you are pushing these updates, don't forget to update the sync with the percent complete -- this will help the user know how far along the sync is, and it prevent Fizz from marking the sync as stalled. This time we are on the second half of the sync so the formula is:
completion = (recordNumber * 100 / totalRecordCount) / 2 + 50
Step #5: Close the Sync
When the sync is complete, all that is left to do is a final update of the
sync object, so Fizz (and the user) will know that you are finished. Make a
PUT request to /fizz/syncs/8.xml&token=TOKEN
with this XML to
close it out:
<sync> <percent-complete>100</percent-complete> <issues>If needed, error/warning messages go here.</issues> <log>These logs are not visible to the user.</log> </sync>