Adding Weather Data to Records with Webhooks

Introduction

When performing field data collection, it can be highly valuable to know the specific weather conditions present at the time of collection. Knowing that it was raining when field staff took a surface water sample, or that the relative humidity was unusually high during mold inspection can give more insight into the other data collected at the time.

In this guide we’ll teach you an easy way for adding weather data from a third party, the Forecast.io API, to your Fulcrum records after they’ve been synced.

Prerequisites

This guide assumes you have read and can implement the Getting Started with Node.js and Webhooks guide. The more technical steps in this post like cloning the repo and deploying to Heroku are covered in depth in that guide.

The Process

The general steps involved are:

Create your custom data collection form with some weather fields like temperature, relative humidity, general conditions, etc.
Sign up for a Forecast.io API key.
Clone the sample fulcrum-record-weather repo.
Configure the code in the repo to match your specific form, field names and API keys.
Deploy your app to Heroku (for free).
Create a Fulcrum webhook.

Create Your Form

Create a new form or update a current form, and add weather fields to be populated later. In the example below all of the weather fields are in a separate section, which could be marked as read-only or hidden to keep field staff from populating them.

Be sure to take note of the data_name property for each field you want to populate. We’ll need these later when editing the script to update the record.

Register at Forecast.io

Forecast.io provides a weather API for weather forecasts and for historical weather, which is what we’ll use for finding weather data at the time the record was created in the field. Register and take note of your API key. You’ll get a generous number of free daily API calls that will be more than enough for testing.

Clone the Sample Repo

We’ve created a sample repository with a Node.js app that, after a few configuration changes, can be deployed and put to use quickly - https://github.com/fulcrumapp/fulcrum-record-weather. Once you’ve cloned the repo to a locally editable copy, you’re ready to make the necessary configuration changes to reference your Fulcrum app.

Configure the Code

All of the webhook processing code in the repo is in a single file, index.js. The configuration changes you’ll need to make start around line 11.

The formId variable can be found in the URL bar of your browser when looking at your app’s dashboard page.
You should have your forecastApiKey from when you registered in the steps above.
You can find the fulcrumApiKey by following finding your API key guide.
The number of fields in fulcrumWeatherFields will vary depending on how many weather fields you want to populate from the Forecast.io API. Each key (summary, temperature, etc.) in fulcrumWeatherFields should be a valid weather metric returned via the Forecast.io API. You can find the list of these in their documentation. Each key will need a corresponding Fulcrum field data name. This example attempts to populate 4 weather metrics, but you can have more or less. Just add or remove items from the fulcrumWeatherFields object.

var formId               = 'your_fulcrum_form_id';
var forecastApiKey       = 'your_forecastio_api_key';
var fulcrumApiKey        = 'your_fulcrum_api_key';
var fulcrumWeatherFields = {
  summary     : 'wx_summary',
  temperature : 'wx_air_temperature',
  humidity    : 'wx_relative_humidity',
  pressure    : 'wx_barometric_pressure'
};

Once you’ve made the code changes above, save and commit your changes.

Deploy your App

We’re going to deploy our app to Heroku. Detailed steps for creating and deploying your Heroku app can be found in the Getting Started with Node.js and Webhooks guide.

heroku create  
git push heroku master

After you’ve created and deployed your app, use the heroku domains domains command to find the domain name for your deployed app. It will look something like weird-words-7820.

Create the Webhook

You’ll need to create a new Fulcrum webhook that tells our server where to send record create messages. Use the heroku app name returned from heroku domains above to form your webhook url. The sample application is configured to listen for webhook requests at the /fulcrum path. With this information we can form the string we’ll enter for the url when creating the webhook - http://your_heroku_app_name.herokuapp.com/fulcrum . Enter this value for the URL when creating your new webhook.

Wrapup

If everything is configured properly your newly created Fulcrum records will now be automatically populated with weather data after they’ve been synced. If you’re not seeing results, trying executing the heroku log command to see if there are any errors in the log.

Data Events Example

Since this guide was first published we released a new feature, Data Events. For an example of how to add weather data to your records with Data Events, check out this example.