All Collections
Working With Data Events or Calculation fields
Data Events
Introduction to Fulcrum Data Events
Introduction to Fulcrum Data Events

A general introduction to Data Events, how they work, and what you can build with them. (Advanced)

Kat Kim avatar
Written by Kat Kim
Updated over a week ago

Data Events allow users to perform specific actions when certain events are triggered. Actions can include things like custom alerts and validation messages, setting field values, choices, labels, descriptions, requirement & visibility settings, HTTP requests and more. Event triggers include things like record loading, editing, validating, saving, value changing, and more.

This functionality enables listening for record changes, programmatically changing values, as well as building dynamic hyperlinks, writing custom quality assurance logic and much more! You can build out simple extensions or construct highly sophisticated applications with these components using standard JavaScript. Data Events essentially provide a flexible set of tools to control exactly what happens when your team collects data in Fulcrum.

As an advanced feature, Data Events are only available on the Professional Plan.

How Data Events Work

You can think of Data Events as an extension of calculation fields. While calculation fields allow you to define dynamic expressions for a particular field, data events allow you to define actions for the entire record. You have access to all the existing calculation expressions, in addition to many data event functions for building out truly custom workflows.

When building your app, you will see a “Data Events” button in the app builder setting sidebar on the right. Clicking this launches a modal window, very similar to the expression builder modal for calculated fields. This is where you define your data events for form actions.

Creating a Data Event to change the status of a record to inspected after it has been saved.

In the screenshot above, we’ve configured a data event for automatically changing the record’s status any time the record is saved. This is a very simple example but shows just how easy it is to build out custom workflows with a little bit of JavaScript. We’ve setup a listener for the save-record event, which calls the changeStatus function when the record is saved. Inside the changeStatus function, we are calling the SETSTATUS function with a status parameter of ‘inspected’.

This could easily be expanded to programmatically set the record status based on values from other fields or even filter the list of available status options based on the user or their role.

Events

We’ve exposed the following events that you can hook into while building your forms.

Record / Repeatable Events

  • load-record  / load-repeatable  - Fires when the record / repeatable editor is displayed

  • new-record  / new-repeatable - Fires when a new record / repeatable is created, after load-record  / load-repeatable 

  • edit-record  / edit-repeatable - Fires when a record / repeatable is edited, after load-record / load-repeatable 

  • save-record  / save-repeatable  - Fires immediately before a record / repeatable is saved and after it’s been validated

  • validate-record  / validate-repeatable  - Fires right before the record / repeatable is saved to check any validations

  • change-geometry  - Fires when a record’s / repeatable’s geometry changes

  • change-project  - Fires when a record’s project changes

  • change-status - Fires when a record’s status changes

Field Events

  • change  - Fires when a field’s value changes

  • click  - Fires when a hyperlink field is tapped

Media Events

  • add-photo  - Fires when a photo is added

  • add-video - Fires when a video is added

  • add-audio  - Fires when an audio clip is added

Actions

After registering an event to listen for, you’ll generally want to take some type of action. Actions typically fall into the following categories:

Display A Message

  • ALERT  - Displays a message as an alert popup

  • INVALID  - Displays a validation error message and prevent the record or repeatable item from being saved

  • PROGRESS  - Displays a non-dismissible progress message (useful when loading external data)

  • Messagebox  - Displays a message that allows the user to select an option within the message box that is being displayed.

Set Form Elements

  • SETDESCRIPTION  - Sets the description of a field

  • SETHIDDEN  - Sets the visibility of a field

  • SETLABEL  - Sets the label of a field

  • SETMAXLENGTH  - Sets the maximum length for a field

  • SETMINLENGTH  - Sets the minimum length for a field

  • SETREADONLY  - Sets a field to be read-only or editable

  • SETFORMATTRIBUTES - Set various attributes of your app, like being able to save as draft or the photo quality settings.

Set Field Values

  • SETLOCATION  - Sets the location of the record

  • SETPROJECT  - Sets the project of the record

  • SETSTATUS  - Sets the status of the record

  • SETVALUE  - Sets the value of a field

Set Field Options

  • SETCHOICEFILTER  - Filters the choices in a choice field

  • SETCHOICES  - Sets the available choices for a choice field

  • SETSTATUSFILTER  - Sets the available choices for a status field

Interact With External Services

  • OPENURL  - Opens a URL for a website or mobile app

  • REQUEST  - Performs an HTTP request and executes the callback on completion

Developer Documentation

Consult the developer documentation for the full list of available Events and Actions. There are also several Examples which demonstrate how to configure some common workflows.

Did this answer your question?