Per-Customer Overrides

Why use Customization and Template Overrides

Customizations and Templates determine the behavior of OneSchema Importers. Using overrides can allow specific behavior for individual importing sessions.

Template Overrides

When to override

Adjusting template column behavior on a per-customer basis (eg. picklist options).

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

If you are using the API, pass in template_overrides to the create embedded session endpoint.

The format for templateOverrides is OneSchemaTemplateOverrides documented below.

OneSchemaTemplateOverrides

Key	Type	Description
`columns_to_add`	OneSchemaTemplateColumnToAdd[]	Array of columns to add to the template.
`columns_to_update`	OneSchemaTemplateColumnToUpdate[]	Array of columns to update in the template. OneSchema identifies columns via the `key` and replaces the properties of the column with those provided in the template overrides.
`columns_to_remove`	OneSchemaTemplateColumnToRemove[]	Array of columns to remove from the template.
`validation_hooks_to_add`	OneSchemaValidationHooksToAdd[]	Array of validation hook to add to the template.

OneSchemaTemplateColumnToAdd

Key	Type	Required	Description
`key`	string	true	Unique key identifier for a given template column
`label`	string	true	Display label of the template column for end users
`data_type`	string		Data type for the template column (eg. "PICKLIST" or "NUMBER")
`validation_options`	Object		Additional validation properties on top of specific data types (eg. `values` for picklists or `only_int` for numbers)
`description`	string		Description displayed to end user
`is_custom`	boolean		Whether the template column should act as a Custom Column
`is_required`	boolean		Cells in this column cannot have blank values.
`is_unique`	boolean		All values in the column must be unique
`letter_case`	string		Casing validation for the column (eg. "LETTER_CASE_UPPER", "LETTER_CASE_LOWER", or "LETTER_CASE_TITLE")
`min_char_limit`	integer		Min number of characters
`max_char_limit`	integer		Max number of characters
`delimiter`	string		Delimiter character to be used for separating multi-value fields.
`must_exist`	boolean		Column must be mapped
`default_value`	string		Automatically replace empty cells with provided default value
`mapping_hints`	string[]		Array of sheet column names to automatically map this column to

OneSchemaTemplateColumnToUpdate

Key	Type	Required	Description
`key`	string	true	Unique key identifier for a given template column
`label`	string		Display label of the template column for end users
`data_type`	string		Data type for the template column (eg. "PICKLIST" or "NUMBER")
`validation_options`	Object		Additional validation properties on top of specific data types (eg. `values` for picklists or `only_int` for numbers)
`description`	string		Description displayed to end user
`is_custom`	boolean		Whether the template column should act as a Custom Column
`is_required`	boolean		Cells in this column cannot have blank values.
`is_unique`	boolean		All values in the column must be unique
`letter_case`	string		Casing validation for the column (eg. "LETTER_CASE_UPPER", "LETTER_CASE_LOWER", or "LETTER_CASE_TITLE")
`min_char_limit`	integer		Min number of characters
`max_char_limit`	integer		Max number of characters
`delimiter`	string		Delimiter character to be used for separating multi-value fields.
`must_exist`	boolean		Column must be mapped
`default_value`	string		Automatically replace empty cells with provided default value
`mapping_hints`	string[]		Array of sheet column names to automatically map this column to

OneSchemaTemplateColumnToRemove

Key	Type	Required	Description
`key`	string	true	Unique key identifier for a given template column

OneSchemaValidationHooksToAdd

Key	Type	Required	Description
`name`	string	true	Name of the validation hook.
`url`	string	true	The URL where the validation hook will be called. Environment variables can be used when setting the url.
`column_key`	string[]		Columns to be sent in the validation hook.
`custom_column_key`	string[]		Custom columns to be sent in the validation hook
`hook_type`	string		One of `row` or `column`. See Validation Webhook for more details. Defaults to `row` if not provided.
`secret_key`	string		If a secret key is provided, the secret key will be used as the basic auth password.
`batch_size`	integer		Batch size for row hooks. Defaults to 1000 if not provided.

Sample Usage

Below is an example use case for a number of overrides to a sample template with key crm_test. The following actions are taken: 123

Create a new column account_executive which is marked as required.
Replace the valid picklist values on column segment with ["A", "B"]
Update column phone_number to be both required and unique
Update the description and label of column metadata
Remove the column lead_source

const importer = oneSchemaImporter({
  clientId: "CLIENT_ID",
  userJwt: "USER_JWT",
  templateKey: "crm_test",
  templateOverrides: {
    columns_to_add: [
      {
        key: "account_executive",
        label: "Account Executive",
        data_type: "TEXT",
        is_required: true
      }
    ],
    columns_to_update: [
      {
        key: "segment",
        validation_options: {
          values: ["A", "B"]
        },
      },
      {
        key: "phone_number",
        is_required: true,
        is_unique: true,
      },
      {
        key: "metadata",
        label: "Customer Info",
        description: "Provide any additional metadata about the customer as freeform text."
      } 
    ],
    columns_to_remove: [
      { 
        key: "lead_source",
      },
    ],
    validation_hooks_to_add: [
      {
        name: "Phone number validator",
        url: "{{base_url}}/oneschema-webhooks/phone-number-validator",
        column_keys: ["phone_number"]
      }
    ]
  },
})

Customization Overrides

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"
  },
})