Deploying Salesforce communities via the metadata API

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.

Enabling communities

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 class, 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:

Deploying branding

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 Network, CustomSite and 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.

1. Similar to when deploying a new community, Gearset will detect an attempt to deploy the siteAdmin element and offer to fix it for you. When deploying a change to a community, Gearset replaces siteAdmin with the value from the target.
2. SiteDotCom sites 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 SiteDotCom site has actually changed or not. This issue aside, if you make a change to a SiteDotCom site 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.
3. The subdomain element of the CustomSite will automatically be replaced by Salesforce with the value from the target. This is also the case when deploying new communities.

Conclusion

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!