Deploying communities can be challenging, so much so that we wrote a blog post about it, which contains detailed technical guidance and troubleshooting. Since the original blog post, and our subsequent documentation on the subject, Salesforce has continued to evolve. This document addresses those changes.
Why would you want to deploy changes incrementally to a Digital Experience?
Communities, recently (Spring '21) rebranded as Digital Experiences, can be difficult to deploy without experience due to a large number of moving parts needed for a successful deployment. These include branding, permissions, moderation, and content rules, as well as a myriad of other components which make up a complete portal.
It's a common use case to want to update communities one page at a time. An example of the way Digital Experiences are used is a university maintaining a publicly accessible page to keep students updated on the special arrangements in place due to Covid-19. You may not want to redeploy your whole community, as it makes sense just to add to/update the 'Covid' page for your portal or add a new page specifically for the purpose of telling the students how you're handling the latest updates to the rules.
Another reason users want to update their communities incrementally is that they're working in VS Code. As you can see in this Salesforce documentation, the
Experience bundle, when viewed in VS Code, is a folder structure with the various components represented as editable files. As you update each of these files with your changes, you want to get them deployed into the testing environment to get feedback as part of a robust CI/CD process.
How does Gearset selectively deploy Experience Bundle components?
For deployments made through the metadata API, Salesforce requires a complete
Experience bundle. Gearset employs a clever workaround where we combine the selected
Experience bundle components from the source with the existing
Experience bundle components from the target. The net effect is that only the selected
Experience bundle components from the source are updated in the target.
How can you deploy a Digital Experience using Gearset?
Because of the hierarchical nature of metadata in Salesforce, there are a few steps required if the Digital Experience does not already exist in the target.
If the Digital Experience already exists then please skip to the section 'How to deploy pages'.
Step one: Enablement
In order to compare and deploy Digital Experiences using Gearset you will need to make sure that in the settings of your source and target orgs you have
Enable Digital Experiences and
Enable Experience bundle API selected:
Step two: Apex
Upon creating your first community in an org, a variety of supporting Apex pages, components and classes are automatically generated by Salesforce to provide the basic scaffolding for communities.
This scaffolding includes code and pages to handle user registration, login, password resetting, and so on. If you forget these in your deployment, you're likely to receive an error along the lines of
In field: indexPage - no ApexPage named CommunitiesLanding found, so you'll need to make sure to include these in your deployment.
Run a comparison and filter for
Apex component and
You may also need to include
Static resource as it is common for them to be used in communities and therefore referenced by the related Apex pages.
Step three: Digital Experience specific metadata
In 2019 Salesforce released a new metadata type, called
Experience bundle. We wrote a blog post about this at the time, which describes the difference between this and the original
SiteDotCom binary blob that contains information about the community.
Like the transition to SFDX formatted repositories from MDAPI format, the
Experience bundle makes it less likely for independent work to overlap within the same community as it splits the components into individual files. It is also human-readable which is an improvement over the binary blob.
For the second step of your deployment, you need to select the
Custom site, and
Experience bundle components from your comparison. When you search for them you may notice that they are marked with the
(Community) tag in the metadata type filter.
As you can see in the screenshot, the details of the
Experience bundle are readable in the diff viewer, and in this example we can see information about the color values of the branding set.
One common error message when deploying communities is
In field: siteAdmin - no User named [email protected] found. This occurs when the user specified as
siteAdmin in the source doesn't exist in the target.
The problem analyzer generated on the next screen removes references to users (which are unique to the source org) from the
Custom site. This means Salesforce will automatically set
siteAdmin in the target to the user on the target who is currently being used to run the comparison (and subsequent deployment).
Having completed these two steps we have established the community in both source and target and can begin moving customized pages and other components from the development org to the staging org using Gearset.
How to deploy theme customization
In order to deploy theme changes, you will need to select the relevant
Experience bundle component as well as any
Content assets. In this example, these are the elements I required to make the following theme changes.
How to deploy pages
This is one of the most common reasons that users want to deploy updates to their Digital Experiences. It's common to build sites pages by page, or only need to update a specific page. Gearset allows you to deploy components of your community without having to redeploy the entire site.
Once you have created a page it will contain several different components; for example, on this page we have a
rich text area,
content topics, and a
In order to deploy this page into my target org, we will need to deploy the
Experience bundle component that contains my page. You can see the name of the page here:
We will also need to deploy the
Navigation menu so users can find the page and the