TrialOrgSettings Metadata Type in SFDX

Architectural Overview#

The TrialOrgSettings metadata type controls trial lifecycle policies and Trialforce template generation parameters within Salesforce AppExchange partner environments. When independent software vendors (ISVs) distribute packaged enterprise solutions, Trialforce enables them to generate fully configured trial organizations pre-populated with custom schema, sample records, and workflow automations.

From an enterprise ISV architecture viewpoint, TrialOrgSettings is crucial for orchestrating demo environments and free trial experiences. It governs whether prospective customers see trial expiration banners, defines grace periods before org deactivation, and dictates how custom templates snapshot configurations. Automating these settings through Salesforce DX ensures consistent partner packaging pipelines.

Directory and File Conventions#

In Salesforce DX project structure, TrialOrgSettings is stored as a singleton settings file under force-app/main/default/settings/.

Key Metadata Fields#

The TrialOrgSettings XML definition contains the following lifecycle configuration elements:

Declarative XML and Package Manifest Examples#

Below is an enterprise XML declaration for an ISV Trialforce source environment:

<?xml version="1.0" encoding="UTF-8"?>
<TrialOrgSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableTrialExpirationBanner>true</enableTrialExpirationBanner>
    <enableTrialOrgAutoDeactivation>true</enableTrialOrgAutoDeactivation>
    <enableTrialforce>true</enableTrialforce>
</TrialOrgSettings>

Scratch Org Definition (project-scratch-def.json)#

When developing AppExchange demo setups in partner scratch orgs:

{
  "orgName": "ISV Trialforce Source Org",
  "edition": "Partner Developer",
  "settings": {
    "trialOrgSettings": {
      "enableTrialforce": true,
      "enableTrialExpirationBanner": true
    }
  }
}

Manifest Definition (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage TrialOrgSettings using the Salesforce CLI:

# Retrieve TrialOrg settings from the partner source org
sf project retrieve start --metadata Settings:TrialOrg

# Deploy settings to a staging or packaging org
sf project deploy start --metadata Settings:TrialOrg --target-org packaging-org

Architect Best Practices and Gotchas#

• Environment Restriction: Attempting to deploy TrialOrg.settings-meta.xml into a standard customer Enterprise or Unlimited Edition org will produce deployment errors because Trialforce features are unentitled.
• Snapshot Immutability: When generating Trialforce templates from a source org, ensure TrialOrgSettings is deployed before initiating the snapshot; template instances inherit these settings at creation time.
• Trialforce Email Branding: Coordinate trial expiration banner settings with branded email templates configured in the Environment Hub to provide seamless customer onboarding.

Frequently asked questions

What role does TrialOrgSettings serve in AppExchange partner architectures?

It allows ISVs to define Trialforce behavior, controlling how prospect trial orgs behave upon expiration, whether subscription upgrade banners display, and how demo data is maintained.

How do you retrieve TrialOrgSettings with Salesforce CLI?

Run sf project retrieve start with the metadata parameter set to Settings:TrialOrg to pull the TrialOrg.settings-meta.xml file into your local project.

Can TrialOrgSettings be modified in standard production orgs?

No, TrialOrgSettings requires Trialforce Source Org or partner development edition org features to be provisioned on the host environment.

What is the consequence of enabling trial expiration banners?

It shows a prominent header notification inside Lightning Experience warning users of impending org deactivation and providing a direct conversion link.