Using Google Calendar with the Formstack API

Written by Ade Olonoh on September 7, 2007

Posted in Form Hacks

This is the last of three Google mashup articles this week for programmers who want to explore the new Formstack API. If you haven’t seen them yet, take a look at the Google Maps mashup and the Google Spreadsheets mashup.

This one will take data submitted on a Formstack form and create new events in Google Calendar. This might be helpful if you want to use your calendar to track registrations for a workshop series, or if your customers are submitting requests to schedule service. Once integration is setup, new events can appear on the calendar soon after a form is submitted. You can also extend the example so events aren’t created as soon as the form is submitted — you can create a hidden date/time field on your form that is for administrative use only, and have events created only when that field has been set.

cal1.png

Feel free to download the example PHP code and follow along. The example code uses the Zend Framework PHP Client Library to access the Google Calendar API. You will need to download the Zend framework in order to use this.

To get started you’ll need to have a form with at least one date field that contains the event start time. You’ll also need to create a Formstack API key that has data access to your form.

In this example we have a date field labeled “Start Time”, another labeled “End Time” and a text field labeled “Event Title”. We’ll map these to the appropriate values when creating a calendar event. More information about all the event attributes can be found in the Google Calendar API documentation.

The script starts by getting a list of fields on the form, looking for the fields we need to create the event, then mapping the field id to the event attribute.

$field_labels = array(
    'title' => 'Event Title',
    'start' => 'Start Time',
    'end'   => 'End Time',
);
 
// Get information on the Formstack form
$form = Formstack::request($api_key, 'form', array( 'id' => $form_id ));
 
// Get form field ids for the title, start and end fields
$fields = array();
foreach ($form['fields'] as $field) {
    foreach ($field_labels as $key => $label) {
        if ($field['label'] == $label) {
            $fields[$field['id']] = $key;
        }
    }
}

Now we can start searching submitted data and creating events. As with yesterday’s example, the assumption is made that this script will be scheduled to run in cron on a regular basis. We’ll need some mechanism to make sure that we don’t create new events for old submissions. For the sake of simplicity, in the example we do that by downloading the prior day’s worth of submissions and assume that the script will only run once a day. The min_time and max_time parameters (which search against the submission date and time for each record) can easily be changed to do this on an hourly basis, or we can locally store the unique id of the last submission so the script isn’t tied to the date and time it’s run.

When downloading the submitted data only a pre-defined number of results (25 by default) are returned at each time, and we’ll need to make multiple requests to the API to download each “page” of results.

// Loop through each page, making one query per page of data
$pages = 1;
while ($parameters['page'] <= $pages) {
 
    // Get submitted data
    $data = Formstack::request($api_key, 'data', $parameters);
 
    // Update the number of pages
    $pages = $data['pages'];
 
    // Iterate over each entry
    foreach ($data['submissions'] as $submission) {
 
        // ....
    }
 
    // Increment the page # for the next request
    $parameters['page']++;
}

Within the submission loop, we create a new event for each form submission, then add that to the calendar using the Zend library.

// Iterate over each data item to get the event information
$event = array();
foreach ($submission['data'] as $item) {
    if (isset($fields[$item['field']])) {
        $field = $fields[$item['field']];
        $event[$field] = $item['value'];
    }
}
 
// Create a new calendar event
$newEvent = $gdataCal->newEventEntry();
$newEvent->title = $gdataCal->newTitle($event['title']);
$when = $gdataCal->newWhen();
$when->startTime = date3339($event['start']);
$when->endTime = date3339($event['end']);
$newEvent->when = array($when);
 
// Add the event to the calendar
$createdEvent = $gdataCal->insertEvent($newEvent);

You’ll need to refresh your calendar to view new events, and can edit them just like you would any other ones.

That’s it for our series on Formstack-Google mashups. Feel free to comment below if you have any questions, ideas for mashups you’d like to see, or links to ones that you’ve built yourself.