Bulk Navigation Import

The Bulk Import endpoint provides a mechanism for creating navigations and optionally, precedence rules, without configuring them individually via Command Center.

Please note that Precedence Rules can only be defined via the Bulk Import Endpoint as of this time.

The Bulk Import service will remove all previously imported navigations before performing a bulk import, these navigations are always hidden in the command center. Only items created by the merchandiser will not be affected during a bulk import.

Import Navigations

To perform a bulk import, you will need a data file and configuration file.

Configuration File Example

TXT

clientKey: --clientKey--
area: Production
type: navigation

The area field is optional in the configuration file. If not supplied, a default area of Production will be used during import.

A maximum of 20,000 navigations can be created with the bulk upload tool.

If you exceed the number of navigations the upload will fail with an error message.

Data File Example

json

{"name":"type","displayName":"Printer Type","type":"String"}
{"name":"model","displayName":"Printer Model","type":"String", "unionable" : true }
{"name":"manufacturer","displayName":"Manufacturer","type":"String","precedence":[[{"key":"type","value":"Laser"}]]}
...

Refer the Navigation Properties section to understand different fields used to create Navigation File.

Warning

If you are uploading non-String type data, please remember to define it as a Float or Integer. If you do not define it explicitly, the engine could infer the wrong type. The Bulk Import tool only supports .json or .json.gz (gzipped equivalent) file extension.

Enabling OR

If you want to OR-enable a navigation (so that the navigation treats the selections within the navigation as multi select), add "unionable" : true.

The same restrictions on which navigations can be OR-enabled apply - for example, Range navigations do not support OR-filters. Please see Command Center Navigation module to learn more about navigation management.

Sample syntax:

{"name":"model","displayName":"Printer Model","type":"String", "unionable" : true }

Precedence Rules

You can define precedence rules for each navigation - “Show a navigation only when another specific value, or another navigation was picked”. This enables you to show deeper hierarchy only when a higher level was chosen.

You can define precendence rules within the bulk-upload file only.

For each precedence rule defined, a maximum of 250 triggers can be defined, with 10 clauses within each.

If you exceed the number of triggers the upload will fail with an error message.

Note: The precedence rule keys and values are both case sensitive.

Precedence off this OR that

Each precedence list will be treated as an OR expression at evaluation time, for example:

{"name":"Variants.Attributes.Head_Height","displayName":"Head Height","type":"String","precedence":[[{"key":"categoryL2","value":"Screws"}], [{"key":"categoryL3","value":"Nuts"}]]}

The first line will be evaluated as: if categoryL2 is Screws OR categoryL3 is Nuts, then show Navigation Head Height.

Precedence off this AND that

To set the precedence list as an AND expression at evaluation time combine the keys into the array:

{"name":"Variants.Attributes.Head_Height","displayName":"Head Height","type":"String","precedence":[[{"key":"categoryL2","value":"Screws"}, {"key":"categoryL3","value":"Nuts"}]]}

The first line will be evaluated as: if categoryL2 is Screws AND categoryL3 is Nuts, then show Navigation Head Height.

Precedence off any value

To denote an ANY match, simply remove the value parameter from as follows :

{"name":"manufacturer","displayName":"Manufacturer","type":"String","precedence":[[{"key":"categoryL2"}]]}

Navigations with no precedence rules defined can also be uploaded via the Bulk Import tool. Each record in the data file must be added on a separate line.

Navigation Properties

The following properties can be used to create navigation. Note that all properties are case-sensitive.

Field	Mandatory	Usage
`name`	Yes	The name, or the JSON address, of the data field that this navigation will be based on. The name field must be unique or the upload will fail. E.g.: `"name": "product.price"`
`displayName`	Yes	Does not have to be unique. The display name of the navigation item. E.g.: `"displayName":"Price"`
`priority`	Optional	Defaults to 1000. Defines the priority order of this navigation for display purposes. A smaller number means it will be displayed higher in the order of the navigations. E.g.: `"priority":980`
`type`	Optional	Set the type of Navigation from the available types. Defaults to String. Valid types: `Float`, `Integer`, `String`, `Range_Integer`, `Range_Float`. E.g.: `"type":"Integer"`
`sort`	Optional	Defaults to Value Ascending. Options: `Count_Ascending`, `Count_Descending`, `Value_Ascending`, `Value_Descending`. E.g.: `"sort":"Count_Ascending"`
`ranges`	Optional	Defaults to empty. Highest value for the range is not inclusive. e.g. 0 - 10 will result in a range from 0 - 9.99. Ranges define the list buckets that will be shown to a user. E.g.: `"ranges":[{"low":"0","high":"10"},{"low":"10","high":"20"}]`
`unionable`	Optional	Defaults to empty. Allows you to set up a nagiation as OR-enabled. E.g.: `"unionable":true`
`pinnedRefinements`	Optional	Defaults to empty. Allows you to push specific refinements to the top of the navigation, as long as records are returned for that refinement. E.g.: `"pinnedRefinements": ["Nike", "Adidas"]`
`metadata`	Optional	Defaults to empty. Key value pairs that should be associated with navigation for use by the front-end. E.g.: `"metadata":[{"key":"hidden","value":"true"}]`