Configuring 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

OneSchemaTemplateColumnToAdd

OneSchemaTemplateColumnToUpdate

OneSchemaTemplateColumnToRemove

OneSchemaValidationHooksToAdd

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:

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

Picklist Overrides

Picklist overrides are a subset of templateOverrides. For picklist columns, you must configure the options via validation_options. If you only want to update the values themselves, you can pass in values as an array of strings. OneSchema will automatically assign colors to your options in reverse rainbow order (from purple to red).

validation_options: {
  values: ["Seedling","Still growing", "Fully grown"]
},

However, if you would like to specify the color, description, and/or alternative picklist names, you should instead pass in picklist_options. This should be an array of OneSchemaPicklistOption objects

OneSchemaPicklistOption

Picklist Color Overrides

Colors should either be one of the OneSchemaPicklistColors or, you can simply pass in a hex code (eg. #FF00AA).

OneSchemaPicklistColors

Picklist Descriptions

If you would like to provide additional information to your customers, you can specify string descriptions which will be displayed below each option.

Sample Usage

const importer = oneSchemaImporter({
  clientId: "CLIENT_ID",
  userJwt: "USER_JWT",
  templateKey: "products",
  templateOverrides: {
    columns_to_update: [
      {
        key: "size",
        validation_options: {
         picklist_options: [
           {
             value: "Seedling", 
             color: "ColorSelectorPurple100",
             alternative_names: ["Sprout"],
             description: "A seedling is any young plant that has not yet been transported. Also known as a sprout."
           },
           {
             value:"Still growing", 
             color:"#FFAA00",
           },
           {
             value:"Fully grown",
             color:"ColorSelectorGreen100"
           }
         ]
        },
      }
    ]
  },
})

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