Community Deployment | ExperienceBundle

With the Spring ’20 release (API 48.0), ExperienceBundles have become Generally Available (GA) to any Salesforce instance, allowing you to deploy Community configurations! Have a read to understand why and how to migrate deploying your community using [Network, NetworkBranding, CustomSite and SiteDotComSites] to [Network, CustomSite and ExperienceBundles].

What and why?

Salesforce Release Documentation:
Previously, a community was defined by the combination of the Network, NetworkBranding, CustomSite, and SiteDotCom metadata types. However, retrieving the SiteDotCom type produces a binary .site file, which isn’t human readable. By retrieving the ExperienceBundle type instead of SiteDotCom, you can extract granular community metadata in a human-readable format, contained in a three-level folder structure.

The experiences folder contains all the Lightning communities in your org. Each community folder contains subfolders that represent the different components that you access in Experience Builder. Edit the .json files on your local machine or scratch org, and then quickly deploy your changes.

With the ExperienceBundles, you’ll now be able to see exactly what changes have been made, allowing a much better version control and understanding of changes. Hence, you can explicitly decide which changes to check-in, instead of crossing your fingers, hoping no colleague has worked on something else in the same community, which would then also be included in the big blurry SiteDotCom .xml-file.

With ExperienceBundles you’ll be able to control and own the release of your Community. Of course there will be some manual steps left in the beginning, but hopefully Salesforce will tackle those missing items shortly (like Theme Layout Properties which are included per Summer ’20).

• BrandingSets – includes all branding configuration like colors and fonts; replaces NetworkBranding metadata;
• Config – includes Site config (e.g. login page, guest access enabled, trusted sites), Language config (available and default) and Single-Page Application Configs (CMS Settings, Custom Head Markup);
• Routes – includes Page routing (page type, page access and url);
• Themes – includes Theme configuration (like Search and Hero settings as well as Theme Region assignments);
• Variations – includes Audience variations (visibility of branding, page and/or component);
• Views – includes Page content (Regions and their related Components incl. attributes).

How to migrate?

1. In you Salesforce Org select “Enable ExperienceBundle Metadata API” and save in Setup > Community Settings;
2. Retrieve ExperienceBundles in your IDE or using Workbench
   1. You might need to regenerate the Offline Symbol Table (was needed for IntelliJ with IlluminatedCloud to get this properly fetched)
3. Add the ExperienceBundle folder(s) and remove the SiteDotComSite and NetworkBranding folder(s) from your Deployment Package, reflect this in the package.xml [e.g. Commit to Repository];
4. Perform a validate deployment
   1. Optionally include settings/Communities.settings and ExperienceBundle.settings;
   2. Perform the manual pre-deployment step of enabling the ExperienceBundle Metadata API in the target environment, since this is apparently not yet possible by only adding ExperienceBundle.settings, or at least not within the same package deployment as the one including ExperienceBundles;
5. Fix the ExperienceBundles validate failures in your IDE and save back to your DEV environment; update them in your Deployment Package and validate again, till you have a successful validation deployment.

As specified above, my experience have been that SiteDotComSites have been a bit more lenient due to the complexity in the Binary file. Now all is clearly visible in .json files, Salesforce can restrict the logic a bit more.

Known Deployment errors

Common issues which could occur while deploying ExperienceBundles:

• Implement “forceCommunity:availableForAllPageTypes” for the Aura component c:XXX with ID YYY and try again.
  • Cause: implements="forceCommunity:profileMenuInterface" and implements="forceCommunity:searchInterface" are not sufficient anymore when deploying via ExperienceBundles
  • Fix: enrich the existing implements with forceCommunity:availableForAllPageTypes and commit the updated Aura component
• The PageAccess property of /routes/[page].json can’t be changed during deployment. Update your file and try again.
  • Cause: For me, my IDE (IntelliJ) caused malformed ExperienceBundles when retrieving from an org with multiple (6) Communities. Not all mainApps.json (config folder) were retrieved and all route-pages referenced the mainApp Id of one other community;
  • Fix 1: install a version later than IlluminatedCloud 2.1.2.7 (fixed by issue 1646)
  • Fix 2: retrieve package using Workbench and copy that metadata into your IDE folder to commit;
• We couldn’t validate componentAttributes in views/[page.json] for component XXX. Error: attribute [relatedListName]: Attribute is required and missing a value. Check your file and try again.
  • Cause: For some reason a required field is unspecified, e.g. due to some invalid CommunityBuilder configuration.
  • Fix: In my scenario I could compare with other values specified for the parentRecordId and relatedListName attributes of a forceCommunity:relatedList, which resulted in "{!recordId}" and "{!relationshipApiName}", respectively.
• We couldn’t validate componentAttributes in views/mDFAndCoop.json for component XXX. Error: attribute [scope]: Specify a valid entity..
  • Cause: The template for a Partner Community by default includes the mDFAndCoop page (Market Development Funds). This page contains three references to Related lists of the objects: PartnerFundAllocation, PartnerFundRequest, PartnerFundClaim. When those don’t exist in your org. This failure occurs.
  • Fix: simply remove the Related List component of the page when not in use and retrieve the package again
• Site Component Label: data value too large: Dealer_Contract_Allocation_Detail_Dealer_Contract_Allocation_Detail_Page Component Variant (max length=80)
  • Cause: Salesforce has apparently restricted the Page Variations developer- and filename by a max. length of 80 when deploying via ExperienceBundles. This name is constructed by the Page Name and the Page Variation Name. Having a large Object name already (by default) causes a too long name (e.g. Dealer_Contract_Allocation__c > Dealer_Contract_Allocation_Detail_Dealer_Contract_Allocation_Detail_Page)
  • Fix: Delete the Page Variation and rebuild the page with a shorter Page Variation Name (my end result: Dealer_Contract_Allocation_Detail_DCA_Detail_Page)
• We couldn’t validate componentAttributes in views/[page.json] for component XXX. Error: attribute [layoutType]: Attribute value is not valid 1. Check your file and try again.
  • Cause: when the exported value (in the .json) is not matching the input of the CommunityBuilder component. In my case this was related to the CMTD Enhanced Related List component. The exported value was 1 (Number), while the value in Community Builder was “1 Column”
  • Workaround: Manually update the incorrect value to the exact value specified in the Community Builder and validate the result
  • Fix: Salesforce acknowledged in a Case reply the ExperienceBundle generator had a bug, causing any attribute named layoutType to be exported as 1, independent of the specific scenario (e.g. in my case a Managed Package). This will be resolved by Summer ’20 (around July 18th);

Known issues after Deploying Experience Bundles

The first successful build after migrating from SiteDotComSites to ExperienceBundles. You’re excited to have overcome the previous challenges in deploying the new .json-structures. You open your CommunityBuilder to check whether all is deployed properly and the you see…

• Navigation menu is not shown properly
  • Issue: Theme Styling alters when deployed using ExperienceBundles. In our case our Navigation Menu disappeared, caused by links being shown in white on a white Header back background
  • Cause: for some reason the original theme was shown in the sequential environment, even while it was changed and committed properly in the develop environment.
  • Fix: Salesforce released patch 8.0 to all Summer ’20 environments to tackle this issue (link)

Conclusion

Salesforce has made a significant step in the maturity of Community Deployments, allowing us to have more control and insights in what is deployed, when and for what reason.

Personally, I use the below package.xml to deploy communities and limit the number of manual post-deployment steps:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>Audience</name>
    </types>
    <types>
        <members>*</members>
        <name>CustomSite</name>
    </types>
    <types>
        <members>*</members>
        <name>ExperienceBundle</name>
    </types>
    <types>
        <members>*</members>
        <name>NavigationMenu</name>
    </types>
    <types>
        <members>*</members>
        <name>Network</name>
    </types>
    <types>
        <members>*</members>
        <name>NetworkBranding</name>
    </types>
    <version>48.0</version>
</Package>