Category: Headless Development

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 –

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.

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.