DataImportWizard
Parse a CSV, map destination fields, correct values and submit validated rows to application-owned import logic.
Live TypeScript example
Try the component here, then use the source below in your application.
- JavaScript
- 12.1 KiB
- Component CSS
- 2.6 KiB
- Shared theme CSS
- 5.5 KiBonce per application
How sizes are measured
The JavaScript figure includes this component’s required helpers. CSS includes its styling dependencies. Each entry is bundled separately for ES2022, minified, then compressed with gzip level 9. Your bundler may share helpers across components. Images, fonts, examples and application code are excluded.
Before compression: JavaScript 33.4 KiB; component CSS 11.6 KiB. These figures describe browser assets, not the complete package download.
View all component measurements →Browse for a CSV, map fields, then use the editable review table. Validation messages are associated with each input; Go to first issue finds the earliest error.
import '@blukavantui/community/theme.css'
import {createDataImportWizard} from '@blukavantui/pro/data-import-wizard';
import '@blukavantui/community/theme.css';
import '@blukavantui/pro/data-import-wizard.css';
export function mount(host:HTMLElement) {
const target=document.createElement('div'),status=document.createElement('p'),output=document.createElement('pre');
status.setAttribute('role','status');host.append(target,status,output);
const component=createDataImportWizard(target,{
Fields:[],AllowSchemaEditing:true,OutSystemsNulls:false,
RecordTypes:[
{Key:'products',Label:'Products',KeyField:'id',StartKey:100,Fields:[
{Key:'id',Label:'Product ID',DataType:'Integer',IsRequired:true},
{Key:'name',Label:'Product name',DataType:'Text',IsRequired:true}]},
{Key:'variants',Label:'Variants',KeyField:'id',StartKey:500,Fields:[
{Key:'id',Label:'Variant ID',DataType:'Integer',IsRequired:true},
{Key:'productId',Label:'Product ID',DataType:'Identifier',IsRequired:true,ReferencesRecordType:'products'},
{Key:'size',Label:'Size',DataType:'Text'}]}
],MaxRows:1000,MaxFileSizeMB:2,
},{
FieldsChanged:(type,fields)=>{status.textContent=`${type}: ${fields.length} destination fields. Revalidate schema on your server.`;},
BundleImportRequested:(requestId,bundle)=>{
// Runnable preview only. Replace with an awaited application API transaction.
// The payload contains RecordTypes[].Rows and KeyMap plus Rekeyed.
// Success must mean the whole transaction committed; reject with false on failure.
// AutoNumber IDs: insert parents on the server and use returned IDs for children.
// Do not insert the wizard's preview IDs into AutoNumber columns.
output.textContent=JSON.stringify(bundle,null,2);
queueMicrotask(()=>component.update({ImportResultRequestId:requestId,ImportResultSuccess:true,
ImportResultMessage:'Prepared related records. This example does not write to a database.'}));
},Error:message=>{status.textContent=message;},
});
status.textContent='Products: id,name. Variants: id,productId,size. Select both CSVs together and confirm the header-based suggestions. Re-keying is optional.';
return {destroy(){component.destroy();target.remove();status.remove();output.remove();}};
}
const instance = mount(document.getElementById('example')!)
// When this page or framework component is removed:
// instance.destroy()
Install the library and add the host element
npm install https://blukavantui.blutekmedia.com/downloads/blukavantui-community-0.4.0.tgz
# Install your licensed Pro archive alongside Community
npm install ./blukavantui-pro-0.2.1.tgz<div id="example"></div>Community components use @blukavantui/community. The ten Pro components use the separate @blukavantui/pro add-on alongside Community. Your application handles persistence and authentication through its typed callbacks. Choose the matching edition when installing the example.
createDataImportWizard
Set Fields for a single type, or Fields: [] with RecordTypes for related files. Destination cards show which CSV belongs to each output table and which files are still needed. Select multiple CSVs together; normalized header names suggest a unique destination, and ambiguous matches require a choice before loading. A missing file is a pending step, not a row validation error. AllowSchemaEditing exposes the expected output schema. ReferencesRecordType links a foreign-key field to another type’s KeyField. The optional re-key checkbox assigns new keys and repairs foreign keys before BundleImportRequested. Generated keys are for application-assigned identifiers; OutSystems AutoNumber IDs must be generated by the server, which inserts parents first and maps returned IDs in one transaction. Revalidate schema, ownership, uniqueness and relationships on the server. Acknowledge ImportResultRequestId with success only after commit; a rejection retains corrections. Use an overall ImportResultMessage for bundle failures; row errors currently apply to the active file. OutSystemsNulls defaults True natively and False on web; only numeric literal null/NULL becomes 0.
import { createDataImportWizard } from '@blukavantui/pro/data-import-wizard';
import '@blukavantui/pro/data-import-wizard.css';Load @blukavantui/community/theme.css once in your app shell.createDataImportWizard(host: HTMLElement, options: T.DataImportWizardOptions, events?: T.DataImportWizardEvents)Reference for @blukavantui/pro 0.2.1. Required and optional follow the shipped TypeScript declarations; optional does not imply a particular default. Pass typed arrays and objects directly where shown.
Options
15| Name | Type / requirement | Usage |
|---|---|---|
RecordTypes | BluImportRecordType[]Optional | Related CSV types; upload one file per type. Fields may be [] when configured. |
AllowSchemaEditing | booleanOptional | Enables editing destination schema inside the live wizard. |
OutSystemsNulls | booleanOptional | Opt-in OutSystems numeric/identifier literal null -> 0 conversion. False on web. |
Fields | BluImportField[]Required | Destination schema used for mapping and validation. |
MaxRows | numberOptional | Maximum data rows, from 1 to 100000. Default: 10000. |
MaxFileSizeMB | numberOptional | Maximum CSV file size in MB, from 1 to 50. Default: 5. |
Delimiter | stringOptional | Auto, Comma, Semicolon or Tab. Default: "Auto". |
IsDisabled | booleanOptional | Disables choosing, editing and submitting data. Default: False. |
ImportResultRequestId | stringOptional | Echo OnImportRequested.RequestId when the import finishes. Default: "". |
ImportResultSuccess | booleanOptional | True completes the import; False retains the file and corrections. Default: False. |
ImportResultMessage | stringOptional | Feedback for the matching import request. Default: "". |
ImportResultErrorsJson | stringOptional | Optional BluImportError array returned by the server. Default: "[]". |
ResetKey | stringOptional | Change to clear the file, mapping and review state when no import is running. Default: "". |
AccessibleLabel | stringOptional | Accessible component name; empty uses the component default. Default: "". |
ExtendedClass | stringOptional | Additional CSS classes on the Block root. Default: "". |
Callbacks
5| Name | Type / requirement | Usage |
|---|---|---|
FieldsChanged | (recordTypeKey: string, fields: T.BluImportField[]) => void | Promise<void>Optional | Reports the selected record-type key and edited field schema. |
BundleImportRequested | (requestId: string, bundle: T.BluImportBundle) => void | Promise<void>Optional | Receives the complete related graph and old/new KeyMap for each type. Submit as one atomic application-owned transaction. |
ImportRequested | (requestId: string, rows: Record<string, string | number | boolean | null>[], fileName: string) => void | Promise<void>Optional | |
StepChanged | (step: string) => void | Promise<void>Optional | |
Error | (message: string) => void | Promise<void>Optional |
Instance methods & properties
3| Name | Signature / type | Usage |
|---|---|---|
element | HTMLElement | Root owned by this instance. Dispose before removing its host. |
update | (patch: Partial<T.DataImportWizardOptions>) => void | Apply a partial options update to this instance. |
destroy | () => void | Dispose the instance and its listeners when the view is removed. |
Related data types
Expand a type for its fields and allowed values.
BluImportBundle
interface BluImportBundle {
Rekeyed: boolean;
RecordTypes: {
Key: string;
FileName: string;
Rows: Record<string, string | number | boolean | null>[];
KeyMap: {
OldKey: string | number;
NewKey: string | number;
}[];
}[];
}BluImportField
interface BluImportField {
/** Record type whose KeyField this foreign key references. */
ReferencesRecordType?: string;
/** Unique destination field key. */
Key: string;
/** Destination field label. */
Label: string;
/** Text, Integer, Decimal, Boolean, Date or DateTime. */
DataType: "Text" | "Integer" | "Identifier" | "Decimal" | "Boolean" | "Date" | "DateTime";
/** Rejects empty values. */
IsRequired?: boolean;
/** Rejects duplicate nonempty values within the submitted file. */
IsUnique?: boolean;
/** Used for an unmapped field or empty cell. */
DefaultValue?: string;
/** Help text shown during mapping. */
Description?: string;
}BluImportRecordType
Parse a CSV, map destination fields, correct values and submit validated rows to application-owned import logic.
interface BluImportRecordType {
Key: string;
Label: string;
Fields: BluImportField[];
KeyField?: string;
StartKey?: number;
}Use these inputs, events, actions and structures in Service Studio. Names and data bindings are specific to the native Blocks.
One of ten Pro components on Web and OutSystems. Commercial license required. View OutSystems editions →
Open OutSystems showcase ↗- Web runtime
- Supported
- TypeScript
- Supported
- OutSystems
- Supported
Statuses describe the component’s rendered code and interactions. Supply accessible content and follow the component guidance when integrating it.
Accessibility guidance →Purpose and use
Parse a CSV, map destination fields, correct values and submit validated rows to application-owned import logic.
Keyboard design guidance
Browse for a CSV, map fields, then use the editable review table. Validation messages are associated with each input; Go to first issue finds the earliest error.
See the support status above for review coverage and any limitations.
In your application
Provide useful labels, preserve visible focus, and test the component with your actual content. Use text alongside status colors and check contrast in each state.
Events0No events yet.
Interact with an example to see its events.