Deploy Salesforce Communities via ANT Migration Tool

2018, Oct 23    

If you recently worked with Salesforce Communities it is not easy to deploy or move to different environments. Here we will demonstrate how to use ANT script and Metadata API to deploy Communities and manage source in GitHub. This an updated blog for Summer 18 & Winter 19 releases as of 10/23/2018.

Based on what I learned from Salesforce one reason it is not easy to deploy Community is its design. Communities Team initially expected Enterprises will be making changes and building Community direct in Production and then move it to sandboxes using the refresh sandbox feature. Going down from PROD to other QA/UAT environment distribution model. The Production org is expected as a source of truth. However, the reality of development is most processes start in DEV sandbox and are expected to move through multiple test stages like QA, UAT, and then PROD. Understanding these requirements Salesforce is working to change the initial idea and make the Community more source-driven with metadata and DX. That is a need that has been recognized and hopefully is coming in some later releases.

For now, we need to deal with the current state and try to deploy our Community from DEV to QA sandbox and later to Production. We start with the existing community we already built with all configurations, pages, and Lightning components, etc. Assume we have all that. Our next step is to export all these customizations and development into source control, in our case it is GitHub. Then deploy this to the target Organization - QA or Production.

Extract Communities Metadata

We need to make a package.xml file for this type of deployment. There is no full set of documentation available on metadata items until Summer 18 Metadata Coverage Report that help with APIs but not for package ANT deployments. I created this GitHub repository sf-metadata-pkg for myself as a reminder maybe it will be a useful reference.

Our community may consist of many different metadata artifacts, VF Pages, Configs settings, Lightning Components, APEX classes, and other things. Metadata for APEX code, Lightning aura components are well documented and known to most developers. Note here we are dealing with new API Version 44.00 Winter 19 for ant.salesforce.jar

We will focus here on the Community itself that is stored in the following metadata components

  • Network - Community settings XML file
  • CustomSite - Associated site settings XML file
  • SiteDotCom - Site content, binary blob autogenerated for community
  • Audience - Built audiences added in recent releases
  • NetworkBranding - branding parameters for the main site (does not include page variations) and need to prefix cb<Name>

Possibly Page variants are supported, I just did not see detailed documentation and could not reverse engineer how to get these items into source. We start our package.xml with these Communities components. Our Community name was ECom as an example.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>ECom</members>
        <name>CustomSite</name>
    </types>
    <types>
        <members>ECom</members>
        <name>Network</name>
    </types>
    <types>
        <members>ECom_C</members>
        <name>SiteDotCom</name>
    </types>
    <types>
        <members>A_Faculty</members>
        <members>B_Faculty</members>
        <members>C_Faculty</members>
        <name>Audience</name>
    </types>
    <types>
        <members>cbECOM_Community</members>
        <name>NetworkBranding</name>
    </types>
    <version>44.0</version>
</Package>

Notice SiteDotCom name ECom_C initially I was not aware this component was there until I try to deploy got this error from ant.

networks/ECom.network -- Error: In field: PicassoSite - no SiteDotCom named ECom_C found

Added this component, it is auto-generated for each Community. This file is stored in the form of a large binary blob that represents various content in our Communities and meta XML file. Incidentally, this blob also holds Builder Page configuration (site pages that seem to be cached for the environment). Why this is IMPORTANT I will explain this later.

<?xml version="1.0" encoding="UTF-8"?>
<SiteDotCom xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>ECom</label>
    <siteType>ChatterNetworkPicasso</siteType>
</SiteDotCom>

CustomSite is XML file that describes Force.com Site associated with each Community and automatically created when Community is created.

<?xml version="1.0" encoding="UTF-8"?>
<CustomSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <active>true</active>
    <allowHomePage>false</allowHomePage>
    <allowStandardAnswersPages>false</allowStandardAnswersPages>
    <allowStandardIdeasPages>false</allowStandardIdeasPages>
    <allowStandardLookups>false</allowStandardLookups>
    <allowStandardPortalPages>true</allowStandardPortalPages>
    <allowStandardSearch>false</allowStandardSearch>
    <authorizationRequiredPage>EXT_CommunitiesLoginPage</authorizationRequiredPage>
    <bandwidthExceededPage>EXT_CommunityMaintenanceErrorPage</bandwidthExceededPage>
    <changePasswordPage>EXT_ResetPassword</changePasswordPage>
    <clickjackProtectionLevel>SameOriginOnly</clickjackProtectionLevel>
    <fileNotFoundPage>EXT_CommunityNotFoundErrorPage</fileNotFoundPage>
    <genericErrorPage>EXT_CommunityNotFoundErrorPage</genericErrorPage>
    <inMaintenancePage>EXT_CommunityMaintenanceErrorPage</inMaintenancePage>
    <inactiveIndexPage>CommunitiesLogin</inactiveIndexPage>
    <indexPage>CommunitiesLogin</indexPage>
    <masterLabel>ECom</masterLabel>
    <requireHttps>true</requireHttps>
    <requireInsecurePortalAccess>false</requireInsecurePortalAccess>
    <siteAdmin>my-admin@email.com</siteAdmin>
    <siteType>ChatterNetwork</siteType>
    <subdomain>communitydev</subdomain>
    <urlPathPrefix>ecom</urlPathPrefix>
</CustomSite>

Now that we have our metadata files we can use ant to deploy Community to our target org. Once we run ant command ‘ant deployQA’ as an example and if it is a success we can see all our community elements in target org. Site, Community are in new org, we can also see Admin side has our configs. All seem to be good. Now let’s try Community Builder pages and our components. Open Builder… oh oh we get some JavaScript error.

Community Builder error

Support’s answer to this is to refresh the Community template. This issue is possibly caused by a “caching” (in Salesforce) issue after deployment, (possibly that Site.com BLOB I mentioned earlier). To resolve this issue, we will need to switch the Community Template to Salesforce Tabs + VisualForce then switch it back to Napili Template. Using the following steps below:

  1. Go to Setup > Customize > Communities > All Communities.
  2. Click Manage.
  3. Go to Administration > Settings.
  4. Click Change Template.
  5. Click Salesforce Tabs + Visualforce.
  6. Click Get Started.
  7. Enter the Name and URL then click Create.
  8. Click Manage & Moderate.
  9. Go back to Administration > Settings.
  10. Click Change Template.
  11. Click Customer Service (Napili).
  12. Click Get Started.
  13. Enter the Name & URL then click Create.
  14. Click Build & Customize.

We can do this and it will fix the Community Builder access, but all our custom page configurations and site template layouts will be lost. It is saying to almost flush your Community site pages and build a new site. If it is simple Napili with default pages that will not be a problem. In our case, we had a custom template layout, custom look UI, custom Builder pages all that will need to be rebuilt. I think that is the most common use of Communities today. It is not a very detailed CSS/HTML level rebuild but a Community Builder drag-drop kind of a build but still lots of details in pages and component properties need to be managed. This makes it difficult if not impossible to store Community in source control for distribution or CI/CD.

Conclusion, while deploying a Community is made possible with metadata API Network metadata component not everything can be handled by this method. When we need a complete custom looking community it may be better to package it as a custom Community Template with pages and distribute it this way. I will have to try that method next and see how that works. We will also need to look at the DX-Community deployment option may be a way to handle this in the future.

Twitter Facebook Google+