Import and export navigation

Navigation trees can be imported into and exported from Elevate using the Navigation API. Both the import and export of navigation nodes are based on the market and locale attributes, which must be supplied as a query parameter for the export, and in the request body for the import. Both endpoints require the Api-Key header. When a navigation tree is updated via an import through the Navigation API, it is automatically published, meaning changes will go live upon the import’s completion. Nodes not included in the import will remain in place to the extent that is possible.

Import types

Imports of navigation nodes can have three different levels of significance:

PARTIAL — Only nodes included in the import will be affected, all other nodes will remain.
FULL — All previously existing nodes that originate from earlier imports will be removed or replaced.
FORCE — All previously existing nodes will be deleted, regardless of origin.

Which import type to use depends on the intended workflow for the navigation:

If the navigation tree can be manually rearranged within the Elevate app, use partial imports to add or remove nodes, or use full imports in conjunction with exports to not override changed orderings.
If new navigation nodes may be manually added within the Elevate app, only use either partial or full imports so as to not override any additions from the apps.
If the Navigation API will be used as the only source, use any import type.

Retention handling

Nodes included in the import will be listed in order of appearance in the import body. When there are nodes in the navigation tree that are not included in the import (for example, during a partial import), Elevate will attempt to merge the changes with the existing tree. In general, the import will follow these rules for the nodes that are not included in the import:

Nodes that no longer have a parent will be deleted.
If a parent node was moved, its children are moved with it.
Sibling nodes will be reordered if that would bring them closer to their original position.

An example of the last case would be having two nodes, A and B, and making a partial import of A and C. Since B initially came after A, it will be placed after A during the import, resulting in a final order of A B C. Had B also been included in the import, for example importing A C B, then that would have been the final order. Similarly, if C had come before A in the import, that would have been reflected in the final order of C A B. In cases where only new nodes are added, they are simply appended last among their siblings.

Node types

There are three types of navigation nodes:

Page nodes — A page node has a corresponding page and makes up the main tree structure.
Link nodes — A link node has a URL, linking to another resource on the same or another domain.
Label nodes — A node that only has a title.

Note that only page nodes may be parents to other nodes.

Custom data

Like pages, custom data can be added to navigation nodes using the customData attribute. Custom data is limited to 1,000 characters and 50 keys per locale. Be careful not to include too much data here, as doing so may quickly bloat query responses.

Exports

Exports will return a JSON structure in the same format as supplied in imports. By default, only nodes originating from imports will be returned, but the export endpoint can be supplied with an optional query parameter to also include app-created nodes.

Examples

Full import

A full import will replace all previously imported nodes on the specified market with the content of addOrUpdate.

Example

{
  "market": "UK",
  "locale": "en-GB",
  "type": "FULL",
  "addOrUpdate": [
    {
      "id": "/ladies",
      "title": "Ladies",
      "type": "PAGE",
      "pageReference": "/ladies"
    },
    {
      "id": "/ladies/dresses",
      "title": "Dresses",
      "parentId": "/ladies",
      "type": "PAGE",
      "pageReference": "/ladies/dresses"
    }
  ]
}

Partial import

A partial import will add nodes to the navigation on the specified market.

Example

{
  "market": "UK",
  "locale": "en-GB",
  "type": "PARTIAL",
  "addOrUpdate": [
    {
      "id": "guides",
      "title": "Guides",
      "type": "LABEL"
    },
    {
      "id": "shipping",
      "title": "Shipping Guide",
      "type": "LINK",
      "url": "/shipping-guide"
    }
  ],
  "remove": ["/ladies/dresses"]
}

Overview

Catalog modeling

Feature concepts

Search and facets

Recommendations

Pages and navigation

Storefront responses

Operations

Import types

Retention handling

Node types

Custom data

Exports

Examples

Full import

Partial import

​Import types

​Retention handling

​Node types

​Custom data

​Exports

​Examples

​Full import

​Partial import

Import types

Retention handling

Node types

Custom data

Exports

Examples

Full import

Partial import