StageAssignment | Metadata API Developer Guide

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

StageAssignment components have the suffix .stageAssignment and are stored in the stageAssignments folder.

Version

StageAssignment components are available in API version 64.0 and later.

Fields

Field Name	Description
active	Field Type boolean Description Required. Indicates whether the stage assignment rule is active (`true`) or not (`false`). The default value is `true`. Active rules are evaluated when determining stage definition assignments.
description	Field Type string Description Description for the stage assignment rule.
masterLabel	Field Type string Description Required. A user-friendly name for the stage assignment rule, which is defined when the metadata component is created.
referenceObject	Field Type string Description Required. Reference object that's associated with the stage assignment rule. This is the API name of the Salesforce object for which the stage assignment rule applies (for example, ApplicationForm or Order).
referenceObjectRecordType	Field Type string Description Record type of a reference object that's associated with the stage assignment rule. When specified, the assignment rule applies only to records of the specified record type.
ruleCriteria	Field Type StgAssignmentRuleCriteria[] Description Collection of rule criteria to determine stage definition assignment. Rules are evaluated in priority order, and the first matching rule determines which stage definition is assigned to the record.
stageDefinition	Field Type string Description Default stage definition to assign when no rule criteria match. This provides a fallback assignment when none of the defined rule criteria evaluate to true.

StgAssignmentRuleCriteria

Represents a collection of fields to define rule criteria for stage definition assignment. Rule criteria are evaluated in priority order, with lower priority numbers evaluated first.

Field Name	Description
condition	Field Type StgAssignmentRuleCond[] Description Collection of conditions to evaluate for this rule criteria. You can combine multiple conditions by using the `criteriaType` field to determine the overall evaluation result.
criteriaType	Field Type StageCriteriaType (enumeration of type string) Description Required. Specifies the criteria type that's used to evaluate the rule conditions. Valid values are: `AND` `CUSTOMLOGIC` `OR`
logicalExpression	Field Type string Description Formula to specify custom logic for evaluating conditions. It's used when `criteriaType` is set to `CUSTOMLOGIC`.
name	Field Type string Description Required. Name of the rule criteria.
priority	Field Type int Description Required. Priority order for evaluating this rule criteria when multiple criteria are defined. Rules are evaluated in ascending priority order where lower numbers have higher priority. For example, a rule with priority 1 is evaluated before a rule with priority 2. The first rule that evaluates to true determines the stage definition assignment.
stageDefinition	Field Type string Description Required. Stage definition to assign when this rule criteria matches. This must be the API name of a valid StageDefinition for the same reference object.

StgAssignmentRuleCond

Represents a collection of fields to define individual condition rules for stage assignment rule criteria. Each condition compares a field value against a specified value using a comparison operator.

Field Name	Description
fieldName	Field Type string Description Required. API name of the field to evaluate for this condition.
operator	Field Type StageConditionOperator (enumeration of type string) Description Required. Operator that's used to evaluate the field value. Valid values are: `Contains` `DoesNotContain` `Equals` `GreaterOrEqual` `GreaterThan` `LessOrEqual` `LessThan` `NotEqualTo` `StartsWith`
sequenceNumber	Field Type int Description Required. Specifies the sequence number of this condition for reference in logical expressions. The sequence number is used in the `logicalExpression` field to create custom boolean logic. For example, a condition with sequenceNumber 1 is referenced as "1" in the expression "1 AND 2".
value	Field Type string Description Required. Defines the value to compare against the field value. The value is specified as a string regardless of the field type. For example, numeric values are specified as "10000", dates as "2025-10-27", and text values as "Approved".

Usage

StageAssignment works in conjunction with StageDefinition to provide automated stage management. While StageDefinition defines the stages, transitions, and workflows, StageAssignment determines which stage definition to apply to a record based on rule criteria.

Evaluation Process:

When a record is created or updated, the system evaluates active StageAssignment rules for the object.
Rule criteria are evaluated in priority order where lower numbers have higher priority.
The first rule criteria that evaluates to true determines the stage definition assignment.
If no rule criteria matches, the default stageDefinition from the StageAssignment is used.
The assigned stage definition governs the stage behavior for that record.

Use Cases:

Value-based Assignment—Assign different stage definitions based on transaction amounts. For example, premium stages for high-value applications.
Type-based Assignment—Use different stage workflows for different record types.
Status-based Assignment—Apply specific stage definitions based on record status or classification.
Complex Criteria—Combine multiple conditions to create sophisticated assignment rules.

Declarative Metadata Sample Definition

The following is an example of a StageAssignment component.

1<?xml version="1.0" encoding="UTF-8"?>
2<StageAssignment xmlns="http://soap.sforce.com/2006/04/metadata">
3    <active>true</active>
4    <description>Assigns stage definitions to applications based on amount</description>
5    <masterLabel>Application Stage Assignment</masterLabel>
6    <referenceObject>ApplicationForm</referenceObject>
7    <ruleCriteria>
8        <name>High Value Applications</name>
9        <priority>1</priority>
10        <criteriaType>AND</criteriaType>
11        <condition>
12            <fieldName>Amount</fieldName>
13            <operator>GreaterThan</operator>
14            <sequenceNumber>1</sequenceNumber>
15            <value>10000</value>
16        </condition>
17        <condition>
18            <fieldName>Status</fieldName>
19            <operator>Equals</operator>
20            <sequenceNumber>2</sequenceNumber>
21            <value>Approved</value>
22        </condition>
23        <stageDefinition>Premium_Application_Stages</stageDefinition>
24    </ruleCriteria>
25    <ruleCriteria>
26        <name>Standard Applications</name>
27        <priority>2</priority>
28        <criteriaType>AND</criteriaType>
29        <condition>
30            <fieldName>Amount</fieldName>
31            <operator>LessOrEqual</operator>
32            <sequenceNumber>1</sequenceNumber>
33            <value>10000</value>
34        </condition>
35        <stageDefinition>Standard_Application_Stages</stageDefinition>
36    </ruleCriteria>
37    <stageDefinition>Basic_Application_Stages</stageDefinition>
38</StageAssignment>

The following is an example package.xml that references the previous definition.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>*</members>
5        <name>StageAssignment</name>
6    </types>
7    <version>64.0</version>
8</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.