Automap Plugin

The Automap plugin is designed for headless data import workflows in Flatfile. Its primary purpose is to automate the column mapping process. The plugin listens for successfully extracted files, and when a matching file is found, it automatically creates and executes a mapping job to a specified destination Sheet.

This is ideal for scenarios where files with consistent schemas are uploaded programmatically, bypassing the need for a user to manually map columns in the UI. The plugin determines whether to proceed with the mapping based on a configurable confidence level, ensuring that only high-quality matches are automated. If the mapping confidence is too low, it can trigger a failure callback for custom notifications or alternative handling.

​

Installation

npm install @flatfile/plugin-automap

​

Configuration & Parameters

The automap function accepts an AutomapOptions configuration object with the following parameters:

​

Required Parameters

​

Optional Parameters

​

Usage Examples

​

Basic Usage

This example shows the simplest way to use the automap plugin, targeting a specific sheet for all uploaded CSV files.

import { FlatfileListener } from '@flatfile/listener';
import { automap } from '@flatfile/plugin-automap';

const listener = FlatfileListener.create((listener) => {
  listener.use(
    automap({
      accuracy: 'confident',
      defaultTargetSheet: 'Contacts',
      matchFilename: /\.csv$/,
    })
  );
});

​

Configuration with Failure Handling

This example demonstrates a more complete configuration, including a failure callback and targeting a specific workbook.

import { FlatfileListener } from '@flatfile/listener';
import { automap } from '@flatfile/plugin-automap';

const listener = FlatfileListener.create((listener) => {
  listener.use(
    automap({
      accuracy: 'confident',
      defaultTargetSheet: 'Contacts',
      targetWorkbook: 'MyPrimaryWorkbook',
      matchFilename: /^(contacts|people|users)\.csv$/i,
      debug: true,
      onFailure: (event) => {
        console.error(
          `Automap failed for file in space ${event.context.spaceId}. Please map manually.`
        );
        // Add custom logic here, like sending an email or Slack message.
      },
    })
  );
});

​

Dynamic Sheet Targeting

This example uses a function for defaultTargetSheet to dynamically route data to different sheets based on the filename.

import { FlatfileListener } from '@flatfile/listener';
import { automap } from '@flatfile/plugin-automap';

const listener = FlatfileListener.create((listener) => {
  listener.use(
    automap({
      accuracy: 'exact',
      defaultTargetSheet: (fileName) => {
        if (fileName.includes('invoice')) {
          return 'Invoices';
        } else if (fileName.includes('contact')) {
          return 'Contacts';
        }
        // Return a default or handle cases where no match is found
        return 'DefaultSheet';
      },
      onFailure: (event) => {
        console.log('Automap failed, manual mapping required.');
      },
    })
  );
});

​

Troubleshooting

The most effective way to troubleshoot the plugin is to set the debug: true option in the configuration. This will provide a step-by-step log of the plugin’s execution, including:

• Which files are matched
• What workbooks and sheets are targeted
• The contents of the mapping plan
• The reason for any failures

import { FlatfileListener } from '@flatfile/listener';
import { automap } from '@flatfile/plugin-automap';

const listener = FlatfileListener.create((listener) => {
  listener.use(
    automap({
      accuracy: 'exact',
      defaultTargetSheet: 'Contacts',
      debug: true, // Enable verbose logging
      onFailure: (event) => {
        const { spaceId, fileId } = event.context;
        console.error(
          `Could not automap file ${fileId} with 'exact' accuracy. ` +
          `Please visit space ${spaceId} to map it manually.`
        );
      },
    })
  );
});

​

Notes

​

Default Behavior

• File processing: If no matchFilename is provided, the plugin will attempt to automap every uploaded file
• Target sheet: It is highly recommended to set defaultTargetSheet for basic workflows, as the plugin cannot map single-sheet files automatically without it
• Workbook selection: When targetWorkbook is not specified, the plugin filters out file-associated workbooks and selects the remaining one, or the one with the ‘primary’ label if multiple exist
• File naming: By default, the plugin updates file names with status indicators (“⚡️” during processing, destination sheet name on success)

​

Special Considerations

• This plugin is intended for use in a server-side listener, not in the browser
• The plugin relies on two key events: job:completed:file:extract to start the process, and job:updated:workbook:map to check the mapping plan
• The logic for selecting a targetWorkbook works best when there’s a clear primary workbook in the space

​

Limitations

• The accuracy check is all-or-nothing. If even one column mapping does not meet the required confidence level, the entire automatic mapping job is aborted
• The plugin’s default behavior works best with single-sheet source files. For multi-sheet source files, you must provide more complex logic
• For internal errors (e.g., API call failures, inability to find a file or workbook), the plugin uses try/catch blocks and logs errors to the console, which are more verbose when debug is set to true

​

Error Handling Patterns

The primary pattern for user-defined error handling is the onFailure callback, which is triggered when mapping confidence is too low. This allows you to implement custom notification systems or alternative workflows when automatic mapping cannot proceed.