AnimationRule Metadata Type in SFDX

Architectural Overview#

The AnimationRule metadata type configures the celebratory virtual confetti animation displayed in Lightning Experience when a user moves a PathAssistant component to a designated milestone value (such as Closed Won on an Opportunity or Resolved on a Case).

While AnimationRule appears to be a minor UI flourish, in source-driven SFDX orgs it is decoupled from the PathAssistant XML file itself. If an architect deploys a PathAssistant to production without including its corresponding AnimationRule in package.xml, the Path stages and guidance fields will deploy, but the celebration settings configured in Setup will be missing.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

The following example triggers a confetti animation every time an Enterprise Sales Opportunity transitions to Closed Won.

<?xml version="1.0" encoding="UTF-8"?>
<AnimationRule xmlns="http://soap.sforce.com/2006/04/metadata">
    <animationFrequency>always</animationFrequency>
    <developerName>Enterprise_Opportunity_Closed_Won</developerName>
    <isActive>true</isActive>
    <masterLabel>Enterprise Opportunity Closed Won</masterLabel>
    <recordTypeContext>Custom</recordTypeContext>
    <recordTypeName>Enterprise_Sales</recordTypeName>
    <sobjectType>Opportunity</sobjectType>
    <targetField>StageName</targetField>
    <targetFieldChangeToValues>Closed Won</targetFieldChangeToValues>
</AnimationRule>

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

Querying AnimationRule via SOQL#

You can audit active AnimationRule records across your org using standard SOQL or the Tooling API:

SELECT Id, DeveloperName, MasterLabel, SobjectType, TargetField,
       RecordTypeContext, TargetFieldChangeToValues, AnimationFrequency, IsActive
FROM AnimationRule
WHERE IsActive = true
ORDER BY SobjectType, DeveloperName

Senior Architect Best Practices and Gotchas#

1. Always Retrieve Alongside PathAssistant: When an admin enables celebrations inside the Path Setup wizard (Setup -> Path Settings), Salesforce silently creates or updates an AnimationRule metadata component. Always run sf project retrieve start --metadata PathAssistant AnimationRule together so celebration rules are not left behind in a sandbox.
2. Picklist Value Dependency: If you rename or deactivate a picklist value on targetField without updating targetFieldChangeToValues in the AnimationRule, deployments to clean scratch orgs will fail with a picklist validation error.
3. Client-Side Trigger Only: AnimationRule only fires when a user updates the Path stage interactively in Lightning Experience. Bulk updates via Apex, Flow, or Data Loader never trigger client-side animations.

Frequently asked questions

Where are AnimationRule metadata files stored in an SFDX project?

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

What are the valid values for animationFrequency in AnimationRule?

The valid values are always, often, sometimes, and rarely, which control how frequently the confetti animation plays when a user selects the target picklist value.

Can I deploy an AnimationRule without deploying PathAssistant?

Yes, AnimationRule is an independent metadata file, though it only renders visually in the UI when a PathAssistant component is configured for that object, record type, and field.

Can I query AnimationRule records using SOQL?

Yes, AnimationRule is exposed in the Tooling API and standard SOQL so you can inspect active celebration rules by SobjectType and TargetField.