Portal Metadata Type in SFDX

Architectural Overview#

The Portal metadata type represents first-generation Salesforce Customer Portal and Partner Portal configurations. Long before the introduction of Experience Cloud and Lightning Communities (governed by the Network metadata type), enterprise organizations deployed Customer and Partner Portals to give external users direct access to Salesforce cases, knowledge bases, and partner lead distribution.

While legacy portals are grandfathered in mature enterprise organizations, Salesforce no longer allows new legacy portal provisioning. Understanding Portal metadata is essential for Enterprise Technical Architects managing org technical debt, executing modern cloud migrations, and safely refactoring legacy portal login workflows, document attachments, and user profiles to Experience Cloud.

Directory and File Conventions#

In SFDX source format, Portal configurations are stored in the portals/ directory.

Key Metadata Fields#

The XML structure of Portal includes branding, authentication, and layout elements:

Declarative XML and Package Manifest Examples#

Below is a declarative XML file representing a legacy Customer Portal:

<?xml version="1.0" encoding="UTF-8"?>
<Portal xmlns="http://soap.sforce.com/2006/04/metadata">
    <active>true</active>
    <description>Legacy customer self-service support portal for tier-1 case submission.</description>
    <footerDocument>SharedDocuments/Portal_Footer_HTML</footerDocument>
    <headerDocument>SharedDocuments/Portal_Header_HTML</headerDocument>
    <logoDocument>SharedDocuments/Company_Branded_Logo</logoDocument>
    <type>CustomerSuccess</type>
</Portal>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Customer_Self_Service</members>
        <name>Portal</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Manage Portal metadata via Salesforce CLI:

# Retrieve all portal configurations from legacy org
sf project retrieve start --metadata Portal

# Retrieve a specific named portal
sf project retrieve start --metadata Portal:Customer_Self_Service

# Deploy portal definition to sandbox environment
sf project deploy start --metadata Portal:Customer_Self_Service

Architect Best Practices and Gotchas#

• Experience Cloud Migration Strategy: Legacy portals should be systematically refactored into Experience Cloud digital sites (Network). Modern digital sites leverage Lightning Web Components, Salesforce CMS, and advanced identity verification (Headless Identity and MFA).
• User License Compatibility: Users assigned legacy portal user licenses (e.g., Customer Portal Manager, High Volume Customer Portal) can be migrated to Customer Community or Customer Community Plus licenses to preserve historical record ownership and access.
• Document Dependencies: Portal metadata explicitly links to static documents for headers, footers, and logos via the Document metadata type. Deploying a Portal XML without deploying the referenced Document assets will fail.

Frequently asked questions

What is the primary purpose of the Portal metadata type?

Portal represents legacy Customer Portal and Partner Portal site configurations, predecessor architectures to modern Experience Cloud Networks.

Where are Portal metadata files located in an SFDX project?

They are stored in force-app/main/default/portals/ with the file extension .portal-meta.xml and retrieved as metadata type Portal.

Why do enterprise architects study the Portal metadata type today?

It is crucial for legacy org modernization, technical debt auditing, and orchestrating migrations from classic portals to Experience Cloud.

Can new Customer Portals still be provisioned in modern Salesforce orgs?

No. Salesforce has retired legacy portal provisioning for new orgs in favor of Experience Cloud, but existing portals remain supported in older orgs.