Guides
Handling data

Data Hooks® are concise functions that automatically re-format, correct, validate, and enrich data during the data import process. These hooks can be executed on a complete record, or row, of data using methods on the FlatfileRecord class.

Record-level hooks have access to all fields in a row and should be utilized for operations that require access to multiple fields or when creating a new field.

Getting started

Listen for updates to data records, and respond with three types of record hooks: compute, computeIfPresent, and validate. These hooks are available as methods on the FlatfileRecord class.

import { FlatfileRecord } from '@flatfile/hooks'

In these examples, we’ll reference the workbook from the Quickstart guide.

Methods

FlatfileRecord.compute

Computes a new value for a field based on its original value or other field values on the record. Optionally pass a message to surface to the user about the transformation. compute will run even when no value is set for the field (see computeIfPresent).

Syntax

FlatfileRecord.compute(fieldName, transformation, message)
fieldName
string

The name of the field to transform.

transformation
(value, record) => string | number | boolean | null

The transformation to perform on the field value. Receives the intial value of the field, as well as the entire record if you want to access other field values on the record.

message
string

(optional) a message to show on the cell after the transformation.

Example

Generate email from first and last name:

client.use(
  recordHook('contacts', (record: FlatfileRecord) => {
    record.compute(
      'email',
      (email, record) => {
        return `${record.get('firstName') + record.get('lastName)}@gmail.com`
      },
      // optional
      'Email was generated from first and last name.'
    )
    return record
  })
)

FlatfileRecord.computeIfPresent

Same as compute, but only computes a new value if an initial value is provided (not null). Useful for computations that may throw an error on null values.

Syntax

FlatfileRecord.computeIfPresent(fieldName, transformation, message)
fieldName
string

The name of the field to transform.

transformation
(value, record) => string | number | boolean | null

The transformation to perform on the field value. Receives the intial value of the field, as well as the entire record if you want to access other field values on the record.

message
string

(optional) a message to show on the cell after the transformation.

Example

Change email to lower case:

client.use(
  recordHook('contacts', (record: FlatfileRecord) => {
    record.computeIfPresent(
      'email',
      (email) => email.toLowerCase(),
      // optional
      'Email was converted to lower case.'
    )
    return record
  })
)

FlatfileRecord.validate

Sets a field as invalid if its value does not meet a specified condition, and displays a message to the user.

Syntax

validate(fieldName, validator, message)
fieldName
string

The name of the field to validate.

validator
(value, record) => boolean

A function that determines whether a given field value is valid. Receives the intial value of the field, as well as the entire record if you want to access other field values on the record.

message
string

A message to show on the cell if the field is invalid.

Example

client.use(
  recordHook('contacts', (record: FlatfileRecord) => {
    record.validate(
      'lastName',
      (value) => !/\d/.test(value.toString()),
      'Last name cannot contain numbers'
    )
    return record
  })
)