ParticipantRole Metadata Type in SFDX

Architectural Overview#

ParticipantRole is an industry data model metadata type used heavily in Salesforce Financial Services Cloud (FSC), Health Cloud, and Public Sector Solutions. Modern service workflows—such as insurance claim processing, patient care management, legal investigations, and public complaints—involve complex stakeholder networks of internal employees, external advocates, medical professionals, and beneficiaries.

Rather than building brittle custom sharing mechanisms or excessive public groups, Salesforce employs ParticipantRole to model relational roles (e.g., “Primary Investigator”, “Care Coordinator”, “Legal Guardian”). When a user or contact is added to a record’s participant list, the associated ParticipantRole dynamically determines their row-level access permissions (Read or Edit), streamlining compliance and auditability.

Directory and File Conventions#

In SFDX source format, each ParticipantRole is stored as an XML file within the participantRoles/ directory.

Key Metadata Fields#

The XML schema of ParticipantRole includes configuration for labels, access grants, and lifecycle states:

Declarative XML and Package Manifest Examples#

Below is a declarative definition for a Lead Claim Adjuster role in insurance processing:

<?xml version="1.0" encoding="UTF-8"?>
<ParticipantRole xmlns="http://soap.sforce.com/2006/04/metadata">
    <accessLevel>Edit</accessLevel>
    <masterLabel>Lead Claim Adjuster</masterLabel>
    <roleDescription>Primary operational investigator responsible for claim resolution and payout authorization.</roleDescription>
    <status>Active</status>
</ParticipantRole>

Read-Only Auditor Role#

<?xml version="1.0" encoding="UTF-8"?>
<ParticipantRole xmlns="http://soap.sforce.com/2006/04/metadata">
    <accessLevel>Read</accessLevel>
    <masterLabel>Compliance Auditor</masterLabel>
    <roleDescription>Internal audit and regulatory observer with read-only record access.</roleDescription>
    <status>Active</status>
</ParticipantRole>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage ParticipantRole components using the Salesforce CLI:

# Retrieve all participant roles
sf project retrieve start --metadata ParticipantRole

# Deploy a specific participant role
sf project deploy start --metadata ParticipantRole:Lead_Claim_Adjuster

# Validate participant role metadata deployment
sf project deploy validate --metadata ParticipantRole

Architect Best Practices and Gotchas#

• Industry Cloud Entitlement: Deploying ParticipantRole requires the target org to have an active Industry Cloud license (e.g., FSC, Health Cloud, Public Sector) that supports participant management.
• Access Level Downgrades: If a ParticipantRole access level is modified from Edit to Read, existing record sharing records are asynchronously recalculated by the sharing recalculation queue.
• Deactivation Over Deletion: Once a ParticipantRole has been assigned to historical records in production, deleting the metadata will fail. Instead, set status to Inactive to prevent new assignments while preserving historical integrity.

Frequently asked questions

What is the purpose of ParticipantRole in Salesforce Industry Clouds?

ParticipantRole defines the business role and implicit or explicit record-level access for individuals collaborating on complex industry records.

Where are ParticipantRole metadata files saved in an SFDX project?

They are stored in force-app/main/default/participantRoles/ with the file extension .participantRole-meta.xml.

Which Salesforce Industry Cloud solutions use ParticipantRole?

It is widely used across Financial Services Cloud, Health Cloud, and Public Sector Solutions for complaints, care plans, and claim investigations.

Can access levels be assigned directly within ParticipantRole?

Yes. ParticipantRole allows architects to specify default record access levels such as Read or Edit for users assigned to that role.