Utilizing metadata

​

Overview

Metadata allows you to store and retrieve additional data about an Environment, Space, Record, or Field without exposing it to end users.

​

Environment-level

On the environment level metadata can be configured to record details about your current enivornment state. This can be useful for developers to store information about their deployments and even aggregate information about spaces, users, and data therein.

​

Usage

Utilize @flatfile/api to create or update an Environment with metadata.

await api.environments.update(environmentId, {
  metadata: {
    version: "0.0.0",
    deployedAt: new Date().toISOString(),
  },
});

​

Space-level

The metadata object at the Space level is often used for details such as user ID, Space name, company ID, and company name. Metadata can be added during Space creation or at a later stage.

​

Usage

Utilize @flatfile/api to create or update a Space with metadata.

await api.spaces.update(spaceId, {
  metadata: {
    userId,
  },
});

Learn more about [adding metadata in React embedded Flatfile.

​

Workbook-level

The metadata object at the Workbook level is often used for details such as expirationDate. Metadata can be added during Workbook creation or at a later stage.

​

Usage

Utilize @flatfile/api to create or update a Workbook with metadata.

await api.workbook.update(spaceId, {
  metadata: {
    expirationDate,
  },
});

​

Record-level

Customers often require a way to store extra computed or generated information about a record that goes beyond what the data owner provides.

The metadata object on the record allows you to include details like record IDs or reference IDs to other tables.

​

Usage

Using the @flatfile/plugin-record-hook plugin, you can access and modify record-level metadata, similar to how it works with normal field values. In this example, we will get the firstName from the record and store the length of the name in metadata. This data will now be stored on the record itself.

listener.use(
  recordHook("contacts", (record) => {
    const firstName = record.get("firstName");

    record.setMetadata({
      firstNameLength: firstName?.length ?? 0,
    });

    return record;
  })
);

​

Field-level

The metadata object on a Field allows you to include details like how the column of data should be transformed on egress.

​

Usage

Utilize @flatfile/api to create or update a Workbook’s fields with metadata.

await api.workbooks.create({
  spaceId,
  name: "All Data",
  sheets: [
    {
      name: "Contacts",
      slug: "contacts",
      fields: [
        {
          key: "date_added",
          label: "Date Added",
          type: "date",
          metadata: {
            format: "MM-DD-YYYY",
          },
        },
      ],
    },
  ],
});