Fulcrum Webhooks: Sync Records From One Form to the Other

20 October 2016 by Katrina Engelsted

This Halloween season, let us make one element of your life less spooky: webhooks! Webhooks can be pretty daunting to the average hacker. Luckily, with the correct tools, one can overcome the intimidation that webhooks may present.

Background

Webhooks can be scary; they are live data feeds that allow you to edit, create and delete records through a few lines of code. But the benefits of using webhooks are extraordinary. Webhooks have the ability to provide detailed overviews of what is occurring with data in the field. These event notifications (or HTTP callbacks) can provide vital alerts if someone has accidentally deleted values or overwritten work that was previously collected. Essentially, when data changes in Fulcrum, webhooks push those changes to your servers in real-time. They enable you to analyze and integrate your data.

If you want to learn more about the benefits of webhooks over other options I recommend you spend some time reading this guide on webhooks.

Overview

To get webhooks up and running, you need to write some code with instructions with what you want to do with the Fulcrum data. Once that is completed, you need to host the code up on the web, pop the URL of the hosted script in your Fulcrum account and then watch as the data changes come in.

These code blocks are going to set you up for exchanging data from one Fulcrum form to another (just so you can get a sense of both sides of the story – taking data out from Fulcrum and putting data back in).

Using Node.js

There are a number of languages and platforms one can use to build and host webhooks. In this example, we will use node.js and a few npm packages (libraries). This code assumes that you have set up two forms with duplicated schemas.

In this first code block, we load up libraries. Then, the payloadProcessor() function defines the payload by REST type. If the action conducted in Fulcrum is a “create record”, then the data will go to the createRecord() function and same for updateRecords() and deleteRecords() actions.

FYI the brackets {} in these code blocks indicate places where you need to insert your organization’s IDs.

The Payload

Before we review the functions that the payloads get pushed to, it is useful to understand the structure of the payload, or data that gets pulled and pushed. The Fulcrum payload is a list of field keys and values per record. The field keys are four alphanumeric digits that are assigned to each field in your form. The values are the answers in the form. To grab the values of you custom fields, you will need to go through the form_values object and then find the appropriate element key of the field:

If you ever need to test out what the payload looks like before writing a script, you can use https://requestb.in/ to view the schema of your record. RequestBin allows users to inspect and test requests made to the URL that it provides. To use this, visit the RequestBin site, click “Create A Request Bin”, grab the URL, and paste that URL in your Fulcrum webhook page.

If the payload structure confuses you, you can read more about getting started with webhooks here.

Create Record

When records are created in the original Fulcrum form, the script will push the data to the createRecord() function. This function grabs the data added to the record and then posts that data to a new form with the same schema (assuming that the forms are exact duplicates, and share the same field keys).

Update Record

The PUT and DELETE requests are a little bit more complicated than the POST. Fulcrum assigns unique IDs to each and every record. This assignment makes it impossible to match record IDs from one form to another because they have different IDs. Therefore, to edit and delete a record from one app to another, we will need to find the matching record id. We can use the query API to do that.

Adding A Field To Each Form

The way to solve this dilemma is to add a RECORDID() calculation field in the original form that gets pushed into a text field, called my_record_id. Using the query API we can create a SQL statement that grabs the record with the id that matches the my_record_id text field: "SELECT _record_id AS fulcrum_id FROM \"Table Name\" WHERE my_record_id= '" + payload.record.form_values['FULCRUM ELEMENT KEY'] + "'";`

Delete Record

This code works similarly to the PUT request. We use the query API to grab the proper record through its original ID. Then we delete the record that has the matching record ID.

Bringing it All Together

The last few lines bring all of the functions together to seamlessly pull in the payload data from Fulcrum:

You will need to host this script on a server, such as Heroku or AWS. When the script is online, you will need to place the URL of the script on your organization’s webhook link.

Now, you are able to sync records from one form to the other. That wasn’t so spooky, was it?

If you have not taken a stroll through our guides on webhooks, then I highly suggest you start today! Happy haunting!

About the author

Katrina works with clients to help make Fulcrum work with their workflows. She loves talking tech, design and maps.

comments powered by Disqus

Sign Up Today & Start Collecting Data In Just Minutes!

Start Your FREE Trial