ExperienceBundle: human-readable communities
Ian Hand on June 28th 2019
Salesforce Lightning communities are a great way to drive collaboration between your team members and your customers. That said, collaborative development of communities has always been difficult. Luckily, the new
ExperienceBundle metadata type is here to change that!
The problem with the SiteDotCom type
SiteDotCom metadata type allows you to deploy your community from one org to another, but it stores your community's branding, config, routes, themes, and views as a binary
.site file. This means that you can't compare the differences between two orgs because binary files aren't human-readable.
Another big drawback of the binary format is that you can't merge changes. So if two developers are working on the same community at the same time, there's a risk they'll overwrite each other's changes when they deploy.
How the ExperienceBundle type helps
ExperienceBundle type breaks down the metadata into multiple plain text files - previously, this was all lumped together in the
.site file. As plain text is human-readable, you can compare two communities or two versions of the same community. And now developers can merge their changes!
Even better, there's now a good chance that independent changes won't touch the same files. Previously, if you added two separate branding sets, these would both go in the same
.site file. In the
ExperienceBundle format, the branding sets are separate files in the
brandingSets directory. This is great if you're using source control because Git will be able to merge the two commits for you automatically.
Human-readable is also human-editable: make quick changes locally in your favorite IDE and deploy them to your scratch org - no need to fire up Community Builder every time!
Make sure you enable the feature!
You can only retrieve/deploy an
ExperienceBundle if you enable the feature in
Communities Settings: search for
Communities Settings in
Quick Find, choose
Communities Settings, and make sure
Enable ExperienceBundle Metadata API is checked under
Community Management Settings.
If you try to retrieve an
ExperienceBundle from an org that doesn't have this setting enabled, no
ExperienceBundle will be retrieved - this might mean that your community fails to deploy or that part of it is missing!
For example, I created a new community called CAP in an org that didn't have
Enable ExperienceBundle Metadata API checked, retrieved it using workbench with a
package.xml that included
ExperienceBundle but didn't include
SiteDotCom, and then tried to deploy that package to another org. The deployment partially succeeded but the new community didn't appear in my
All Communities list, and I saw these errors in the
Deployment Status for the deployment:
In field: Name - no Network named CAP found,
Network not found for the CustomBrand : cbCAP, and
In field: PicassoSite - no SiteDotCom named CAP1 found.
When I tried to deploy an
ExperienceBundle to an org that didn't have the
Enable ExperienceBundle Metadata API setting enabled, my deployment failed reporting an error
Not available for deploy for this organization for each item in the
ExperienceBundle overrules SiteDotCom
Don’t use both the
ExperienceBundle metadata types to deploy the same information about your communities because this can have unexpected results.
If you include both the
ExperienceBundle metadata types when you retrieve, Salesforce will give you the metadata in both formats.
If you include both types when you deploy, the
ExperienceBundle overrules the
SiteDotCom; you have to be careful that any changes you want to deploy are included in the
ExperienceBundle. In future, you might be able to include both metadata types without a problem because the
ExperienceBundle is still in Developer Preview and might be changed before it becomes generally available.
At the moment, you can't deploy an
ExperienceBundle to a production org; hopefully this will change in the future. Even without support for deploying to production,
ExperienceBundle can still be super useful: use it while you're developing and testing and then use
SiteDotCom just for that final deployment to production.
This feature is available as a Developer Preview, so the details might change.
[Update, May 21, 2020: The
ExperienceBundle metadata type is now out of Developer Preview and can be deployed to production orgs.]
Want to try it out?
We're currently adding support for this new metadata type in Gearset. Let us know if you've used the
ExperienceBundle metadata type and, more generally, if we can help you with deploying communities. Just get in touch with us via the in-app chat or by email. Alternatively, leave us a suggestion on our feedback forum.
Update: Not all communities are supported!
We've been playing around with communities some more, and discovered that not all of them are supported by the
ExperienceBundle metadata type.
When I tried to deploy a community called
awesome that I created from the
Aloha standard template, no ExperienceBundle was included in the package I retrieved from Salesforce.
The message in the response was pretty to the point:
ExperienceBundle Metadata API doesn't support the template of awesome1.
Hopefully support for more templates will be added as time goes on! For the time being we'll have to fall back on
SiteDotCom for these communities.