Deploy Headless SXA Site to XM Cloud

In this blog blost lets create Project and Environment to deploy the sxastarter site to XM Cloud. The deployment is based on the existing repository in GitHub and have solution ready to deploy. Please see this blog posts on how to fork Foundation Head Template and setup your local instance along with creating Headless SXA Site(sxastarter) also configure the serliazation of Sitecore items.

To create project and environment you need to have access to XM Cloud either Admin or Contributor.

Login to XM Cloud

https://portal.sitecorecloud.io/

XM Cloud Organization-

Contains organization you are assigned to-

An organization is business unit either company or brand and contains team members and Sitecore Products you are subscribed and can have more than one Sitecore Product as seen in the below screen.

XM Cloud Deploy

As highlighted quick links container XM Cloud Deploy

https://deploy.sitecorecloud.io/

Deploy contanis list of projects and deployments done for each project and environments. It also container connections to GitHub or Vercel if site is hosted their.

The highlighted shows Organization name at the top and list of projects.

Connect to GitHub (Source Control Connections)

Ensure the changes (Sitecore Items) are pushed to GitHub repo.

Recommended – create separate branch for each environment. I have created dev, staging and main(prod)

Connections – should show list of all connections for projects mainly Github and Azure Devop for Source Control, while hosting connections can be mafe to Vercel. In this section we will configure GitHub provider.

Create a new GitHub connection

Should ask to login and provide access to a repository, you may choose all or specific repository-

Since I already had connection you will be shown a different option to Install and Authorize

Create Project

Click on Create project option

This should show the type of project to be created. We want to start from our own Source Code(GitHub) based on the connection made.

Since we configured only GitHub connection defaults to this Source Control-

Your connection name will be displayed here. Choose the connection. This will also show any other connections available.

You may also create a new connection from here.

Provide the project name and the repository where Foundation Head code resides along with any other changes you might have done sa a part of development.

Environment name – provide name – should be able to relate which branch is this pulled from.

Production environment – if this is then choose yes, I have selected this as no since I ma setting dev environment

Linked branch- Select the appropriate branch ensure yuo have all the changes available in this branch which you want to deploy

Trigger deployment on commit to branch – Set if this has to be auto deployed if changes are pushed to selected branch.

Deploy. This should start the deployment. This should take 10 -15 mins. Wait for the post actions.

You should now see the newly created project with dev environment-

New Project Created

New Environment Created

New Site Created (sxastarter)

Select environment and goto Sites tab-

Will see in the next blog hot to setup the Hosting

Select environment and Details tab- You should be able to see hostname, url’s and tokens along with Environment details.

Click on the Dashboard link –> Tools to see if the items are synched-

We now have templates, content and relevant items in layouts and image created

Content Editor with Site Collection, Site and Content

Templates Created

Experience Editor

Lets check the home page in experience editor

In the next bog will configure the Site hosting to Vercel.

Errors-

In connections select Create Connection –> GitHub

Click on Uninstall “Sitecore Deploy Prod”

Follow the process of creating a Connection again and this time you will see option to Install & Authorize

Once this is done an confirmed try creating a project –

Loading

Sitecore CDP- Create Guests using REST Api

https://{apiEndpoint}/v2/guests

Request to the api-

Use Client Key in User name and API Token in password to send request with Basic Auth-

Response-

Note ref field. The ref field is a guest reference which can be used further to extend or pull the guests details-

See the Properties tab to verify all the guests details-

cURL code snippet-

curl --location --request POST 'https://api.boxever.com/v2/guests' \
--header 'Authorization: Basic <<Enter Token>>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "guestType": "customer",
    "title": "Mr",
    "firstName": "Icy",
    "lastName": "Saber",
    "gender": "male",
    "dateOfBirth": "",
    "emails": [
        "icy.saber@mailfy.com"
    ],
    "phoneNumbers": [
        "01234567890"
    ],
    "nationality": "British",
    "passportNumber": "GB4B9565",
    "passportExpiry": "",
    "street": [
        "Apartment 140",
        "West Drive Avenue"
    ],
    "city": "London",
    "country": "GB",
    "postCode": "SW12",
    "state": "London"
}

C# code snippet-

var client = new RestClient("https://api.boxever.com/v2/guests");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic <<Enter Token>>");
request.AddHeader("Content-Type", "application/json");
var body = @"{
" + "\n" +
@"    ""guestType"": ""customer"",
" + "\n" +
@"    ""title"": ""Mr"",
" + "\n" +
@"    ""firstName"": ""Icy"",
" + "\n" +
@"    ""lastName"": ""Saber"",
" + "\n" +
@"    ""gender"": ""male"",
" + "\n" +
@"    ""dateOfBirth"": """",
" + "\n" +
@"    ""emails"": [
" + "\n" +
@"        ""icy.saber@mailfy.com""
" + "\n" +
@"    ],
" + "\n" +
@"    ""phoneNumbers"": [
" + "\n" +
@"        ""01234567890""
" + "\n" +
@"    ],
" + "\n" +
@"    ""nationality"": ""British"",
" + "\n" +
@"    ""passportNumber"": ""GB4B9565"",
" + "\n" +
@"    ""passportExpiry"": """",
" + "\n" +
@"    ""street"": [
" + "\n" +
@"        ""Apartment 140"",
" + "\n" +
@"        ""West Drive Avenue""
" + "\n" +
@"    ],
" + "\n" +
@"    ""city"": ""London"",
" + "\n" +
@"    ""country"": ""GB"",
" + "\n" +
@"    ""postCode"": ""SW12"",
" + "\n" +
@"    ""state"": ""London""
" + "\n" +
@"}
" + "\n" +
@"
" + "\n" +
@"";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Python code snippet-

import http.client
import json

conn = http.client.HTTPSConnection("api.boxever.com")
payload = json.dumps({
  "guestType": "customer",
  "title": "Mr",
  "firstName": "Icy",
  "lastName": "Saber",
  "gender": "male",
  "dateOfBirth": "",
  "emails": [
    "icy.saber@mailfy.com"
  ],
  "phoneNumbers": [
    "01234567890"
  ],
  "nationality": "British",
  "passportNumber": "GB4B9565",
  "passportExpiry": "",
  "street": [
    "Apartment 140",
    "West Drive Avenue"
  ],
  "city": "London",
  "country": "GB",
  "postCode": "SW12",
  "state": "London"
})
headers = {
  'Authorization': 'Basic <Enter Token>>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/v2/guests", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Reference-

https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform–data-model-2-1/use-the-create-guest-function-in-sitecore-cdp-rest-api.html

https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform–data-model-2-1/overview-of-sitecore-cdp-rest-apis.html

https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform–data-model-2-1/sitecore-cdp-guest-extensions-data-model-for-rest-api.html

Loading

Sitecore CDP- Generate browser ID

The browser ID is a universally unique identifier (UUID) that Sitecore CDP assigns to every user of your application. It associates sessions, events, and orders with the respective user.

To generate browser id at server side in this case using postman use following URL-

https://{{apiEndpoint}}/{{apiVersion}}/browser/create.json?client_key={{CLIENT_KEY}}&message={}

API Endpoint

{{apiEndpoint}} – API target endpoint depends on the region client key is available in. Following are the regions and url available at the point of writing this blog and as per this document

Europe – https://api.boxever.com

Asia Pacific – https://api-ap-southeast-2-production.boxever.com

United States – https://api-us.boxever.com

See here for more details on the Sitecore CDP Rest API

API Version

API Version is v1.2

Client Key

See here for more details on How to get Client Key and API Token

Get the client key from the Sandbox/CDP & Personalise portal.

Login to portal – https://app.boxever.com/#/

Top right click the clog icon. Select API Access option

Get teh client key from this page-

Request/Response-

Status- OK. The request was served successfuly

Anantmous(Guest) should be created. Browser ID is in “ref” field in the response

Check the guest details in portal with the Browser ID-

Goto the Guests page –

Search guests with browser id. (bid: <<browser id>>)

This should the Guest Type as Visitor which means its Anonymous and not yet known or uniquely identified.

CURL code snippet-

curl --location -g --request GET 'https://api.boxever.com/v1.2/browser/create.json?client_key=<<client key>>&message={}'

C# code snippet-

var client = new RestClient("https://api.boxever.com/v1.2/browser/create.json?client_key=<<client key>>&message={}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Python code snippet-

import http.client

conn = http.client.HTTPSConnection("api.boxever.com")
payload = ''
headers = {}
conn.request("GET", "/v1.2/browser/create.json?client_key=<<code key>>&message=%7B%7D", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

References

Preparing to integrate with Sitecore CDP

Understanding integration details

Loading

XM Cloud local environment – Configure item serialization to sync Headless SXA instance items

Synchronizing items between environments with Sitecore Serialization. The repository already contains the necessary setup for enabling serialization if you are using an official Sitecore XM Cloud foundation template.

Pre-requisite- Setup Sitecore local instance for XM Cloud development. See this blog << Blog to setup Sitecoer instance>>

You may already see the rendering host module setup in the forked repository.

This should be available in the src folder.

Lets sync the sxastarter site created earlier whilst setting up the SXA Headless Site. << Blog post to setuop SXA headless site>>.

Please note this might not be the method you want to sync the items. Ideally you should create project in XM Cloud and site created in XM Cloud environment. I am doing the other way just to demo.

Create various modules to sync your locally created site to serialize the items

This should help to push the config and items to repository and deploy to XM Cloud later.

Sync templates-

Create a scxmcloud.templates.module.json in src folder.

We are trying to serialise templates to local. These items will be searlised-

{
  "$schema": "../.sitecore/schemas/ModuleFile.schema.json",
  "namespace": "SCXMCloud.Templates",
  "items": {
    "includes": [
      {
        "name": "scxmcloud.project.templates",
        "path": "/sitecore/templates/Project",
        "allowedPushOperations": "CreateUpdateAndDelete"
      }
    ]
  }
}

scope by default is ItemAndDescendants. Hence not defined. Any new templates added here will be auto serialised. allowedPushOperations is set to CreateUpdateAndDelete. Like wise define the same for Feature and Foundation folders.

Define the same for Content (if required) or specific items, Media Library and Layout but this may be site specific.

For media I have configured following – Where scope id Single item and allowedPushOperations is CreateOnly, so these items are created only once.

{
  "$schema": "../.sitecore/schemas/ModuleFile.schema.json",
  "namespace": "SXAStarter.Media",
  "items": {
    "includes": [
      {
        "name": "scxmcloud.project.media",
        "path": "/sitecore/media library/Project/scxmcloud",
        "allowedPushOperations": "CreateOnly",
        "scope": "SingleItem"
      },
      {
        "name": "sxastarter.project.media",
        "path": "/sitecore/media library/Project/scxmcloud/sxastarter",
        "allowedPushOperations": "CreateOnly"
      }
    ]
  }
}

For Palcholder settings and Renderings- Configure same for Feature and Foundation folder.

{
  "$schema": "../.sitecore/schemas/ModuleFile.schema.json",
  "namespace": "SXAStarter.Layout",
  "items": {
    "includes": [
      {
        "name": "sxastarter.project.placeholder",
        "path": "/sitecore/layout/Placeholder Settings/Project/scxmcloud",
        "allowedPushOperations": "CreateUpdateAndDelete"
      },
      {
        "name": "sxastarter.project.renderings",
        "path": "/sitecore/layout/Renderings/Project/scxmcloud",
        "allowedPushOperations": "CreateUpdateAndDelete"
      }
    ]
  }
}

For content- I am searlising the the Site Collection and setting this as CreateOnly with scope defaulting to ItemAndDescendants

{
  "$schema": "../.sitecore/schemas/ModuleFile.schema.json",
  "namespace": "SXAStarter.Content",
  "items": {
    "includes": [
      {
        "name": "sxastarter.content",
        "path": "/sitecore/content/scxmcloud",
        "allowedPushOperations": "CreateOnly"
      }
    ]
  }
}

Finally you should have following modules depending upon the youe site requirements and configuration.

Connect the local environment

After SCS configuration you should connect to local environment. To do so use the following command

This will add the endpoint in user.json file located in .sitecore folder. Alrthough there is a default endpoint which should suffice. Provide your Sitecore instnace host name as appropriate.

dotnet sitecore connect --ref xmcloud --cm https://xmcloudcm.localhost --allow-write true -n local

Local environment should be connected and now can perform sync operations.

An entry will be added in user.json file.

Next pull the items from local Sitecore instance-

dotnet sitecore ser pull -n "local"

If you see this error – ensure the names should be unique. I did a mistake by providing same name in templates module

If you see this error ensure the items to be searialised should be repeated in any other module or any other name. You may also exclude the paths for Feature and Foundation folders – /sitecore/layout/Renderings/Feature/Experience Accelerator

/sitecore/layout/Renderings/Feature/Experience Accelerator

Finally we should have the items seraliased to the items folder-

Items are serliased to support the Home page-

Please note I have synchornised Site Collection, Site and all items of the site.

Managed to have built the home page with some images and texts.

Push these changes to the repo we forked.

Reference-

https://doc.sitecore.com/xp/en/developers/101/developer-tools/sitecore-content-serialization-configuration-reference.html

https://doc.sitecore.com/xmc/en/developers/xm-cloud/walkthrough–setting-up-your-full-stack-xm-cloud-local-development-environment.html

Next will configure Project, environment and deploy the Site to XM Cloud.

Loading

XM Cloud local environment – Access Sitecore database hosted in Docker

This blog provides details on accessing local Sitecore instance Database hosted on Docker.

If you wish to backup or share Sitecore Database you can connect to Sitecore DB.

Install Sitecore local instance, see th blog post here and run the docker containers for Sitecore.

In .env file see the SQL connection details-

Check the docker container for the DB port.

You may also see the Connection String in CM container-

  • Sitecore_ConnectionStrings_Security
  • Sitecore_ConnectionStrings_Core
  • Sitecore_ConnectionStrings_Master
  • Sitecore_ConnectionStrings_Web

From your local installed SQL server connect to docker hosted DB-

You should not able to see the DB’s configured to support Sitecore XM Cloud local instance-

Loading

XM Cloud local environment – Working with GraphQL

Assuming Sitecore local instnace is setup, lets look how to work on Graphql in local machine. See this blog post to setup the local machine for XM Cloud development.

<<Blog post url to setup local instance>>

The GraphQL playground (also called the GraphQL IDE) helps you test GraphQL queries before you use them in your application.

For local instance use the following to open the GraphQL IDE- Assuming local host name is – xmcloudcm.localhost

https://xmcloudcm.localhost/sitecore/api/graph/edge/ide

By default it points to https://xmcloudcm.localhost/api/graph/v1 which is a wrong URL as this URL looks for published items.

Use this URL in your local instance-

https://xmcloudcm.localhost/sitecore/api/graph/edge

This required Sitecore API key and looks for unpublished content which is valid for local instance.

Lets query the site info- Local instance site name is sxastarter

And the API key should be at this location. This api key is required to query using GraphQL

Sample query-

query {
 site {
  siteInfo(site: "sxastarter") {
   name
   rootPath
  }
 }
}

Add headers-

{
  "sc_apikey":"5797FECE-6C74-4535-88AC-5303752CCC99"
}

Results-

You now are ready to use your local machine to query using GraphQL.

Hope this helps.

Loading

XM Cloud local environment – Setup a separate JSS application for Headless SXA site

In this blog post we wil setup nextjs application i.e. sxastarter assuming your local Sitecore instance is up and running.

We will create a Headless SXA site in Sitecore local instance and then setup the FE application. This is can also moved outside the Foundation Head repo so that FE devs can work on this spearately.

Setup JSS app to work with local Sitecore instance

Ensure you have Sitecore instance up and running see this blog << 2. XM CLoud for local env>> or you can also see this blog

1. Setup your JSS app

Ensure you execute this commands on FE folder i.e. /src/sxastarter

Ensure you have Sitecore JSS CLI installed on local machine

 

Once this is installed Setup the JSS app-

jss setup

Following is required to setup-

jss setup
Is your Sitecore instance on this machine or accessible via network share? [y/n]: n

Sitecore hostname (e.g. http://myapp.local.siteco.re; see /sitecore/config; ensure added to hosts): https://xmcloudcm.localhost
Sitecore import service URL [https://xmcloudcm.localhost/sitecore/api/jss/import]:
Sitecore API Key (ID of API key item): {5797FECE-6C74-4535-88AC-5303752CCC99}
Please enter your deployment secret (32+ random chars; or press enter to generate one): 

Provide the Sitecore hostname and the api secret, in this case xmcloudpreview item id at following location /sitecore/system/Settings/Services/API Keys/xmcloudpreview

Note the deployment secret. This is required to setup Headless Site, in this case it is bz39czqkd47o0n7nvfm11kaoexuouk5dq2z4fhsrl3

Also note the sscjssconfig.json file updated.

2 . Create a Healdess Tenant and Site

In your Sitecore instance create a Healdess Site Collection, you may create a folder Site Collection Folder if required-

Next provide the Site collection name, in this case scxmcloud and select the required modules-

You should see the Site collection created along with the required templates in Project/scxmcloud folder.

Setup should create folders and required items in following location. Note this as this is required whilst setting the item sync using Sitecore SCS (Sitecore Content Serialization)

Layout Placeholder Settings- /sitecore/layout/Placeholder Settings/Project/scxmcloud

Layout Renderings – /sitecore/layout/Renderings/Project/scxmcloud

Media Library – /sitecore/media library/Project/scxmcloud

Templates – /sitecore/templates/Project/scxmcloud

Create a Headless SXA Site

Create headless site under site collection-

Provide the name of the site- sxastarter

Select the modules- Note I selected the basic site module. This should add sample items to home page along with About page. You may choose not to select the basic site module.

Enter the deployment secret created whilst setting up the JSS app

Site should now be created-

Site without Basic Site module-

Open the experience editor and you should see the blank page-

Lets add the Title component to see if the changes are reflecting in Experience Editor and FE.

Testing GraphQL IDE for local environment

Try the graphql ide here on your local instance –

https://xmcloudcm.localhost/sitecore/api/graph/edge/ide

And the request for same should be sent to –

https://xmcloudcm.localhost/api/graphql/v1

We now have site ready to start developing components.

Run the FE site

On your root folder /src/sxastarter folder run following-

npm install
npm run start:connected

npm install – should download all the required dependencies

You may fix any vulnerabilities by running-

npm audit fix
OR
npm audit fix --force

Before starting the jss app ensure the app name in Sitecore matches the app name in package.json file.

If you wish to change the app name you to make changes in Sitecore and package.json file.

To start the sxastarter jss app run-

npm run start:connected

If no errors the app should be available on http://localhost:3000

The newly added title in header should also be displayed-

Managed to add inbuilt components to page-

This conculdes setting up the local environment with having Sitecore CM instance and the jss app (FE) running on localhost. Note JSS app is not runing on containers as we should not force FE devs to work on containers. This scenario is good for Sitecore developers for bulding and testing the components locally.

You may pull out the sxastarter folder outside this repo and FE devs should be good to develop on theri own. Although there is a dependency to have Sitecore instance hosted on local environment.

In next blog post we will how to setup the FE without having Sitecore local instance and connect to XM Cloud.

But before that we need to setup the XM Cloud project and environments, for that we will configure the Sietcore Content Serilization to push the changes made in local to XM Cloud. Coming in next blog.

Connect your local FE app to XM Cloud.

Although not recommended but if you want ot connect the XM Cloud instance to local FE app. Follow these steps.

I need to make changes in 2 places to get this working.

docker-compose.override.ymlrendering

Change environement settings–

SITECORE_API_HOST – The host name of XM instance.

SITECORE_API_KEY- This is the delivery api token

Generate this from XM Cloud if not done before.

    environment:
      SITECORE_API_HOST: "https://your-instance.sitecorecloud.io" #"http://cm""http://${CM_HOST}"
      NEXTJS_DIST_DIR: ".next-container"
      PUBLIC_URL: "https://${RENDERING_HOST}"
      JSS_EDITING_SECRET: ${JSS_EDITING_SECRET}
      SITECORE_API_KEY: "your_delivery_api_token" #"${SITECORE_API_KEY_xmcloudpreview}"
      DISABLE_SSG_FETCH: ${DISABLE_SSG_FETCH}
      NODE_TLS_REJECT_UNAUTHORIZED: 0

FE (sxastarter) .env file-

GRAPH_QL_ENDPOINT to https://edge.sitecorecloud.io/api/graphql/v1

Spin-up the containers again and shold render the content

Hope this helps.

Loading

XM Cloud local environment – Setup a JSS application – sxastarter for Headless SXA site

In this blog we will create a Headless SXA Site in local instance, setup and resolve any errors while running the rendering app (sxastarter)

We will create a Headless SXA site in Sitecore local instance and then setup the FE application.

With the local Sitecore instance(CM) you should also see the rendering host is configured i.e. https://www.sxastarter.localhost/

While seting up the local instance we haven’t made any changes to docker compose or override files nor to the .env files manually, although while initalizing the app certian key values were updated in .env file.

Check the sxastarter rendering host- https://www.sxastarter.localhost/

At this point you might see the error since we haven;t created a sxastarter app in Sitecore.

This is because the no Site Collection or Headless Site exists in Sitecore. Lets create a Headless Tenant and Site.

2 . Create a Healdess Tenant and Site

In your Sitecore instance create a Healdess Site Collection, you may create a folder Site Collection Folder if required-

Next provide the Site collection name, in this case scxmcloud and select the required modules-

You should see the Site collection created along with the required templates in Project/scxmcloud folder.

Setup should create folders and required items in following location. Note this as this is required whilst setting the item sync using Sitecore SCS (Sitecore Content Serialization)

Layout Placeholder Settings- /sitecore/layout/Placeholder Settings/Project/scxmcloud

Layout Renderings – /sitecore/layout/Renderings/Project/scxmcloud

Media Library – /sitecore/media library/Project/scxmcloud

Templates – /sitecore/templates/Project/scxmcloud

Create a Headless SXA Site

Create headless site under site collection-

Provide the name of the site- sxastarter.

You may choose another name but ensure the package.json file is updated accordingly.

Select the modules- Note I selected the basic site module. This should add sample items to home page along with About page. You may choose not to select the basic site module.

Enter the deployment secret created whilst setting up the JSS app

Site should now be created-

Site without Basic Site module-

Keep the Site Settings as is-

sxastarter site is created along with this the choosen mdoules are installed.

Once this is done ensure the app name in Settings is same as in package.config-

Open the experience editor and you should see the blank page-

Lets add the Title component and images to see if the changes are reflecting in Experience Editor and FE.

Visit the https://www.sxastarter.localhost/ and the images are not loading

This is due to the local instance has relative media url for local instance.

Solution-

Patch the local instance to include – IncludeServerUrlInMediaUrls

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:set="http://www.sitecore.net/xmlconfig/set/" xmlns:env="http://www.sitecore.net/xmlconfig/env/">
  <sitecore>
    <layoutService env:require="Development">
      <configurations>
        <config name="sxa-jss">
          <rendering>
            <renderingContentsResolver>
              <IncludeServerUrlInMediaUrls>false</IncludeServerUrlInMediaUrls>
            </renderingContentsResolver>
          </rendering>
        </config>
      </configurations>
    </layoutService>
  </sitecore>
</configuration>

I did this in VS, Platform project. Added the config file in App_Config/Include/Feature named z.Plaform.Feature.IncludeServerUrlInMediaUrls.config

Publish the project and this file should be then deployed to CM container.

Now this should display the images-

Testing GraphQL IDE for local environment

Try the graphql ide here on your local instance –

https://xmcloudcm.localhost/sitecore/api/graph/edge/ide

And the request for same should be sent to –

https://xmcloudcm.localhost/api/graphql/v1

We now have site ready to start developing components.

The newly added title in header, images should also be displayed-

This conculdes setting up the local environment with having Sitecore CM instance and the jss app (FE) running in docker. JSS app is runing in container.

In next blog post we will how to setup the FE without having Sitecore local instance and connect to XM Cloud.

But before that we need to setup the XM Cloud project and environments, for that we will configure the Sietcore Content Serilization to push the changes made in local to XM Cloud. Coming in next blog.

Errors-

sxastarter site hosted in docker throws below error.

Solution

See the resolution for this error here

https://sitecore.stackexchange.com/questions/35307/sitecore-xm-cloud-local-setup-error-with-node-js

I updated the rendering Dockerfile –> Entrypoint to clean and install the npm

npm ci && npm run start:connected

This should resolve the issue. Hope this helps.

Loading

Secure Sitecore Webhooks using Microsoft Azure AD B2C

Few months back I was trying to Authorize Sietcore Webhooks using Microsoft Actice Directory B2C and found issue that it wasn’t working.

After creating a support ticket, Sitecore logged this as a bug.

This was resolved and release on 20th Feb 2024.

This blog helps on how to configure MS AD B2C and configure in Sitecore as Client Credential grant to generate an access token so the Event receiver can authorize and process the request.

Note- text highlighted in red is required later to configure in Sitecore.

Reference-

https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-manager/webhook-authentication-types.html

https://developers.sitecore.com/changelog/xm-cloud/1.5.69-base-image-update%3a-resolved-issues

Pre-requisite

You should have your Azure AD B2c tenant. See this link on how to set this – Tutorial – Create an Azure Active Directory B2C tenant | Microsoft Learn

Once configured you see the options to register your app.

Before registering app note down the highlighted. This should be available as the part of Endpoint-

This is Authority URL in Sitecore Webhook.

Step 1 – Register App

Click on New registration

Provide the App registration name and selected supported account types. In this case I have given name – SCXMCWebhook and selected “Accounts in this organizational directory only (SC XM Org only – Single tenant)

Register App and it should show the registered app-

It should also list your newly created app-

Step 2 – Add an Application URI

Click on Application ID URI “Add”link and then “Add a scope”

This should create a URI –

Step 3 – Add a scope

Now create a scope “Add a scope”. Enter scope name, admin consent and description. Ensure you enable the scope.

A new scope isadded . Copy the scope as highlighted –

Step 4 – Create Secrets

Navigate to Overview tab and you should see all the configured details.

Step 5 – Create a Client Credential Grant Authorization in Sitecore

Sitecore Client CredentialMicrosoft AD B2C
Authority URL Microsoft Entra ID OpenID Connect
metadata document. (Check Endpoints)
Client IDApplication (client) ID
(Check Overview tab)
Client SecretClient Secret Value
(Check Certificates & Secrets tab)
Scope
(Append /.default)
Application ID URI
(Check Overview tab)
Header Prefix
(Bearer)
Additional Endpoint Base Addresses
(See Semicolon seperated values below)
Directory (tenant) ID
(Part of the url- Check Overview tab)
e.g.:- 10d**************1b4c

Additional Endpoint Base Addresses

https://login.microsoftonline.com/10d**************1b4c/discovery/v2.0/keys
https://login.microsoftonline.com/110d**************1b4c/oauth2/v2.0/token
https://graph.microsoft.com/oidc/userinfo
https://login.microsoftonline.com/10d**************1b4c/oauth2/v2.0/authorize
https://login.microsoftonline.com/10d**************1b4c/oauth2/v2.0/devicecode
https://login.microsoftonline.com/10d**************1b4c/oauth2/v2.0/logout
https://login.microsoftonline.com/10d**************1b4c/kerberos

Client Credential Grant Authorization Item should look like this-

Please note Additional Endpoint Base Address are Semicolon seperated.

Step 6 – Create a Webhook Handler in Sitecore

Create Webhook handler at this location- /sitecore/system/Webhooks/

Provide the Description, Select the events the webhook should trigger, Add any rules as per your requirements, Ensure to Enable the Webhook, provide the Url the webhook should send the item data, select the newly created Authorization and Selrialization type (JSON).

Step 7 – Save an Item in Sitecore

Update an Item, in this case I updated Home item

You should see the webhook sends the request to defined Url with Access Token, as highlighted below-

Hope this helps to cionfigure MS AD B2C in your Sitecore instance

More reads-

Loading

XM Cloud Dev Error: Hydration failed – while using XMC with Nextjs

Recently, I started receiving error-

Unhandled Runtime Error

Error: Hydration failed because the initial UI does not match what was rendered on the server.

This error was specifically while using RichText field.

Resolution-

Hyderation is when React converts the pre-rendered HTML from the server into fullly interactive application by attaching event handlers.

The common casue of this issue is incorrect nesting of HTML tags.

RichText is wrapped in div tag and received this error when the RichText was wrapped in <p> tag

Example where React throws error-

Incorrect way of wrapping RichText-
<p className="page-desc text-white mb-0"> 
   <RichText field={props.fields.Description} />
</p>

Remove the <p> tag or wrap RichText in <div> tag

Correct way-
<RichText className="page-desc text-white mb-0" field={props.fields.Description} />

Remvoing <p> might removing spacing between fields/components, this needs to be adjusted using CSS.

Reference-

https://nextjs.org/docs/messages/react-hydration-error

Loading