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"
},
})
Updated 24 days ago