This property can be used to configure the <DataImporter> so that the importer is tailor-made for your importing process. With this property, you can adjust the design, the display mode, enable or disable certain features and by using the columns property, you can define your preferred output schema. The <DataImporter> instance must have settings and licenseKey as properties to launch. A target data model (columns) and an identifier (identifier) must be defined within settings. Otherwise, the component cannot be launched.
identifier
| |
|---|
| Type | string |
| Required | |
| Description | The identifier helps to identify different imports. For example, you have defined one target data model for a customer import and one target data model for a product import. With the identifier option, you can distinguish between the "customer" and the "product" import. |
columns
| |
|---|
| Type | object |
| Required | |
| Description | Use columns to define the target data model you want to use within your application. columns is an array of objects. Each object is a new column which contains at least the keys label and key. For more information, check out our columns documentation. |
title
| |
|---|
| Type | string |
| Default | "Upload" |
| Description | This can be used to change the pre-set title currently seen as "Upload" inside the "Upload" step when the Ingestro importer is started. For instance, the title could be set to "Upload your product data here". In this case, you would see the following screen: |
When embedUploadArea equals true, the title won't be displayed.
developerMode
| |
|---|
| Type | boolean |
| Default | false |
| Description | This value is supposed to be true when using the Ingestro importer in development or staging environments. The Ingestro importer will display a "developer mode" banner at the top, and these imports will be marked as test imports, which means that they will not count against your contingent. |
stepTracking
| |
|---|
| Type | boolean |
| Default | false |
| Description | When set to true, the importer reports each step as soon as the user completes it, so imports that are started but not completed are also counted in the importer analytics of the User Platform. The reports never contain file contents, headers, mappings or row data. |
mappingViewMode
| |
|---|
| Type | "sourceColumns" or "targetColumns" |
| Default | "sourceColumns" |
| Description | This setting controls the layout of the mapping step. By default ("sourceColumns"), one mapping card is generated per input column from the uploaded file. When set to "targetColumns", the view is reversed: one mapping card is generated per target data model column instead. This is particularly useful when users upload files with many columns but only need to map a few target columns, reducing visual clutter and confusion in the mapping step. |
mappingViewMode: "sourceColumns" (default) | mappingViewMode: "targetColumns" |
|---|
 |  |
sheetSelectionViewMode
| |
|---|
| Type | "grid" or "list" |
| Default | "grid" |
| Description | This setting controls the view in which the "Sheet Selection" step opens. When set to "grid", the sheets are shown as a grid of previews. When set to "list", the sheets are shown as a list. Users can still switch between both views, and their choice is kept for the rest of the import. |
While preProcessing is set to true, this setting has no effect, because the "Sheet Selection" step is replaced by the "Pre-Processing" step.
collapseMatchedColumns
| |
|---|
| Type | boolean |
| Default | false |
| Description | When set to true, all matched rows in the Match Columns step start collapsed when the step renders. Unmatched rows remain expanded regardless of this setting. By default, rows matched to dropdown-type columns (category, country code, currency code, boolean) start expanded, and rows matched to non-dropdown types start collapsed. Users can still manually expand or collapse any row using the chevron. |
disableColumnRemapping
| |
|---|
| Type | boolean |
| Default | false |
| Description | When set to true, columns that are already matched to another row appear grayed out and cannot be selected in other dropdowns. Users can still free up a matched column using the × button on the row that holds the match or the × on the badge inside the dropdown. This setting applies to both mappingViewMode values. |
| |
|---|
| Type | boolean |
| Default | true |
| Description | When set to false, the Input format control and the "Output format" are hidden for all date columns in the "Match Columns" step. Dates are still read with the column's inputFormat, or with the detected format if no inputFormat is set. This setting applies to both mappingViewMode values. |
columnMappingConfiguration
| |
|---|
| Type | object |
| Description | Configures how input columns are matched to the target data model columns. You can define where the mapping runs, which matching layers to apply, and the confidence threshold for accepting matches. |
This setting is available in version 3.x and above. Please follow our First Steps guide to set up the importer. If you previously used version 2.x, make sure to switch to our new npm packages: @ingestro/importer-react, @ingestro/importer-angular, @ingestro/importer-vanilla-js, or @ingestro/importer-vue.
processingMode
| |
|---|
| Type | "browser" or "node" |
| Default | "node" |
| Description | Choose where the column mapping should be executed. You can specify whether it runs inside the browser ("browser") or on the server ("node"). |
"browser" - If selected, the column mapping for this column is executed in the browser. The smart and historic layers cannot be applied in this mode."node" - If selected, the column mapping for this column is executed on the server.
layers
| |
|---|
| Type | [string, ...] |
| Default | ["exact", "historic", "smart", "fuzzy"] |
| Description | Select which mapping layers are used. When multiple methods are selected, they are applied in this order: exact matches first, then historical patterns, followed by AI-powered matching, and finally, fuzzy matching. |
"exact" - Finds exact matches only (ignoring special characters and case)."historic" - Considers mappings from previous imports. Cannot be applied when processingMode equals "browser"."smart" - Uses our Ingestro AI for mapping. Cannot be applied when processingMode equals "browser"."fuzzy" - Identifies partial text similarities.
threshold
| |
|---|
| Type | number |
| Default | 0.6 |
| Description | This threshold (a value between 0 and 1) sets the minimum confidence required for a match to be considered valid. A lower value increases match flexibility, allowing more potential matches, while a higher value enforces stricter matching. The default is 0.6 (60%). |
sheetMappingConfiguration
| |
|---|
| Type | object |
| Description | Controls whether the Join Sheets and Append Columns modals use our AI mapping engine to suggest and pre-fill matching columns between sheets when the modal opens. |
sheetMappingConfiguration: {
join: {
mode: "disabled" | "headers_only" | "headers_with_samples",
},
append: {
mode: "disabled" | "headers_only" | "headers_with_samples",
},
}
Please note that if headers_only or headers_with_samples is set, column names are processed on our server-side (sample rows too, when headers_with_samples is set). For more information, see Data Processing.
join
| |
|---|
| Type | { mode: string } |
| Default | { mode: "disabled" } |
| Description | Controls whether opening the Join Sheets modal requests column suggestions. |
"disabled" - No suggestion request is made. The modal opens with empty dropdowns."headers_only" - Requests suggestions using column names only."headers_with_samples" - Requests suggestions using column names and up to 25 sample rows per sheet.
append
| |
|---|
| Type | { mode: string } |
| Default | { mode: "disabled" } |
| Description | Controls whether opening the Append Columns modal requests column suggestions. |
"disabled" - No suggestion request is made. The modal opens with empty dropdowns."headers_only" - Requests suggestions using column names only."headers_with_samples" - Requests suggestions using column names and up to 25 sample rows per sheet.
sheetVisibility
| |
|---|
| Type | "visible", "hidden" or "veryHidden" |
| Default | "veryHidden" |
| Description | Controls which sheets of a multi-sheet Excel file can be imported, based on their visibility within the workbook. |
"visible" - Only visible sheets can be imported."hidden" - Visible and hidden sheets can be imported. Very hidden sheets are excluded."veryHidden" - All sheets can be imported.
| |
|---|
| Type | [string, ...] |
| Default | ["csv", "tsv", "xls", "xlsx"] |
| Description | With this setting, you can define which file types the importer should support. You can choose between csv, tsv, psv, xls, xlsx, ods, json, xml, and pdf. By adding psv, the importer will support pipe-separated value files. By adding xml, the importer will support any kind of XML files and will provide a modal to choose what each row of the file represents and how nested details are included. By adding pdf, the importer will detect the tables inside PDF files and will provide a modal to choose which tables to import and, optionally, to describe in natural language how they should be reshaped. By adding json, the importer will support flat and nested JSONs with a maximum depth of four. The de-nesting process of JSONs involves replacing arrays with underscores _ and objects with periods . to facilitate the display of data in a 2D table. |
If more than one sheet is built from an XML file, each linked sheet carries a generated ID column that links its rows back to the main sheet.
The following is an example of how nested JSONs are parsed:
[
{ id: 1, games: { type: "football", location: "Germany" }, equipment: ["gloves", "ball"] },
{ id: 2, games: { type: "cricket", location: "England" }, equipment: ["bat", "ball"] },
];
| id | games.type | games.location | equipment_1 | equipment_2 |
| 1 | football | Germany | gloves | ball |
| 2 | cricket | England | bat | ball |
pdfConfiguration
| |
|---|
| Type | { mode: string } |
| Default | { mode: "node" }, or { mode: "browser" } if baseUrl is set |
| Description | Controls where PDF files are parsed when pdf is part of inputTypes. |
"node" - PDF files are parsed on our server side."browser" - PDF files are parsed in the user's browser and are not sent to our server side.
Please note that if mode is set to "node" while baseUrl is set, PDF files are sent to our server side for parsing instead of staying in the browser. Independently of mode, if users describe in the PDF extraction modal how the tables should be reshaped, the instruction, the values of the selected tables and any selected text from the PDF are processed on our server side. For more information, see Data Processing.
modal
| |
|---|
| Type | boolean |
| Default | true |
| Description | This option controls whether the Ingestro importer is implemented as a button or as a full page view. Your users will be guided through the workflow within a modal by default. When set to false, the users will go through the process on the implemented page without any modal occurring. |
Please note the minimum screen width for the Ingestro Importer to work:
- If
modal is set to true, the minimum required screen width is 901px.
- If
modal is set to false, the minimum required screen width is 948px.
embedUploadArea
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables you to implement the Ingestro importer as an embedding area. The Ingestro importer is shown as an embedding area when embedUploadArea equals true, and when it is set to false, the Ingestro importer is displayed as a button. |
If modal equals false, embedUploadArea has no effect.
embedUploadArea: false | embedUploadArea: true |
|---|
 |  |
| |
|---|
| Type | "import", "edit" or "both" |
| Default | "import" |
| Description | Suppose you want to enable your users also to edit/update existing data. In that case, you can use this setting to not only display an "Import data" button but also display an "Edit data" button. By clicking this button, the user is directly forwarded to the last step ("Review Entries" step), where the user can manually add new data or edit and delete existing data. For the latter case, we recommend using the preloadData option, which enables you to preload data into the table of the "Review Entries" step. With this setting, you can determine if you want to display the import, edit, or both buttons at the time. |
If modal equals false or embedUploadArea equals true, buttonMode has no effect.
buttonMode: "import" | buttonMode: "edit" | buttonMode: "both" |
|---|
 |  |  |
preloadData
| |
|---|
| Type | [{columnKey: string, ...}, ...] |
| Default | [] |
| Description | With this setting, you can preload data as an array of objects into the importer if the user does a manual import. If you have set allowManualInput to true, added data to the preloadData array, and the user clicks on the "Manual Entry" button, the preloaded data is displayed inside the table of the "Review Entries" step. The same goes for the "Edit data" button that is shown if buttonMode is set to edit or both. |
persistReviewSession
| |
|---|
| Type | boolean |
| Default | true |
| Description | This option saves the user's progress in their browser for 24 hours, so they can move between steps without losing their work and continue an import after closing the tab. When set to false, no progress is saved in the browser. For more information, see Dynamic Import. |
skipConfiguration
| |
|---|
| Type | object |
| Default | undefined |
| Description | This setting lets you control whether the header selection and column mapping steps are automatically completed and skipped. Instead of requiring users to manually confirm the header row or map columns every time, you can configure the importer to handle these steps automatically. skipConfiguration replaces and unifies the previous automaticHeaderDetection and automaticMapping settings into a single, more powerful configuration object. |
skipConfiguration: {
header: {
enabled: boolean,
showInStepper: boolean,
showInfoBox: boolean,
},
mapping: {
showInStepper: boolean,
showInfoBox: boolean,
automaticMapping: boolean,
applyColumnMapping: 'none' | 'gapFill' | 'always',
applyOptionMapping: 'none' | 'gapFill' | 'always',
requireConfirmation: boolean,
}
}
When configured, the importer automatically detects the header row in the uploaded file and skips the header selection step.
If preProcessing is set to true, skipConfiguration.header has no effect.
Options
| | |
|---|
| Option | Default | Description |
enabled | false | When true, the header row is automatically detected and the header selection step is skipped. When false, the header is still auto-detected and pre-selected, but the step is shown so the user can confirm or change the selection. |
showInStepper | true | When true, the header step remains visible in the progress bar even though it is skipped. The user can click back to review or change the detected header. When false, the step is completely hidden from the progress bar. |
showInfoBox | true | When true, an info box is displayed on the next visible step (Join Sheets or Column Mapping) informing the user that the header was automatically detected. |
Examples
Auto-detect and skip, but let users go back:
skipConfiguration: {
header: {
enabled: true,
showInStepper: true,
showInfoBox: true,
}
}
Auto-detect and skip, fully hidden:
skipConfiguration: {
header: {
enabled: true,
showInStepper: false,
showInfoBox: true,
}
}
Auto-detect and pre-select, but show the step for confirmation:
skipConfiguration: {
header: {
enabled: false,
}
}
Mapping Skip
When configured, the importer can skip the column mapping step by using one or both of the following mechanisms:
- Saved Mapping Scenarios (
automaticMapping) - The importer remembers how columns were mapped in previous imports. When the same data structure appears again, the saved mapping is applied automatically.
- Mapping Module (
applyColumnMapping / applyOptionMapping) - The importer uses smart auto-matching to automatically map columns and options based on your target data model configuration (columnMappingConfiguration / optionMappingConfiguration).
These mechanisms can be used independently or combined.
Options
| | |
|---|
| Option | Default | Description |
automaticMapping | false | When true, the importer looks up saved mappings from previous imports with the same data structure. If a match is found, the saved mapping is applied. |
applyColumnMapping | 'none' | Controls whether smart auto-matching is used for columns. See modes below. |
applyOptionMapping | 'none' | Controls whether smart auto-matching is used for options. See modes below. |
requireConfirmation | false | When true, the mapping step is always shown with the mapping pre-filled by the configured mechanisms, so the user confirms it on every import. Saved mappings are still applied and saved. showInStepper and showInfoBox have no effect, because the step is never skipped. |
showInStepper | true | When true, the mapping step remains visible in the progress bar even though it is skipped. The user can click back to review or change the mappings. When false, the step is completely hidden. |
showInfoBox | true | When true, an info box is displayed on the review step informing the user that column matching was automated. |
Mapping Module Modes
| |
|---|
'none' | Auto-matching is not used. |
'gapFill' | Auto-matching is used only to fill gaps after a saved mapping is applied. If no saved mapping exists, the mapping step is shown normally. |
'always' | Auto-matching is used for any unmapped columns/options. If no saved mapping exists, auto-matching handles everything. |
How Saved Mappings Work
When automaticMapping is enabled:
- After a user completes an import, the column and option mappings are saved and associated with a scenario identifier, a fingerprint made up of the combination of the source data columns and target data model structure.
- On the next import, if the same scenario identifier is detected, the saved mappings are applied automatically and the mapping step is skipped.
- The saved mapping is looked up from the browser's local storage first, then from the remote API.
When is the Mapping Step Skipped?
After all configured mechanisms have been applied (saved mapping, auto-matching gap-fill, or full auto-matching), the importer checks if the result passes mapping validation (all required target columns are mapped) and if every mapped date column has a date format, either detected by the importer or declared with inputFormat. If both checks pass, the mapping step is skipped and the user goes directly to the review step. If either check fails, the mapping step is shown with the results pre-filled so the user can fix any issues. If requireConfirmation is set to true, the mapping step is always shown with the results pre-filled, even if both checks pass.
Please note that if automaticMapping is enabled, option mappings will be saved on our server-side. Option mappings, unlike column mappings, may contain sensitive data. For more information, see Data Processing.
Common Configurations
Skip only when the same data was imported before:
skipConfiguration: {
mapping: {
automaticMapping: true,
}
}
The importer applies a saved mapping if the same data structure was seen before. No auto-matching is used. If no saved mapping exists, the mapping step is shown.
Skip when the same data was imported before, fill gaps with auto-matching:
skipConfiguration: {
mapping: {
automaticMapping: true,
applyColumnMapping: 'gapFill',
applyOptionMapping: 'gapFill',
}
}
The importer applies a saved mapping, then uses auto-matching to fill any unmapped columns or options (e.g., a new column was added since the last import). If no saved mapping exists, the mapping step is shown.
Best effort: saved mapping with auto-matching fallback:
skipConfiguration: {
mapping: {
automaticMapping: true,
applyColumnMapping: 'always',
applyOptionMapping: 'always',
}
}
The importer tries a saved mapping first. If found, it applies it and uses auto-matching to fill gaps. If no saved mapping exists, auto-matching handles everything. The mapping step is only shown if the combined result fails validation.
Always try to skip using auto-matching, no saved mappings needed:
skipConfiguration: {
mapping: {
applyColumnMapping: 'always',
applyOptionMapping: 'always',
}
}
The importer uses smart auto-matching for all columns and options. No saved mapping is required. The mapping step is skipped as long as auto-matching produces a result that passes validation.
Skip mapping, fully hidden from the user:
skipConfiguration: {
mapping: {
automaticMapping: true,
applyColumnMapping: 'always',
applyOptionMapping: 'always',
showInStepper: false,
showInfoBox: false,
}
}
Same as the best-effort configuration above, but the mapping step is completely hidden from the progress bar and no info box is shown.
Pre-fill the mapping, but let users confirm it on every import:
skipConfiguration: {
mapping: {
automaticMapping: true,
applyColumnMapping: 'gapFill',
applyOptionMapping: 'gapFill',
requireConfirmation: true,
}
}
The importer applies a saved mapping and uses auto-matching to fill any gaps, but always shows the mapping step so the user can review and confirm the pre-filled mapping. Changes the user makes are saved for the next import.
Combining Header and Mapping Skip
Both header and mapping skip can be configured together. When both steps are skipped, the user's experience goes directly from uploading a file to the review step.
skipConfiguration: {
header: {
enabled: true,
showInStepper: false,
showInfoBox: true,
},
mapping: {
automaticMapping: true,
applyColumnMapping: 'always',
applyOptionMapping: 'always',
showInStepper: false,
showInfoBox: true,
}
}
When both steps are skipped, a combined info box is shown informing the user that both the header detection and column matching were automated.
Info Box
When a step is skipped and showInfoBox is set to true, an info box appears on the next visible step to inform the user. The message varies based on the configuration:
| | |
|---|
| Skipped step(s) | showInStepper | Info box message |
| Header only | true | Informs the user the header was auto-detected and they can press "Back" to correct it. |
| Header only | false | Informs the user the header was auto-detected and they can restart the import to correct it. |
| Mapping only | true | Informs the user the column matching was automated and they can press "Back" to correct it. |
| Mapping only | false | Informs the user the column matching was automated and they can restart the import to correct it. |
| Both | varies per step | A combined message covering both steps. For each skipped step, the message mentions "Back" if that step's showInStepper is true, or "restart the import" if it is false. |
Interaction with stepHandler
If you are using stepHandler.headerStep or stepHandler.mappingStep, these handlers continue to execute even when the corresponding step is skipped. Step handlers are data transformation hooks that run at transition points, regardless of whether the step UI is visible.
If a step handler calls block(), the automatic skip is interrupted and the step is shown to the user, regardless of the skip configuration. This ensures that step handler logic always takes precedence.
Migration from Previous Settings
| |
|---|
| Previous setting | Equivalent skipConfiguration |
automaticHeaderDetection: true | skipConfiguration: { header: { enabled: true, showInStepper: false, showInfoBox: true } } |
automaticMapping: true | skipConfiguration: { mapping: { automaticMapping: true, showInStepper: true, showInfoBox: true } } |
transpose
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables a "Transpose" button in the header selection step, allowing users to swap rows and columns of their data before proceeding with mapping. When clicked, the data is transposed, the header row is re-estimated, and the table UI is updated accordingly. The button's appearance can be fully customized via style.buttons.transpose. |
This feature does not support the transposition of sheets with more than 10k rows. In this case, the "Transpose" button is disabled.
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables a "Merge headers" button in the header selection step, allowing users to select multiple header rows and merge them into a single combined header row. This is useful when uploaded files contain column labels split across multiple rows (e.g. files exported from Excel). Users can choose from five separator options: space, dash (default), underscore, slash, or none. The merged header can be edited or removed before proceeding. |
The "Transpose" button is hidden while merged headers are active. After removing a merge, the "Transpose" button is shown again (if transpose is set to true).
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables "Select metadata" and "Add column" buttons in the header selection step, allowing users to capture spreadsheet metadata or fixed values as additional columns before proceeding with mapping. With "Select metadata", users can click any non-empty cell to use its value as a new column applied to every row. With "Add column", users can manually define a column name and value, with quick-insert options for the file name and sheet name. Added columns appear in the table and flow through all subsequent steps as regular input columns. |
The "Transpose" and "Merge headers" buttons are hidden while metadata columns are present. They are shown again after all metadata columns are removed.
preProcessing
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option replaces the "Sheet Selection", "Header Selection" and "Join Sheets" steps with a single "Pre-Processing" step. When set to true, the import flow becomes Upload, Pre-Processing, Match Columns and Review Entries. In this step, users see every uploaded file and its sheets in one place, select the sheets they want to import, and choose the header row for each sheet. From there, users can open the "Pre-process" modal to shape the selected data with a recipe: an ordered list of named steps that users can edit, reorder or delete while a live preview shows the result. When several sheets are selected, users combine them inside the modal before continuing, since only one sheet can be passed on to the "Match Columns" step. |
The following recipe steps are available:
| |
|---|
| Recipe step | Description |
| Split column | Splits one column into several columns by a preset or custom delimiter. |
| Merge columns | Merges two or more columns into one column with a separator. |
| Filter rows | Keeps only the rows that match a condition, such as a value being equal to a given value, containing a given text or being empty. |
| Format column | Changes how the values of a column are formatted, for example as currency or in title case. |
| Rename column | Renames a column. |
| Add column | Adds a column with a name and a default value. |
| Remove column | Removes one or more columns. |
| Duplicate column | Copies a column under a new name. |
| Fill empty cells | Fills the empty cells of a column with a value. |
| Split into rows | Splits a cell that holds several values into one row per value, using a preset or custom delimiter. |
| Group rows | Groups rows by a column and defines how the values of the other columns are combined, for example by joining or summing them. |
| Pivot column | Creates new columns from the values of a column. |
| Unpivot columns | Turns column headers into values, creating one column for the header names and one for their values. |
| Unpivot column groups | Turns fields that repeat in numbered column groups into one row per group. |
When joining sheets, users can choose the join type and how duplicate keys are handled, as described under multipleFileUpload.
Users can also describe a transformation in natural language. The importer then adds matching recipe steps, which can be adjusted like any other step. If no recipe step fits the request, the importer adds an AI-generated step instead. This step can be reordered or deleted but not adjusted.
The existing transpose, mergeHeaders and metadataSelection settings continue to work within the "Pre-Processing" step. Transposing and merging headers are available on the previewed sheet, while metadata columns are added from the source tabs of the "Pre-process" modal.
Please note that if users describe a transformation in natural language, the column names and a few sample rows of the selected sheets are processed on our server side. For more information, see Data Processing.
preProcessingSuggestions
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables users to receive suggested recipe steps inside the "Pre-process" modal. When enabled, the modal compares the uploaded data with the target data model and suggests up to five steps, each with a short reason. Users can add or dismiss each suggestion, or all of them at once. Added steps behave like any other recipe step. |
This setting only has an effect when preProcessing is set to true. When several sheets are selected, suggestions are shown once the sheets are combined.
Please note that if this option is activated, the column names and a few sample rows of the selected sheets, as well as the target data model, are processed on our server side. For more information, see Data Processing.
maxEntries
| |
|---|
| Type | number |
| Default | null |
| Description | Define the highest amount of entries that can be imported. Note that the header row will not be taken into account. When a user's upload exceeds the defined amount of maxEntries, an error message is displayed, and your user cannot continue further. |
disableTemplates
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables you to disable the "Download Template"fFunctionality (for the Excel and CSV template) for your users. When this option is set to true, the "Download Template" button/tile won't be displayed inside your application, and your users, therefore, can't download the target data model template as CSV or as XLSX. |
disableExcelTemplate
| |
|---|
| Type | boolean |
| Default | false |
| Description | With this setting, you can disable the "Download Template" functionality (only for the Excel template) for your users. When this option is set to true, the "Excel template (.xlsx)" button won't be displayed inside your application, and your users, therefore, can only download the CSV template of the target data model. They cannot download the template as an Excel/XLSX file. |
| |
|---|
| Type | boolean |
| Default | false |
| Description | Defines if the "Upload" step contains a "Manual Entry" button or not. If set to true and the user clicks on the button, the user is directly forwarded to the "Review Entries" step and can add its values manually. For customizing the button's styling, please check out the following the styling section of (our documentation). |
allowCustomColumns
| |
|---|
| Type | boolean |
| Default | false |
| Description | This property enables the user to add customized columns to the defined target schema. If this option is set to true, the user can add custom columns to the target data model within the dropdown menu inside the "Match Columns" step and map its imported columns to them. The result array object will contain the key of each created custom column which was also mapped to an imported column. Validation rules or the columnType of a custom column cannot be defined. By default, the columnType is set to string. |
Note that the custom columns will be considered for creating the result array object of the current importing process but not for future ones. If you want that custom columns are permanently added to the target schema, you need to generate the columns array dynamically before initializing our component. Please contact us via [email protected] if you have any questions regarding this topic.
allowedCustomColumnTypes
| |
|---|
| Type | [string, ...] |
| Default | ["string", "int", "float", "boolean", "date", "email", "phone", "url", "url_https", "url_www", "percentage", "zip_code_de", "currency_eur", "currency_usd", "bic", "vat_eu", "gtin", "iban"] |
| Optional & usable if | allowCustomColumns: true |
| Description | Restricts which column types users can select when creating a custom column. When omitted, all available column types are shown. When set to a single value (e.g. ["string"]), the column type picker is hidden and the type is locked to that value. When set to two or more values, only those types are shown in the picker, in the declared order. |
allowColumnNameEdits
| |
|---|
| Type | boolean |
| Default | false |
| Description | Adds an "Edit" option to every column's options menu in the review step, letting users rename any column. |
completeImportAction
| |
|---|
| Type | "discard", "submit" or "block" |
| Default | "discard" |
| Description | This property lets you define how rows with errors inside the review step are handled. Apart from discarding ("discard") all rows with an error or submitting every erroneous row ("submit"), you also have the option to block the "Complete import" button if the data contains at least one error cell ("block"). |
The allowInvalidEntries property is deprecated since React version 1.14.3, Angular version 1.6.5, Vue.js version 1.0.2 and vanilla JavaScript version 0.3.3. Please use completeImportAction instead. If you have used allowInvalidEntries equals true, you need to set completeImportAction to "submit".
completeImportAction: "block" | completeImportAction: "discard" | completeImportAction: "submit" |
|---|
 |  |  |
enableMassiveErrorAlert
| |
|---|
| Type | number |
| Default | null |
| Description | This option enables you to display an error message to your users as a pop-up after there are more than x cells with an error. This error message tells the user that the user can either continue to correct its data within the application or that the user can download the matched data as .XLSX to continue the work within Excel. |
showReviewCellState
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option adds a colored bar to the edge of each cell with an error, warning or info message in the "Review Entries" step, in addition to the cell's background color. This makes the cell state visible without relying on the background color alone. |
onlyMappedColumns
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option defines if the user is supposed to see all target data model columns within the "Review Entries" step or just the mapped ones. If this prop is set to true, only the mapped target data model columns are shown and imported. |
Note that the result array object does not contain the keys of the unmapped columns.
enableExamples
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables you to display examples for each column of the target data model within the last step of the import process. When it is set to true, you can define the example property for each object of the columns array. These values are displayed within the table of the last step of the import process. |
language
| |
|---|
| Type | string |
| Default | "en" |
| Description | This setting allows you to choose the default language of the Ingestro Importer, which can be tailored to your particular requirements in combination with the i18nOverrides option. Additionally, you can switch languages dynamically before initializing the importer. This option currently supports a variety of languages, including English, German, Spanish, French, Italian, and more. For more information, please check our multi-language support documentation. |
i18nOverrides
| |
|---|
| Type | object |
| Default | null |
| Description | This option allows you to overwrite every UI text inside the Ingestro importer with your preferred version. You can also define the i18n overrides per language and add language support for languages that are not yet support by our language setting. For more information, please check our multi-language support documentation. |
With the language setting, you can easily and quickly implement support for your preferred language and change the UI language. If you want to support additional languages that we do not cover yet, or if you want to override our default translation keys, we recommend using our i18nOverrides functionality. You can find details about both options and a list of all i18n keys for each default translation here.
style
| |
|---|
| Type | object |
| Default | null |
| Description | The style setting enables you to customize the style of the Ingestro importer. You can adjust the theme for the importer to match your branding. |
Please notice that using your own CSS to override ours can lead to bugs. To avoid that, please use our provided style option. Visit our style documentation for more details on our styling options.
multipleFileUpload
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables you to allow users to upload multiple files and select multiple sheets. Enable this option to show the "Join Sheets" step to your users within the importing process, where they can select the key columns for joining and appending data from multiple sheets. |
When joining sheets, users can choose one of the following join types, which work like the SQL joins of the same name:
- Full join - Keeps every row from both sides. Rows without a match are filled with empty cells.
- Inner join - Keeps only the rows whose key appears on both sides.
- Left join - Keeps every row from the current data and adds data from the new sheet where the keys match.
- Right join - Keeps every row from the new sheet and adds data from the current data where the keys match.
If a key appears more than once, users can either keep every matching combination as its own row or use only the first matching row from the new sheet.
smartTable
| |
|---|
| Type | boolean |
| Default | true |
| Description | This option enables the user to sort, filter, freeze and hide columns, as well as find and replace values. If this property is set to true, a `…" menu is added to each column, with which the user can apply the functionalities mentioned. |
columnResize
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables users to dynamically resize column widths by dragging column borders in the table. When set to true and smartTable is enabled, users can click and drag the edge of any column header to adjust its width. |
cleaningAssistant
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables users to receive suggestions from our smart AI cleaning assistant on how to clean their erroneous data. When enabled, the "Clean data" button is displayed inside the "Review Entries" step. Clicking this button generates cleaning recommendations for each cell with errors, allowing users to apply, ignore, or dismiss these suggestions as needed. |
Please note that if this option is activated the content of the imported files might be processed on our server-side. For more information, see Data Processing.
contextualEngine
| |
|---|
| Type | "prompt", "enabled" or "disabled" |
| Default | "disabled" |
| Description | This option allows users to automate the import process end-to-end. Our Contextual Engine takes care of everything, from mapping to transforming and cleaning the data, immediately after upload. Users can still review the results and make final adjustments in the review step, or opt for the manual import flow instead. When set to "enabled", the Contextual Engine is automatically applied after upload. When set to "prompt", users can choose between using the Contextual Engine or following the manual import workflow. |
contextualEngine: "prompt" | contextualEngine: "enabled" |
|---|
 |  |
Please note that if this option is activated ("prompt" or "enabled"), the content of the imported files will be processed on our server side. For more information, see Data Processing.
prompts
| |
|---|
| Type | boolean |
| Default | false |
| Description | Enables users to describe data transformations in natural language during the review step. The transformations are applied in bulk to individual columns using AI-generated functions. |
additionalInfo
| |
|---|
| Type | object |
| Default | { uploadStep: false, sheetSelectionStep: false, headerStep: false, joinSheetsStep: false, preProcessingStep: false, preProcessingModal: false, xmlModal: false, pdfModal: false, mappingStep: false, reviewStep: false } |
| Description | Controls the visibility of info buttons throughout the import flow. When enabled for specific steps, an info button appears that opens a modal containing guidance and instructions for your users. You can selectively enable the info button for individual steps, customize the modal's title and message content via i18nOverrides, and fully style the button and modal appearance using the style property. The message content supports HTML formatting, allowing you to use rich text elements like paragraphs, lists, bold text, and more to structure your guidance. |
The info modal message content supports HTML tags such as <p>, <strong>, <em>, <ul>, <ol>, <li>, and more. This allows you to create well-structured and formatted guidance for your users. For more details on customizing the modal content, see the i18n documentation.
baseUrl
| |
|---|
| Type | string |
| Default | "" |
| Description | Defines the base URL for using Ingestro in a self-hosted environment. When set, the importer will use your self-hosted Ingestro backend and mapping module instead of the default Ingestro endpoint. This is required when hosting Ingestro on your own infrastructure. |
submitModalConfiguration
| |
|---|
| Type | object |
| Default | { exportButton: true, importSummary: true, display: true} |
| Description | Configures the "Ready to submit" modal that appears when users click "Complete import" in the review step. You can control the export functionality, import summary display, and whether to show the modal at all. You can customize the text elements via i18nOverrides, and remove or replace the icon as well as style the entire modal via style. |
| |
|---|
| Type | boolean |
| Default | true |
| Description | When set to true, displays an "Export error rows" button in the submit modal. This button is enabled when there are error rows and allows users to download an Excel file containing only the rows with errors. |
importSummary
| |
|---|
| Type | boolean |
| Default | true |
| Description | When set to true, displays the import summary section showing the number of clean rows and error rows in the submit modal. The counts are calculated after stepHandler.reviewStep() has been executed. |
display
| |
|---|
| Type | boolean |
| Default | true |
| Description | When set to false, the "Ready to submit" modal is not displayed, and onResults is executed directly. |
Default | importSummary: false |
|---|
 |  |
exportButton: false | importSummary: false & exportButton: false |
|---|
 |  |
successModalConfiguration
| |
|---|
| Type | object |
| Default | { importSummary: false, display: true } |
| Description | Configures the appearance and behavior of the success modal shown after a successful import when complete() is called. You can control whether to display import summary information and whether to show the modal at all. You can customize the text elements via i18nOverrides, and remove or replace the icon as well as style the entire modal via style. |
importSummary
| |
|---|
| Type | boolean |
| Default | false |
| Description | When set to true, shows the import summary section inside the success modal displaying the number of imported rows and failed rows. The numbers shown correspond to the importedRows and failedRows values passed to the complete() function. |
importSummary: false (Default) | importSummary: true |
|---|
 |  |
display
| |
|---|
| Type | boolean |
| Default | true |
| Description | When set to false, the success modal is not displayed after import completion, similar when the deprecated setting disableSuccessModal is set to true. |
Deprecated
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables you to let your users skip the header selection of the import process. When this option is set to true, your users are automatically forwarded to the matching step of the import process after selecting the correct spreadsheet(s). |
automaticHeaderDetection has been deprecated since version 4.3.0. Please use skipConfiguration.header instead. Setting automaticHeaderDetection: true is equivalent to skipConfiguration: { header: { enabled: true, showInStepper: false, showInfoBox: true } }. When skipConfiguration is defined, automaticHeaderDetection is ignored.
automaticMapping (deprecated)
| |
|---|
| Type | boolean |
| Default | false |
| Description | If this property is set to true and the same import scenario occurs as before, the user skips the "Match Columns" step within the import process and is directly forwarded to the "Review Entries" step. The identification of the same import scenario depends on the column headers of the imported data, the key, isMultiSelect key-value pair of each TDM column, and the value key-value pair of each dropdown option in a category TDM column. This means that if all of these are the same as those from a previously completed import, automatic mapping is triggered, and the mapping step is skipped.
As a result, the column and option mappings from the last time this import scenario occured will be applied to the imported data. The user is notified by an additional info box above the table if the "Match Columns" step was skipped, and the user can always go back and enter the mapping step to correct any incorrect mappings.
If any of these differ, or if a column/option was added or removed, automatic mapping is not triggered, and the user must proceed through the mapping step as usual. |
automaticMapping has been deprecated since version 4.3.0. Please use skipConfiguration.mapping instead. Setting automaticMapping: true is equivalent to skipConfiguration: { mapping: { automaticMapping: true, showInStepper: true, showInfoBox: true } }. When skipConfiguration is defined, automaticMapping is ignored.
disableTemplateDropdowns (deprecated)
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option disables the dropdown fields inside the Excel/XLSX template and the "Export as Excel" file. When this setting is set to true, the downloadable Excel/XLSX template and the output of the "Export as Excel" functionality inside the "Review Entries" step do not include any dropdown fields. |
allowCustomOptions (deprecated)
| |
|---|
| Type | boolean |
| Default | false |
| Description | This property enables the user to add custom dropdown options to a category column (columnTypes equals category). If this option is set to true, the user can add custom options to a category column within the category dropdown menu and map the unique values of an imported column to them. |
allowCustomOptions has been deprecated in the global settings. You can now define, for each category column, whether this functionality should be enabled or disabled. More information can be found in the columns documentation.
allowInvalidEntries (deprecated)
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option enables you to allow users to submit entries with at least one error. If set to true, the entries which include an error will also be submitted. |
The allowInvalidEntries property has been deprecated since React version 1.14.3, Angular version 1.6.5, Vue.js version 1.0.2 and vanilla JavaScript version 0.3.3. Please use completeImportAction instead. If you have used allowInvalidEntries equals true, you should set completeImportAction to "submit".
allowNestedData (deprecated)
| |
|---|
| Type | boolean |
| Default | false |
| Description | By enabling this feature, users can upload nested .json files which will be de-nested based on a predefined set of rules. The de-nesting process involves replacing arrays with underscores _ and objects with periods . to facilitate the display of data in a 2D table. |
allowNestedData has been deprecated. You can use the advancedParsing setting that enables the parsing of nested JSON and XML files. More information can be found in the advancedParsing documentation.
advancedParsing (deprecated)
| |
|---|
| Type | boolean |
| Default | false |
| Description | By enabling this feature, users can upload nested JSON and XML files, which will be parsed based on a predefined set of rules.
When a user uploads complex XML files, the advanced parsing splits the XML file into multiple sheets corresponding to each dataset within the XML file. This allows the user to choose whether to import a specific subset of data or the entire dataset. Complex XML files are treated similarly to Excel workbooks with multiple sheets when this option is activated. |
advancedParsing has been deprecated. You can now easily add "xml" or/and "json" to inputTypes to achieve the same functionality. For seeing an example, how the de-nesting works and for more information you can go to our inputTypes documentation.
processingEngine (deprecated)
| |
|---|
| Type | "default" or "node" |
| Default | "default" |
| Description | This option enables you to decide whether the option mapping is done inside the browser (default) or on our server side (node). By default, the spreadsheet content and therefore also the option mapping (mapping of the unique values of an imported column with the dropdown options of a category column) will remain in the browser. If you want to speed up the process and reduce the mapping time, you can change the setting to node, so that the option mapping is done on our server side. |
disableSuccessModal (deprecated)
| |
|---|
| Type | boolean |
| Default | false |
| Description | This option defines whether the "Successful Upload" modal is shown at the end of the importing process or not. If it is set to true, no modal is displayed after the user clicks on the "Complete Import"/"Submit" button within the "Review Entries" step. |