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)
The name of the field to transform.
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.
(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)
The name of the field to transform.
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.
(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)
The name of the field to validate.
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.
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
})
)