Channels

Definition

A channel is a site that can be managed in the Experience manager app by users with the Site Editor role.

Channel is the "root" entity in the site configuration model: all other entities in the model exist as part of a specific channel.

Properties

A channel's configuration includes a content root. Any content paths configured in the entities that are part of that channel are relative to that content root.

For a full overview of properties, see the Channel schema in the Site Management API reference documentation.

Additionally, a channel configuration can include parameters that are user-configurable in the Channel properties dialog in the Experience manager. The editing experience of a parameter can be customized through metadata. For example, a parameter can be configured to be rendered as a dropdown or content picker.

For a full overview of channel parameter metadata properties, see the Parameter schema in the Site Management API reference documentation.

Platform property placeholders

You can access specific technical values defined by Bloomreach in channel properties using property placeholders. The main purpose is to enable developers to pass these values to their frontend app, so their frontend components can use it.

A placeholder can be used in your channel property values as follows:

${placeholder}

The available placeholders are listed in the table below:

Placeholder name	Description
`public.brx.smEndpoint`	Endpoint URL for Bloomreach Discovery APIs.
`public.brx.smAccountId`	Bloomreach Discovery account ID.
`public.brx.smAccountName`	Bloomreach Discovery account name.
`public.brx.graphql.baseurl`	Base URL of the GraphQL Commerce API.
`public.brx.reference.spa.baseurl`	Base URL of the default shared hosted frontend app for the Reference SPA channel template.
`public.brx.spartacus.spa.baseurl`	Base URL of the default shared hosted frontend app for the SAP Spartacus channel template.
`public.brx.vuestorefront.spa.baseurl`	Base URL of the default shared hosted frontend app for the Vue Storefront channel template.

Example channel JSON

The example below shows the JSON representation of a channel created using the Reference SPA template.

{
    "id": "pacific-home",
    "name": "Pacific Home",
    "projectName": null,
    "projectState": null,
    "branch": null,
    "branchOf": null,
    "externalPreviewEnabled": false,
    "externalPreviewToken": null,
    "contentRootPath": "/content/documents/pacific-home",
    "icon": "data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNjQgMzQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CiAgPG1ldGFkYXRhPgogICAgPHJkZjpSREYKICAgICAgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIgogICAgICB4bWxuczpkYz0iaHR0cHM6Ly93d3cuZHVibGluY29yZS5vcmcvc3BlY2lmaWNhdGlvbnMvZHVibGluLWNvcmUvZGNtaS10ZXJtcy8iPgogICAgICA8cmRmOkRlc2NyaXB0aW9uPgogICAgICAgIDxkYzpjcmVhdG9yPgogICAgICAgICAgPHJkZjpCYWc+CiAgICAgICAgICAgIDxyZGY6bGk+Qmxvb21yZWFjaDwvcmRmOmxpPgogICAgICAgICAgPC9yZGY6QmFnPgogICAgICAgIDwvZGM6Y3JlYXRvcj4KICAgICAgPC9yZGY6RGVzY3JpcHRpb24+CiAgICA8L3JkZjpSREY+CiAgPC9tZXRhZGF0YT4KICA8c3R5bGU+CiAgICAuYmFkZ2UgewogICAgICBmb250LWZhbWlseTogJ0FyaWFsIE5hcnJvdycsIEFyaWFsLCBzYW5zLXNlcmlmOwogICAgICBmb250LXNpemU6IDIwcHg7CiAgICAgIGZvbnQtd2VpZ2h0OiA2MDA7CiAgICAgIGZvbnQtc3RyZXRjaDogY29uZGVuc2VkOwogICAgICBhbGlnbm1lbnQtYmFzZWxpbmU6IG1pZGRsZTsKICAgICAgZG9taW5hbnQtYmFzZWxpbmU6IG1pZGRsZTsKICAgICAgdGV4dC1hbmNob3I6IG1pZGRsZTsKICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IHg9IjEiIHk9IjEiIHdpZHRoPSI2MiIgaGVpZ2h0PSIzMiIgcng9IjMiIHN0cm9rZT0iIzE0N0FDOCIgc3Ryb2tlLXdpZHRoPSIxIiBmaWxsPSIjRTdGMUY5Ii8+CiAgPHRleHQgeD0iMzIiIHk9IjE4IiBmaWxsPSIjMTQ3QUM4IiBjbGFzcz0iYmFkZ2UiPmVuX1VTPC90ZXh0Pgo8L3N2Zz4=",
    "locale": "en_US",
    "devices": [],
    "defaultDevice": null,
    "responseHeaders": null,
    "linkurlPrefix": null,
    "cdnHost": null,
    "remoteHostProtection": false,
    "parameters": {
        "discoveryAccountId": "${public.brx.smAccountId}",
        "graphql_baseurl": "${public.brx.graphql.baseurl}",
        "discoveryRealm": "PRODUCTION",
        "graphqlTenantName": "${public.brx.graphql.tenantName}",
        "externalLocale": "en_US",
        "discoveryDomainKey": "${public.brx.smDomainKey}",
        "discoveryViewId": "",
        "spaUrl": "${public.brx.reference.spa.baseurl:https://brxm-react-spa.herokuapp.com/}"
    }
}

Example channel parameter JSON

The example below shows a JSON representation of the metadata for the discoveryRealm channel parameter, configured as a dropdown with two predefined values to choose from:

{
    "name": "discoveryRealm",
    "valueType": "string",
    "required": true,
    "hidden": false,
    "overlay": false,
    "defaultValue": "PRODUCTION",
    "displayName": "Discovery Realm",
    "system": false,
    "config": {
        "value": [
            "PRODUCTION",
            "STAGING"
        ],
        "structuredValues": null,
        "valueListProvider": null,
        "sourceId": null,
        "type": "dropdown"
    }
}

The next example shows the JSON representation of the metadata for a custom logo channel parameter, configured as a content path with an image picker:

{
    "name": "logo",
    "valueType": "string",
    "required": false,
    "hidden": false,
    "overlay": false,
    "defaultValue": "",
    "displayName": "Logo",
    "system": false,
    "config": {
        "pickerConfiguration": "cms-pickers/images",
        "pickerInitialPath": null,
        "pickerRememberLastVisited": true,
        "pickerSelectableNodeTypes": [],
        "relative": false,
        "pickerRootPath": null,
        "enableUpload": false,
        "type": "contentpath"
    }
}

Operations

The Site Management API currently supports Channel Operations, but not create and delete. The creation of new channels is handled inside the Content web interface: a user with the Site Admin role can create new channels in the channel overview of the Experience manager app.

Modification of channel configuration is only allowed in the context of a development project. As such, it is a prerequisite for using the API, that a development project for your channel exists. The Channels tab of the Projects app displays the branch ID, a sequence of 4 random alphanumeric characters prefixed with a 'v' (for example: "vIUy9"), which must be used in combination with the channel ID, separated by a dash (for example: "pacific-home-vIUy9").

The API additionally supports the management of a channel’s configuration parameters and their grouping in the Channel properties dialog through field groups.

See Channel Operations in the Site Management API reference documentation for a list of operations.

You can find examples of using the channel endpoints in the Postman collection.