Transform & validate data

In the previous step, you performed a number of actions:

• Created a workbook with a simple schema
• Populated the workbook with a sample CSV file
• Edited the workbook using the Flatfile user interface

Each of these actions creates an EventAnatomy of an Event.... You can author code to listen and react to these events by performing tasks such as validating and transforming records, importing and joining data from other sources, and even offloading data processing to your own API.

​

Setting up a listener

Using the Flatfile SDK, you can register any javascript function as an event listener and start working with events.

Follow these steps:

1. Fork this Replit
2. Hit the Run green button or type npx flatfile@latest develop in console
3. Go back to your Flatfile Workbook and make a few changes. For example try uploading a CSV and then importing the data to the Workbook.
4. Finally return to your terminal in Replit to see how those events were logged

Here’s an example of a very basic event listener:

export default function(listener) {
  listener.on("**", (event) => {
    console.log(
      `-> My event listener received an event: ${JSON.stringify(event.topic)}`)
  });
}

> npm run dev

> gettingstarted@1.0.0 dev
> npx flatfile develop

✔ 2 environment(s) found for these credentials
✔ Environment "development" selected
ncc: Version 0.36.1
ncc: Compiling file index.js into CJS

✔ File change detected. 🚀 
listening for events at 5/18/2023, 8:52:19 PM

commit:created us_evt_abc 5/18/2023, 2:36:36 PM
commit:created us_evt_abc 5/18/2023, 2:36:38 PM

This code exports a single function that accepts an instance of an object (named listener in the example). This object can be used to subscribe to different events within your Flatfile SpaceA micro-application.... The example code subscribes to all events (using the ** selector) and writes the event’s topic name to the console.

Listeners are the basic building block of Flatfile logic. They span from simple validations and transformations to complex, multi-sheet workflows.

​

Working with Plugins

Flatfile provides a number of transformation & validation plugins to reshape data before it gets updated. These plugins build on the listener and provide a simpler interface for working with your data.

​

Adding your first data transformation

In this example, we’ll use the @flatfile/plugin-record-hook plugin to notify us of every row addition or modification and give us the ability to modify the data. For this example, we will take the first name record and make it lowercase.

import { recordHook } from '@flatfile/plugin-record-hook';

  listener.use(
    recordHook('contacts', (record) => {
      const value = record.get('firstName')?.toString()
      if (value) {
        record.set('firstName', value.toLowerCase())
      }

      return record
    })
  )

​

Using your transformation

Once the focus is off of the new First Name field, your transformation will run and convert the characters in your value to lowercase.

1. With the develop command still running in terminal, navigate to your Contacts sheet and insert a new row where the First Name is written entirely in capital letters.
2. When the focus leaves the First Name field, your transformation will run and convert the characters in your value to lowercase.

​

Adding your first validation

Similar to transforming data, we can use the record-hook plugin as the starting point for validating data.

import { recordHook } from '@flatfile/plugin-record-hook';

// While not the most correct, simple for the purpose of an example
const validEmailAddress = /^[\w\d.-]+@[\w\d]+\.\w+$/;

  listener.use(
    recordHook('contacts', (record) => {

      //previous code here

      if (!validEmailAddress.test(record.get('email'))) {
        console.log("got email")
        record.addError('email', 'Invalid email address')
      }

      return record
    })
  )

​

Using your validation

Once you take focus off of the field, your validation will run and the sheet user interface will display an error for the changed field.

1. With the develop command still running in terminal, go back to your Contacts sheet.
2. Modify any value of Email Address to make it an invalid email address.
3. Take focus off the field you entered (click outside that field).

​

Recap & Next Steps

You now have an example listener that is responding to record changes in your Workbook, and can perform simple data transformations and validations.

Next, we will add an action that will call out to an external webhook receiver provided by the webhook.site service.