​
What are Workbooks?

Workbooks are analogous to a database, and like a database, they are configured with a type-strict Blueprint. A Workbook replaces the spreadsheet template you may share with your users today when requesting data during the data collection phase of customer onboarding or other file-based data exchange processes.

Unlike a spreadsheet, Workbooks are designed to allow your team and users to validate, correct, and import data with real-time feedback.

With Workbooks, you can:

  1. Accept data from many file types beyond CSVs (and you can write your own file extractors if you can’t find a Plugin)
  2. Automatically apply any validation rules a developer has previously defined
  3. Provide end users the ability to add, remove, review, filter, and correct any data imported into a Workbook. For advanced filtering techniques, see our Advanced Filters guide
  4. Define Actions that can trigger any arbitrary code/function, like submitting the reviewed data to a destination API, database, or a workflow step of your choosing

​
Basic Blueprint Structure

​
Example Workbook Configuration

The following examples demonstrate the configuration of isolated Workbooks, which are intended to be used in the context of a Blueprint configuration.

​
Single-Sheet Workbook Configuration

This example configures a single Workbook with a single Sheet containing two Fields.

const customerWorkbook = {
  name: "Customer Import",
  description: "Import and validate customer data",
  sheets: [
    {
      name: "customers",
      slug: "customers",
      fields: [
        {
          key: "name",
          type: "string",
          label: "Full Name",
          constraints: [{ type: "required" }],
        },
        {
          key: "email",
          type: "string",
          label: "Email Address",
          constraints: [{ type: "required" }, { type: "unique" }],
        },
      ],
    },
  ],
};

​
Multi-Sheet Workbook Configuration

This example configures a Workbook with three Sheets containing several Fields each.

const ecommerceWorkbook = {
  name: "E-commerce Data Import",
  description: "Import customers, products, and orders",
  sheets: [
    {
      name: "customers",
      slug: "customers",
      fields: [
        { key: "customerId", type: "string", label: "Customer ID" },
        { key: "email", type: "string", label: "Email" },
        { key: "firstName", type: "string", label: "First Name" },
        { key: "lastName", type: "string", label: "Last Name" },
      ],
    },
    {
      name: "products",
      slug: "products",
      fields: [
        { key: "productId", type: "string", label: "Product ID" },
        { key: "name", type: "string", label: "Product Name" },
        { key: "price", type: "number", label: "Price" },
        { key: "category", type: "string", label: "Category" },
      ],
    },
    {
      name: "orders",
      slug: "orders",
      fields: [
        { key: "orderId", type: "string", label: "Order ID" },
        {
          key: "customerId",
          type: "reference",
          label: "Customer",
          config: { ref: "customers", key: "customerId" },
        },
        {
          key: "productId",
          type: "reference",
          label: "Product",
          config: { ref: "products", key: "productId" },
        },
        { key: "quantity", type: "number", label: "Quantity" },
        { key: "orderDate", type: "date", label: "Order Date" },
      ],
    },
  ],
};

​
Actions and Workflows

This example configures a Workbook with three Actions that can be used to validate and enrich the data in the workbook.

A note about Actions: Actions also require a listener to respond to the event published by clicking on them. For more, see Using Actions

const workbookWithActions = {
  name: "Advanced Customer Import",
  sheets: [customerSheet, productsSheet],

  actions: [
    {
      operation: "validate-all",
      mode: "foreground",
      label: "Validate All Data",
      description: "Run comprehensive validation on all sheets",
      primary: true,
      constraints: [
        {
          type: "hasData",
        },
      ],
    },
    {
      operation: "enrich-data",
      mode: "background",
      label: "Enrich Customer Data",
      description: "Add company information and social profiles",
      constraints: [
        {
          type: "hasData",
        },
      ],
    },
    {
      operation: "export-to-crm",
      mode: "foreground",
      label: "Export to CRM",
      description: "Send validated customers to Salesforce",
      constraints: [
        {
          type: "hasAllValid",
        },
      ],
    },
  ],
};

​
Workbook Metadata

For comprehensive metadata usage patterns, see our metadata guide.

Add contextual information:

const metadataWorkbook = {
  name: "Q1 2024 Customer Import",
  description: "Quarterly customer data migration for Q1 2024",

  metadata: {
    version: "2.1",
    created: "2024-01-15",
    department: "Sales",
    compliance: "GDPR",
    dataRetention: "7-years", // Configure [data retention policies](/guides/data-retention) to automatically manage workbook lifecycle

    // Custom fields for your tracking
    projectId: "PROJ-2024-001",
    priority: "high",
    estimatedRecords: 50000,
  },

  sheets: [customerSheet],
};

Workbooks work together with several other core concepts in Flatfile:

  • Blueprints - Define the structure and validation rules for workbook data
  • Fields - Individual column definitions within schemas
  • Records - Individual data rows that populate workbooks
  • Spaces - Environments that contain workbooks and manage user access
  • Actions - Custom buttons and workflows that operate on workbook data
  • Listeners - Event handlers that respond to workbook activities
  • Jobs - Background tasks that process workbook data