Using Linked Fields in Data Hooks® in the Platform SDK

This article is for Flatfile's Portal 3.0 and Workspaces. If you'd like to check out the latest version of the Flatfile Data Exchange Platform, click here!

There are two methods available that will allow you to update LinkedField values in Data Hooks® in the Flatfile Platform SDK. When modifying or looking up data in LinkedFields, regular methods will not be able to access that data as it can with non-relational fields, so the getLinkedValue and setLinkedValue methods will be necessary here. These methods can only be used in recordCompute and batchRecordsCompute data hooks.

The getLinkedValue method takes two arguments - the key of the LinkedField on the current template and the key of the child field on the linked template - and returns whatever value was mapped to that combination of fields by the user.

The setLinkedValue method takes three arguments - the key of the LinkedField on the current template, the key of a child field on the linked template, and the new value for those fields - and updates the LinkedField and child field with that value. At least one unique child field must be set for the records to link. If no child record is found with a unique value matching the incoming mapped value, one will be created with the upserted values unless upsert is set to false.

Currently these methods cannot be tested with the SheetTester tests included in the Platform SDK, but we are investigating ways to make this possible.

Here is a brief example of how these methods might be implemented in a Data Hook:

const PeopleData = new Sheet(
  'People Data',
  {
    firstname: TextField(),
    lastname: TextField(),
    fullName: TextField(),
    company: TextField(),
    emailAddress: TextField({ unique: true, required: true }),
    title: TextField(),
    employeeId: TextField({ unique: true, required: true }),
  },
  { previewFieldKey: 'fullName' }
)
const CompanyData = new Sheet(
  'Company Data',
  {
    companyName: TextField(),
    industry: TextField(),
    ceo: LinkedField({ required: true, sheet: PeopleData }),
  },
  {
    recordCompute: (record, session, logger) => {
      if (!record.getLinkedValue('ceo', 'emailAddress')) {
        record.setLinkedValue('ceo', 'emailAddress', 'stevejobs@apple.com')
        record.addError('ceo', 'Default CEO Added')
      }
    },
  }
)

To start using these methods:

These methods are only available starting with version 1.2.1 of the @flatfile/hooks package in your Flatfile Platform SDK implementation. If you are running an earlier version of @flatfile/hooks you can upgrade by running the command npm install @flatfile/hooks@1.2.1.

Please note that these methods cannot be added to any sheets you have already created and deployed to Flatfile; they must be used on new sheets. If you need to add them to a template you are currently using, you must create a new version of that template and at minimum change the name of the template.