Impler is open-source data import infrastructure, built for engineering teams to help them build rich data import experience without constantly reinventing the wheel.
Why?
The ability to import data is often needed in the application. It usually starts the same, reading .csv or .xlsx file and insert records into the database. But after a while, you'll find yourself looping over large files, validating rows, and providing support for file types that you've never heard of before.
Impler's goal is to help developers create an efficient and smooth data import experience between the product and its users. All with an easy-to-use API and outstanding developer experience.
Integrated into your Product
Integrating the import widget into your product can take just a few minutes. The feature-rich experience of the widget makes the data onboarding experience fun for users. Users can map columns and even review invalid records in their spreadsheets so that the right data gets imported.
As developers, we tend to care about the performance of the application, but following the growing number of file types support, mapping, and data validation become a burden on the team and make life hard.
Open Source
One of the reasons for making Impler open-source was to ensure privacy and give back to the community. We heard from many teams and we also felt How hard it's to give support for Data import functionality. So to make it accessible to everyone, we decided to build the Impler with awesome people like you.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Get sanitized and formatted user-imported data Directly on your frontend application. Helping you to access data directly.
Available from @impler/[email protected] SDK. Not advisable to access imported data on the front end, if importing more than 10K records.
Once the user completes importing the spreadsheet in the widget, you access imported data immediately on the frontend application.
Enable Frontend Callback Destination
Open the Import and go to the Destination section.
Enable Get Imported Data in Frontend.
Get Imported Data on Frontend
Once the destination is enabled Impler will start sending Imported data on the frontend.
To access we can use onDataImported method at if using react or can check for aDATA_IMPORTED event as per if using HTML & JavaScript.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Impler allows facility to automate data import from remote locations. Data import from remote locations makes it easy when data needs to be imported automatically without human intervention.
Automated Import feature is available in the Scale plan only! Feel free to reach out in case you want to try it out!
How do I enable the automated import feature?
The process of automatic data import looks the same as manual data import, where the user uploads a file and impler imports the data. To convert any import to automated import we just need to switch its mode from Manual to Automatic. Once done your import is transformed from Manual to Automatic Import Mode.
How does Automated Import work?
When we switch import mode to Automatic, the Import widget gets transformed and instead of accepting the file from the user, the import widget asks the user for a source from where data will get imported on interval.
At the moment impler accepts RSS URL as a source from where data will be fetched at user-specified intervals. The embed process of automatic import is the same as manual import. Here is how automatic import works:
Step 1: Configure
The first step is to provide a source from where data will be imported at regular intervals. Here on RSS URL input, the user can provide the RSS URL and Impler will keep importing data from the URL.
Step 2: Map Columns
The second step is to Map appropriate columns from the RSS file. As RSS follows XML structure, Impler parses the RSS file, extracts all paths for possible values in the XML file, and returns headings. Users can pick an appropriate heading for the column.
Step 3: Schedule Timing
Impler imports data from specified sources at regular intervals. In the schedule step user defines the Interval. The ability to specify intervals in Minutes, Hours, Days, Months, and Days makes it limitless for a user to provide any timing.
Step 4: Confirm
At the end, impler confirms the automated import configuration. Which shows the source and when it will run.
Automated Imports are associated with users
Automated imports are associated with users. Users referred to here are users of end application who uses Impler. To mention userId we have to provide externalUserId extra parameters. As mentioned in (React) and (HTML & JS).
You can provide anything in externalUserId. ID or Email address that uniquely identifies the user is best suitable for value in externalUserId.
Showing Automated Imports in Application
Automated Imports refers to the user. It becomes obvious to show users import jobs into your application. Here are all the APIs to deal with import jobs in Impler.
Getting User Import Jobs
Pause the User Import Job
Resume the User Import Job
Delete the User Import Job
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Make Your Team
Invite your peers and make your team on Impler with facility to invite, manage and remove team members.
With inspiration from Birds of a feather flock together, you can invite your peers in Impler with different background, who are responsible for different work. Here are the details about which role has which capabilities in Impler.
Roles and Permissions
Action\Role
Admin
Tech
Finance
How Invitation Flow Works
1) Create a new account or Sign In
2) Click on `Invite` Button on Team Members
The person who created project will be on Admin role by default.
3) Provide Member Details and their Roles
Based on your current plan you can invite members to your team. Provide email IDs of your members and their roles. An invitation email will be sent to the invited members with a link to take action on the invitation.
4) Receive Invitation Link by Email or Copy from Sent Invitations
Invited members will get an email to accept the invitation or you can copy the invitation link from Sent Invitations section on Team Members.
5) Take Action on Invitation
On visiting the invitation link, if anyone is new to Impler, they can create an account or if they already have an account they can simply click on Accept Invitation.
Invitation Link View if a user is not logged In
While clicking on Signup
Email will be automatically filled while going to signup from invitation section.
Take action on the invitation
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
How subscription works?
Get idea about how subscription works in impler. How pricing will be calculated, payment gateway being used internally and how it will affect usage.
Impler provides the most generous way to integrate world-class CSV Excel Import functionality in any application. Impler only considers Imported Records as a metric to collect the amount and not additional parameters like no. of imports and no. of templates.
Working of Subscription in Impler
Impler assigns every user the Starter Plan, which includes 5,000 free records per month. Here’s how the subscription and billing process works:
The Starter Plan Includes 5,000 free records per month. Importing more than 5,000 records incurs a charge relative to $1 for every 10,000 records.
By default, the Starter Plan renews every month. If you have imported more than 5,000 records, you must pay the outstanding amount to renew your subscription. You can choose an appropriate plan to cover this.
You must add a card before purchasing any plan. Adding a card creates a mandate of a certain amount, which helps the user to not provide payment details repeatedly and backend to deduct the amount at intervals.
Plan upgrades take effect immediately. While Plan downgrades occur at the end of the current billing cycle.
Users can cancel their plan anytime. Upon cancellation, the canceled plan does not renew at the end of the billing cycle, and the default Starter Plan is reactivated. Outstanding amounts are deducted at the end of the billing cycle after cancellation.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Runtime Schema
Do you need to import data in columns that are not fixed firsthand? Impler provides a facility to provide schema at the moment of opening the import widget.
View to Create new Account or Sign In for invitation
Create an account to accept invitation
Accept or Decline Invitation
Purpose
Consider you have an ERP application that needs to import sales information. Our system provides a way to add extra information to sales information, like challan-no. Other users might have different columns.
In that case, fixing the import data structure is impossible. So we need to pass schema during run time when the user clicks on Import button to import the data.
You can find relevant implementation for react in and for HTML & HS in
Example Schema
Available properties for schema
Here are the keys
name (required): The name of the column, will be displayed in the import widget during mapping.
key (required): The key of the column, will be used to create an Excel file and match it with available headings in the file.
type (optional): One of the types from String, Number, Date, Email, Regex, Select, and Any to override the existing type for the column.
isRequired (optional): A boolean value indicating whether values in the current column are required.
isUnique (optional): A boolean value indicating whether values in the current column must be unique.
selectValues (optional): Select values indicating what are the possible values when the type is select.
regex (optional): A regular expression to override when the type is regex.
dateFormats (optional): Date formats indicating a list of formats acceptable for the date field. Required when type is Date. For example, ['dd/mm/yyyy','dd/mm/yy']
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Need to import a file that doesn't have a header or data starting after a few rows? Choose to import the file with headers or select the header row from where the data is starting.
How it works?
Open the Importer and select the file you want to import.
Import file
Select Header step will be opened. Which shows the first 15 rows for header selection. You can select the Header row of your choice or continue importing without headers by clicking on File does not have headers.
Mapping will be based on the selected header row. Rows above the header row will not be imported.
In the case of importing files without headers, the first row will be shown in the Mapping Step.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Multiselect Dropdown
The Multiselect feature in Impler allows users to pick multiple values for a single cell. This feature is useful in various scenarios like selecting categories for products, tagging items, and more.
We can enable the Multiselect feature by providing a custom schema with the allowMultiSelect flag in our frontend code.
Sample file generation and format
Impler creates .xlsx and .xlsm files based on the columns' configuration:
.xlsx File: Generated if no columns have Multiselect enabled.
.xlsm File: Generated if any column has Multiselect enabled.
Writing in .xlsm Files
When a column is marked as Multiselect, Impler appends #MULTI to the end of the column name in the Excel file. This allows users to select multiple options in the cell.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Freeze Columns
Freeze columns in excel and editor to better view data while editing and adding records
Three ways to freeze columns
We can freeze columns in many ways. Here is how,
i. Freeze the column while adding a new one
Click on the + button to add a new column.
Provide column Name, Key name and rest of the values based on your choice.
Check Frozen?
ii. Freezing already created column
Click on the Pencil (Edit) icon for any created column.
Check the Frozen? checkbox.
Click on Save.
iii. Freezing column with
We can freeze the column while providing a custom schema too with the isFrozen flag in our frontend code.
Effects on Sample File Generation
The generated sample file will have specified columns freeze on the left side. So they won't gets hidden if we scroll to the right.
Effects on Spreadsheet Editor
While importing data spreadsheet editor freezes two default Checkbox and Sr. No. Columns. Other mentioned columns get frozen as per schema.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Manage Project
Group your Imports into projects to make managing multiple imports easy
Projects in Impler play a vital role in organizing imports effectively. You can invite your peers to the team and collaborate on Imports.
How Projects Work?
Open Projects Modal
Click on your project name on the top left corner of the Impler platform below the Impler logo to open Projects Modal.
Create Project
You can create unlimited projects in Impler. To create a new project write the project name in text input and click on Create. Upon creating a project you will be switched to a new project automatically.
Switch Project
Once the project is created it will be shown on the projects menu. As Owner only you can delete the project.
Only the Project Owner can delete the project.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Column Description
Add description to your columns to help users understand what value to put into column.
Users filling excel sheet often get's confused with "What value will go into this column?", "In which format I need to add phone number?", "What format to follow for date?", etc. We can answer these user questions with Column Descriptions.
How to provide column description?
Description input is available in Column Details Form, which get's opened by clicking on Validations Button.
How to use it? In 5 steps
Leverage Impler capabilites to build rich, scalable and user friendly data import experience
Impler is built around configuring your import once and letting the user import spreadsheet data every time using Widget.
5 Easy Steps
Email Alerts
Impler will send you alert mail for anything that goes wrong during importing data
We heard issues like "I imported data but didn't receive callback", "Imported data is not showing in my application", "Validation code is not working as expected", etc. Also, "imported data not seen in the application", is something no one wants to face.
As a solution, Impler will send alert mail to users in the following scenarios,
Added webhook endpoint is not proper.
Application threw an error while sending imported data over the webhook.
Which opens column modal which has input for column description.
Providing column description
How column description works?
Provided column description gets visible in review step while showing imported data to user.
It's possible to change border of tooltip by providing primaryColor while opening import widget.
Showing column description to user
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
1. Log in to your Account:
Head over to Impler by visiting https://web.impler.io and log in using your credentials
2. Create a New Import:
After logging in, you will land on the dashboard. Click on Create Import which will open the create modal asking you to give the appropriate name to the Import.
Creating new Import
3. Add Columns to Your Import:
Once you've created a new import, you need to add columns to your import spreadsheet. The columns represent the data fields you wish to import.
The image represents a few fields and a button to add a new field.
Click on + to add column to Import
4. Provide API Destination (Optional):
You can send Imported data to your backend application or Bubble.io application.
Enable Webhook destination and provide a REST api endpoint in case you want to send imported data to your application.
Proivde Webhook Destination for Imported Data
5. Import the data:
It's time to import your CSV or Excel file. We can do it in two ways:
Import from Dashboard: You can click on Import the button and the import widget will be opened. Which allows you to use data import functionality without any extra configuration.
Embed Widget into Application: You can embed CSV Excel Import widget into your application too, regardless of which tech stack you're using. Follow the steps mentioned in Snippet section of Importer, to embed a widget into your application. Read more in Importer
Embed Import widget into your application
And that's it! With these five straightforward steps, you are well on your way to revolutionizing your data onboarding process and delivering an exceptional user experience.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Validation code throws an error during execution, which happens when data import is in progress.
Here is the sample mail,
Sample mail sent to user while validation code fails
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
HTML & JS Embed
If you are using a (currently) unsupported client framework, you can use our embedded script. This will show the Widget inside an iframe.
Add Script
You copy this snippet to your code before the closing body tag.
It will add impler variable in window, so we can call its init and show methods later.
Add Import Button
Import widgets get opened when the user clicks on Import button. So let's add an import button,
Initialize Widget
Before the widget gets shown you have to call its init method. So write this code, after added embed script.
Here is the description of what we just did,
generateUuid the function generates UUID which helps add multiple import widgets on the same page.
init method on impler initializes impler widget.
readyCheckInterval calls impler isReady()
Show Widget
After the initialization, when the user clicks on the Import button we will call show method to open the widget,
You can pass more parameters to show a method like schema, data, etc. Have a look at section on React embed.
That's it, your app is now ready to onboard user data into your application.
Customize Texts
You can customize any text in the import widget, here is the sample. A full list of available texts is available at .
Listening to Events
Impler instance provides message an event listener which gets called for various events happening with the widget. Here is how to attach event listener,
eventData follows the { type, value } structure.
type
value
Description
Complete Code Example
in Sample File
You can provide default data to fill in the Sample Excel file that gets generated from the Import widget. Default data act as a placeholder for the user to further add or update the data in the file.
Here is an example of how to provide data to fill in the sample file,
Advanced Validations
You can provide in the column as validations key,
Providing
The schema and output provided in the portal for any import behave as default values for any Import. It's possible to override the default schema and output, to adapt dynamic nature of Import.
Here is an example of how to provide dynamic schema and output,
Passing Extra Parameters
It's an obvious need that we want to pass userId or orgId representing who imported the data. In that case, you can pass that data in an extra parameter.
You can pass string, object, or array in extra. Here is an example of how to do it,
The extra parameters get sent to an application during the webhook call.
Changing Import Title
By default, the Import widget takes the name of the Import to show in the title. But it's possible to change the title from the implementation side too. Helpful to keep the title separate from what the name is given in the web portal.
Here is how,
Programmatically Closing the Import Widget
You can close the import widget programmatically by calling close method on impler instance,
Here is how,
Changing Theme Color
You can pass a primary color to the import widget, which will update the colors of all buttons accordingly to match your app's theme color.
Providing Authentication Header Value
In case the backend endpoint is authenticated with the token, it's possible to provide token value from the implementation side.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Get data delivered straight into your application whenever a user imports a file using Impler.
Once the user completes importing the spreadsheet via the widget, Impler sends the imported data to the callback URL specified in the destination section.
If your callback URL is protected, you can enable header-based authentication. This ensures secure data transfer to your API endpoints.
How to add a Webhook Destination?
To configure a webhook destination in Impler:
Open the Import panel and navigate to the Destination section.
Enable the Webhook option.
Provide the REST API Endpoint of your application.
🔒 Use authHeaderName and authHeaderValue if your endpoint requires authentication.
Chunk Size
You can configure the number of records sent per request by specifying a Chunk Size. This determines how many records Impler will include in a single webhook payload.
Authentication
To secure your API, Impler supports header-based authentication.
Use the authHeaderName field to define the name of the header.
Use the authHeaderValue prop in the import button to define its value.
These values are not visible to end users and are only transmitted when the webhook is triggered.
For integration help, refer to: for React and for HTML & JS Embed.
Rate Limiting & Retry Mechanism
To ensure reliable data delivery and avoid data loss during transient errors or server-side rate limits, Impler supports a configurable retry mechanism. This is particularly useful when your webhook endpoints are subject to rate-limiting or temporary unavailability.
How Retry Works
When a webhook request to your endpoint fails (due to timeouts, rate-limiting responses like 429 Too Many Requests, or other non-2xx errors), Impler will retry the request based on the following two parameters:
Retry Count: Defines how many times Impler will attempt to resend the data after the initial failure.
Retry Interval: The interval (in milliseconds) between each retry attempt.
📝 Note: If not configured, Impler will not retry by default (RetryCount = 0).
Developer Notes
The retries apply per chunk of data sent.
Retries apply only for failed HTTP responses (non-2xx).
If the final retry still fails, the chunk is considered undelivered, and a failure log is recorded.
Webhook Data Format
Name
Description
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Writing effectively into .xlsm files
Step-by-step guide showing how you and your users can handle .xlsm file constraints, while editing into it.
The .xlsm file format includes macro code that enables the Multiselect feature in Impler. Due to varying security protocols on different operating systems, there are specific steps to follow to ensure these macros run effectively.
Windows
Microsoft Excel on Windows restricts macro execution by default due to security concerns. Follow these steps to enable macros and use the Multiselect feature:
Steps to Enable Macros in Excel
Download the Sample File:
First, download the sample file generated by Impler. If any column has Multiselect enabled, it will be in .xlsm format.
By default, Microsoft Excel displays an Security Risk error for such files in its latest versions.
These steps will ensure that the macro code for the Multiselect feature is enabled, allowing you to select multiple options within the specified columns.
Linux
Linux users typically use LibreOffice Calc, which does not run macro code by default. However, you can still work with the Multiselect feature by manually entering options.
Steps for LibreOffice Calc
Open the .xlsm File:
Open the .xlsm file in LibreOffice Calc.
A warning message about macros will appear.
By following these steps, you can effectively use the Multiselect feature in .xlsm files on both Windows and Linux.
Summary
Windows:
Download the .xlsm file.
Mark the file as safe through Properties.
Enable macros in Excel to use the Multiselect feature.
Linux:
Open the .xlsm file in LibreOffice Calc.
Manually type the options in multi-select fields.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Column Warning
The Warning Column feature allows you to show helpful suggestions to users without blocking their data import. Unlike errors that stop the import process, warnings let users proceed while highlighting potential issues.
How it Works
Two Types of Validations
Validation Type
Behaviour
Visual Indicator
Key Benefits
Key Benefit: Users are informed of any issues through warnings, but their uploads aren’t blocked.
Implementation Guide
Basic Structure
Every warning validation function follows this pattern:
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Directly Enter your Data
No need to download Excel, do mapping, review, and complete import. Directly write data into the importer and finish your import in just one step.
Normal Flow
The normal importer flow has a higher number of steps to import the file and follows the below structure,
Download Sample File.
Write data into the file using spreadsheet editing software like Excel, Libre Office Calc, Numbers, etc.
Upload the file in which data is entered.
Select the header row.
Map columns.
Review data and fix invalid data if there is any.
Complete the Import.
This process takes a lot of time and involves many steps in the data import process. We introduced the facility to "Directly enter your data" to reduce the time and effort required to complete the import.
Directly enter your data
Open the Importer and click on Directly enter your data.
The spreadsheet editor will be opened which will show the column names as header and as per column types, columns will be shown. For example, for the date column, a date picker will be shown.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Data Seeding
Populate essential data fields in your Excel samples with Data Seeding. Simplify data input by preloading records, allowing users to build upon or modify data.
Available after impler version 0.9.1
To seed the file that gets downloaded as Sample, one need to pass data in showWidget function, which is exported from the useImpler hook.
This function, when provided with your data, allows Impler to automatically populate sample files with the specified information.
Here is how to do it,
Using the `showWidget` Function
Import the useImpler Hook: Start by importing the useImpler hook from @impler/react into your project. This hook provides access to essential Impler functions.
Initialize Impler: Create an instance of Impler by calling useImpler with the required configuration, including templateId
Benefits at a Glance
Efficient Data Import: Simplify the process of importing relational data by seeding sample file.
Developer-Friendly: Integrate data sources seamlessly into Impler's import workflow.
User-Focused: Enhance the user experience by providing prepopulated sample files for download.
With the Data Seeding feature in Impler, you can save time and effort by automating the generation of sample files.
This is particularly valuable when importing data with complex relationships, ensuring a smooth and efficient data import experience.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Output Customization
Customize output format to receive data in a manner that the system can use.
There are chances that the system which is receiving data is not made or managed by us. But as a plugin or integration, we need to send imported data to that system. In that case, Impler allows changing the output format which follows the system's syntax.
Output Format Sample
Usage Examples
Joining First Name and Last Name
Providing an Object for each value
Passing an Array for value
Output Format works differently for dynamic schema
If you're providing schema runtime from the application, in that case, default provided output isn't taken into consideration. Because columns defined in the output might not match with columns getting imported.
In that case, we need to provide schema runtime. We have listed examples for react in and for HTML & JS versions in .
This output customization capability empowers you to direct imported data to any destination and in any preferred format.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
FAQs
Find answers to most common questions our users have while using Impler
How to get TemplateId, ProjectId, and Access Token?
Open the Import description and go to the Snippet portion of the Import.
Open the last item of the accordion, where you will find the necessary keys.
While making call to my API, do I need to provide our own authorization header value?
Yes, you need to provide your authorization header value, which you can provide from the front end.
If I use Axios in my custom validator, will it pass the cookies from my logged-in user to my server, or is the validator call being made from Impler's servers?
No, logged-in user cookies won't be passed to your server. Validator calls are being made from Impler's servers.
Is there any way to access user uploaded file?
Yes, Impler provides a REST API endpoint to fetch a user-uploaded file. Here is CURL,
You can get :uploadId using Upload Complete event and ACCESS_TOKEN will be available from the Settings panel.
API will send a file with headers Content-Type and
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Base Validations
Utilize default validation options to build your desired data import experience.
List of available validators:
String Validator: This validator ensures that the column value is a string. String and Number are both valid values.
Number Validator: The Number validator verifies that the column value is a valid numeric entry. It only permits numerical values like 12 but will not allow 12.33 and john.
Double Validator: The Double validator verifies that the column value is either a Number or a Number with decimals. Valid values are 12 and 12.5 but john is not valid.
Email Validator: With the Email validator, you can ensure that the column value conforms to a valid email format. Valid values look like [email protected] while values like john and john.com are not valid.
Regex Validator: The Regex validator enables you to define a custom regular expression pattern that the column value must match.
Select Validator: Use the Select validator to restrict column values to a predefined set of options. For instance, you can use it to ensure that a "Gender" column contains only values like "Male" or "Female."
Any Validator: Any validator offers maximum flexibility by allowing any value in the column.
Validator Enhancements
isRequired: Ensures that a value must exist in each cell for the column.
isUnique: Ensures that the value is unique throughout the column.
allowMultiSelect: Accepts multiple values separated by , for the cell.
It's possible to extend validation functionality to adjust according to your needs. Read more in .
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Activity Page
Your hub for tracking and understanding your import activity.
The Activity Page provides a comprehensive overview of your data imports, giving you insights into import statistics, trends, and detailed histories.
Let's explore the various sections and functionalities that the Activity Page has to offer.
1. Overview Statistics
The Activity Page greets you with key statistics that provide a quick snapshot of your data import activity:
Architecture
Guide on various building blocks of Impler, How they communicate and How Impler works?
Impler is built upon scalable architecture to validate and process records of any size.
Separation of concern helps organizing code across various packages, libraries and apps. The idea is that app is divided into various parts, and each one is responsible for a spacific task.
Let's dive deep into building blocks of Impler.
The mental model
Widget Customization
Customise your import widget to match your brand and design system using the AppearanceConfig options.
Total Imports: The count of all imports conducted using Impler.
Total Records: The cumulative number of records imported across all your imports.
Total Error Records: The count of records that encountered errors during the import process.
2. Import Count Trends (Bar Chart)
A graphical representation of the import count over the last seven days is displayed using a bar chart. This visual tool allows you to quickly identify trends and fluctuations in your import activity.
3. Import History Table
The Import History Table presents a paginated view of your import history, facilitating a deeper dive into each import's details. This table consists of the following columns:
Import Id: A unique identifier for each import.
Name: The name associated with the import.
Date: The date on which the import occurred.
Time: The time at which the import was initiated.
Status: The status of the import, categorized as Upload, Mapped, Review, Confirmed, or Completed. The "Completed" status indicates that the imported data has been successfully sent to the application.
Total Records: The total number of records in the import.
Filtering and Insight
The Import History Table offers filtering capabilities, allowing you to narrow down the displayed history by date and import name. This enables you to quickly locate specific imports and track their progress over time.
Import Insights
The Activity Page serves as a valuable resource for gaining insights into your import operations:
Overview: Get a bird's-eye view of your import statistics.
Trends: Identify patterns and trends in your import activity with the import count bar chart.
Detailed History: Dive deep into each import's journey, from initiation to completion.
Error Analysis: Monitor error records to address data quality issues.
Whether you're seeking a quick overview or a comprehensive analysis, the Activity Page equips you with the tools you need to assess your data import processes effectively.
Impler's Activity Page is designed to streamline your import tracking, optimize your workflow, and empower you with data-driven decision-making capabilities.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Define Your Data: In the onShowWidgetClick function, gather the data you want to prefill into the sample file. This data should match the structure and content you expect in the final imported files.
Call showWidget: Pass your data to the showWidget function, which will handle the process of populating the sample files.
Downloading sample file with data: Finally, when user clicks on button with text Import, the Import widget gets opened. Where by clicking on Download sample the user can download the excel file with data provided.
Note - All properties, including the appearance object, are optional. If none are provided, the widget will fall back to its default appearance.
ApperaranceConfig Property with Available Customization Options
Widget Properties:
backgroundColor - Sets the main widget background color
primaryColor - Main brand color used throughout the widget
fontFamily - Font family for all text elements
borderRadius - Corner rounding for all elements
Button Properties:
backgroundColor - Button background color (default state)
textColor - Button text color (default state)
borderColor - Button border color (default state)
buttonShadow - Drop shadow effect
hoverBackground - Background color when hovering
hoverTextColor - Text color when hovering
hoverBorderColor - Border color when hovering
Quick Note
⚠️ Important: We're moving primaryColor inside the appearance object. The old way still works but will be deprecated in future releases.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
const axios = require('axios');
exports.code = async (params) => {
const result = [];
// Loop through each item in the dataset
for (const item of params.data) {
result.push({
index: item.index,
warnings: {
Country: 'Please specify your country',
},
});
}
return result;
};;
import { useImpler } from '@impler/react';
const { showWidget, isImplerInitiated } = useImpler({
projectId: "...",
templateId: "...",
accessToken: "...",
});
function onShowWidgetClick = () => {
// Fetch or generate your data from a relevant source
let data = [ /* Your data here */ ];
showWidget({ data });
}
<button disabled={!isImplerInitiated} onClick={onShowWidgetClick}>
Import
</button>
Widget is the main app where import happens. Widget provides UI to upload, map, validate and reivew data files. Widget gets embedded into iframe using embed script. It communicates with API to accomplish file processing work.
Queue Manager
Queue manager handles processing data. Once user completes file import, the command gets passed to Queue Manager app to start processing data and sending it to application in chunks.
Chunk contains chunked data along with import information. More information on Using Webhook
Authentication
API keys are used to authenticate APIs happening from import widget. Additionally developers can integrate Impler into their application by manually calling Impler API.
SDKs
SDKs removes the need of managing import widget manually. In case of missing SDK developer can take reference of HTML & JS Embedto embed widget into application.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
You can customize the visual appearance of the Impler widget to better match the look and feel of your application. This is achieved by passing an appearance configuration object when initializing the widget (e.g., within the useImpler hook).
The AppearanceConfig Object
The core of customization lies in the AppearanceConfig object. You pass this object to the appearance property during widget initialization.
All customization options are optional. You only need to include the properties you wish to override from the default theme. If the appearance object itself is not provided, the widget will use its default styling.
Available AppearanceConfig Properties:
Property
Type
Usage
The ButtonConfig Object
Both primaryButtonConfig and secondaryButtonConfig accept a ButtonConfig object with the following optional properties to style buttons:
Property
Type
Usage
Reference: Type Definitions
For clarity, here are the TypeScript type definitions:
Widget Customization Examples
You can transform the Impler widget's appearance significantly using the appearance object. Below are a few styled examples showing how you might customize it to match your brand or product design.
By utilizing the appearance object and its nested configurations, you can effectively theme the Impler widget to integrate visually with your application. Remember that all properties are optional, allowing you to customize as much or as little as needed.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Import Excel with Image
Impler allows importing data files with images. Image import is useful in scenarios like Employee data with profile photos, Products with images, or Assets with pictures.
Excel with the Image Import feature is available in the Scale plan only. Feel free to contact us if you want to try it out!
How do I enable Image upload in Import?
The first step for image import is to add or update a column with the Image type. In case providing keep column type as Image and importer will be ready to import images.
How does Image Import work?
Once the import is configured to import data with Image. We can start importing data with Images. Here is the image import flow,
1. Generate a Template with Images,
The first step is to upload all images and generate a template with uploaded image names. All columns with the type Image will appear in Select Column dropdown and Uploaded images will be shown below Upload Image section.
Once all image files are selected, click on Generate Template to generate an Excel file holding the names of all uploaded images.
2. Upload Excel with data and image names.
Clicking on Generate Template will download an Excel file and Importer will move to the Upload section. You can enter data in the downloaded Excel file and select image names for image columns.
It's possible to generate a template again by clicking on Generate Template.
Once selected click on Map Columns.
3. Do mapping for columns
Click on Review Data to verify data getting imported.
4. Review Data
The review step checks if image columns contain the name of the uploaded image. If not shows a validation error.
Click on Re-Review Data to complete the import, once all records are valid.
5. Complete Import
6. Get Imported Data
Imported data will be sent to a webhook with an endpoint to download and access the uploaded file.
7. Download or Access the uploaded file
The download file endpoint is secured using accesskey which is available in Settings section on the left side. Here is the CURL for a review,
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Default Value
Default value facility empowers developers to specify fallback values for empty or missing columns. This ensures data consistency and completeness while receiving the data.
Till the date, if imported spreadsheet contains missing value or any column is not mapped, the response uses {{key}} as placeholder. By utilizing Default Value functionality developer has more control over format of response they will receive.
Setting Default Values
Default value can be applied to columns either at the time of adding column or updating column. Wildcard values like null
Advanced Validations
Validations help you to ensure that data is in the format you want them to be in. A tooltip will be shown for invalid data and you can ensure that errors get resolved before data gets submitted.
An object to customize the appearance of primary action buttons (e.g., "Import", "Continue"). See ButtonConfig details below.
secondaryButtonConfig
ButtonConfig
An object to customize the appearance of secondary action buttons (e.g., "Cancel", "Back"). See ButtonConfig details below.
hoverTextColor
string
The text color when the mouse hovers over the button.
hoverBorderColor
string
The border color when the mouse hovers over the button.
buttonShadow
string
Adds a CSS box-shadow to the button (e.g., '0 2px 4px rgba(0,0,0,0.1)').
primaryColor
string (Depricated)
Sets the main theme color used for accents, highlights, and often the default primary button background.
fontFamily
string
Specifies the font family for the text within the widget. Use standard CSS font-family values (e.g., 'Inter', sans-serif, 'Arial', Helvetica, sans-serif).
borderRadius
string
Controls the roundness of corners for elements like the main widget container and buttons. Use standard CSS border-radius values (e.g., '4px', '10px', '0.5rem').
widget
object
Contains properties to style the main widget container.
backgroundColor (string, optional): Sets the background color of the main widget area.
backgroundColor
string
The background color of the button in its normal state.
textColor
string
The text color of the button in its normal state.
borderColor
string
The border color of the button in its normal state.
hoverBackground
string
The background color when the mouse hovers over the button.
curl --location --request GET 'https://api.impler.io/v1/upload/66b759d087a854c817cd3e98/asset/logo-icon.png' \
--header 'accesskey: <ACCESS_TOKEN>'
,
undefined
can also be used, which available in the dropdown.
Means developer can choose one of these predefined values or write default value as a string of their choice.
null: Represents the null value.
undefined: Represents an undefined value.
Empty String: Represents an empty string.
Empty Array ([]): Represents an empty array.
Boolean true: Represents the boolean value true.
Boolean false: Represents the boolean value false.
While providing custom schema you can mention with defaultValue key and put your desired string or appropriate value from mentioned table.
Label
Value
null
<<null>>
undefined
<<undefined>>
Empty String
<<>>
Empty Array ([])
<<[]>>
Boolean true
<<true>>
When default value gets applied?
The provided default value is used when imported data gets sent to application as response. The default value will be applied to column when,
Column Not Required and Not Selected During Mapping:
When a column is not marked as required, and the user chooses not to select the column during the mapping phase, the default value will be used in response.
Column Not Required and Contains Empty Value:
When a column is not marked as required, and the column contains an empty value, the default value will be applied to fill the gap.
Web portal GUI makes it easy to assign default value to column. Based on needs you can provide default value while providing schema during runtime too.
The Default Value functionality provides flexibility and control to developers when importing data. Whether dealing with optional columns or handling empty values, this feature enhances the overall data import experience.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Validates that field's values for Number and Double columns fall within a min and max values. Either min, max or both must be defined. Values are inclusive.
Name
Value
Is Required
validate
range
min
max
errorMessage
Length
Validates that field's value for String column falls within min and max number of characters.
Either min, max or both must be defined. Values are inclusive.
Name
Value
Is Required
validate
length
min
max
errorMessage
Unique Across Multiple Fields
Validate uniqueness across multiple fields. To use it, place a unique_with validation on each field that you want to be part of the uniqueness validation, all sharing the same uniqueKey.
Name
Value
Is Required
validate
unique_with
uniqueKey
errorMessage
Here is an example set of fields using unique_with validations used to validate that the combination of department code and employee Id fields are unique.
Here is the example of unique_with validation in action,
Checking uniqueness of Employee No using unique_with validation
Adding Validations
From Platform
Click on Validations while adding column or click on Edit to edit the column.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Custom Validation
Write your own validation code, making it possible to perform complex checks, such as validating data against external databases or APIs.
Available after impler version 0.9.1
To implement custom validation logic, you can use the code editor provided in the Validator tab of the Import Details page.
Your custom validation function should adhere to this structure:
The code function must have the name code, and it can return an array of error records if validation failures occur. Impler will call this code function when performing custom validation.
Parameters provided to the `code` Function
The params object provided to your custom validation function contains essential information about the import process and the data being validated. It follows this structure:
uploadId is the id of import happening at the moment.
extra is the string, number or json provided at the time of import.
Returned Error Records
Error records returned from your custom validation code should follow this structure:
In the case of all records passing validation, return an empty array [].
Example, Validating data against database data
Here's an example of how to validate data against data from a database using the Axios library:
Features
Access to variables inside code editor
Developers can access schema keys by pressing Ctrl + Space to display a list of available variables and selecting from it.
Additionally, the suggestion box contains variables available in params, such as params.uploadId, params.fileName, and more.
Performing HTTP calls
Your custom validation code can make HTTP calls using libraries like Axios. For example, you can retrieve data from your own API and validate it against the imported data.
Validation execution in chunks
The custom code function is executed in chunks, typically in batches of 500 records.
For example, if you are validating 10,000 records, the function will be called 20 times to validate the data in manageable segments.
Combining with static validation
Error records generated from your custom validation code are merged with errors generated from Impler's static validation processes, creating a comprehensive error report.
Scalable Architecture
Impler's custom validation functionality is built on a scalable architecture, allowing you to handle and validate large datasets, even in the millions.
With custom validation in Impler, you have the flexibility to implement intricate validation logic, ensuring data integrity and quality in your import processes.
This feature empowers you to customize your imports to meet your specific needs, making complex data imports more accessible and efficient.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
React Embed
Using @impler/react package you can embed CSV Excel Importer into your application with just few lines of code.
Let's do a quick review of how to use @impler/react in your application.
Add Script
You copy this snippet to your code before the closing body tag.
It will add impler variable in window, so you can call its init and show method.
Install the Package
Add @impler/react in your application by running the following command.
Add Import Button
@impler/react provides headless useImpler hook that you can use to show an import widget in your application.
isImplerIntiated becomes true when the import widget is ready to open and import data. It remains false when there are some errors with the provided values. Errors get logged in the console panel of the browser.
Customize Texts
You can customize any text in the import widget, here is the sample. A full list of available texts is available at .
Listening for Events
Prop
Type
Description
Usage Example
Applying App's Color Scheme
Your application may be developed by keeping dark and light modes in mind. So to let the Import widget show the widget overlay properly, you need to pass colorScheme in showWidget function.
Allowed values for colorScheme are light or dark.
in Sample File
You can provide default data to fill in the Sample file that gets generated from the Import widget. Default data act as a placeholder for the user to further add or update the data.
Here is an example of how to provide data to fill in the sample file,
Providing
The schema and output provided in the portal for any import behave as default values for any Import. It's possible to override the default schema and output, to adapt dynamic nature of Import.
Here is an example of how to provide dynamic schema and output,
Advanced Validations
You can provide in the column as validations key,
Using Typescript
If you're using typescript, you can leverage typescript types, like,
Passing Extra Parameters
It's an obvious need that we want to pass userId or orgId representing who imported the data. In that case, you can pass that data in an extra parameter.
You can pass string, object, or array in extra. Here is an example of how to do it,
The extra parameters get sent to an application during the webhook call.
Programmatically Closing Import Widget
Impler's import widget provides closeWidget a method that closes the import widget. Useful to close the import widget once data is imported.
Changing Import Title
By default, the Import widget takes the name of the Import to show in the title. But it's possible to change the title from the implementation side too. Helpful to keep the title separate from what the name is given in the web portal.
Here is how,
Changing Theme Color
You can pass a primary color to the import widget, which will update the colors of all buttons accordingly to match your app's theme color.
Providing Authentication Header Value
In case the backend endpoint is authenticated with the token, it's possible to provide token value from the implementation side. You can provide a string or async function that returns the token value.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Text Customization
Customize Import Widget to match tone of your application. Use this feature to update text or localize the Import Widget
Text customization is possible from the application using (React) and (HTML & JS). With this powerful feature, you can update every text on the Import widget. Useful for updating text on import widgets or even implementing localization.
Available Texts
Although you may not need to update every text on the import widget. Here is the complete text object which is used in Impler.
Texts contain variables, Like
Widget Security (Allowed Domains)
Restrict which browser-based requests can use your API key and widget by whitelisting specific domains.
By default, your Impler API key can be used from any origin. When your API key is embedded in a frontend app, it's visible to anyone who inspects the page source — meaning someone could copy it and embed your Impler widget on their own site. Allowed Domains prevents this by telling Impler which browser origins are permitted to use the key.
Important: This restriction applies only to browser-originated requests where an Origin or Referer header is present. Server-to-server API calls (e.g. from your backend, CI pipelines, or scripts) do not send these headers and are not affected by this setting, regardless of what domains are configured.
Data Migrations
Learn how to update your database data through migrations.
Occasionally, Impler might add features that call for data or database schema alterations. This typically occurs when a feature requires certain data to be present on a database entity to function. To make these modifications to your database, you can utilize migrations.
Running Migrations
To run data migrations, enter the following sequence of commands in your terminal from the repository root:
Certain features can require more than one migration; in that case, you must do each migration in the following order.
When doing manual import of data the most commonly used texts are mentioned below. You can customize the same texts if you want to change language.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
[
{
index: 1,
errors: {
email: 'Email is already in use.'
}
}
]
const axios = require('axios');
exports.code = async (params) => {
let errorRecords = [];
let users = await axios.get('https://your-api.com/users');
let userEmails = users.map(user => user.email);
for(let item of params.data) {
let error = {
index: item.index,
errors: {},
}
if(userEmails.includes(item.record.email)) {
error.errors['email'] = "Email must be unique."
}
errorRecords.push(error);
}
return errorRecords;
}
{
COMMON: {
SORRY: 'Sorry!',
CANCEL: 'Cancel',
CLOSE_WIDGET: 'Close',
UPLOAD_AGAIN: 'Upload Again',
},
STEPPER_TITLES: {
GENERATE_TEMPLATE: 'Generate Template',
UPLOAD_FILE: 'Upload',
MAP_COLUMNS: 'Map Columns',
REVIEW_DATA: 'Review',
COMPLETE_IMPORT: 'Complete',
CONFIGURE_JOB: 'Configure',
SCHEDULE_JOB: 'Schedule',
CONFIRM_JOB: 'Confirm',
},
FILE_DROP_AREA: {
DROP_FILE: 'Drop and drop a file here or ',
BROWSE_FILE: 'Browse from computer',
IMAGE_FILE_SIZE:
'Image size should be less than 5 MB. Supported formats are PNG, JPG and JPEG.',
BRING_FILE: 'Bring any .csv or .xlsx file here to start Import',
FILE_SELECTED: 'File selected successfully',
},
'PHASE0-1': {
IMPORT_FILE: 'Import File',
GENERATE_TEMPLATE: 'Generate Template',
IMAGE_INFO_TITLE: 'Generate template with images',
IMAGE_INFO_SUBTITLE:
'Drag and drop images below for image columns and generate a template file containing names of uploaded images.',
},
PHASE1: {
SELECT_TEMPLATE_NAME: 'Template',
SELECT_TEMPLATE_NAME_PLACEHOLDER: 'Select Template',
SELECT_TEMPLATE_REQUIRED_MSG: 'Please select a template from the list',
SELECT_SHEET_NAME: 'Select sheet to Import',
SELECT_SHEET_NAME_PLACEHOLDER: 'Select Excel sheet',
SELECT_SHEET_CONFIRM: 'Select',
SELECT_SHEET_REQUIRED_MSG: 'Please select sheet from the list',
DOWNLOAD_SAMPLE: 'Download sample',
GENERATE_TEMPLATE: 'Generate Template',
SEE_MAPPING: 'See Mapping',
SELECT_FILE_NAME: 'Select a file',
SELECT_FILE_REQUIRED_MSG: 'Please select a file',
SELECT_FILE_FORMAT_MSG:
'File type not supported! Please select a .csv or .xlsx file.',
TEMPLATE_NOT_FOUND_MSG:
"We couldn't find the template you're importing! Please check the passed parameters.",
INCOMPLETE_TEMPLATE_MSG:
'This import does not have any columns. Please try again after some time!',
},
PHASE2: {
REVIEW_DATA: 'Review Data',
IN_SCHEMA_TITLE: 'Column in schema',
IN_SHEET_TITLE: 'Column in your sheet',
MAPPING_NOT_DONE_TEXT: 'Not Mapped',
MAPPING_DONE_TEXT: 'Mapping Successful',
MAPPING_FIELD_PLACEHOLDER: 'Select Field',
},
PHASE3: {
COMPLETE: 'Complete',
EXPORT_DATA: 'Export Data',
RE_REVIEW_DATA: 'Re-Review Data',
ALL_RECORDS_VALID_TITLE: ' All records are found valid!',
ALL_RECORDS_VALID_DETAILS:
'All {total} row(s) found valid! Would you like to complete the Import?',
LABEL_ALL_RECORDS: `All {records}`,
LABEL_VALID_RECORDS: `Valid {records}`,
LABEL_INVALID_RECORDS: `Invalid {records}`,
REPLACE: 'Replace',
FIND_REPLACE: 'Find and Replace',
ALL_COLUMNS_LABEL: 'All Columns',
FIND_LABEL: 'Find',
FIND_PLACEHOLDER: 'Empty Cell',
REPLACE_LABEL: 'Replace',
IN_COLUMN_LABEL: 'In Column',
CASE_SENSITIVE_LABEL: 'Case Sensitive',
MATCH_ENTIRE_LABEL: 'Match Entire Cell',
},
PHASE4: {
TITLE: 'Bravo! {count} rows have been uploaded',
SUB_TITLE:
'{count} rows have been uploaded successfully and currently is in process, it will be ready shortly.',
UPLOAD_AGAIN: 'Upload New File',
},
AUTOIMPORT_PHASE1: {
MAPCOLUMN: 'Map Column',
},
AUTOIMPORT_PHASE2: {
SCHEDULE: 'Schedule',
IN_SCHEMA_TITLE: 'Column in schema',
IN_FEED_TITLE: 'Key in your RSS feed ',
},
AUTOIMPORT_PHASE3: {
CONFIRM: 'Confirm',
INVALID_CRON_MESSAGE:
'Expression values are incorrect. Please update values as per valid values below!',
},
DELETE_RECORDS_CONFIRMATION: {
TITLE: `{total} rows will be deleted. Are you sure?`,
DETAILS: 'This action cannot be undone.',
CONFIRM_DELETE: 'Yes',
CANCEL_DELETE: 'Cancel',
},
CLOSE_CONFIRMATION: {
TITLE: `Are you sure? You will lose your work in progress.`,
DETAILS: 'Your import is in progress, clicking <b>Yes</b> will reset it.',
CONFIRM_CLOSE: 'Yes',
CANCEL_CLOSE: 'No',
},
}
{
"COMMON": {
"SORRY": "Sorry!",
"CANCEL": "Cancel",
"CLOSE_WIDGET": "Close",
"UPLOAD_AGAIN": "Upload Again"
},
"STEPPER_TITLES": {
"GENERATE_TEMPLATE": "Generate Template",
"UPLOAD_FILE": "Upload",
"MAP_COLUMNS": "Map Columns",
"REVIEW_DATA": "Review",
"COMPLETE_IMPORT": "Complete",
"CONFIGURE_JOB": "Configure",
"SCHEDULE_JOB": "Schedule",
"CONFIRM_JOB": "Confirm"
},
"FILE_DROP_AREA": {
"DROP_FILE": "Drop and drop a file here or ",
"BROWSE_FILE": "Browse from computer",
"IMAGE_FILE_SIZE": "Image size should be less than 5 MB. Supported formats are PNG, JPG and JPEG.",
"BRING_FILE": "Bring any .csv or .xlsx file here to start Import",
"FILE_SELECTED": "File selected successfully"
},
"PHASE1": {
"SELECT_TEMPLATE_NAME": "Template",
"SELECT_TEMPLATE_NAME_PLACEHOLDER": "Select Template",
"SELECT_TEMPLATE_REQUIRED_MSG": "Please select a template from the list",
"SELECT_SHEET_NAME": "Select sheet to Import",
"SELECT_SHEET_NAME_PLACEHOLDER": "Select Excel sheet",
"SELECT_SHEET_CONFIRM": "Select",
"SELECT_SHEET_REQUIRED_MSG": "Please select sheet from the list",
"DOWNLOAD_SAMPLE": "Download sample",
"GENERATE_TEMPLATE": "Generate Template",
"SEE_MAPPING": "See Mapping",
"SELECT_FILE_NAME": "Select a file",
"SELECT_FILE_REQUIRED_MSG": "Please select a file",
"SELECT_FILE_FORMAT_MSG": "File type not supported! Please select a .csv or .xlsx file.",
"TEMPLATE_NOT_FOUND_MSG": "We couldn't find the template you're importing! Please check the passed parameters.",
"INCOMPLETE_TEMPLATE_MSG": "This import does not have any columns. Please try again after some time!"
},
"PHASE2": {
"REVIEW_DATA": "Review Data",
"IN_SCHEMA_TITLE": "Column in schema",
"IN_SHEET_TITLE": "Column in your sheet",
"MAPPING_NOT_DONE_TEXT": "Not Mapped",
"MAPPING_DONE_TEXT": "Mapping Successful",
"MAPPING_FIELD_PLACEHOLDER": "Select Field"
},
"PHASE3": {
"COMPLETE": "Complete",
"EXPORT_DATA": "Export Data",
"RE_REVIEW_DATA": "Re-Review Data",
"ALL_RECORDS_VALID_TITLE": " All records are found valid!",
"ALL_RECORDS_VALID_DETAILS": "All {total} row(s) found valid! Would you like to complete the Import?",
"LABEL_ALL_RECORDS": "All {records}",
"LABEL_VALID_RECORDS": "Valid {records}",
"LABEL_INVALID_RECORDS": "Invalid {records}",
"REPLACE": "Replace",
"FIND_REPLACE": "Find and Replace",
"ALL_COLUMNS_LABEL": "All Columns",
"FIND_LABEL": "Find",
"FIND_PLACEHOLDER": "Empty Cell",
"REPLACE_LABEL": "Replace",
"IN_COLUMN_LABEL": "In Column",
"CASE_SENSITIVE_LABEL": "Case Sensitive",
"MATCH_ENTIRE_LABEL": "Match Entire Cell"
},
"PHASE4": {
"TITLE": "Bravo! {count} rows have been uploaded",
"SUB_TITLE": "{count} rows have been uploaded successfully and currently is in process, it will be ready shortly.",
"UPLOAD_AGAIN": "Upload New File"
},
"DELETE_RECORDS_CONFIRMATION": {
"TITLE": "{total} rows will be deleted. Are you sure?",
"DETAILS": "This action cannot be undone.",
"CONFIRM_DELETE": "Yes",
"CANCEL_DELETE": "Cancel"
},
"CLOSE_CONFIRMATION": {
"TITLE": "Are you sure? You will lose your work in progress.",
"DETAILS": "Your import is in progress, clicking <b>Yes</b> will reset it.",
"CONFIRM_CLOSE": "Yes",
"CANCEL_CLOSE": "No"
}
}
Function that gets called when widget is closed
onDataImported
(data) => void
Function that gets called with all imported data. Read more at
onUploadStart
(value) => void
Function that get's called when user starts upload
onUploadTerminate
(value) => void
Function that get's called when user leaves spreadsheet import in between
onUploadComplete
(value) => void
Function that gets called when user completes the import
When an allowed domains list is configured, Impler inspects the Origin (or Referer) header on each incoming request:
If the header is absent (typical of server-to-server calls) → request proceeds normally
If the header is present and matches an allowed domain → request proceeds normally
If the header is present but not on the list → request is rejected with 401 Unauthorized
If no domains are configured at all, all origins are permitted — this is the default, so existing integrations are unaffected.
Who Can Manage Allowed Domains?
🔐 Only the project creator can update the allowed domains list.
Impler enforces this at the API level. When saving allowed domains, the system validates that the authenticated user is the same user who originally created the project. Team members who were invited to the project cannot modify this setting, even if they have other access.
This ensures that a sensitive security configuration like domain restrictions can only be changed by the person who owns the project — preventing collaborators from accidentally or maliciously unlocking access to untrusted origins.
If you are a team member and need to update this setting, contact the project owner.
Configuring Allowed Domains
Go to your project's Settings page in the Impler web app.
Click the Widget Security tab.
In the Allowed Domains input, type a domain (e.g. https://yourapp.com) and press Enter to add it.
Add as many domains as needed.
Click Save Domains.
Note: Only http:// and https:// origins are accepted. Domains are matched on protocol + host — so https://yourapp.com and https://yourapp.com/ are treated as the same entry, but http://yourapp.com and https://yourapp.com are treated as different origins.
Example
Say your widget is embedded on https://app.yourcompany.com. Configure it like this:
Now any API request made with your project's API key from https://malicious-site.com will be rejected automatically, while your widget continues to work normally.
If you have multiple environments or domains, add all of them:
Behavior Reference
Scenario
HTTP Status
Result
No allowed domains configured
All origins permitted
Request has no Origin/Referer header (server-to-server)
Always allowed, restriction does not apply
Origin matches an allowed domain
Request allowed
Origin does NOT match any allowed domain
Clearing All Allowed Domains
To go back to allowing all origins, remove all entries from the Allowed Domains input and click Save Domains. An empty list disables the restriction.
Frequently Asked Questions
Does this affect server-to-server API calls?
No. The restriction only applies to requests that carry an Origin or Referer header, which browsers automatically attach. Calls from your server, scripts, or tools like Postman do not include these headers and are never blocked.
Can I add localhost for local development?
Yes. Add http://localhost:3000 (or whichever port you use) as an allowed domain during development and remove it before going to production.
What happens if I misconfigure and lock myself out?
You can always update the allowed domains list from the Impler dashboard — the settings UI is authenticated via your user session, not the API key, so it remains accessible regardless.
I'm a team member but I can't change the Widget Security settings. Why?
This setting is restricted to the project creator only. Reach out to the person who originally created the project to make changes.
Migrations History
Below you will find a list of migrations introduced in previous versions of Impler, alongside the migration path to use in the script above.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
What do you need to run Impler locally and how to perform the setup?
Requirements
Node.js version v18.13.0
MongoDB
RabbitMQ
localstack (required for storing files)
(Optional) pnpm - Needed if you want to install new packages
You can also run docker containers for MongoDB, RabbitMQ, and Localstatck.
Setup the project
After installing the required services on your machine, you can clone and set your forked version of the project:
Fork . Clone or download your fork to your local machine.
Run the initial setup command npm run setup:project to install and build all dependencies.
Run the project locally using npm run start:dev
The npm run start:dev will start all of the services in parallel including APIs and Widget clients. if you only want to run parts of the platform, you can use the following run commands from the root project.
start:api - Starts the API in watch mode
start:dal - Builds the Data Access Layer package in watch mode
start:embed - Serves the embed script via HTTP, which is required to open the widget
You can run pnpm start:<APP> command one by one too, in case you want to run applications separately.
Set up your environment variables
The command npm run setup:project creates default environment variables that are required to run Impler in a development environment. You can change them based on your requirements. These are all the available environment variables:
API Backend
JWT_SECRET - The secret token used to create jsonwebtoken.
NODE_ENV
Queue Manager
NODE_ENV - The environment of the app. Possible values are: dev, prod, and local
RABBITMQ_CONN_URL
Widget
REACT_APP_API_URL - The base URL of the API. Example, http://localhost:3000
REACT_APP_ENVIRONMENT
Web
NEXT_PUBLIC_API_BASE_URL - The base URL of API. Example, http://localhost:3000
NEXT_PUBLIC_EMBED_URL - Full url of embed script. Example, http://localhost:4701/embed.umd.min.js
Running Tests
Writing tests are currently In Progress. You can test packages or apps using appropriate CLI commands:
API
To run the API tests, run the following command:
Ports used by services when the project spins up
3000 - API
4701 - Embed
3500 - Widget
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
npm run setup:project
cd apps/api
npm run migration -- ./src/migrations/<MIGRATION_PATH>.ts
# e.g. npm run migration -- ./src/migrations/update-date-formats/update-date-formats.migration.ts
Want to let your users easily import data from spreadsheets directly into your Bubble application? Impler provides a smooth, user-friendly data import experience. This guide will walk you through inte
Before You Start: Prerequisites
Bubble Paid Plan: You must have a paid Bubble plan. The Bubble Data API, which Impler uses to push data, is only available on paid plans.
Impler Account: You'll need an account with Impler. Sign up or log in at .
i. Prepare Your Bubble App
First, we need to set up the data structure in Bubble and enable the API for Impler to connect.
Go to Data Tab: In your Bubble editor, navigate to the "Data" tab.
Select Data Types: Ensure you have the "Data types" sub-tab selected.
Define/Verify Your Data Type:
Important: Add at least one entry (row) manually to this data type.
ii. Enable Bubble Data API & Get Key
Go to Settings Tab: Navigate to the Settings tab in your Bubble editor.
Go to API Sub-Tab: Click on the API sub-tab.
Enable Data API: Scroll down to the Public API endpoints
2. Set Up Your Import Project
Now, let's configure Impler to receive data and send it to your Bubble app.
2.1) Create an Import
Log in to Impler: Go to and log in.
Create New Import: Click the Create Import button.
Name Your Import: Give it a clear name (e.g., "Bubble Employees Import") and click Create & Continue
2.2) Configure Bubble.io as the Destination
Go to Destination Tab: Inside your newly created import, click on the Destination tab.
Enable Bubble.io: Find the "Bubble.io" option and toggle it ON.
Fill in Bubble App Details:
2.3) Map Columns (Automatic)
Click "Map Columns": After saving the destination, click the "Map Columns" button (often located near the Bubble.io destination settings).
Auto-Mapping: Impler will attempt to automatically detect the fields from your Bubble Data Type and map them. Review the mappings to ensure they look correct. You can typically adjust these mappings later in the main Impler schema editor if needed.
3. Install the Impler Plugin
Let's add the importer interface to your Bubble app.
3.1) Install the Impler Plugin
Go to Plugins Tab: In your Bubble editor, go to the "Plugins" tab.
Add Plugins: Click the "+ Add plugins" button.
Search: Search for "CSV Excel Import Plugin Impler".
3.2) Add the Impler Element to Your Page
Go to Design Tab: Navigate to the page where you want the import button/functionality.
Find Impler Element: In the "Visual Elements" section on the left panel, find "CSVExcelImporter" (the name might vary slightly based on the plugin version).
Drag onto Page: Drag and drop this element onto your page. Note: This element is usually invisible to the end-user; it just provides the necessary functions. You can place it anywhere, even outside the visible page area if you prefer.
3.3) Get Your Impler Project Credentials
Go Back to Impler: Return to your Impler project () and open the importer.
Click Integrate: Find and click the Integrate button (in the top-right of your Importer).
Copy Credentials: A modal or section will appear showing:
3.4) Configure the Impler Element in Bubble
Select Impler Element: Back in your Bubble editor (Design tab), double-click the CSVExcelImporter element you added in Step 3.2 to open its properties editor.
Paste Credentials: Paste the projectId, templateId, and accessToken you copied from Impler into the corresponding fields in the element's properties panel.
3.5) Initialize the Importer (Workflow)
We need to tell the Impler element to get ready when the page loads.
Go to the Workflow Tab: In your Bubble editor, switch to the "Workflow" tab.
Create Page Load Event: Click "Click here to add an event..." and choose "General" -> "Page is loaded".
Add Initialize Action: Click "Click here to add an action...", choose "Element Actions" -> "Initialize Importer" (the action name might vary slightly, select the one related to your CSVExcelImporter element).
3.6) Trigger the Importer (Workflow)
Users need a way to open the importer, typically via a button.
Add a Button: Go back to the "Design" tab and add a standard Bubble Button element to your page. Label it something like "Import Data" or "Upload CSV".
Add Button Workflow: Select the button and click "Start/Edit workflow".
Add Open Widget Action: Click "Click here to add an action...", choose "Element Actions" -> "Open Import Widget" (again, select the action associated with your CSVExcelImporter element).
You're ready to test! Preview your Bubble page. Clicking the "Import Data" button should now open the Impler import widget, ready for your users to upload their files.
4. Optional Advanced Configuration
4.1: Associating Imported Data with a User (UserId)
If you want to link the imported data to the specific Bubble user who uploaded it (e.g., storing the user on each imported Employee record):
In Bubble (Plugin Element):
Select the CSVExcelImporter element in the Design tab.
In its properties, find the User Id field.
4.2) Customizing Importer Appearance (Theming)
In Bubble (Plugin Element):
Select the CSVExcelImporter element in the Design tab.
In its properties, find the Primary Color field.
4.3) Customizing Widget Texts
You can fully customize the text content displayed by the Impler widget to better align with your app’s tone, language, and user expectations.
Whether you want to:
Add custom messages
Localize labels and placeholders to a different language
Adjust text for a friendlier user experience
This is especially useful if you're building for international users or want to provide more context during the data import process.
To learn how to customize widget texts, refer to the detailed guide in the following section:
4.4)Advanced Widget Customization (Bubble.io)
The Impler importer widget supports full theming so you can match it to your app’s look and feel. In Bubble.io using the Appearance field on the plugin element. This field accepts a JSON configuration that controls colors, fonts, borders, and button styles.
How to Apply Custom Styling
Go to the Workflow tab in your Bubble app.
Select the step where you trigger Start Import (or similar) from the CSVExcelImporter plugin.
In the plugin action settings, find the Appearance or Theme field.
That's it! You've now integrated the Impler data importer into your Bubble application. Your users can now benefit from a streamlined way to upload data via CSV or Excel files. Remember to test thoroughly with different file types and data variations.
If you have any questions, suggestions, or comments. Feel free to reach out to us over . We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
Angular Embed
Using @impler/angular package you can embed CSV Excel Importer into your application with just few lines of code.
Here is the step-by-step guide to embed CSV Excel Importer into your angular application using @impler/angular.
Add Script
You copy this snippet to your code before the closing body tag.
It will add impler
Identify the Data Type you want to import data into (e.g., Employees, Products, Contacts).
Make sure this Data Type has all the necessary fields you want to import (e.g., Full Name (text), Email (text), Date of Birth (date), Social Security Number (text)). Create any missing fields using the "Create a new field" button.
Crucially: This Data Type must be set to Publicly visible. Impler needs this permission to see the structure. Check the privacy rules for this data type if needed, but the type definition itself needs to be discoverable.
section. Check the box labeled
Enable Data API
.
Expose Your Data Type: In the list below Enable Data API, find the Data Type you prepared in Step 1.1 (e.g., Employees) and check the box next to it. This allows API access specifically for this data type.
Generate API Private Key: Scroll further down to "API Tokens".
Enter a descriptive label for your key (e.g., "Impler Key").
Click "Generate a new API token".
Bubble will generate a Private key. Copy this key immediately and save it somewhere secure. You will need it shortly, and Bubble won't show it to you again.
Bubble App Name: Enter the name of your Bubble app. This is the part before .bubbleapps.io in your app's URL (e.g., if your app is mycoolapp.bubbleapps.io, enter mycoolapp).
Environment: Choose production (for your live app) or development (for your test version).
Custom Domain Name (Optional): If your app uses a custom domain (e.g., app.mycompany.com), enter it here. Otherwise, leave it blank.
API Private Key: Paste the Private key you generated and saved from Bubble (Step 1.2).
Datatype Name: Enter the exact name of the Bubble Data Type you prepared (e.g., Employees). Case-sensitivity might matter, so match it precisely.
Test and Save: Click "Test and Save". Impler will attempt to connect to your Bubble app using the details provided. Fix any errors if they occur.
Install: Find the correct plugin and click "Install", then "Done".
projectId
templateId
accessToken
Copy these three values.
Select Element: In the action properties, make sure the correct CSVExcelImporter element is selected.
Select Element: Ensure the correct CSVExcelImporter element is selected in the action properties.
Use Bubble's dynamic data capabilities to insert the relevant user ID. This is often Current User's unique id.
Configuring User Id
In Impler (Destination Output):
Go to your Impler project settings -> Destination tab.
Find the output schema or transformation settings (this might look like a code editor).
You need to tell Impler to include the User ID it receives from the plugin. Add a field mapping like this: "user": "{extra.userId}" (or potentially "Creator": "{extra.userId}" if your Bubble field is named Creator and is of type User). The exact syntax might depend on Impler's current interface, but the principle is to map the incoming extra.userId to the correct Bubble User field. Important: The field name on the left (user or Creator) MUST match the field name in your Bubble Data Type that holds the user information.
Set a hex color code (e.g., #FF0000 for red) to customize the theme of the Impler widget to match your app's branding.
Paste your custom theme as a single-line JSON object.
Making sure that at least one entry is exist in datatype
Click on "Create Import" button
Give appropriate name in create Import for
Bubble app configuration
CSV Excel Import Plugin by Impler on Bubble.io
Adding Importer on UI
Click on Integrate to open the integration modal
Get the ProjectId, TemplateId and Access Token
Configuring Importer with Credentials from Impler Application
Workflow Initialize Importer on Page Load
Add Button and Workflow
Open Import Widget on Button Click
Providing Primary Color to the Importer
Providing the CUstom Texts for the Import Widget
Adding The appereance config according to your app's style
variable in
window
, so you can call its
init
and
show
method.
Install the Package
Add @impler/angular in your application by running the following command.
Use Impler Service
@impler/angular provides ImplerService that you can use to initialize and show an importer to your application.
Customize Texts
You can customize any text in the import widget, here is the sample. All customizable texts are available at Available Texts.
Listening for Events
Event Name
Data Type
Description
UPLOAD_STARTED
Upload Partial Information
An event that gets triggered when a user starts the upload.
UPLOAD_TERMINATED
Upload Partial Information
An event that gets triggered when a user leaves import in the middle.
UPLOAD_COMPLETED
Upload Information
An event that gets triggered when a user completes the import.
Usage Example
Applying App's Color Scheme
Your application may be developed by keeping dark and light modes in mind. So to let the Import widget show the widget overlay properly, you need to pass colorScheme in showWidget function.
You can provide default data to fill in the Sample file that gets generated from the Import widget. Default data acts as a placeholder for the user to add or update the data further.
Here is an example of how to provide data to fill in the sample file,
The schema and output provided in the web.impler.io portal for any import behave as default values for any Import. It's possible to override the default schema and output, to adapt a dynamic nature of Import.
Here is an example of how to provide dynamic schema and output,
If you're using typescript, you can leverage typescript types, like,
Passing Extra Parameters
It's an obvious need that we want to pass parameters like userId or orgId representing who imported the data. In that case, you can pass that data in an extra parameter.
You can pass string, object, or array in extra. Here is an example of how to do it,
The extra parameters get sent to an application during the webhook call.
Programmatically Closing Import Widget
Impler's import widget provides closeWidget a method that closes the import widget. Useful to close the import widget once data is imported.
Changing Import Title
By default, the Import widget takes the name of the Import to show in the title. But it's possible to change the title from the implementation side too. Helpful to keep the title separate from what the name is given in the web portal.
Changing Theme Color
You can pass a primary color to the import widget, which will update the colors of all buttons accordingly to match your app's theme color.
Providing Authentication Header Value
In case the backend endpoint is authenticated with the token, it's possible to provide token value from the implementation side. You can provide a string or async function that returns the token value.
If you have any questions, suggestions, or comments. Feel free to reach out to us over Discord. We’re constantly improving to deliver the best Data Importer for your product, and we value your input.
