Getting started

This page outlines some of the basic setups that may be helpful when getting started with channels and destinations in Experience Orchestration.

Introduction

Channels are inherently agnostic to any specific medium, such as web or mobile. You can customize them to fit your use case, but there are a few core concepts to consider.

Channel

A basic web channel can be created with the following properties:

{
  "name": "Web",
  "description": "Web channel with path-based routing for marketing and product pages",
  "properties": [{ "name": "Base URL", "id": "baseUrl", "type": "String" }],
  "nodeProperties": [{ "name": "Path", "type": "Path" }]
}

When deciding what properties to set, consider your sitemap and SEO strategy, as this information will be sent as part of the destination sitemap delivery API.

For the web, you will likely want “Path” as a node property, as this allows you to use path-based routing for your experiences.

Do I need any specific properties for my channel?

In the example web channel above, “Base URL” is a property. This is not required and may be derived from environment variables or other client-side configuration. However, it demonstrates the scope of channel properties: site-wide properties that are relevant to all nodes in the destination.

Keep in mind that you can have many destinations for one channel, similar to having one content type for multiple entries. Consider how you want to structure your destinations and which properties are relevant to all of them.

What happens if I don’t use “Path”?

Destinations and their nodes are inherently hierarchical. Regardless of whether you enable the Path property, the same node types are available and work in the same way.

The difference is that a node’s ID becomes a path segment in the hierarchy. For example, instead of accessing a node through a human-friendly path such as /store/shoes/the-best-shoe, you could use IDs such as /node-123/node-456/node-789, where each segment is the ID of a node instance.

Why should I use a path rather than simply an experience ID?

A node is a navigational structure that can represent a specific location within a destination. Nodes can be organized to match a client’s screen hierarchy, meaning a screen can be coupled with the destination’s structure rather than a specific experience. The experience can then be changed in Contentful, and clients automatically consume the change. Consider using the upsert API pattern when you want more control over node IDs.

Destination

For a web channel, a destination might be a specific website. The configuration can be very simple:

{
  "name": "My Website",
  "description": "My website for marketing and product pages",
  "channelId": "<channel-id>"
}

Where are the experiences?

Experiences aren’t defined in the destination, but in its destination nodes. This allows you to define a destination once and then create many nodes for it, each with its own experiences.

Nodes

Overview

There are the following types of nodes:

• Experience node: A node connected to an experience. These nodes enable delivery of experiences through the destination. For example, an experience node might represent a product detail page or marketing landing page.
• Folder node: A node that isn’t connected to an experience. These nodes are used for organizational purposes and contribute to the structure of the destination without having experiences associated with them. For example, a folder node might represent a product category or section of a website.
• Redirect node: A node that points to another node. These nodes redirect traffic from one node to another. For example, a redirect node might represent a legacy URL that should redirect to a new URL.

Node types are polymorphic and are categorized by their shape when created. Below are JSON examples of the different node types.

// experience node
{
  "properties": [{ "type": "path", "path": "product" }],
  "parent": {
    "sys": {
      "type": "Link",
      "linkType": "DestinationFolderNode",
      "id": "{{node ID}}"
    }
  },
  "experience": {
    "sys": {
      "type": "ResourceLink",
      "linkType": "Contentful:Experience",
      "urn": "crn:contentful:::experience:spaces/$self/environments/$self/experiences/{{gettingStartedExperienceId}}"
    }
  }
}
// folder node
{
  "properties": [{ "type": "path", "path": "products" }],
  "parent": {
    "sys": { "type": "Link", "linkType": "Destination", "id": "{{destinationId}}" }
  }
}
// redirect node
{
  "properties": [{ "type": "path", "path": "getting-started" }],
  "redirectTo": {
    "sys": {
      "type": "Link",
      "linkType": "DestinationExperienceNode",
      "id": "{{gettingStartedNodeId}}"
    }
  }
}

Details

Paths

The following rules apply to the Path property:

• Each node gets one path segment. For example, use slug and not multiple/slugs.
• Paths can’t have duplicates. When the path segments from all parent nodes are concatenated, no two resolved paths can be identical.
• Omit separators from path segments. For example, use slug and not /slug. The / separator is added automatically when paths are resolved.

Home node

To create a node that represents “home”, leave the path empty, for example:

{
  "properties": [{ "type": "Path", "path": "" }],
  "experience": {
    "sys": {
      "type": "ResourceLink",
      "linkType": "Contentful:Experience",
      "urn": "crn:contentful:::experience:spaces/$self/environments/$self/experiences/380xIeTxkBevTuwDZ3Pz0M"
    }
  }
}

This special case resolves to /. In line with the broader rules, paths can’t be duplicated, so you can have only one home node.

Redirect behavior

Redirects are not web-specific and should not be treated as HTTP redirects. If a node requested by ID or path resolves to a redirect, the API returns a 200 response with a redirect object:

{
  "redirect": { "path": "/products" }
}

The redirect provides a new path that you can request to return a resolved experience.