Step Handler

Advanced

Concept

The Step Handler provides powerful hooks that execute after each step of the import process, giving you complete control over the data flow and user experience. Unlike its predecessor (Data Handler) which runs before the header and the review steps, the Step Handler runs after each step is completed, allowing you to validate, modify, or block progression based on your requirements.


Description	The Step Handler is an advanced feature that provides hooks after each step of the import process. It enables you to access the raw uploaded and parsed files, validate data, add cell-specific errors/warnings/infos, and control the import flow with built-in or custom modals. With the Step Handler, you can implement complex validation logic, throw pre-submission errors, access column and option mappings, and provide custom user feedback at any stage of the import process. Step Handler replaces the Data Handler and provides more granular control with hooks for upload, header selection, mapping, and review steps.
Available hooks	`uploadStep()` - Runs after file upload and parsing `headerStep()` - Runs after header selection confirmation `preProcessingStep()` - Runs after the "Pre-Processing" step, when `preProcessing` is enabled `mappingStep()` - Runs after mapping confirmation `reviewStep()` - Runs when user clicks "Complete import" in the review step
Control functions	`proceed()` - Advances to the next step without showing a modal `stay()` - Keeps the user on the current step without showing a modal `alert()` - Shows a customizable warning modal with proceed/cancel options `block()` - Shows a customizable error modal that blocks progression `updateData()` - Updates the data for the next step

Basic syntax

Here is an example of the Step Handler's syntax:

stepHandler={{
  uploadStep: async ({parsedData, rawData, updateData, alert, block}) => {
    // Hook runs after file upload and parsing
  },
  headerStep: async ({data, updateData, alert, block, proceed, stay}) => {
    // Hook runs after header selection confirmation
  },
  preProcessingStep: async ({data, updateData, alert, block, proceed, stay}) => {
    // Hook runs after the Pre-Processing step
  },
  mappingStep: async ({data, tdm, updateData, alert, block, proceed, stay, logs}) => {
    // Hook runs after mapping confirmation
  },
  reviewStep: async ({data, updateData, block, proceed, stay, logs}) => {
    // Hook runs when user clicks "Complete import" in the review step
  }
}}

uploadStep()


Description	This hook runs after the user has uploaded one or multiple files and the files have been parsed. It provides access to both the raw uploaded files and their parsed data, allowing validation and transformation before proceeding to the next step.
Parameters	`parsedData` - Array of parsed file objects with `data`, `fileName`, `fileSize`, `fileType`, and `sheetName` properties `rawData` - Array of raw/unparsed data for each uploaded file `updateData` - Function to update the data structure for the next step `alert` - Function to show a warning modal with proceed/cancel options `block` - Function to show an error modal that blocks progression
Run event	The `uploadStep` function is executed immediately after file upload and parsing is complete

Parameters

`parsedData`

Array of sheet objects containing the parsed data and metadata for each uploaded file/sheet.

Sheet object properties:

data: A 2D array representing the content of the sheet
fileName: The name of the uploaded file
fileSize: The size of the file in megabytes (MB)
fileType: The file extension (e.g., "xlsx", "csv", "xls")
sheetName: The name of the sheet (for Excel files) or defaults to the fileName for single-sheet files

Example:

[
  {
    "data": [
      [
        "company",
        "order_id",
        "customer_email",
        "order_instructions",
      ], ...
    ],
    "fileName": "test-file.xlsx",
    "fileSize": 0.0067,
    "fileType": "xlsx",
    "sheetName": "test-sheet-1"
  }, ...
]

`rawData`

Array of raw file objects containing the unprocessed files exactly as they were uploaded. This gives you access to the original files before any parsing or processing.

`updateData`

Function to modify the data structure before proceeding to the next step.

Return format:

updateData([
  {
    fileName: "Customers",
    sheetName: "Internal", // optional
    data: [
      // supports 2D array and array of row objects
      ["id", "name"],
      ["12345", "Jason"],
    ],
  },
  {
    fileName: "Products",
    data: [
      // supports 2D array and array of row objects
      { id: "12", quantity: 24 },
      { id: "13", quantity: 88 },
    ],
  },
]);

`alert`

Function to show a warning modal with proceed/cancel options.

Parameters:

title: Title of the warning modal
description: Description text explaining the warning
cancelButton: Text for the cancel button
proceedButton: Text for the proceed button

`block`

Function to show an error modal that blocks progression.

Parameters:

title: Text for the modal title
description: Text explaining the error
closeButton: Text for the close button

Implementation example

stepHandler={{
  uploadStep: async ({parsedData, rawData, updateData, alert, block}) => {
    // Access raw uploaded files
    console.log('Raw files:', rawData);

    // Process parsed data
    const processedData = parsedData.map(file => ({
      fileName: file.fileName,
      sheetName: file.sheetName,
      data: file.data.filter(row => row.length > 0) // Remove empty rows
    }));

    // Check for issues and potentially block
    if (processedData.some(file => file.data.length === 0)) {
      block({
        title: "Empty File Detected",
        description: "One or more files contain no data. Please upload valid files.",
        closeButton: "Close"
      });
      return;
    }

    // Update data for next step
    updateData(processedData);
  }
}}

Interaction with other features

allowManualInput: When the user clicks the "Manual Entry" button, uploadStep() is not triggered, and the user is forwarded to the review step.
automaticHeaderDetection: When automaticHeaderDetection === true, it does not affect uploadStep(). uploadStep() is triggered after parsing. If it finishes without alert() or block() being called, the user is forwarded to the next step (sheet or header selection).
Contextual Engine: uploadStep() runs after file upload, before the Contextual Engine is applied or the modal to use the Contextual Engine is displayed.

headerStep()


Description	This hook runs after the user has confirmed their header selection. It allows validation of the selected headers and provides the ability to modify the data structure before proceeding to either the mapping step or join step.
Parameters	`data` - Array of sheet objects with selected headers `updateData` - Function to update data structure `alert` - Function to show a warning modal `block` - Function to show an error modal `proceed` - Function to advance to the next step without showing a modal `stay` - Function to keep the user on the current step without showing a modal
Run event	The `headerStep` function is executed when the user confirms their header selection

Parameters

`data`

Array of sheet objects containing the data after header selection. It can contain one or multiple sheet objects depending on how many sheets have been selected inside the sheet selection. Each sheet object extends the structure of parsedData from uploadStep with additional properties that describe the transformations and decisions made during header selection.

Sheet object properties:

data: A 2D array representing the content of the sheet, where the first row contains the headers
fileName: The name of the uploaded file
fileSize: The size of the file in megabytes (MB)
fileType: The file extension (e.g., "xlsx", "csv", "xls")
sheetName: The name of the sheet (for Excel files) or defaults to the fileName for single-sheet files
transposed: A boolean indicating whether the user transposed the sheet during header selection. This field is always present regardless of whether transpose is enabled. When the feature is not enabled, the value is always false.
headerRowIndexes: An array of 0-based row indexes indicating which row(s) were selected as the header. For a single header row, this is a single-element array (e.g., [0]). For merged header rows, it contains all merged row indexes in order (e.g., [0, 1]). If the sheet was transposed, the indexes refer to the transposed layout.
addedColumns: An array of objects describing columns added during header selection via metadata cell selection or the "Add column" action. When no columns were added, this is an empty array []. This field is always present regardless of whether metadataSelection is enabled. Each entry contains:
- columnName (string): The name the user entered for the column
- value (string): The value applied to every row
- source (string): How the column was created. One of "metadata_cell", "custom_value", "file_name", or "sheet_name"

Example:

[
  {
    "data": [
      [
        "company",
        "order_id",
        "customer_email",
        "order_instructions",
      ], ...
    ],
    "fileName": "test-file.xlsx",
    "fileSize": 0.0067,
    "fileType": "xlsx",
    "sheetName": "test-sheet-1",
    "transposed": false,
    "headerRowIndexes": [0],
    "addedColumns": []
  }, ...
]

Example with merged headers and added columns:

[
  {
    "data": [
      [
        "2024 - Revenue",
        "2024 - Costs",
        "2024 - Profit",
        "Region",
      ],
      ["50000", "30000", "20000", "EU"],
      ["80000", "45000", "35000", "EU"],
    ],
    "fileName": "financials.xlsx",
    "fileSize": 0.0045,
    "fileType": "xlsx",
    "sheetName": "Q1 Report",
    "transposed": false,
    "headerRowIndexes": [0, 1],
    "addedColumns": [
      {
        "columnName": "Region",
        "value": "EU",
        "source": "custom_value"
      }
    ]
  }, ...
]

`updateData`

Function to modify the data structure before proceeding to the next step.

Return formats:

Single 2D array: Forwards the user to the mapping step
Single array of row objects: Forwards the user to the mapping step
Array with single sheet object: Forwards the user to the mapping step
Array with multiple sheet objects: Forwards the user to the join step when multipleFileUpload is activated

Example:

// Single 2D array
updateData([
  ["id", "name"],
  ["12345", "Jason"],
]);

// Single array of row objects
updateData([
  { id: "12", quantity: 24 },
  { id: "13", quantity: 88 },
]);

// Array with single sheet object
updateData([
  {
    fileName: "Sheet1",
    data: [
      ["header1", "header2"],
      ["value1", "value2"],
    ],
  },
]);

// Array with multiple sheet objects
updateData([
  {
    fileName: "Sheet1",
    data: [
      ["header1", "header2"],
      ["value1", "value2"],
    ],
  },
  {
    fileName: "Sheet2",
    data: [
      ["header3", "header4"],
      ["value3", "value4"],
    ],
  },
]);

`alert`

Function to show a warning modal with proceed/cancel options.

Parameters:

title: Title of the warning modal
description: Description text explaining the warning
cancelButton: Text for the cancel button
proceedButton: Text for the proceed button

`block`

Function to show an error modal that blocks progression.

Parameters:

title: Text for the modal title
description: Text explaining the error
closeButton: Text for the close button

`proceed`

Function to advance to the next step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately before advancing.

`stay`

Function to keep the user on the current step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately while keeping the user on the current step.

Implementation example

headerStep: async ({ data, updateData, alert, block }) => {
  // Validate required headers
  const requiredHeaders = ["id", "email", "name"];
  const headers = data[0].data[0];
  const missingHeaders = requiredHeaders.filter((h) => !headers.includes(h));

  if (missingHeaders.length > 0) {
    alert({
      title: "Missing required headers",
      description: `The following headers are required: ${missingHeaders.join(", ")}`,
      cancelButton: "Fix headers",
      proceedButton: "Continue anyway",
    });
  }

  // Remove empty columns
  const cleanData = data.map((sheet) => ({
    ...sheet,
    data: sheet.data.map((row) => row.filter((_, colIndex) => sheet.data.some((r) => r[colIndex]?.trim()))),
  }));

  updateData(cleanData);
};

Interaction with other features

automaticHeaderDetection: When the user clicks the "Manual Entry" button, headerStep() is not triggered, and the user is forwarded to the review step.
multipleFileUpload: If multiple sheets are returned via updateData() but multiple file upload is not activated, only the first sheet object is used for the mapping step.
allowManualInput: When automaticHeaderDetection === true, headerStep() is triggered at the end of the automated header selection. If block() or alert() is called, the corresponding modal is shown. Closing the modal returns the user to the previous step. Continuing forwards the user to the next step.
Contextual Engine: If the Contextual Engine is triggered in the header selection step (single sheet import), headerStep() does not run. If the Contextual Engine is triggered in the join step (multiple sheets import), headerStep() runs at the end of header selection/before going to the join step.
preProcessing: When preProcessing is set to true, headerStep() has no effect. Use preProcessingStep() instead.

preProcessingStep()


Description	This hook runs after the user has completed the "Pre-Processing" step, which replaces the sheet selection, header selection and join steps when `preProcessing` is set to `true`. It allows validation of the sheet that is passed on to the mapping step and provides the ability to modify its data structure before proceeding.
Parameters	`data` - Array with the sheet object that is passed on to the mapping step `updateData` - Function to update data structure `alert` - Function to show a warning modal `block` - Function to show an error modal `proceed` - Function to advance to the next step without showing a modal `stay` - Function to keep the user on the current step without showing a modal
Run event	The `preProcessingStep` function is executed when the user continues from the "Pre-Processing" step to the mapping step

Parameters

`data`

Array containing a single sheet object: either the sheet the user selected or the sheet produced by the "Pre-process" modal.

Sheet object properties:

data: A 2D array representing the content of the sheet, where the first row contains the headers
fileName: The name of the uploaded file
fileSize: The size of the file in megabytes (MB)
fileType: The file extension (e.g., "xlsx", "csv", "xls")
sheetName: The name of the sheet (for Excel files) or defaults to the fileName for single-sheet files
transposed: A boolean indicating whether the user transposed the sheet. This field is always present regardless of whether transpose is enabled. When the feature is not enabled, the value is always false.
headerRowIndexes: An array of 0-based row indexes indicating which row(s) were selected as the header. For a single header row, this is a single-element array (e.g., [0]). For merged header rows, it contains all merged row indexes in order (e.g., [0, 1]). If the sheet was transposed, the indexes refer to the transposed layout.
addedColumns: Always an empty array [] in preProcessingStep().

Example:

[
  {
    "data": [
      [
        "company",
        "order_id",
        "customer_email",
        "order_instructions",
      ], ...
    ],
    "fileName": "test-file.xlsx",
    "fileSize": 0.0067,
    "fileType": "xlsx",
    "sheetName": "test-sheet-1",
    "transposed": false,
    "headerRowIndexes": [0],
    "addedColumns": []
  }
]

`updateData`

Function to modify the data structure before proceeding to the mapping step.

Return formats:

Single 2D array: Forwards the user to the mapping step
Single array of row objects: Forwards the user to the mapping step
Array with single sheet object: Forwards the user to the mapping step

Example:

// Single 2D array
updateData([
  ["id", "name"],
  ["12345", "Jason"],
]);

// Single array of row objects
updateData([
  { id: "12", quantity: 24 },
  { id: "13", quantity: 88 },
]);

// Array with single sheet object
updateData([
  {
    fileName: "Sheet1",
    data: [
      ["header1", "header2"],
      ["value1", "value2"],
    ],
  },
]);

`alert`

Function to show a warning modal with proceed/cancel options.

Parameters:

title: Title of the warning modal
description: Description text explaining the warning
cancelButton: Text for the cancel button
proceedButton: Text for the proceed button

`block`

Function to show an error modal that blocks progression.

Parameters:

title: Text for the modal title
description: Text explaining the error
closeButton: Text for the close button

`proceed`

Function to advance to the next step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately before advancing.

`stay`

Function to keep the user on the current step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately while keeping the user on the current step.

Implementation example

preProcessingStep: async ({ data, block }) => {
  // Validate required headers
  const requiredHeaders = ["id", "email", "name"];
  const headers = data[0].data[0];
  const missingHeaders = requiredHeaders.filter((h) => !headers.includes(h));

  if (missingHeaders.length > 0) {
    block({
      title: "Missing required headers",
      description: `The following headers are required: ${missingHeaders.join(", ")}`,
      closeButton: "Fix headers",
    });
  }
};

mappingStep()


Description	This hook runs when the user confirms their column mappings and all required mappings are complete. It provides access to the mapped data and the Target Data Model (TDM), allowing validation and modification of both the schema and data.
Parameters	`data` - Array of row objects containing the TDM keys `tdm` - Target Data Model object with schema modification methods `updateData` - Function to update data with validation messages `alert` - Function to show a warning modal `block` - Function to show an error modal `proceed` - Function to advance to the next step without showing a modal `stay` - Function to keep the user on the current step without showing a modal `logs` - Object containing details about the column and option mappings, the custom-added columns and options
Run event	The `mappingStep` function is executed after the user confirms their column mappings and all required mappings are complete

Parameters

`data`

Array of row objects containing the mapped values using the Target Data Model (TDM) keys.

Example:

[
  {
    id: "12345",
    name: "Jason Miller",
    email: "[email protected]"
  }, ...
]

`tdm`

Target Data Model object for modifying the schema.

Available methods:

addColumn(): Add a new column to the schema. Accepts an optional second parameter { index } to control where the column is inserted.
```
tdm.addColumn(
  {
    key: "column_key",
    label: "column_label",
    columnType: "string",
    validations: [{ validate: "required" }],
    hidden: false,
    disabled: false,
  },
  { index: 0 }, // optional, inserts at this position (0-based)
);
```
When index is omitted or out of bounds, the column is added at the end of the TDM. If the key matches an existing TDM column, a console warning is thrown and the existing column is not modified.
updateColumn(): Update an existing column's properties. Accepts the column key, an object of properties to update, and an optional { index } to reorder the column.
```
tdm.updateColumn(
  "column_key",
  {
    label: "Updated Label",
    disabled: true,
  },
  { index: 0 }, // optional, moves the column to this position (0-based)
);
```
The provided changes are shallow-merged onto the existing column definition, so only the specified properties are overwritten and all others retain their current values. The key of a column cannot be changed via this method. When the provided key does not match any existing column, the update is silently ignored. When index is omitted, the column stays in its current position. When index is out of bounds, the column is moved to the end.
removeColumn(): Remove a column from the schema via its key
```
tdm.removeColumn("column_key");
```

`updateData`

Function to update data and add cell-specific error/warning/info messages.

Data formats:

Simple data: Array of row objects without validation messages

updateData([
  { id: "12345", name: "Jason" },
  { id: "67890", name: "Max" },
]);

Data with validation: Array of row objects with value and info properties
```
updateData([
  {
    id: {
      value: "12345",
      info: [
        {
          message: "Invalid ID format",
          level: "error",
        },
      ],
    },
  },
]);
```
info
The message field inside info supports HTML content when used in mappingStep(). This allows you to render rich text and interactive elements such as links, lists, paragraphs, and other common HTML tags inside the corresponding popovers.

`alert`

Function to show a warning modal with proceed/cancel options.

Parameters:

title: Title of the warning modal
description: Description text explaining the warning
cancelButton: Text for the cancel button
proceedButton: Text for the proceed button

`block`

Function to show an error modal that blocks progression.

Parameters:

title: Text for the modal title
description: Text explaining the error
closeButton: Text for the close button

`proceed`

Function to advance to the next step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately before advancing.

`stay`

Function to keep the user on the current step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately while keeping the user on the current step.

`logs`

Object containing details about the column and option mappings, the custom-added columns and options during the mapping step.

Properties:

mappings: Array of mapping objects containing relation between input and target columns, including option mappings for category columns
columns: Object containing added columns and options via allowCustomColumns and allowCustomOptions
Advanced

Example:

{
  "mappings": [
    {
      "sourceColumn": "Company Identification Number", // input column
      "targetColumn": "company_code" // matched Target Data Model column
    },
    {
      "sourceColumn": "Status",
      "targetColumn": "deal_status",
      "options": [ // when this is a category column (columnType === "category", "currency_code", "country_code_alpha_2" or "country_code_alpha_3"
        {
          "sourceValue": "In progress", // input value
          "targetOptions": ["Ongoing", ...] // matched Target Data Model dropdown option (can contain multiple strings when isMultiSelect === true)
        },
        {
          "sourceValue": "TBD",
          "targetOptions": [] // when being unmatched
        }
      ]
    },
    {
      "sourceColumn": "",
      "targetColumn": "address"
    }, ...
  ],
  "columns": {
    "addedColumns": [
      {
        "label": "Revenue",
        "key": "revenue",
        "columnType": "currency_eur"
      }
    ],
    "addedOptions": [
      {
        "columnKey": "deal_status",
        "dropdownOptions": [
          {
            "label": "Done",
            "value": "done",
            "type": "string"
          }
        ]
      }
    ]
  }
}

Implementation example

mappingStep: async ({ data, tdm, updateData, alert, block, logs }) => {
  // Check mapping completeness
  const unmappedRequired = logs.mappings.filter((m) => !m.sourceColumn).map((m) => m.targetColumn);

  if (unmappedRequired.length > 0) {
    block({
      title: "Unmapped Columns",
      description: `Every column needs to be mapped. Please map the following columns: ${unmappedRequired.join(", ")}`,
      closeButton: "Fix mappings",
    });
    return;
  }

  // Add custom validation column
  tdm.addColumn({
    key: "status",
    label: "Validation status",
    columnType: "string",
    hidden: true,
  });

  // Validate email format
  const validatedData = data.map((row) => {
    const validatedRow = { ...row };

    if (row.email && !row.email.includes("@")) {
      validatedRow.email = {
        value: row.email,
        info: [
          {
            message: "Invalid email format",
            level: "error",
          },
        ],
      };
      validatedRow.status = "Invalid";
    }

    return validatedRow;
  });

  updateData(validatedData);
};

Interaction with other features

Cleaning Functions: mappingStep() is executed before column hooks and onEntryInit(). columnHooks() receives the data returned by mappingStep() (without errors, warnings, infos). If alert() or block() is called, columnHooks() and onEntryInit() are not triggered.
automaticMapping: mappingStep() is called even if the mapping step is skipped via automatic mapping. If block() or alert() are used, the mapping step is not skipped and the corresponding alert/block modal is shown.
onlyMappedColumns: Normally, row objects in data contain all TDM keys. If onlyMappedColumns === true, only mapped TDM columns are included.
Contextual Engine: If the Contextual Engine runs and is successful, mappingStep() is triggered with the output of the Contextual Engine.
Hidden & disabled: Hidden and disabled columns are accessible and updatable via data and updateData in mappingStep(). Errors on hidden columns are ignored.

reviewStep()


Description	This hook runs when the user attempts to complete their import from the review step. It serves as the final validation point before submission, allowing pre-submission checks and data enrichment.
Parameters	`data` - Array of row objects with validation messages `updateData` - Function to update the data `block` - Function to show an error modal `proceed` - Function to advance to the next step without showing a modal `stay` - Function to keep the user on the current step without showing a modal `logs` - Object containing details about the mappings, the custom-added columns and options
Run event	The `reviewStep` function is executed when the user clicks "Complete import" in the review step

Parameters

`data`

Array of row objects containing the data, shown in the review step, including all error/warning/info messages. If the cell has no extra message, info is undefined.

Example:

[
  {
    id: {
      value: "12345",
      info: [{
        message: "ID verified",
        level: "info"
      }]
    },
    email: {
      value: "@getIngestro.com",
      info: [{
        message: "Invalid email format",
        level: "error"
      }]
    },
    amount: {
      value: 36000,
      info: [{
        message: "This value seems to extraordinary high. Please check again.",
        level: "warning"
      }]
    },
    name: {
      value: "Jason Miller",
      info: undefined
    },
    ...
  }, ...
]

`updateData`

Function to update the final data before submission. You can modify the values and add error/warning/info messages cell-specific.

Example:

// Add an error message to every name cell
updateData(
  data.map((row) => ({
    ...row,
    name: {
      value: row.name,
      info: [
        {
          message: "Invalid name",
          level: "error",
        },
      ],
    },
  })),
);

info

The message field inside info supports HTML content when used in reviewStep(). This allows you to render rich text and interactive elements such as links, lists, paragraphs, and other common HTML tags inside the corresponding popovers.

`block`

Function to show an error modal that blocks progression.

Parameters:

title: Text for the modal title
description: Text explaining the error
closeButton: Text for the close button

info

Note that alert is not available in reviewStep()

`proceed`

Function to advance to the next step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately before advancing.

`stay`

Function to keep the user on the current step without showing a modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately while keeping the user on the current step.

`logs`

Object containing details about the column and option mappings, the custom-added columns and options during the entire import process.

Properties:

mappings: Array of mapping objects containing relation between input and target columns, including option mappings for category columns
columns: Object containing added columns and options via allowCustomColumns and allowCustomOptions
Advanced

Example:

{
  "mappings": [
    {
      "sourceColumn": "Company Identification Number", // input column
      "targetColumn": "company_code" // matched Target Data Model column
    },
    {
      "sourceColumn": "Status",
      "targetColumn": "deal_status",
      "options": [ // when this is a category column (columnType === "category", "currency_code", "country_code_alpha_2" or "country_code_alpha_3"
        {
          "sourceValue": "In progress", // input value
          "targetOptions": ["Ongoing", ...] // matched Target Data Model dropdown option (can contain multiple strings when isMultiSelect === true)
        },
        {
          "sourceValue": "TBD",
          "targetOptions": [] // when being unmatched
        }
      ]
    },
    {
      "sourceColumn": "",
      "targetColumn": "address"
    }, ...
  ],
  "columns": {
    "addedColumns": [
      {
        "label": "Revenue",
        "key": "revenue",
        "columnType": "currency_eur"
      }
    ],
    "addedOptions": [
      {
        "columnKey": "deal_status",
        "dropdownOptions": [
          {
            "label": "Done",
            "value": "done",
            "type": "string"
          }
        ]
      }
    ]
  }
}

Implementation example

stepHandler={{
  reviewStep: async ({data, updateData, block, logs}) => {
    // Pre-submission validation
    const errorRows = data.filter(row =>
      Object.values(row).some(cell =>
        cell?.info?.some(info => info.level === 'error')
      )
    );

    if (errorRows.length > 0) {
      block({
        title: "Data Validation Failed",
        description: `${errorRows.length} rows contain errors that must be fixed before submission.`,
        closeButton: "Fix Errors"
      });
      return;
    }

    // Add submission timestamp
    const timestampedData = data.map(row => ({
      ...row,
      submitted_at: new Date().toISOString()
    }));

    updateData(timestampedData);
  }
}}

Interaction with other features

onlyMappedColumns: Normally, data contains all TDM keys, even if empty or null. If onlyMappedColumns === true, only mapped TDM columns are included.
Hidden & disabled: Hidden and disabled columns are accessible and updatable via data and updateData in reviewStep(). Errors on hidden columns are ignored.

Control functions

If a handler returns without calling any control function, the SDK advances as if proceed() was called.

proceed()

Description:

Advances to the next step. Does not show a built-in modal. Use this to drive navigation from your own custom UI.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately before advancing. Capped at 10 re-invocations per submission, after which the SDK advances to the next step and a console error is thrown.

Example:

proceed();
// or
proceed({ rerunHandler: true });

Callback availability:

Callback	Availability
Callback	Availability
`uploadStep()`	No
`headerStep()`	Yes
`mappingStep()`	Yes
`reviewStep()`	Yes

stay()

Description:

Cancels forward navigation for the current submission and keeps the user on the current step. Clears any loading state without showing a built-in modal.

Parameters:

rerunHandler (optional, default false): When true, re-invokes the same step handler immediately while keeping the user on the current step. Capped at 10 re-invocations per submission, after which the SDK advances to the next step and a console error is thrown.

Example:

stay();
// or
stay({ rerunHandler: true });

Callback availability:

Callback	Availability
Callback	Availability
`uploadStep()`	No
`headerStep()`	Yes
`mappingStep()`	Yes
`reviewStep()`	Yes

The following pattern uses proceed(), stay(), and rerunHandler to drive a custom confirmation modal. It also applies to headerStep() and reviewStep().

const phaseRef = useRef(false);

stepHandler={{
  mappingStep: async ({ data, proceed, stay }) => {
    if (!phaseRef.current) {
      openMyConfirmationModal({
        onConfirm: () => {
          phaseRef.current = true;
          proceed({ rerunHandler: true });
        },
        onCancel: () => stay(),
      });
      return;
    }

    await syncToBackend(data);
    phaseRef.current = false;
    proceed();
  },
}}

alert()

Description:

Shows a warning modal with "Continue" and "Cancel" options. Clicking "Cancel" or the "X" button closes the modal and keeps the user on the current step. Clicking "Continue" allows the user to proceed to the next step.

Alert modal:

Parameters:

title: Title of the modal (default: "Are you sure you want to continue?")
description: Description text (default: "Some required steps may not be completed yet.")
cancelButton: Text for cancel button (default: "Cancel")
proceedButton: Text for proceed button (default: "Continue")

Example:

alert({
  title: "Warning Title",
  description: "Warning description text",
  cancelButton: "Cancel",
  proceedButton: "Continue",
});

Callback availability:

Callback	Availability
Callback	Availability
`uploadStep()`	Yes
`headerStep()`	Yes
`mappingStep()`	Yes
`reviewStep()`	No

block()

Description:

Shows an error modal that prevents the user from proceeding. Clicking the "Close" or "X" button closes the modal and returns the user to the current step.

Block modal:

Parameters:

title: Title of the modal (default: "Unable to continue")
description: Description text (default: "Something went wrong. Please try again.")
closeButton: Text for close button (default: "Close")

Example:

block({
  title: "Error Title",
  description: "Error description text",
  closeButton: "Close",
});

Callback availability:

Callback	Availability
Callback	Availability
`uploadStep()`	Yes
`headerStep()`	Yes
`mappingStep()`	Yes
`reviewStep()`	Yes

Implementation examples

React
Angular
Vue
JavaScript

<DataImporter
  licenseKey="Your License Key"
  settings={{
    developerMode: true,
    identifier: "product_data",
    columns: [
      {
        key: "id",
        label: "Product ID",
        columnType: "string",
        validations: [{ validate: "required" }],
      },
      {
        key: "name",
        label: "Product Name",
        columnType: "string",
        validations: [{ validate: "required" }],
      },
      {
        key: "price",
        label: "Price",
        columnType: "number",
      },
      {
        key: "email",
        label: "Contact Email",
        columnType: "string",
      },
    ],
  }}
  stepHandler={{
    uploadStep: async ({ parsedData, rawData, updateData, alert, block }) => {
      // Hook runs after file upload and parsing
    },
    headerStep: async ({ data, updateData, alert, block, proceed, stay }) => {
      // Hook runs after header selection confirmation
    },
    mappingStep: async ({ data, tdm, updateData, alert, block, proceed, stay, logs }) => {
      // Hook runs after mapping confirmation
    },
    reviewStep: async ({ data, updateData, block, proceed, stay, logs }) => {
      // Hook runs when user clicks "Complete import" in the review step
    },
  }}
  onResults={(results, errors, complete, logs, block) => {
    console.log("Import completed:", results);
    complete();
  }}
/>

Add the DataImporter module to app.module.ts:

import { DataImporterModule } from "@ingestro/importer-angular";

@NgModule({
  declarations: [AppComponent],
  imports: [DataImporterModule, BrowserModule, AppRoutingModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

Add the component to app.component.html:

<data-importer [licenseKey]="licenseKey" [settings]="settings" [stepHandler]="stepHandler" [onResults]="onResults.bind(this)" />

Define properties in app.component.ts:

export class AppComponent implements OnInit {
  settings!: SettingsAPI;
  licenseKey!: string;
  stepHandler!: StepHandler;

  ngOnInit(): void {
    this.licenseKey = "Your license key";
    this.settings = {
      identifier: "product_data",
      developerMode: true,
      columns: [
        {
          key: "id",
          label: "Product ID",
          columnType: "string",
          validations: [{ validate: "required" }],
        },
        {
          key: "name",
          label: "Product Name",
          columnType: "string",
          validations: [{ validate: "required" }],
        },
        {
          key: "email",
          label: "Contact Email",
          columnType: "string",
        },
      ],
    };

    this.stepHandler = {
      uploadStep: async ({ parsedData, rawData, updateData, alert, block }) => {
        // Hook runs after file upload and parsing
      },
      headerStep: async ({ data, updateData, alert, block, proceed, stay }) => {
        // Hook runs after header selection confirmation
      },
      mappingStep: async ({ data, tdm, updateData, alert, block, proceed, stay, logs }) => {
        // Hook runs after mapping confirmation
      },
      reviewStep: async ({ data, updateData, block, proceed, stay, logs }) => {
        // Hook runs when user clicks "Complete import" in the review step
      },
    };

    onResults = (result, errors, complete, logs, block) => {
      console.log("Result:", result);
      console.log("Error rows:", errors);
      console.log("Logs:", logs);
      complete();
    };
  }
}

Add the component to App.vue:

<template>
  <div id="app">
    <DataImporter :settings="settings" :licenseKey="licenseKey" :stepHandler="stepHandler" :onResults="onResults" />
  </div>
</template>

Define the component script:

export default {
  name: "App",
  components: {
    DataImporter,
  },
  setup() {
    const settings = {
      developerMode: true,
      identifier: "product_data",
      columns: [
        {
          key: "id",
          label: "Product ID",
          columnType: "string",
          validations: [{ validate: "required" }],
        },
        {
          key: "name",
          label: "Product Name",
          columnType: "string",
          validations: [{ validate: "required" }],
        },
        {
          key: "email",
          label: "Contact Email",
          columnType: "string",
        },
      ],
    };
    return { settings };
  },
  data: () => {
    return {
      licenseKey: "Your License Key",
      stepHandler: {
        uploadStep: async ({ parsedData, rawData, updateData, alert, block }) => {
          // Hook runs after file upload and parsing
        },
        headerStep: async ({ data, updateData, alert, block, proceed, stay }) => {
          // Hook runs after header selection confirmation
        },
        mappingStep: async ({ data, tdm, updateData, alert, block, proceed, stay, logs }) => {
          // Hook runs after mapping confirmation
        },
        reviewStep: async ({ data, updateData, block, proceed, stay, logs }) => {
          // Hook runs when user clicks "Complete import" in the review step
        },
      },
    };
  },
  methods: {
    onResults: (result, errors, complete, logs, block) => {
      console.log("Result:", result);
      console.log("Error rows:", errors);
      console.log("Logs:", logs);
      complete();
    },
  },
};

<div class="importer" />
<script type="module">
  import { launchDataImporter } from "@ingestro/importer-vanilla-js";

  launchDataImporter(".importer", {
    licenseKey: "Your License Key",
    settings: {
      developerMode: true,
      identifier: "product_data",
      columns: [
        {
          key: "id",
          label: "Product ID",
          columnType: "string",
          validations: [{ validate: "required" }],
        },
        {
          key: "name",
          label: "Product Name",
          columnType: "string",
          validations: [{ validate: "required" }],
        },
        {
          key: "email",
          label: "Contact Email",
          columnType: "string",
        },
      ],
    },
    stepHandler: {
      uploadStep: async ({ parsedData, rawData, updateData, alert, block }) => {
        // Hook runs after file upload and parsing
      },
      headerStep: async ({ data, updateData, alert, block, proceed, stay }) => {
        // Hook runs after header selection confirmation
      },
      mappingStep: async ({ data, tdm, updateData, alert, block, proceed, stay, logs }) => {
        // Hook runs after mapping confirmation
      },
      reviewStep: async ({ data, updateData, block, proceed, stay, logs }) => {
        // Hook runs when user clicks "Complete import" in the review step
      },
    },
    onResults: (result, errors, complete, logs, block) => {
      console.log("Import completed:", result);
      complete();
    },
  });
</script>

Interaction with Cleaning Functions

The Step Handler can be used together with our Cleaning Functions to validate and transform data after the mapping step. mappingStep() runs first, followed by columnHooks(), which operates on the data returned from mappingStep(). Finally, onEntryInit() executes using the data as modified by both of the preceding functions.

Here is an overview of all import steps and hooks, including those from the Step Handler, the Cleaning Functions, and onResults().

Migration from Data Handler

The Step Handler replaces the Data Handler with improved functionality.

Here is a quick overview of the main differences and similarities:


Data Handler	Step Handler	Description
`headerStep()`	`uploadStep()`	Runs after file upload
`reviewStep()`	`mappingStep()`	Runs after mapping confirmation
N/A	`headerStep()`	New hook for accessing/modifying data after header selection
N/A	`reviewStep()`	New hook for pre-submission validation
N/A	`block()`	Blocks user from progression under certain conditions
N/A	`alert()`	Shows custom alert modal under certain conditions
N/A	Raw file access	Available in `uploadStep()`
N/A	Blocking user during pre-submission	Available in `reviewStep()` via `block()`

Migration steps:

Replace dataHandler with stepHandler
Move dataHandler.headerStep() logic to stepHandler.uploadStep()
Move dataHandler.reviewStep() logic to stepHandler.mappingStep()
Update data access patterns for new parameter structure & return mechanism
Optionally: Add new stepHandler.headerStep() to access and modify data after the header selection and stepHandler.reviewStep() for pre-submission validation

Need help migrating?

We offer two options to help with your migration:

Use our Migration GPT for automated guidance
Contact our support team at [email protected]

For more examples and advanced use cases, visit our knowledge base in our User Platform.

Concept​

Basic syntax​

uploadStep()​

Parameters​

parsedData​

rawData​

updateData​

alert​

block​

Implementation example​

Interaction with other features​

headerStep()​

Parameters​

data​

updateData​

alert​

block​

proceed​

stay​

Implementation example​

Interaction with other features​

preProcessingStep()​

Parameters​

data​

updateData​

alert​

block​

proceed​

stay​

Implementation example​

mappingStep()​

Parameters​

data​

tdm​

updateData​

alert​

block​

proceed​

stay​

logs​

Implementation example​

Interaction with other features​

reviewStep()​

Parameters​

data​

updateData​

block​

proceed​

stay​

logs​

Implementation example​

Interaction with other features​

Control functions​

proceed()​

stay()​

Custom modal flow using proceed() and stay()​

alert()​

block()​

Implementation examples​

Interaction with Cleaning Functions​

Migration from Data Handler​

Concept

Basic syntax

uploadStep()

Parameters

`parsedData`

`rawData`

`updateData`

`alert`

`block`

Implementation example

Interaction with other features

headerStep()

Parameters

`data`

`updateData`

`alert`

`block`

`proceed`

`stay`

Implementation example

Interaction with other features

preProcessingStep()

Parameters

`data`

`updateData`

`alert`

`block`

`proceed`

`stay`

Implementation example

mappingStep()

Parameters

`data`

`tdm`

`updateData`

`alert`

`block`

`proceed`

`stay`

`logs`

Implementation example

Interaction with other features

reviewStep()

Parameters

`data`

`updateData`

`block`

`proceed`

`stay`

`logs`

Implementation example

Interaction with other features

Control functions

proceed()

stay()

Custom modal flow using proceed() and stay()

alert()

block()

Implementation examples

Interaction with Cleaning Functions

Migration from Data Handler