PermissionSetLicenseDefinition in SFDX

Architectural Overview#

PermissionSetLicenseDefinition represents the underlying system definition of Permission Set Licenses (PSLs) in Salesforce. While base user licenses (e.g., Salesforce, Identity, Platform) determine the fundamental data and administrative capabilities of a user, PSLs grant incremental access to specialized features—such as CRM Analytics, Service Cloud Voice, Field Service, or Health Cloud.

In source-driven development and packaging, PermissionSet components often include a <hasActivationRequired> flag or an explicit <license> tag referencing a permission set license developer name. Understanding PermissionSetLicenseDefinition enables Technical Architects to audit license pools, enforce entitlement checks in CI/CD pipelines, and prevent deployment failures caused by missing licenses in scratch orgs or sandboxes.

Directory and File Conventions#

PermissionSetLicenseDefinition is a system-level metadata entity. While PSLs cannot be arbitrarily created by subscribers through metadata XML deployments, their developer names are referenced in permission sets and inspected via the Tooling and Metadata APIs.

Key Entity Fields#

When inspecting PSL definitions through the Tooling and REST APIs, the following fields determine feature entitlement:

Declarative XML and Package Manifest Examples#

Below is a declarative PermissionSet metadata file referencing an underlying Permission Set License:

<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Grants access to advanced sales insights and predictive forecasting.</description>
    <hasActivationRequired>false</hasActivationRequired>
    <label>Sales Insights User</label>
    <license>SalesUserPsl</license>
    <userPermissions>
        <enabled>true</enabled>
        <name>ViewAllData</name>
    </userPermissions>
</PermissionSet>

Scratch Org Feature Entitlement Configuration#

To provision the required permission set licenses inside developer scratch orgs, declare them in the scratch org definition features array:

{
  "orgName": "Sales Insights Feature Org",
  "edition": "Enterprise",
  "features": ["SalesUserPsl", "ServiceCloudVoiceUserPsl"],
  "settings": {
    "userManagementSettings": {
      "enableEnhancedPermsetList": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Inspection and Query Commands#

Query available permission set licenses and usage in target orgs using the Salesforce CLI:

# Query active permission set licenses and seat allocations
sf data query --query "SELECT Id, DeveloperName, MasterLabel, TotalLicenses, UsedLicenses, Status FROM PermissionSetLicense" --target-org prodOrg

# Query users assigned to a specific PSL
sf data query --query "SELECT Id, Assignee.Name, PermissionSetLicense.DeveloperName FROM PermissionSetLicenseAssign WHERE PermissionSetLicense.DeveloperName = 'SalesUserPsl'"

# Assign a permission set license to a user
sf org assign permsetlicense --name SalesUserPsl --target-org devOrg

Architect Best Practices and Gotchas#

• Scratch Org Provisioning Failures: A frequent source of CI/CD pipeline breakage occurs when permission sets with <license> tags are deployed into scratch orgs that lack the corresponding feature flag in project-scratch-def.json. Always test scratch definitions with newly referenced licenses.
• Auditing Seat Depletion: In large enterprise orgs, implement automated SOQL monitoring scripts on PermissionSetLicense to alert platform teams when UsedLicenses reaches 95% of TotalLicenses.
• Decoupling Permission Sets: Where possible, design permission sets without the <license> restriction unless the user permission strictly demands a PSL. This preserves architectural flexibility across mixed user tiers.

Frequently asked questions

What is PermissionSetLicenseDefinition in Salesforce?

It represents a permission set license (PSL) definition that grants specific feature entitlements not included in a standard user profile.

Can PermissionSetLicenseDefinition be deployed directly in metadata?

No. Permission set licenses are provisioned by Salesforce contracts and licenses, but they are referenced in PermissionSet metadata definitions.

How is PermissionSetLicenseDefinition inspected using the CLI?

Architects query PermissionSetLicense via SOQL or Tooling API to inspect available license keys, total allocations, and assigned user counts.

What happens if a PermissionSet references an unassigned license?

Assigning the permission set to a user fails with a LICENSE_REQUIRED exception unless the user has first been assigned the corresponding PSL.