Fulcrum is a hacker’s dream. If you know your way around the command line and through Javascript functions, you can automate and integrate numerous processes.
In this post, I will walk you through a way to automatically change the status value after a certain amount of time has transpired. This type of time-based workflow can be applied to other field changes as well.
Google Apps Script and the Fulcrum API are the two tools needed to set up a time trigger script. Google Apps Script is a platform that Google offers for free in Google Drive. There are numerous JavaScript functions that you can use in these scripts. Best of all, you can trigger specific functions based on time or through event listeners.
This script does two things:
1) It adds a date to the Fulcrum record when you would like the status to change. 2) It runs daily to change a record’s status value when the date that you added in the first step equals the date today. These functions will grab all new records and set them up for timed status changes. It does not work for records already collected. You will have to tweak the script to input those dates.
Let’s walk through the steps:
Prep work
1. Grab the Fulcrum API token to be able to read/write to your records. You must have a professional Fulcrum plan and be the owner of your account to access the API tokens.
2. Grab the form id (looks something like a8245687-0373-432e-98a2-b53074708ac9). It can be found on the URL of your form.
3. Add a hidden text field. This field will be used to house the date that the record status will change. You can name this whatever you prefer, such as “Timed Status Date” or “Date Status Changes”.
Setup
1. Part I: This function grabs all of the records from your Fulcrum form. Make a GET call to the Fulcrum API to grab the record’s information in JSON. Parse out the JSON.
view rawfetchRecords hosted with ❤ by GitHub
2. This is the important part! In this function, you will loop through the JSON of the Fulcrum records to find the records that have been created and/or updated today (in UTC). If a record is updated today, then we are going to add 30 days to the date and push it into the “Timed Status Date” field.
The myDateString variable grabs today’s date in Greenwich Mean Time (GMT). You can change the time zone by using the initials of the time zone. The formattedDate variable is the date that the record was updated. Since that value is a timestamp, we are using the substr() function to crop the timestamp to only the date (and not the time).
The now variable is today’s date formatted in a way so that days can be added to the variable.
function loopThrough(records){ var myDateString = Utilities.formatDate(new Date(),”GMT”, “yyyy-MM-dd”); for (var i = 0; i < records.length; i++) { var formattedDate = records[i].updated_at.substr(0, 10); var now = new Date(); if (formattedDate === myDateString) { now.setDate(now.getDate() + 30); var stringDate = Utilities.formatDate(now,”GMT”, “yyyy-MM-dd”); updateDate(records[i].id, stringDate); } if (records[i][“form_values”][“8302”] === myDateString){ updateStatus(records[i].id); } } }
view rawloopThrough hosted with ❤ by GitHub
Next, we call the updateDate() function.
3. This function goes out to the Fulcrum record and updates the empty date field with a date that the status field should change on.
function updateDate (recordID, date) { var url = “https://api.fulcrumapp.com/api/v2/records/” + recordID + “.json?token=” + fulcrumAPIkey; var options = { “method”: “GET”, “contentType”: “application/json” }; var recordJSON = UrlFetchApp.fetch(url, options); // Update record with wx info var record = JSON.parse(recordJSON); record.record.form_values[“8302”] = date.toString(); // PUT updated record to Fulcrum var url = “https://api.fulcrumapp.com/api/v2/records/” + recordID + “.json?token=”+fulcrumAPIkey; var options = { “method”: “PUT”, “contentType”: “application/json”, “payload”: JSON.stringify(record) }; var recordJSON = UrlFetchApp.fetch(url, options); }
view rawupdateDate hosted with ❤ by GitHub
4. Part II: This function GETs the status of the Fulcrum records that should have a trigger change today.
function updateStatus (recordID) { var url = “https://api.fulcrumapp.com/api/v2/records/” + recordID + “.json?token=” + fulcrumAPIkey; var options = { “method”: “GET”, “contentType”: “application/json” }; var recordJSON = UrlFetchApp.fetch(url, options); // Update record with status info var record = JSON.parse(recordJSON); record.record.status = “Needs A Re-Visit”; // PUT updated record to Fulcrum var url = “https://api.fulcrumapp.com/api/v2/records/” + recordID + “.json?token=” + fulcrumAPIkey; var options = { “method”: “PUT”, “contentType”: “application/json”, “payload”: JSON.stringify(record) }; var recordJSON = UrlFetchApp.fetch(url, options); }
view rawupdateStatus hosted with ❤ by GitHub
5. You can test out the script using Log.logger() in a similar way to console.log(). The values you test out are found in the Menu > Logs.
Deploying
1. To ensure that this script runs daily, you need to deploy the script, or publish it to the web. Head to “Publish” > “Deploy as Web App”.
2. You also need to set up your trigger. Head to “Resources” > “Current Project’s Triggers”. Click “No triggers set up. Click here to add one now.”
We want to run the first method fetchRecords() with a “day-timer” “time-driven” trigger. Also, we want this to run at the end of the workday, so that it can grab all of the new records and push in the date that will trigger the status change (in this case, “8pm to 9pm”).
3. Lastly, to get this working today, you need to run the functions so that the “Timed Status Date” works for today’s records.
One of Fulcrum’s strengths is the ability to automate tasks. If you have any questions or comments about this work flow, send a message to the Integrations team.