The XM Cloud build configuration

The XM Cloud build configuration for an environment is defined in the xmcloud.build.json file. The file contains configurations for editing hosts, build targets, serialization modules to deploy to the XM instance for that environment, and more.

Tip

You can consult the PLAY! Summit project repository for a working example of the xmcloud.build.json file.

The XM Cloud build configuration object has the following structure:

RequestResponse

{
  "deployItems": {
    "modules": []
  },
  "buildTargets": [],
  "renderingHosts": {
    "<key>": <value>
  },
  "transforms": [],
  "postActions": {
    "actions": {
      "<key>": <value>
    }
  }
}

The following table shows the properties of the XM Cloud build configuration object:

Name	Description
`deployItems`	Allows you to define what serialization item modules you want to deploy. It is similar to the serialization configuration defined in the `sitecore.json` file. Useful to limit what you deploy when working locally. All modules defined here are converted into an Items as Resources (IAR) file. It does not support roles. If you need to deploy roles, use the SCS module deployment action. For example: RequestResponse `"deployItems": { "modules": [ "Foundation.", "Feature.", "Project.*" ] }`
`buildTargets`	Allows you to define which projects and solutions to build. For example: RequestResponse `"buildTargets": [ "./src/CM/Platform.csproj", "./src/CM/Root.sln" ],` This configuration affects how you pass arguments to the `msbuild` command: RequestResponse `msbuild .\src\platform\Platform.csproj /p:Configuration=$env:BUILD_CONFIGURATION /m /p:DeployOnBuild=true /p:PublishProfile=Local`
`renderingHosts`	Allows you to configure the location for the rendering hosts and the sites they map to. It consists of key-value pairs where the key is a unique site name , and the value contains information about the site.
`transforms`	An array of items mapping an XDT path to a target path. Allows you to specify fully qualified paths with wildcards to the location where you want to process XDT transforms.
`postActions`	Operations to perform following the deployment stage of an XM Cloud deployment process.

Configuration options for rendering hosts

You can define rendering hosts in the XM Cloud build configuration file. Each definition maps a unique site name to information about the site.

For example:

RequestResponse

  "renderingHosts": {
    "xmcloudpreview": {
      "path": "./src/rendering",
      "nodeVersion": "16.3.19",
      "jssDeploymentSecret": "super-secret-value",
      "enabled": true,
      "type": "sxa",
      "buildCommand": "build",
      "runCommand": "next:start"
    }
  }

The following table describes the properties you use to configure the site information:

Name	Type	Description
`path`	`string`	The relative path from the `xmcloud.build.json` file to the app source code. Usually, it is the relative path from the root folder.
`nodeVersion`	`string`	Specific Node.js version for rendering host.
`jssDeploymentSecret`	`string`	A randomly generated string of 32 or more characters. The deployment secret is a shared secret that authorizes the application to deploy items to the Sitecore instance. It populates the value for `deploySecret` in the `scjssconfig.json` file.
`enabled`	`boolean`	Enables the site. Default: `false`.
`type`	`string`	Type of rendering host. Allowed values: `"jss"` or `"sxa"`. Default: `"jss"` Note An SXA site is created from an SXA template and uses item-based configuration. A JSS site is created from a JSS template and uses file-based configuration.
`buildCommand`	`string`	Build command from the `package.json` file to run. Default: `"build"`
`runCommand`	`string`	Run command from the `package.json` file to run. Default: `"next:start"`

Important

startCommand has been deprecated and is ignored. Use buildCommand and runCommand instead.

XDT transformations

To support XDT transforms, you must specify the fully qualified paths to a folder or an XDT source file and configuration destination files.

Transformations occur on the fully built solution.

The paths must be relative to the web root of the built code. For example, assuming your XDT source files are located in the src/platform/xdts folder, you can configure transform paths as follows:

RequestResponse

  "transforms": [
    {
      "xdtPath": "/xdts/<some-transforms>/",
      "targetPath": "/<somewhere>/"
    },
    {
      "xdtPath": "/xdts/<trasforms-at-the-root>/",
      "targetPath": "/"
    },
    {
      "xdtPath": "/xdts/web.config.xdt",
      "targetPath": "/web.config"
    }    
  ]

Note

The value of the xdtPath property for each transform depends on how you organize your project files. In this example, we assume your project is based on a foundation template provided by Sitecore and that your transformations are in the /src/platform/xdts/ folder. For information on how to define XDT files, consult the documentation for web.config transformations.

Post-deployment actions

You can configure various operations, called post actions, that run after the deployment stage of an XM Cloud deployment process.

The XM Cloud build configuration includes default actions you can customize to fit your requirements. They are defined using the actions property of the postActions object and include:

CM warm-up.
Deploying SCS modules.
Schema population.
Reindexing.
Publishing.

Note

Post actions run one after the other, in the order which they appear in the configuration file. Therefore, when configuring your post actions, we highly recommend that you do not change the order of the actions.

The order shown in the following example ensures that if you deploy SCS modules, they will be published. And that the indexes are populated before reindexing.

The post actions configuration has the following structure:

RequestResponse

"postActions": {
  "actions":{
    "warmUpCm": {
      "urls": []
    },
    "scsModules": {
      "modules": []
    },
    "populateSchema": {
      "indexNames": []
    },
    "reindex": {
      "indexNames": []
    },
    "publish": {
      "path": "",
      "languages": [],
      "itemIds": [],
      "targets": [],
      "republish": true,
      "publishSubItems": true
    }
  }
}

The CM warm-up action

You can warm up various Sitecore XM Cloud pages by defining an array of relative URLs in the urls property of the warmUpCm action.

For example:

RequestResponse

"warmUpCm": {
  "urls": [
    "/sitecore/shell",
    "/sitecore/shell/Applications/Content%20Editor.aspx?sc_bw=1",
    "/sitecore/client/Applications/Launchpad",
    "/sitecore/client/Applications/ControlPanel.aspx?sc_bw=1"
  ]
}

The SCS module deployment action

You can deploy Sitecore Content Serialization (SCS) modules to the Sitecore instance using the scsModules action.

The structure of the scsModules action is:

RequestResponse

"scsModules": {
  "modules": ["Module1","Module2"]
}

The schema population action

You can restrict the managed schema population to specific indexes by defining a list of index names in the indexNames property of the populateSchema action.

An empty array results in the population of all available indexes.

For example:

RequestResponse

"populateSchema": {
  "indexNames": []
}

The reindexing action

You can restrict reindexing to specific indexes by defining a list of index names in the indexNames property of the reindex action.

An empty array results in the reindexing of all available indexes.

For example:

RequestResponse

"reindex": {
  "indexNames": []
}

The publishing action

You can configure publishing operations using the publish action.

The structure of the publish action is:

RequestResponse

"publish": {
  "path": "",
  "languages": [],
  "itemIds": [],
  "targets": "",
  "republish": true,
  "publishSubItems": true
}

When using the publish action to publish an item, you can control the publishing of its subitems by defining the publishSubItems property within the publish action. If this property is not included, subitems will be published by default.

Allowed values:

true - subitems will be published.
false - subitems will not be published.

The following example does not publish the subitems of /sitecore/content/Home:

RequestResponse

"publish": {
  "path": "/sitecore/content/Home",
  "languages": [],
  "itemIds": [],
  "targets": [],
  "republish": true,
  "publishSubItems": false
}

Change the post action timeout

The default timeout for each post action is 30 minutes. In some cases, you might need to override the default timeout, for example if there is a large number of items to reindex.

You can change the default timeout by defining the taskTimeOut property in the post actions structure.

The following example changes the post action timeout to 45 minutes:

RequestResponse

"postActions": {
  "actions":{
    ...
  },
  "taskTimeOut": "00:45:00"
}

Do you have some feedback for us?

If you have suggestions for improving this article,