IFORM XML POST SERVICE FOR GOOGLE DOCSOne of the great things about iFormBuilder is they support more than one way to get data out of their service and into other systems. The XML Post API is an alternative to the XML data feeds that I’ve used in my ebook examples and in articles by-and-large.

I typically prefer using iForm’s XML feeds API because it is far simpler than any other approach to get data into Google Docs, leaving you more time to focus on the bigger objectives of a reporting or integration project. However, there are times when iForm’s XML Post API should be considered such as when dealing with large and complex forms.

The XML feed approach is not ideally efficient because iForm must create a complete data document for every request and your integration process must also poll for updates on a timed interval. Luckily the ImportXML() function in Google Docs handles this for you automatically. In any case, feed requests can overtax the iForm servers.

Another issue with iForm’s XML feeds involves the latency of the reporting process. If your reporting system requires fast throughput of reports, the XML Post API is perfectly suited as a data interchange method.

Regardless of your reasons for choosing the XML Post API, this approach is exactly the opposite of the XML Feeds approach. Instead of polling iFormBuilder for the latest data submissions, the XML Post method “posts” new data submissions to a web service as soon as it receives them. This is truly the most efficient integration process for getting data out of iFormBuilder and into Google Docs.

Posting new submissions to a system such as Google Docs is achieved by configuring your iFormBuilder form with a URL for the web service that will be receiving the data submissions and a key identifying the submissions.

The catch here, of course, is that there’s no ready-made web service in Google Docs that can take your XML posts. We have to build it, and luckily all the scripting functions necessary to create a seamless integration with iForm’s XML Post API are available in GAS (Google Apps Script).

A Google Docs Web Service for XML Posts

On paper, this is an extremely simple web application. In practice, it’s pretty complex to understand and to implement and why so few Google Docs integrations are done this way. In this article, I’ve in included a link to a spreadsheet that includes a functional script and instructions for deploying an iForm-compliant web service that will retrieve, parse, and store iForm XML Post data submissions in real-time.

The web service is created in the same manner you create any scripts in Google Docs. And the script source can reside in a free-standing script document in Google Drive, or

it can be stored as an integral part of a Google Docs spreadsheet. Since the data coming in from iForm needs to be stored in a spreadsheet table (a general requirement), the example provided assumes the script is part of the spreadsheet that will contain the received data.

Installing the Example Web Services Spreadsheet and Script

If you already have a Google account, the easiest way to get your own web service set up is to make a copy of the sample iFormXMLPost spreadsheet with this link (http://goo.gl/YwjPO).

When you click it or copy the URL into your browser, it will prompt you to make a copy of the spreadsheet in your own Google Docs space. The source code will also be installed, however, it will not be configured for your own iForm app nor will it be published as a web app - both important steps before you’ll have a working solution.

Configuring the Web App Script

The requirements for creating a Google Docs integration solution using this example is to configure the script for your iForm database app, version it, publish it as a web app (service), and then configure your iForm form to call it every time a new data submission is made.

Follow these general steps.

1. With your copy of the iFormXMLPost spreadsheet open, select Tools | Script editor; this will open the script project; you’ll then see the source code in the script editor.

2. Modify the spreadsheet ID. In the browser address bar you will find the spreadsheet ID when viewing the iFormXMLPost spreadsheet. If you’re uncertain about locating this ID, this example might help:

http://spreadsheets.google.com/pub?key=pPbcejygf5gah0jNsqV-lVQ#gid=3

In bold is the identifying key of the spreadsheet. Highlight and copy only the bold portion to get the spreadsheet key.

3. The objective is to remove the example ID and replace it with your own spreadsheet ID, otherwise data sent to this web service will not be posted to your spreadsheet table. Paste over the ID in the source code with the ID you

copied in step 2 above.

4. Change the XML post key. The XML post key validates submissions from iFormBuilder. This key is created by you and used when configuring iFormBuilder to post your data to this web service.

Ideally, the key is unique and known only to you. Edit the key (inside the quotes) and jot it down so you’ll have it later when you configure iFormBuilder.

5. Map your iForm table fields into the iForm Data sheet in the spreadsheet. The spreadsheet you copied contains test data. That data got there because there is a field map in the web service script that fetches the data elements from the XML posts and drops each element into the spreadsheet’s “iForm Data” sheet.

To get started, you may want to leave the first six fields as-is; these are common fields that you’ll probably want in the integration solution. Starting with column G2, however, you’ll need to plug in actual data fields that match the field names in your own iForm data table.

You are free to make additional column mappings to accommodate the data you are collecting in your iForm app.

Now save the script changes.

6. To create a working web service, you must now publish this script as a Web App. If you’re uncertain about this, the official Google documentation on this subject is actually quite useful.

The first task is to save your latest code as a managed version. Select the File | Manage Versions option in the script editor.

7. Once the version is saved, select the Publish | Deploy As A Web App ... option also on the script editor’s menu.

This process will require that you select the latest version created in step 6 and it will also provide the opportunity to copy the web service URL. I recommend you copy it now and paste it as a comment into your script source code. You’ll need this URL when you configure the iForm XML Post for your iForm form.

Note, the URL will end with /exec. Make sure you use this URL and only this URL when configuring XML form posts in iFormBuilder. Google also provides a /dev URL that can be used to accelerate testing. However, the /dev URL is not compatible with iFormBuilder.

IMPORTANT - you must select the option to run the script as if it were using your Google account, and also by anyone, even anonymous anyones.

Also note that whenever you change the script in the web service, you must repeat steps 6 and 7 before testing again.

8. Configure your iFormBuilder form to post new submissions to your web service. This process is covered in detail at this link. The steps are simple - select the form you want to assign the XML Post behavior to in the same manner you assign users to access your form. Select the HTTP Key/Value Pair option and enter the web service URL copied in step 7 above. Also enter the XML Post Key you created in step 4 above as well as your email address for error notifications.

Your Google Docs web service is now ready to be tested.

In the iFormBuilder web interface, display and edit an existing record submission for your form. Change something in the record and save the change. In a few seconds, the same record should appear in the iForm Data sheet.