Using Per-Customer Customization Overrides

How to set up OneSchema customizations via the SDK

Customization Overrides

Customizations can be configured via the customizationOverrides property in the SDK as well as via the OneSchema admin dashboard.

When to override

  • Updating branding options for specific customers.

If you are using our SDK to initialize your importer, pass in customizationOverrides as part of the OneSchemaLaunchParams.

If you are using the API, pass in customization_overrides to the Create an Embedded Session endpoint.

A comprehensive list of all customization options can be found on the Customizations page.

Sample Usage

Below is an example of how to pass in customizationOverrides to the base JavaScript SDK. These options will:

  • Update the primaryColor to be "#FF0000"
  • Show the informational sidebar on upload pane
  • Change the import experience to be "ignoreErrors"
const importer = oneSchemaImporter({
  clientId: "CLIENT_NAME",
  userJwt: "USER_JWT",
  templateKey: "crm_test",
  customizationOverrides: {
   primaryColor: "#FF0000",
   uploaderShowSidebar: true,
   importErrorUX: "ignoreErrors"
  },
})

Branding

General

ConfigurationKeyTypeDescription
Primary colorprimaryColorHex ColorHover state in select drop downs, selected rows, loading icons
Background colorbackgroundPrimaryColorHex ColorThe color of the background of each pane, includes the background of spreadsheet cells
Secondary background colorbackgroundSecondaryColorHex ColorThe color of the background for secondary features, includes column names and row numbers of the spreadsheet
Header colorheaderColorHex ColorThe color of the header
Footer colorfooterColorHex ColorThe color of the footer
Border colorborderColorHex ColorThe color of the lines that border features
Success state colorsuccessColorHex ColorThe color of certain UI elements like success check marks
Warning state colorwarningColorHex ColorThe color of spreadsheet cells with warnings before opacity is added, also used for warning icons
Error state colorerrorColorHex ColorThe color of spreadsheet cells with errors before opacity is added, also used for error icons
Fullscreen modemodalFullscreenbooleanWhether the importer should take up all the space of the iframe. This will override border radius and modal mask settings
Hide close buttonhideCloseButtonbooleanWill hide the 'x' to close the modal when checked. Only works when using Fullscreen mode.
Modal mask colormodalMaskColorHex ColorThe color of the mask for the modal
Modal border radiusmodalBorderRadiusstring (_px)The border radius of the modal frame

Buttons

ConfigurationKeyTypeDescription
Button border radiusbuttonBorderRadiusstring (_px)The amount of curvature the button corners have
Primary button fill colorbuttonPrimaryFillColorHex ColorThe color of the primary buttons (like "Import" or "Next")
Primary button stroke colorbuttonPrimaryStrokeColorHex ColorBorder color for the main buttons
Primary button text colorbuttonPrimaryTextColorHex ColorText color on the primary button
Secondary button fill colorbuttonSecondaryFillColorHex ColorThe color of the secondary buttons (like "Previous")
Secondary button stroke colorbuttonSecondaryStrokeColorHex ColorBorder color for the secondary buttons
Secondary button text colorbuttonSecondaryTextColorHex ColorText color on the secondary button
Tertiary button fill colorbuttonTertiaryFillColorHex ColorThe color of the tertiary buttons (like "Find and replace" and "Export")
Tertiary button stroke colorbuttonTertiaryStrokeColorHex ColorBorder color for the tertiary buttons
Tertiary button text colorbuttonTertiaryTextColorHex ColorText color on the tertiary buttons
Alert button fill colorbuttonAlertFillColorHex ColorThe color of the alert buttons
Alert button stroke colorbuttonAlertStrokeColorHex ColorBorder color for alert buttons
Alert button text colorbuttonAlertTextColorHex ColorText color on alert buttons

Font

ConfigurationKeyTypeDescription
Custom font URLfontUrlstringURL for the font, font family must also be provided
Font familyfontFamilystringName of the font family, custom font URL must also be provided; comma-separated fallback families can be provided (i.e. Sans serif, Aerial would set a default font of Sans serif with a fallback of Aerial)
Primary font colorfontColorPrimaryHex ColorColor for the primary font (like spreadsheet cells, column names)
Secondary font colorfontColorSecondaryHex ColorColor for the secondary font (like sample data, titles, error descriptions)
Placeholder font colorfontColorPlaceholderHex ColorColor for the placeholder font (like unmapped columns and "Fix formatting errors" buttons)

Automations

1-click mode

ConfigurationKeyTypeDescription
1-click modeoneClickModeboolean1-click mode enables end users to skip all steps of the importer if the file matches certain conditions. Read our docs for more information.

Pane Skipping

ConfigurationKeyTypeDescription
Skip Select Header Row paneskipHeaderRow"always" | "detect" | "never"Strategy for when (if ever) to skip the Select Header Row pane. Defaults to "detect"
Skip Map Columns pane if columns automatically matchskipMapping[]: "exact" | "fuzzy" | "historical_user" | "historical_org"What strategies to test when attempting to skip the mapping pane. Note that we will only skip if all columns are matched.
Import data without showing the Review & Finalize paneskipCleaningbooleanOmit the Review & Finalize pane if there aren’t any errors in the file. The Importer will close once the user has successfully completed the Map Columns step.

Behavior will depend on the setting for import experience. If ignore errors is set, Review & Finalize will always be skipped.

Data Mapping

ConfigurationKeyTypeDescription
Uploaded column to template column matching strategymappingStrategy[]: "exact" | "fuzzy" | "historical_user" | "historical_org"What strategies to apply when suggesting mappings on mapping pane
AI-suggested mappingsaiSuggestedMappings[]: "column" | "picklist"Enable OneSchema AI to suggest potential column mappings and picklist mappings. Learn more about how these suggestions are made in our docs.

Error Resolution

ConfigurationKeyTypeDescription
Fix all errors automaticallyautofixAfterMappingbooleanWhether OneSchema should autofix errors after the mapping step. This is akin to clicking the "Fix all formatting errors" button
Accept webhook suggestions automaticallyacceptCodeHookSuggestionsbooleanIf there are validation webhooks on the template, OneSchema will automatically apply the suggested fix, skipping user confirmation. Applies only when moving from the mapping screen to review & finalize.

User Education

Global text

ConfigurationKeyTypeDescription
Back button textbackButtonTextstringThe text that appears on the back button in the Importer
Next button textnextButtonTextstringThe text that appears on the next button in the Importer

Education Widget

ConfigurationKeyTypeDescription
Show upload education widgetshowUploadEducationWidgetbooleanWhether to have a custom education widget on the upload pane
Upload education widget messageuploadEducationWidgetMessagestringThe contents of the education widget on the upload pane

Supports markdown
Auto open upload education widgetuploadEducationWidgetAutoOpenbooleanWhether the education widget should auto open
Show set header education widgetshowSetHeaderEducationWidgetbooleanWhether to have a custom education widget on the select header pane
Set header education widget messagesetHeaderEducationWidgetMessagestringThe contents of the education widget on the select header pane

Supports markdown
Auto open set header education widgetsetHeaderEducationWidgetAutoOpenbooleanWhether the education widget should auto open
Show mapping education widgetshowMappingEducationWidgetbooleanWhether to have a custom education widget on the mapping pane
Mapping education widget messagemappingEducationWidgetMessagestringThe contents of the education widget on the mapping pane

Supports markdown
Auto open mapping education widgetmappingEducationWidgetAutoOpenbooleanWhether the education widget should auto open
Show cleaning widgetshowCleaningEducationWidgetbooleanWhether to have a custom education widget on the review and finalize pane
Cleaning education widget messagecleaningEducationWidgetMessagestringThe contents of the education widget on the review and finalize pane

Supports markdown
Auto open cleaning education widgetcleaningEducationWidgetAutoOpenbooleanWhether the education widget should auto open

Upload a file

ConfigurationKeyTypeDescription
Informational SidebaruploaderShowSidebarbooleanWhether to show the sidebar on the upload pane
Show template column detailsuploaderSidebarDetails"required" | "all"What columns to list on the sidebar of the upload pane
Info banneruploaderShowSidebarBannerbooleanWhether to show the banner above the sidebar of the upload pane
Info banner textuploaderSidebarBannerTextstringThe text of the banner above the sidebar of the upload pane
Include a downloadable Excel template for your usersincludeExcelTemplatebooleanWhether a button to download an Excel template should appear in the footer of the upload pane. By default, this template is auto-generated by OneSchema, alternatively, you can upload your own template via the Settings menu on any template.
Uploader pane header textuploadPaneHeaderTextstringThe text at the top of the upload pane
Uploader header textuploaderHeaderTextstringThe text underneath the illustration in the middle of the importer.
Uploader subheader textuploaderSubheaderTextstringThe text below the header on the uploader

Select header row

ConfigurationKeyTypeDescription
Pane header textsetHeaderPaneHeaderTextstringThe text at the top of the select header row pane

Map columns

ConfigurationKeyTypeDescription
Informational SidebarmappingShowSidebarbooleanWhether to show the sidebar on the mapping pane
Show template column detailsmappingSidebarDetails"required" | "all"What columns to list on the sidebar of the mapping pane
Info bannermappingShowSidebarBannerbooleanWhether to show the banner above the sidebar of the mapping pane
Info banner textmappingSidebarBannerTextstringThe text of the banner above the sidebar of the mapping pane
Pane header textmappingPaneHeaderTextstringThe text at the top of the mapping pane
Uploaded column labelmappingUploadedColumnTextstringThe text label above the user’s uploaded column
Template column labelmappingTemplateColumnTextstringThe text label for a template column. This appears above the mapping table as well as in the template column dropdown

Review and Finalize

ConfigurationKeyTypeDescription
Pane header textcleaningPaneHeaderTextstringThe text at the top of the Review and Finalize pane
Confirmation button textcleaningConfirmButtonTextstringThe text that appears on the confirmation button prior to import

Advanced Options

Upload a file

ConfigurationKeyTypeDescription
File size limitfileSizeLimitnumberThe maximum file size a user can upload in megabytes (MB)
IllustrationillustrationUrlstring (url)A URL to an image for the importer

Map columns

ConfigurationKeyTypeDescription
Automatically include unmapped columnsincludeUnmappedColumnsbooleanWhether unmapped columns should appear on imports. See our docs on Unmapped Columns

Review and Finalize

ConfigurationKeyTypeDescription
Prevent row deletionpreventRowDeletion[]: "selection" | "errors"Prevents users from deleting rows (either manually via row selection or via the delete all error rows)
Import row limitimportMaxRowLimitintegerMax number of rows allowed for import
Row limit modal headerimportRowLimitHeaderstringCustom header text for row limit error modal
Row limit modal descriptionimportRowLimitDescriptionstringCustom description text for row limit error modal
Allow empty filesallowEmptyImportsbooleanWhether to allow users to import a file with only a header row
Import experienceimportErrorUX"blockIfErrors" | "promptIfErrors" | "ignoreErrors"Determines behavior for prompting the user when they click "Import" when there are errors

Multiple Customizations

If you have multiple importers in your app and want each one to use different customizations, you can create a customization for each importer on the Customizations page and then use their customization keys with the SDK to customize each importer.

First, "Create a copy" of your initial customization.

Then, set the settings that you want to use for your second importer.

Finally, use the "Customization key" that you specified as the customizationKey in the SDK.