Lightning Communities Developer Guide

Get Up to Speed with Lightning Communities
Develop Lightning Communities: The Basics
Customize the Look and Feel of a Lightning Template
Example: Build a Condensed Theme Layout Component
Develop Secure Code: Lightning Locker and CSP
Analyze and Improve Community Performance
Use a CMS with Your Community
Report on Deflections: The Deflection Signals Framework
Deploy a Community from Sandbox to Production
Deploy Your Community with Change Sets
Deploy Your Community with the Metadata API
ExperienceBundle for Lightning Communities
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Deploy Your Community with the Metadata API

Use the Metadata API to move your community from one Salesforce org to another. Set up and test your community in your test environment, and then retrieve the community’s data and deploy it to your production org.
Available in: Salesforce Classic (not available in all orgs) and Lightning Experience
Available in: Enterprise, Performance, Unlimited, and Developer Editions

You can use the Metadata API to move Lightning communities and Salesforce Tabs + Visualforce communities.

The following metadata types combine to define a community. To successfully migrate a community, use the Metadata API retrieve call to retrieve XML file representations of your org’s components.

  • Network—Represents a community. Contains administration settings, such as page override, email, and membership configurations.
  • CustomSite—Contains the domain and page setting information, including indexPage, siteAdmin, and URL definitions.
  • ExperienceBundle or SiteDotCom—If you’re deploying a Lightning community, we recommend using ExperienceBundle instead of SiteDotCom. ExperienceBundle provides text-based representations of the different Experience Builder settings and site components, such as pages, branding sets, and themes, that make up a Lightning community.

    Before the Summer ’19 release (API version 45.0 and earlier), the Network, CustomSite, and SiteDotCom metadata types combined to define a Lightning community. However, retrieving the SiteDotCom type produces a binary .site file that isn’t human readable. By enabling the ExperienceBundle type, you can retrieve editable community metadata, and quickly create, update, publish, and deploy Lightning communities programmatically. See ExperienceBundle for Lightning Communities.

For additional information on these metadata types and instructions on migrating data, see the Metadata API Developer Guide and the Salesforce CLI Command Reference.

Tips and Considerations

  • Before migrating data to another org, enable Communities in the destination org and enter the same domain name that you used in your sandbox org to avoid getting an error.
  • For each community, the network component has a unique name and URL path prefix. When you retrieve the network component, the generated XML file name is based on the name of the network. When migrating, the API looks at the file name and if it exists, updates the community. If it doesn’t exist, the API creates a community. If someone changes the community name in the sandbox and then tries to migrate, they see an error because the API is trying to create a community with the existing path prefix.
  • Examine the XML file for CustomSite to make sure that all dependencies are brought over. If any are missing, explicitly state them in the XML file.
  • In addition to the Network, CustomSite, and ExperienceBundle components, include all the other components required by your community, such as custom objects, custom fields, custom Lightning components, and Apex classes.
  • When deploying a Lightning community with ExperienceBundle, ensure that the SiteDotCom type isn’t included in the manifest file.
  • If you rename a community in Administration | Settings, make sure that the source and target communities have matching values for the picassoSite and site attributes in the Network component.
  • If there are any changes to the guest user profile, include the profile as part of the community migration.
  • When you migrate user profiles, users are added to the community in the production org. Emails are then sent to members in the same way as for any new community.
  • During deployment, make sure that the NavigationMenu developer name in the target org is the same as the developer name in the source org.
  • If the containerType is CommunityTemplateDefinition, you can’t update an existing NavigationMenu via the metadata API.
  • Deploying the navigation menu with additional menu items deletes any translations applied to existing menu items in the target environment.
  • You can’t deploy to a target org that’s using an earlier release version. For example, if your source org is on Summer ’19 (API version 46.0), you can’t deploy to a target org on Spring ’19 (API version 45.0).
  • ExperienceBundle doesn’t support retrieving and deploying across different API versions. If you’re trying to upgrade ExperienceBundle metadata from an earlier API version to a later one—for example, from API version 48.0 to 49.0—take the following steps:
    1. Set the API version in the package.xml manifest file to 48.0 and deploy the package.
    2. Then, set the API version in package.xml to 49.0.
    3. Retrieve the package to get the latest ExperienceBundle updates.

Sample Template

The following sample contains all the fields that you can migrate through the Metadata API.
1<?xml version="1.0" encoding="UTF-8"?>
2<Network xmlns="http://soap.sforce.com/2006/04/metadata">
3    <allowInternalUserLogin>true</allowInternalUserLogin>
4    <allowMembersToFlag>true</allowMembersToFlag>
5    <allowedExtensions>txt,png,jpg,jpeg,pdf,doc,csv</allowedExtensions>
6    <caseCommentEmailTemplate>unfiled$public/ContactFollowUpSAMPLE</caseCommentEmailTemplate>
7    <changePasswordTemplate>unfiled$public/CommunityChangePasswordEmailTemplate</changePasswordTemplate>
8    </communityRoles>
9    <disableReputationRecordConversations>true</disableReputationRecordConversations>
10    <emailSenderAddress>admin@myorg.com</emailSenderAddress>
11    <emailSenderName>MyCommunity</emailSenderName>
12    <enableCustomVFErrorPageOverrides>true</enableCustomVFErrorPageOverrides>
13    <enableDirectMessages>true</enableDirectMessages>
14    <enableGuestChatter>true</enableGuestChatter>
15    <enableGuestFileAccess>false</enableGuestFileAccess>
16    <enableInvitation>false</enableInvitation>
17    <enableKnowledgeable>true</enableKnowledgeable>
18    <enableNicknameDisplay>true</enableNicknameDisplay>
19    <enablePrivateMessages>false</enablePrivateMessages>
20    <enableReputation>true</enableReputation>
21    <enableShowAllNetworkSettings>true</enableShowAllNetworkSettings>
22    <enableSiteAsContainer>true</enableSiteAsContainer>
23    <enableTalkingAboutStats>true</enableTalkingAboutStats>
24    <enableTopicAssignmentRules>true</enableTopicAssignmentRules>
25    <enableTopicSuggestions>true</enableTopicSuggestions>
26    <enableUpDownVote>true</enableUpDownVote>
27    <forgotPasswordTemplate>unfiled$public/CommunityForgotPasswordEmailTemplate</forgotPasswordTemplate>
28    <gatherCustomerSentimentData>false</gatherCustomerSentimentData>
29    <lockoutTemplate>unfiled$public/CommunityLockoutEmailTemplate</lockoutTemplate>
30    <maxFileSizeKb>51200</maxFileSizeKb>
31    <navigationLinkSet>
32        <navigationMenuItem>
33            <label>Topics</label>
34            <position>0</position>
35            <publiclyAvailable>true</publiclyAvailable>
36            <target>ShowMoreTopics</target>
37            <type>NavigationalTopic</type>
38        </navigationMenuItem>
39    </navigationLinkSet>
40    <networkMemberGroups>
41        <permissionSet>MyCommunity_Permissions</permissionSet>
42        <profile>Admin</profile>
43    </networkMemberGroups>
44    <networkPageOverrides>
45        <changePasswordPageOverrideSetting>VisualForce</changePasswordPageOverrideSetting>
46        <forgotPasswordPageOverrideSetting>Designer</forgotPasswordPageOverrideSetting>
47        <homePageOverrideSetting>Designer</homePageOverrideSetting>
48        <loginPageOverrideSetting>Designer</loginPageOverrideSetting>
49        <selfRegProfilePageOverrideSetting>Designer</selfRegProfilePageOverrideSetting>
50    </networkPageOverrides>
51    <picassoSite>MyCommunity1</picassoSite>
52    <selfRegistration>true</selfRegistration>
53    <sendWelcomeEmail>true</sendWelcomeEmail>
54    <site>MyCommunity</site>
55    <status>Live</status>
56    <tabs>
57        <defaultTab>home</defaultTab>
58        <standardTab>Chatter</standardTab>
59    </tabs>
60    <urlPathPrefix>mycommunity</urlPathPrefix>
61    <welcomeTemplate>unfiled$public/CommunityWelcomeEmailTemplate</welcomeTemplate>
62</Network>

Sample package.xml Manifest File

A manifest file defines the components that you’re trying to retrieve. The following sample shows a package.xml manifest file for retrieving all the components of a Lightning community.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>*</members>
5        <name>Network</name>
6    </types>
7    <types>
8        <members>*</members>
9        <name>CustomSite</name>
10    </types>
11    <types>
12        <members>*</members>
13        <name>ExperienceBundle</name>
14    </types>
15    <types>
16        <members>*</members>
17        <name>CustomTab</name>
18    </types>
19    <types>
20        <members>*</members>
21        <name>CustomObject</name>
22    </types>
23    <types>
24        <members>*</members>
25        <name>ApexClass</name>
26    </types>
27    <types>
28        <members>*</members>
29        <name>ApexPage</name>
30    </types>
31    <types>
32        <members>*</members>
33        <name>ApexComponent</name>
34    </types>
35    <types>
36        <members>*</members>
37        <name>Portal</name>
38    </types>
39    <types>
40        <members>*</members>
41        <name>Profile</name>
42    </types>
43    <types>
44        <members>*</members>
45        <name>Document</name>
46    </types>
47    <version>46.0</version>
48</Package>