Deploying Salesforce communities via the metadata API
Matt Dickens on July 24th 2017
We're all agreed that deploying Salesforce communities can be fairly tricky. If the following errors are familiar to you, read on:
In field: indexPage - no ApexPage named CommunitiesLanding found
In field: siteAdmin - no User named [email protected] found
In field: Network - no Network named Gearset found
In field: Site - no CustomSite named Gearset found
Deploying new communities
If you're deploying a new community to an org that's never used communities before, then there are a few steps you'll need to be aware of.
You'll first need to make sure that communities are enabled in that target org. You can do this from "Communities" in your org's setup:
Just check the "Enable communities" checkbox, and specify a valid subdomain.
Version 40 of the metadata API includes a
NetworksEnabled preference in
OrgPreferenceSettings - if communities are enabled in the source and not in the target, then you'll see this appear in the diff view in Gearset for the
OrgPreference item. Unfortunately, as of time of writing a change to this value isn't deployable via the metadata API, so enabling communities will remain a manual step for the timebeing.
Deploying apex scaffolding
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:
You can narrow down the comparison view in Gearset to these types using Gearset's filtering - just pick
Apex component and
Apex page, or use this handy regex in Gearset's comparison result filter:
regex:^Apex class$|^Apex component$|^Apex page$
Deploying the community itself
At this point, we're ready to address the community itself. In its simplest form, a community will consist of the following metadata types:
Network- The community's settings
CustomSite- The settings for the associated site
SiteDotCom- The binary blob that contains the site content
You'll need to make sure all three of these types are included in your comparison. Note that by default,
SiteDotCom sites aren't included in comparisons in Gearset, so you'll need to add this to your comparison filter in Gearset before running your comparison. Note that this list doesn't include the
Community (Zone) metadata type, which refers to chatter answers and ideas.
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. Gearset includes a problem analyzer that will help you avoid this issue by removing the
siteAdmin element from the
CustomSite's metadata. 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):
If you've enabled communities, selected all the related apex classes, pages and components, and the three parts of your new community, you should find that you can successfully validate and deploy your deployment package:
If you've customised your community's branding, there are a few extra types you'll need to consider:
NetworkBranding- The core of your community's branding, including colours and logos
BrandingSet- Additional assorted branding properties
ContentAsset- The metadata for an asset file, required for logos and header images
Including these alongside
SiteDotCom in your deployment will ensure that the look and feel of your community is migrated to the target org.
Deploying changes to communities
Deploying changes to communities is very similar to deploying new communities, just without the initial prerequisite steps. Communities will already be enabled in the target, and the default apex scaffolding will already be present. Just pick the main constituents of your community and any new or changed dependencies and Gearset should do the rest. There are, however, a couple of things to be aware of.
- Similar to when deploying a new community, Gearset will detect an attempt to deploy the
siteAdminelement and offer to fix it for you. When deploying a change to a community, Gearset replaces
siteAdminwith the value from the target.
SiteDotComsites are inscrutable binary blobs, so Gearset only gives you the MD5s of the source and target in the comparison view. Unfortunately, Salesforce generates a different binary blob each time it's fetched from Salesforce, meaning that the MD5s will change every comparison. This makes it difficult to establish whether a
SiteDotComsite has actually changed or not. This issue aside, if you make a change to a
SiteDotComsite and deploy it via Gearset, the change will be deployed to the target, though you'll still see a different MD5 next time you run a comparison.
subdomainelement of the
CustomSitewill automatically be replaced by Salesforce with the value from the target. This is also the case when deploying new communities.
We've heard from a lot of users that deploying new and changed communities is challenging. With the latest release of Gearset, a lot of those pains should disappear.
Have you hit other snags while deploying communities? If so, we'd love to hear from you - just leave a message for the team at [email protected], or through the in-app chat!