Excel/CSV Data Import

Introduction

Excel/CSV Data Import is a Joget Userview Menu plugin that lets end users upload a .csv, .xls, or .xlsx file, preview its contents, and import the data directly into a configured Joget form's data store — without needing a developer to write custom import code.

For Excel files, the plugin automatically detects all worksheets in the workbook and lets the user pick which one to import from.

Plugin Information

Plugins Available in the Bundle:

• Excel/CSV Data Import (Userview Menu)

This plugin is compatible with Joget DX 9.

Where to Get the Plugin

You can download the plugin JAR file from the official JogetOSS GitHub Repository.

How to Install

1. Download the latest release .jar file from the repository page.
2. In the Joget Console, navigate to the Admin Bar > Settings > Manage Plugins.
3. Click the Upload Plugins button.
4. Under the Upload Plugin screen, select your downloaded JAR file and click Upload.

How To Use It

1. Open your app in App Composer and go to Form Builder. You can either edit an existing form or create a new one, for example, a form named test.
   
2. Drag in the fields you plan to import data into. For example, to match the Column Mapping example used later in this article, add three Text Field elements named empId, fullName, and dept. Click Save. This form (and these exact field names) is what you'll reference in Column Mapping when configuring the import excel/csv data userview menu, so it's worth noting down the field IDs before moving on.
   
3. Then go UI Builder, add the plugin as a menu item (Userview Builder > Menu > Add Userview Menu > Excel/CSV Data Import), then configure it. Once added, click on the menu item to open its properties panel and configure it — see Configure Excel/CSV Extraction Properties below for what each field does.
   

Configure Excel/CSV Extraction Properties

Fields to configure:

• Label: Excel/CSV Data Import — This is the display name shown to end users as the menu item's heading on the live page. It's left at the plugin's default value here rather than being customized.
• Menu ID: (blank) — This is the optional internal identifier for the menu item, used if you need to reference it elsewhere (e.g. via URL or code). Left blank here, so Joget will auto-generate one.
• Form: test — This is the target form the imported data will be written into. It's correctly selected from the dropdown (not typed manually) and points to the test form created in Step 1.
• Column Mapping: 0 → empid, 1 → fullName, 2 → dept — This defines which spreadsheet column (by 0-based number) maps to which field on the target form. Column 0 (the first column, e.g. "Employee ID") maps to the form field empid; column 1 maps to fullName; column 2 maps to dept. As flagged earlier, empid here doesn't match the camelCase empId field created in Step 1 — this mismatch should be corrected before relying on this configuration.
• Key Column Number: 0 — This tells the plugin that column 0 (Employee ID) holds the unique key used to detect existing records. When re-importing a file, rows whose key value already exists will be updated or skipped (depending on Import Mode) rather than inserted as duplicates.
• Start From Row Number: (blank) — Left empty, meaning there's no extra title/banner row to skip beyond the header row. Import starts normally at row 1.
• First row contains column headers: checked — Confirms row 1 of the uploaded file (e.g. "Employee ID, Full Name, Department") is treated as headers, not data — it will be excluded from both the preview and the actual import.
• Custom CSV Delimiter Character: (blank) — Left empty, so the plugin uses the default comma (,) as the delimiter when parsing CSV files. Would only need a value if your source files use a different delimiter (e.g. semicolon).
• Custom CSV Quote Character: (blank) — Left empty, so the plugin uses the default double-quote (") character for quoted fields in CSV files. Would only need a value if your source files use a non-standard quote character.

Actions

Fields to configure:

• Confirmation Message — If set, shows a JS confirm() dialog before the form submits (applies to Preview and Import).
• Message to Show When Error Occurs — Custom error text shown to the user instead of the generic error message.
• Message to Show After Data Is Extracted — Popup alert shown after a successful import.
• Redirection (Hyperlink) — URL to redirect the parent page to after a successful import.

How to Run the Plugin

Step 1 — Choose a file

The user clicks Choose file and selects a .csv, .xls, or .xlsx file.

If the file is .xls/.xlsx, the form automatically submits in the background to detect worksheets — a Worksheet dropdown appears immediately, listing every sheet name in the workbook.

If the file is .csv, no worksheet step is needed.

Step 2 — Choose Import Mode

Before or after previewing, the user selects one of:

• Import new record only (NEW) — Inserts rows as new records. If a row's key value already matches an existing record, that row is skipped.
• Import new record or update existing record (NEW & UPDATE) — Default. Inserts new rows; if a row's key matches an existing record, that record is updated instead.
• Delete record (DELETE) — Deletes the existing record matching the row's key value. Only shown if not disabled in config and the form supports deletion.

There is also a Validate data? checkbox (checked by default):

• Checked — Joget's form validation rules run during import.
• Unchecked — bypasses field validation.

Step 3 — Preview

Clicking Preview parses the file and shows:

Detected/generated column headers (from row 1, or synthetic "Column 1, Column 2..." if headers are disabled) A paginated table of rows, 10 rows per page Row/column counts and a page navigator (Previous/Next, "Showing rows X–Y")

Step 4 — Import

Clicking Import processes all rows (not just the previewed page) according to the column mapping and selected mode, then shows a results screen:

How Column Mapping Works (Example)

Say your CSV looks like this:

• (col 0) Employee ID | (col 1) Full Name | (col 2) Department
• E1001 | Jane Tan | Finance
• E1002 | Michael Ong | Sales

And your target form (the one created in Step 1) has fields empId, fullName, dept.

Your Column Mapping grid would be:

• Column Number 0 → Field Name empId
• Column Number 1 → Field Name fullName
• Column Number 2 → Field Name dept

Set Key Column Number = 0 so that re-importing the same file with NEW & UPDATE mode updates existing employees instead of duplicating them.

Troubleshooting

Message shown to user: "Please choose a file to upload." Cause: No file selected on Preview/Import and nothing previously cached in session. Fix: Select a file before clicking Preview or Import.

Message shown to user: "Invalid file type. Only .csv, .xls, and .xlsx are supported." Cause: File extension isn't one of the three supported types. Fix: Re-save/export the file as CSV, XLS, or XLSX.

Message shown to user: Generic "file size too large" error Cause: Uploaded file exceeds Joget's configured file size limit. Fix: Reduce file size or ask an admin to raise the limit.

Message shown to user: "Please upload a CSV or Excel file in UTF-8 encoding" Cause: UTF-8 Encoding Checking is enabled and the file isn't detected as UTF-8. Fix: Re-save the file with UTF-8 encoding, or disable the check in plugin config.

Message shown to user: "Form not found." Cause: The configured Form property points to a form that no longer exists, or was never properly selected from the dropdown. Fix: Reselect a valid form in the plugin config — click into the Form field and choose the form from the dropdown list rather than typing it manually.

Message shown to user: "Column mapping is required." Cause: The Column Mapping grid is empty. Fix: Add at least one column→field mapping.

Message shown to user: "Delete mode is not supported." Cause: User selected Delete mode but the form's binder doesn't support deletion. Fix: Use a deletable form binder, or disable Delete mode in config.

Message shown to user: Rows unexpectedly skipped Cause: Row's key value already exists and mode is NEW (not NEW & UPDATE). Fix: Switch to NEW & UPDATE if updates are wanted, or note that this is expected behavior.

Message shown to user: Header row appears as data / first data row missing Cause: "First row contains column headers" checkbox doesn't match your file's actual structure. Fix: Toggle the checkbox to match your file.

Example error message: