03: Adding Actions to Your Listener

In the previous guides, we created a Listener with Space configuration and data validation. Now we’ll extend that Listener to handle user Actions, allowing users to submit and process their data.

Following along? Download the starting code from our Getting Started repository and refactor it as we go, or jump directly to the final version with actions.

What Are Actions?

Actions are interactive buttons that appear in the Flatfile interface, allowing users to trigger custom operations on their data. Common Actions include:

Submit: Process your data and POST it to your system via API
Validate: Run custom validation rules
Transform: Apply data transformations
Export: Generate reports or exports

Actions appear as buttons in the Flatfile interface

For more detail on using Actions, see our Actions guide.

What Changes We’re Making

To add Actions to our Listener with validation, we need to make two specific changes:

1. Add Actions Array to Blueprint Definition

In the space:configure Listener, we’ll add an actions array to our Workbook creation. This enhances our Blueprint to include interactive elements:

actions: [
  {
    label: "Submit",
    description: "Send data to destination system",
    operation: "submitActionForeground",
    mode: "foreground",
  },
]

2. Add Action Handler Listener

We’ll add a new Listener to handle when users click the Submit button:

listener.on(
  "job:ready",
  { job: "workbook:submitActionForeground" },
  async (event) => {
    // Handle the action...
  }
);

Complete Example with Actions

This example builds on the Listener we created in the previous tutorials. It includes the complete functionality: Space configuration, email validation, and Actions.

import api from "@flatfile/api";
export default function (listener) {
  // Configure the space when it's created
  listener.on("job:ready", { job: "space:configure" }, async (event) => {
    const { jobId, spaceId } = event.context;
    try {
      // Acknowledge the job
      await api.jobs.ack(jobId, {
        info: "Setting up your workspace...",
        progress: 10,
      });
      // Create the Workbook with Sheets and Actions
      await api.workbooks.create({
        spaceId,
        name: "My Workbook",
        sheets: [
          {
            name: "contacts",
            slug: "contacts",
            fields: [
              { key: "name", type: "string", label: "Full Name" },
              { key: "email", type: "string", label: "Email" },
            ],
          },
        ],
        actions: [
          {
            label: "Submit",
            description: "Send data to destination system",
            operation: "submitActionForeground",
            mode: "foreground",
            primary: true,
          },
        ],
      });
      // Update progress
      await api.jobs.update(jobId, {
        info: "Workbook created successfully",
        progress: 75,
      });
      // Complete the job
      await api.jobs.complete(jobId, {
        outcome: {
          message: "Workspace configured successfully!",
          acknowledge: true,
        },
      });
    } catch (error) {
      console.error("Error configuring space:", error);
      // Fail the job if something goes wrong
      await api.jobs.fail(jobId, {
        outcome: {
          message: `Failed to configure workspace: ${error.message}`,
          acknowledge: true,
        },
      });
    }
  });
  // Handle when someone clicks Submit
  listener.on(
    "job:ready",
    { job: "workbook:submitActionForeground" },
    async (event) => {
      const { jobId, workbookId } = event.context;
      try {
        // Acknowledge the job
        await api.jobs.ack(jobId, {
          info: "Starting data processing...",
          progress: 10,
        });
        // Get the data
        const job = await api.jobs.get(jobId);
        // Update progress
        await api.jobs.update(jobId, {
          info: "Retrieving records...",
          progress: 30,
        });
        // Get the sheets
        const { data: sheets } = await api.sheets.list({ workbookId });
        // Get and count the records
        const records = {};
        let recordsCount = 0;
        for (const sheet of sheets) {
          const {
            data: { records: sheetRecords },
          } = await api.records.get(sheet.id);
          records[sheet.name] = sheetRecords;
          recordsCount += sheetRecords.length;
        }
        // Update progress
        await api.jobs.update(jobId, {
          info: `Processing ${sheets.length} sheets with ${recordsCount} records...`,
          progress: 60,
        });
        // Process the data (log to console for now)
        console.log("Processing records:", JSON.stringify(records, null, 2));
        // Complete the job
        await api.jobs.complete(jobId, {
          outcome: {
            message: `Successfully processed ${sheets.length} sheets with ${recordsCount} records!`,
            acknowledge: true,
          },
        });
      } catch (error) {
        console.error("Error processing data:", error);
        // Fail the job if something goes wrong
        await api.jobs.fail(jobId, {
          outcome: {
            message: `Data processing failed: ${error.message}`,
            acknowledge: true,
          },
        });
      }
    },
  );

  // Listen for commits and validate email format
  listener.on("commit:created", async (event) => {
    const { sheetId } = event.context;
    try {
      // Get records from the sheet
      const response = await api.records.get(sheetId);
      const records = response.data.records;
      // Simple email validation regex
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
      // Prepare updates for records with invalid emails
      const updates = [];
      for (const record of records) {
        const emailValue = record.values.email?.value;
        if (emailValue) {
          const email = emailValue.toLowerCase();
          if (!emailRegex.test(email)) {
            updates.push({
              id: record.id,
              values: {
                email: {
                  value: email,
                  messages: [
                    {
                      type: "error",
                      message:
                        "Please enter a valid email address (e.g., user@example.com)",
                    },
                  ],
                },
              },
            });
          }
        }
      }
      // Update records with validation messages
      if (updates.length > 0) {
        await api.records.update(sheetId, updates);
      }
    } catch (error) {
      console.error("Error during validation:", error);
    }
  });
}

import type { FlatfileListener } from "@flatfile/listener";
import api, { Flatfile } from "@flatfile/api";

export default function (listener: FlatfileListener) {
  // Configure the space when it's created
  listener.on("job:ready", { job: "space:configure" }, async (event) => {
    const { jobId, spaceId } = event.context;
    
    try {
      // Acknowledge the job
      await api.jobs.ack(jobId, {
        info: "Setting up your workspace...",
        progress: 10
      });

      // Create the Workbook with Sheets and Actions
      await api.workbooks.create({
        spaceId,
        name: "My Workbook",
        sheets: [
          {
            name: "contacts",
            slug: "contacts",
            fields: [
              { key: "name", type: "string", label: "Full Name" },
              { key: "email", type: "string", label: "Email" },
            ],
          },
        ],
        actions: [
          {
            label: "Submit",
            description: "Send data to destination system",
            operation: "submitActionForeground",
            mode: "foreground",
            primary: true,
          },
        ],
      });

      // Update progress
      await api.jobs.update(jobId, {
        info: "Workbook created successfully",
        progress: 75
      });

      // Complete the job
      await api.jobs.complete(jobId, {
        outcome: {
          message: "Workspace configured successfully!",
          acknowledge: true
        }
      });

    } catch (error) {
      console.error("Error configuring space:", error);
      
      // Fail the job if something goes wrong
      await api.jobs.fail(jobId, {
        outcome: {
          message: `Failed to configure workspace: ${error instanceof Error ? error.message : 'Unknown error'}`,
          acknowledge: true
        }
      });
    }
  });

  // Handle when someone clicks Submit
  listener.on(
    "job:ready",
    { job: "workbook:submitActionForeground" },
    async (event) => {
      const { jobId, workbookId } = event.context;

      try {
        // Acknowledge the job
        await api.jobs.ack(jobId, {
          info: "Starting data processing...",
          progress: 10
        });

        // Get the data
        const job = await api.jobs.get(jobId);
        
        // Update progress
        await api.jobs.update(jobId, {
          info: "Retrieving records...",
          progress: 30
        });

        // Get the sheets
        const { data: sheets } = await api.sheets.list({ workbookId });

        // Get and count the records
        const records: { [name: string]: any[] } = {};
        let recordsCount = 0;
        for (const sheet of sheets) {
          const { data: { records: sheetRecords}} = await api.records.get(sheet.id);
          records[sheet.name] = sheetRecords;
          recordsCount += sheetRecords.length;
        }

        // Update progress
        await api.jobs.update(jobId, {
          info: `Processing ${sheets.length} sheets with ${recordsCount} records...`,
          progress: 60
        });

        // Process the data (log to console for now)
        console.log("Processing records:", JSON.stringify(records, null, 2));

        // Complete the job
        await api.jobs.complete(jobId, {
          outcome: {
            message: `Successfully processed ${sheets.length} sheets with ${recordsCount} records!`,
            acknowledge: true
          }
        });

      } catch (error) {
        console.error("Error processing data:", error);
        
        // Fail the job if something goes wrong
        await api.jobs.fail(jobId, {
          outcome: {
            message: `Data processing failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
            acknowledge: true
          }
        });
      }
    }
  );

  // Listen for commits and validate email format
  listener.on("commit:created", async (event) => {
    const { sheetId } = event.context;
    
    try {
      // Get records from the sheet
      const response = await api.records.get(sheetId);
      const records = response.data.records;

      // Simple email validation regex
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

      // Prepare updates for records with invalid emails
      const updates: Flatfile.RecordWithLinks[] = [];

      for (const record of records) {
        const emailValue = record.values.email?.value as string; 
        
        if (emailValue) {
          const email = emailValue.toLowerCase();

          if (!emailRegex.test(email)) {
            updates.push({
              id: record.id,
              values: {
                email: {
                  value: email,
                  messages: [{
                    type: "error",
                    message: "Please enter a valid email address (e.g., user@example.com)",
                  }],
                },
              },
            });
          }
        }
      }

      // Update records with validation messages
      if (updates.length > 0) {
        await api.records.update(sheetId, updates);
      }

    } catch (error) {
      console.error("Error during validation:", error);
    }
  });
}

Complete Example: The full working code for this tutorial step is available in our Getting Started repository: JavaScript | TypeScript

Understanding Action Modes

Actions can run in different modes:

foreground: Runs immediately with real-time progress updates (good for quick operations)
background: Runs as a background job (good for longer operations)

The Action operation name (submitActionForeground) determines which Listener will handle the Action.

Testing Your Action

Local Development

To test your Listener locally, you can use the flatfile develop command. This will start a local server that will listen for Events and respond to them, and will also watch for changes to your Listener code and automatically reload the server.

# Run locally with file watching
npx flatfile develop

Step-by-Step Testing

After running your listener locally:

Testing Steps

Create a new Space in your Flatfile Environment
Upload (or manually enter) some data to the contacts Sheet with both valid and invalid email addresses
See validation errors appear on invalid email Fields
Click the “Submit” button
Watch the logging in the terminal as your data is processed and the job is completed

What Just Happened?

Your Listener now handles three key Events and provides a complete data import workflow. Here’s how the new action handling works:

1. Blueprint Definition with Actions

We enhanced the Blueprint definition to include action buttons that users can interact with. Adding actions to your workbook configuration is part of defining your Blueprint.

actions: [
  {
    label: "Submit",
    description: "Send data to destination system",
    operation: "submitActionForeground",
    mode: "foreground",
    primary: true,
  },
]

actions: [
  {
    label: "Submit",
    description: "Send data to destination system",
    operation: "submitActionForeground",
    mode: "foreground", 
    primary: true,
  },
]

2. Listen for Action Events

When users click the Submit button, Flatfile triggers a Job that your listener can handle using the same approach we used for the space:configure job in 101.01. Jobs are named with the pattern <domain>:<operation>. In this case, the domain is workbook since we’ve mounted the Action to the Workbook blueprint, and the operation is submitActionForeground as defined in the Action definition.

listener.on(
  "job:ready",
  { job: "workbook:submitActionForeground" },
  async (event) => {
    const { jobId, workbookId } = event.context;

listener.on(
  "job:ready", 
  { job: "workbook:submitActionForeground" },
  async (event) => {
    const { jobId, workbookId } = event.context;

3. Retrieve and Process Data

Get all the data from the workbook and process it according to your business logic.

// Get the sheets
const { data: sheets } = await api.sheets.list({ workbookId });

// Get and count the records
const records = {};
let recordsCount = 0;
for (const sheet of sheets) {
  const { data: { records: sheetRecords } } = await api.records.get(sheet.id);
  records[sheet.name] = sheetRecords;
  recordsCount += sheetRecords.length;
}

// Get the sheets
const { data: sheets } = await api.sheets.list({ workbookId });

// Get and count the records
const records: { [name: string]: any[] } = {};
let recordsCount = 0;
for (const sheet of sheets) {
  const { data: { records: sheetRecords }} = await api.records.get(sheet.id);
  records[sheet.name] = sheetRecords;
  recordsCount += sheetRecords.length;
}

4. Provide User Feedback

Keep users informed about the processing with progress updates and final results.

// Update progress during processing
await api.jobs.update(jobId, {
  info: `Processing ${sheets.length} sheets with ${recordsCount} records...`,
  progress: 60,
});

// Complete with success message
await api.jobs.complete(jobId, {
  outcome: {
    message: `Successfully processed ${sheets.length} sheets with ${recordsCount} records!`,
    acknowledge: true,
  },
});

// Update progress during processing  
await api.jobs.update(jobId, {
  info: `Processing ${sheets.length} sheets with ${recordsCount} records...`,
  progress: 60
});

// Complete with success message
await api.jobs.complete(jobId, {
  outcome: {
    message: `Successfully processed ${sheets.length} sheets with ${recordsCount} records!`,
    acknowledge: true
  }
});

Your complete Listener now handles:

space:configure - Defines the Blueprint with interactive actions
commit:created - Validates email format when users commit changes
workbook:submitActionForeground - Processes data when users click Submit

The Action follows the same Job lifecycle pattern: acknowledge → update progress → complete (or fail on error). This provides users with real-time feedback during data processing, while validation ensures data quality throughout the import process.

Next Steps

Congratulations! You now have a complete Listener that handles Space configuration, data validation, and user Actions. For more detailed information:

Learn more about Actions
Understand Job lifecycle patterns in Jobs
Learn more about Events
Organize your Listeners with Namespaces
Explore plugins: Job Handler and Space Configure

Getting Started

Core Concepts

Coding Tutorial

Plugins

Advanced Guides

Embedding Flatfile

Reference

What Are Actions?

What Changes We’re Making

1. Add Actions Array to Blueprint Definition

2. Add Action Handler Listener

Complete Example with Actions

Understanding Action Modes

Testing Your Action

Local Development

Step-by-Step Testing

Testing Steps

What Just Happened?

1. Blueprint Definition with Actions

2. Listen for Action Events

3. Retrieve and Process Data

4. Provide User Feedback

Next Steps

​What Are Actions?

​What Changes We’re Making

​1. Add Actions Array to Blueprint Definition

​2. Add Action Handler Listener

​Complete Example with Actions

​Understanding Action Modes

​Testing Your Action

​Local Development

​Step-by-Step Testing

Testing Steps

​What Just Happened?

​1. Blueprint Definition with Actions

​2. Listen for Action Events

​3. Retrieve and Process Data

​4. Provide User Feedback

​Next Steps

What Are Actions?

What Changes We’re Making

1. Add Actions Array to Blueprint Definition

2. Add Action Handler Listener

Complete Example with Actions

Understanding Action Modes

Testing Your Action

Local Development

Step-by-Step Testing

What Just Happened?

1. Blueprint Definition with Actions

2. Listen for Action Events

3. Retrieve and Process Data

4. Provide User Feedback

Next Steps