DOCSEARCHbyAlgolia
Submit Docs

Flatfile v2.0 Documentation

website·Indexed 35 days ago

https://docs.flatfile.com/versioned-docs/3.0

Developer documentation for Flatfile v2.0, featuring guides on the Flatfile Portal, Data Hooks®, and the @flatfile/adapter SDK. Includes implementation details for React, Vue.js, Angular, Ember, and JavaScript, covering custom themes, schema and advanced field configuration, regex usage, and REST and GraphQL API integration.

Tokens
64.3K
Snippets
321
Records
410
Agent score
52%

What's inside Flatfile

  1. Overview of Flatfile Data Hooks

    Data Hooks are used to automatically re-format, validate, or correct data during the import process to reduce manual user correction. There are three types of hooks:

    1. Field Hooks (Column Hooks): Run once at the beginning of the matching stage. Best for bulk editing a field or validating against external data sources.
    2. Record Hooks (Row Hooks): Run on each record during the 'review' step. They trigger on init (start of review) and on change (when a record is updated).
    3. Step Hooks: (Mentioned as available, details provided in subsequent sections).

  2. Overview of Flatfile Data Hooks

    Data Hooks are used to automatically re-format, validate, or correct data during the import process without requiring manual user intervention. They are executed in a specific sequence: fieldHooks run first (once after the matching stage), followed by onRecordInit (at the start of the review step), and finally onRecordChange (whenever a record is updated during the review step).

  3. Overview of Flatfile Data Hooks

    Data Hooks are used to automatically re-format, validate, or correct data during the import process. They are executed in a specific order: fieldHooks run first (once after the matching stage), followed by onRecordInit (at the start of the review step), and finally onRecordChange (whenever a record is updated during the review step).

  4. Overview of Data Hooks in Flatfile

    Data Hooks are short functions used to re-format, correct, validate, and enrich data automatically during a data import. They can be applied at the field level (individual cells) or the record level (entire rows or batches of rows).

  5. Overview of Flatfile data exchange workflow

    Flatfile is a platform for importing, transforming, and validating unstructured data. The developer workflow consists of three primary steps: 1. Configure a data engine using the SDK and deploy it to Flatfile. 2. Embed an import UI component into your application to collect user data. 3. Receive the cleaned and processed data in your systems via webhooks or the Flatfile API.

  6. Overview of Flatfile Data Hooks

    Data Hooks are used to automatically re-format, validate, or correct data during import to reduce manual user correction. There are three types of hooks: Field Hooks (column-level), Record Hooks (row-level), and Step Hooks.

    Execution Order:

    1. registerFieldHook() runs first, once after the 'matching' stage.
    2. registerRecordHook() runs on all records after field hooks, and by default continues to run on individual records as they are updated.

  7. Overview of Flatfile data exchange workflow

    Flatfile allows developers to import, transform, and validate unstructured data from end-users before it reaches their internal systems. The standard implementation workflow consists of three main steps: configuring a data engine via the SDK and deploying it, embedding the import UI component into the application to collect user data, and receiving the processed data via webhooks or the Flatfile API.

  8. Add field descriptions for user guidance

    The description property (string, optional) allows you to provide additional details about a field. In the importer, this appears as an info icon in the field's header that displays the message when hovered over by the user.

  9. Understand the Flatfile webhook JSON payload

    When a webhook event is triggered, Flatfile sends an HTTP POST request with a JSON body. The payload is split into an event object (containing metadata about the trigger) and a data object (containing the actual import records).
    {
  "event": {
    "id": "String", // Uniquely generated webhook event ID
    "type": "String", // Event type (e.g., batch.update)
    "sequence": {
      "count": "Integer", // Total number of requests for this event
      "index": "Integer"  // Current request number, starting at 1
    }
  },
  "data": {
    "meta": {
      "batch": { "id": "String" }, // Current Batch ID
      "settings": { "id": "Integer" }, // Current Settings ID
      "count": "Integer" // Number of records in the request (max 1,000)
    },
    "validRows": [{}],   // Array of row data objects that passed validation
    "invalidRows": []     // Array of row data objects that failed validation
  }
}

  10. BaseMeta interface reference

    The BaseMeta interface in the @flatfile/adapter package provides metadata about a file upload batch, including file details, processing status, and row/column counts. It serves as the base for Meta and StreamedMeta.
    interface BaseMeta {
  batchID: string;
  status: string;
  endUser?: EndUserObject;
  originalFile: FileObject | null;
  csvFile: FileObject | null;
  filename: string;
  managed: boolean;
  manual: boolean;
  filetype: string;
  parsing_config: object;
  config: object;
  count_rows: number;
  count_rows_accepted: number;
  count_columns: number;
  skipped_rows: number;
  count_columns_matched: number;
  headers_raw: Array<object> | null;
  headers_matched: Array<object> | null;
  custom_columns: Array<object>;
  failure_reason: string;
  submitted_at: string;
  failed_at: string;
  created_at: string;
  handled_at: string;
  matched_at: string;
}

  11. Reference the Meta interface properties in @flatfile/adapter

    The Meta interface (extending BaseMeta) provides metadata about file uploads, batch processing, and parsing status. It is used to track the lifecycle and configuration of a data import batch.
    // Example of the Meta object structure based on the interface
interface Meta {
  batchID: string;
  status: string;
  filename: string;
  filetype: string;
  managed: boolean;
  manual: boolean;
  count_rows: number;
  count_rows_accepted: number;
  count_columns: number;
  count_columns_matched: number;
  skipped_rows: number;
  config: object;
  parsing_config: object;
  headers_raw: Array<object> | null;
  headers_matched: Array<object> | null;
  custom_columns: Array<object>;
  created_at: string;
  submitted_at: string;
  failed_at: string | null;
  failure_reason: string | null;
  handled_at: string | null;
  matched_at: string | null;
  originalFile: FileObject | null;
  csvFile: FileObject | null;
  endUser?: EndUserObject;
}

  12. Retrieve import metadata and status from FlatfileResults

    Use these accessors to get metadata about the import process, such as timing, file names, and failure reasons:
    const batchId = results.batchId; // UUID assigned by Flatfile
const fileName = results.fileName; // Original uploaded filename
const createdAt = results.createdAt; // Time import began
const submittedAt = results.submittedAt; // Time data was submitted
const failedAt = results.failedAt; // Time of failure, if applicable
const reason = results.failureReason; // Reason for failure, if applicable
const isManual = results.manual; // Boolean: true if data was entered manually
const isManaged = results.managed; // Boolean: true if managed by private endpoint
const stats = results.stats; // Stats and counts about the upload