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 attribute, 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. 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 existing nodes that originate from earlier imports will be removed.
• FORCE - All 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 is to be manually rearranged within the Elevate apps, 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 are to be manually added within the Elevate Apps, only use either partial or full imports as to not override any additions from the apps.

• If the Navigation API will be used as an 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, e.g. 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.

Exports¶

Exports will return a JSON structure on 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.

{
  "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.

{
  "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"]
}