Deploy Your Experience Cloud Site with the Metadata API

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

Network

Represents an Experience Cloud site. 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.

DigitalExperienceBundle and DigitalExperienceConfig or ExperienceBundle or SiteDotCom

The metadata type you require varies depending on the site type. Represents the different settings and components, such as pages, branding sets, and themes, that make up a site.

• For enhanced LWR sites, introduced in Winter ’23 (API version 56.0), DigitalExperienceBundle and DigitalExperienceConfig combine to provide text-based representations of your site elements and settings. You can retrieve editable site metadata and quickly create, update, publish, and deploy sites programmatically. You can also partially deploy enhanced LWR sites.
• For non-enhanced LWR sites, ExperienceBundle provides text-based representations of the site’s settings, pages, and components. You can retrieve editable site metadata and quickly create, update, publish, and deploy sites programmatically.
• For Aura sites, you can choose to use either ExperienceBundle or SiteDotCom, but we recommend using ExperienceBundle. Before Summer ’19 (API version 45.0 and earlier), the Network, CustomSite, and SiteDotCom metadata types combined to define an Aura site. However, retrieving the SiteDotCom type produces a binary .site file that isn’t human readable. See ExperienceBundle for Experience Builder Sites.
• For Visualforce sites, SiteDotCom represents the site.

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

Required Metadata Types at a Glance

The metadata types that you use to deploy a site vary depending on the site type.

Required Metadata Type	Enhanced LWR Site	LWR Site	Aura Site	Visualforce Site
Network
CustomSite
DigitalExperienceBundle
DigitalExperienceConfig
ExperienceBundle			ExperienceBundle (recommended) or SiteDotCom
SiteDotCom

Tips and Considerations

• Before migrating data to another org, enable digital experiences in the destination org and enter the same domain name that you used in your sandbox org to avoid getting an error.
• For each Experience Cloud site, 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 site. If it doesn’t exist, the API creates a site. If someone changes the site name in the sandbox and then tries to migrate, they see an error. The API is trying to create a site 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 required components described previously, include all the other components required by your site. Components can include such items as custom objects, custom fields, custom Lightning components, and Apex classes.
• To deploy the Network and Profile components using unlocked packages, create a separate unlocked package for each component and deploy them individually.
• When deploying an Aura site with ExperienceBundle, ensure that the SiteDotCom type isn’t included in the manifest file.
• If you rename a site in Administration | Settings, make sure that the source and target sites 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 site migration.
• When you migrate user profiles, users are added to the site in the production org. Emails are then sent to members in the same way as for any new site.
• 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 Metadata API.
• To deploy an Aura site with a custom template, first retrieve and deploy the CommunityTemplateDefinition and the relevant metadata types, such as CommunityThemeDefinition. Then retrieve and deploy ExperienceBundle or SiteDotCom and the relevant metadata types.
• Deploying the navigation menu with additional menu items deletes any translations applied to existing menu items in the target environment.
• To include navigation menus when you move your site, use the NavigationMenu metadata type.
• 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).
• NavigationLinkSet was deprecated in Winter ’20 (API version 47.0) and replaced by NavigationMenu.
• If your site includes pages from Site.com Studio, use the SiteDotCom metadata type, because deploying the site using ExperienceBundle permanently deletes the Site.com Studio pages.
• 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. To get the latest ExperienceBundle updates, retrieve the package .
• When deploying a site, you sometimes receive a warning message about invalid ID values. For example: The topicId property of component 9b8a4e98-e724-4292-bd3c-0813adf9ddc2 references an object with the ID value 0TO4R000000EGPEWA4. Occasionally, when deployed to a destination org, ID values can become invalid—for example, if the referenced ID doesn’t exist in the destination org. If you encounter component issues in your destination org, verify that the ID values are correct.

  In these situations, you can deploy the site successfully despite the warning. However, we recommend verifying in the target org that the object ID referenced in the component is still valid. If the ID is incorrect, manually update the ID to resolve any component issues in the target org. Alternatively, if it’s a custom component that you created, consider replacing the object ID with the object’s API name instead to avoid the issue in future.

Sample Template

The following sample contains all the fields that you can migrate through the Metadata API.

<?xml version="1.0" encoding="UTF-8"?>
<Network xmlns="http://soap.sforce.com/2006/04/metadata">
    <allowInternalUserLogin>true</allowInternalUserLogin>
    <allowMembersToFlag>true</allowMembersToFlag>
    <allowedExtensions>txt,png,jpg,jpeg,pdf,doc,csv</allowedExtensions>
    <caseCommentEmailTemplate>unfiled$public/ContactFollowUpSAMPLE</caseCommentEmailTemplate>
    <changePasswordTemplate>unfiled$public/CommunityChangePasswordEmailTemplate</changePasswordTemplate>
    </communityRoles>
    <disableReputationRecordConversations>true</disableReputationRecordConversations>
    <emailSenderAddress>admin@myorg.com</emailSenderAddress>
    <emailSenderName>MyCommunity</emailSenderName>
    <enableCustomVFErrorPageOverrides>true</enableCustomVFErrorPageOverrides>
    <enableDirectMessages>true</enableDirectMessages>
    <enableGuestChatter>true</enableGuestChatter>
    <enableGuestFileAccess>false</enableGuestFileAccess>
    <enableInvitation>false</enableInvitation>
    <enableKnowledgeable>true</enableKnowledgeable>
    <enableNicknameDisplay>true</enableNicknameDisplay>
    <enablePrivateMessages>false</enablePrivateMessages>
    <enableReputation>true</enableReputation>
    <enableShowAllNetworkSettings>true</enableShowAllNetworkSettings>
    <enableSiteAsContainer>true</enableSiteAsContainer>
    <enableTalkingAboutStats>true</enableTalkingAboutStats>
    <enableTopicAssignmentRules>true</enableTopicAssignmentRules>
    <enableTopicSuggestions>true</enableTopicSuggestions>
    <enableUpDownVote>true</enableUpDownVote>
    <forgotPasswordTemplate>unfiled$public/CommunityForgotPasswordEmailTemplate</forgotPasswordTemplate>
    <gatherCustomerSentimentData>false</gatherCustomerSentimentData>
    <lockoutTemplate>unfiled$public/CommunityLockoutEmailTemplate</lockoutTemplate>
    <maxFileSizeKb>51200</maxFileSizeKb>
    <networkMemberGroups>
        <permissionSet>MyCommunity_Permissions</permissionSet>
        <profile>Admin</profile>
    </networkMemberGroups>
    <networkPageOverrides>
        <changePasswordPageOverrideSetting>VisualForce</changePasswordPageOverrideSetting>
        <forgotPasswordPageOverrideSetting>Designer</forgotPasswordPageOverrideSetting>
        <homePageOverrideSetting>Designer</homePageOverrideSetting>
        <loginPageOverrideSetting>Designer</loginPageOverrideSetting>
        <selfRegProfilePageOverrideSetting>Designer</selfRegProfilePageOverrideSetting>
    </networkPageOverrides>
    <picassoSite>MyCommunity1</picassoSite>
    <selfRegistration>true</selfRegistration>
    <sendWelcomeEmail>true</sendWelcomeEmail>
    <site>MyCommunity</site>
    <status>Live</status>
    <tabs>
        <defaultTab>home</defaultTab>
        <standardTab>Chatter</standardTab>
    </tabs>
    <urlPathPrefix>mycommunity</urlPathPrefix>
    <welcomeTemplate>unfiled$public/CommunityWelcomeEmailTemplate</welcomeTemplate>
</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 an Experience Builder site.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>Network</name>
    </types>
    <types>
        <members>*</members>
        <name>CustomSite</name>
    </types>
    <types>
        <members>*</members>
        <name>ExperienceBundle</name>
    </types>
    <types>
        <members>*</members>
        <name>CustomTab</name>
    </types>
    <types>
        <members>*</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>*</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>*</members>
        <name>ApexPage</name>
    </types>
    <types>
        <members>*</members>
        <name>ApexComponent</name>
    </types>
    <types>
        <members>*</members>
        <name>Portal</name>
    </types>
    <types>
        <members>*</members>
        <name>Profile</name>
    </types>
    <types>
        <members>*</members>
        <name>Document</name>
    </types>
    <version>46.0</version>
</Package>