Newer Version Available

This content describes an older version of this product. View Latest

ApprovalProcess

Represents the metadata associated with an approval process. An approval process is an automated process your organization can use to approve records in Salesforce. An approval process specifies the steps necessary for a record to be approved and who must approve it at each step. A step can apply to all records included in the process, or just records that meet certain administrator-defined criteria. An approval process also specifies the actions to take when a record is approved, rejected, recalled, or first submitted for approval. This type extends the Metadata metadata type and inherits its fullName field.

To use approval processes on Salesforce Knowledge articles with the Metadata API, the article type must be deployed. For article version (_kav) in approval processes, the supported action types are: Knowledge Action, Email Alert, Field Update, and Outbound Message.
Send actions and approval processes for email drafts aren’t supported in the Metadata API.
The metadata doesn’t include the order of active approval processes. You may need to reorder the approval processes in the destination organization after deployment.
Before you implement an approval process for your organization, see “Considerations for Approval Processes” in the Salesforce Help.

Note

File Suffix and Directory Location

ApprovalProcess components have the suffix .approvalProcess and are stored in the approvalProcesses folder.

Version

ApprovalProcess components are available in API version 28.0 and later.

Fields

Field Name	Field Type	Description
active	boolean	Required. Whether the approval process is active. After an approval process is activated, you can't add, delete, or change the order of the steps or change reject or skip behavior for that process, even if you make the process inactive.
allowRecall	boolean	Whether to allow submitters to recall approval requests. If set to `false`, only administrators can recall approval requests.
allowedSubmitters	ApprovalSubmitter[]	Required. An array of users who are allowed to submit records for approval.
approvalPageFields	ApprovalPageField	Specifies which fields to display on the approval page, where the approver goes to approve or reject the record. By default, the approval page displays the following: Name field Owner field (except for child objects) If you enable notifications in Salesforce1, keep in mind that approvers may view this list of fields on a mobile device. Select only the fields necessary for users to decide whether to approve or reject records.
approvalStep	ApprovalStep[]	An array of approval step definitions.
description	string	Describes the approval process.
emailTemplate	string	Specifies which email template to use for approval requests. If not specified, the default email template is used. When an approval process assigns an approval request to a user, Salesforce automatically sends the user an approval request email. The email contains a link to the approval page in Salesforce, where the user can approve or reject the request and add comments.
enableMobileDeviceAccess	boolean	Whether users can access an external version of the approval page from any browser, including those on mobile devices, without logging in to Salesforce. Corresponds to Security Settings in the user interface. If set to `true`, approval steps can’t have approvers of type `adhoc`. If set to `false`, approvers must log in to Salesforce to access the approval page.
entryCriteria	ApprovalEntryCriteria	Determines which records can enter the approval process. Exclude this field to allow all records to enter the approval process.
finalApprovalActions	ApprovalAction	Specifies which workflow actions to execute when all required approvals have been given for a record.
finalApprovalRecordLock	boolean	Whether to keep the record locked after it receives all necessary approvals. Default: `false`.
finalRejectionActions	ApprovalAction	Specifies which workflow actions to execute after a record enters the final rejection state.
finalRejectionRecordLock	boolean	Whether to keep the record locked after it’s finally rejected. Default: `false`.
initialSubmissionActions	ApprovalAction	Specifies which workflow actions to execute when a record is initially submitted for approval.
label	string	Required. Name of the approval process.
nextAutomatedApprover	NextAutomatedApprover	Specifies a standard or custom user hierarchy field that can be used to automatically assign the approver for an approval step. If you exclude this field, then no approval step can use a user hierarchy field to automatically assign the approver.
postTemplate	string	Post template to use for Approvals in Chatter. Chatter post approval notifications are only available for approval processes associated with an object that has been enabled for feed tracking.
recallActions	ApprovalAction	Specifies which workflow actions to execute when a pending approval request is withdrawn.
recordEditability	RecordEditabilityType (enumeration of type string)	Specifies which users can edit records that are pending approval. When a record is submitted for approval, it is automatically locked to prevent other users from editing it during the approval process. Valid values are: `AdminOnly`—Records pending approval can be edited by: Users with the “Modify All Data” permission Users with the “Modify All” object-level permission for the given object `AdminOrCurrentApprover`—Records pending approval can be edited by: Users with the “Modify All Data” permission Users with the “Modify All” object-level permission for the given object The assigned approver, who must have edit access to the record through user permissions and the organization-wide sharing defaults for the given object
showApprovalHistory	boolean	Whether to add the Approval History related list to the approval page, which is where the approver can view the approval request details and approve or reject the record. The Approval History related list tracks a record through the approval process. If you also want to add the Approval History related list to record detail and edit pages, use the Salesforce user interface to customize the page layouts for the given object.

ApprovalSubmitter

Represents a user or set of users who can submit records for approval.

Field Name	Field Type	Description
submitter	string	Identifies a specific user or set of users who can submit records for approval. This field is required, except when the following types are specified and the submitter field is ignored: `owner` `creator` `allInternalUsers` Example: `1<allowedSubmitters> 2 <type>allInternalUsers</type> 3</allowedSubmitters> 4<allowedSubmitters> 5 <submitter>myGroup</submitter> 6 <type>group</type> 7</allowedSubmitters>`
type	ProcessSubmitterType (enumeration of type string)	Required. Type of user or set of users who can submit records for approval. Valid values are: `group` `role` `user` `roleSubordinates` `roleSubordinatesInternal` `owner` `creator` `partnerUser` `customerPortalUser` `portalRole` `portalRoleSubordinates` `allInternalUsers`—all Salesforce users in the organization

ApprovalPageField

Represents the selection of fields to display on the approval page, where an approver can view the approval request details and approve or reject the record.

Field Name	Field Type	Description
field	string[]	An array of fields that are displayed on the page for the approver to approve or reject the record.

ApprovalStep

Represents a step in the approval process. Approval steps assign approval requests to various users and define the chain of approval for a particular approval process. Each approval step specifies the attributes a record must have to advance to that approval step, the user who can approve requests for those records, and whether to allow the delegate of the approver to approve the requests. The first approval step in a process specifies the action to take if a record does not advance to that step. Subsequent steps in the process allow you to specify what happens if an approver rejects the request.

The order of the ApprovalStep entries in the approval process definition determines the order in which the approval steps are executed.
After an approval process is activated, you can't add, delete, or change the order of the steps or change reject or skip behavior for that process, even if you make the process inactive.
There is a limit of 30 steps.

Note

Field Name	Field Type	Description
allowDelegate	boolean	Whether to allow delegated approvers in this step of the approval process. A delegated approver is a user appointed by an assigned approver as an alternate for approval requests.
approvalActions	ApprovalAction	Specifies which workflow actions to execute when a record is approved in this step of the approval process.
assignedApprover	ApprovalStepApprover	Specifies the assigned approvers for this step of the approval process.
description	string	Describes the approval step.
entryCriteria	ApprovalEntryCriteria	Determines which records can enter this step of the approval process.
ifCriteriaNotMet	StepCriteriaNotMetType (enumeration of type string)	Specifies what to do for records that don’t meet the entry criteria. Valid values are: `ApproveRecord`—Approve the request and execute all final approval actions. `RejectRecord`—Reject the request and execute all final rejection actions. This option is available only for the first step in the approval process. `GotoNextStep`—Skip to the next approval step. If you select this option for the first approval step, and a record doesn’t meet the entry criteria for any other step, the record is rejected.
label	string	Required. Name of the approval step.
name	string	Required. Unique name of the approval step. It must contain only underscores and alphanumeric characters, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. The requirement for uniqueness is only within the specific approval process.
rejectBehavior	ApprovalStepRejectBehavior	Required, except for the first step in the approval process. Specifies what happens if the approver rejects the request during this approval step, unless it’s the first step in the approval process. If the approver rejects the request in the first step in the approval process, the reject behavior is determined by the finalRejectionActions.
rejectionActions	ApprovalAction	Specifies which workflow actions to execute when a record is rejected in this step of the approval process.

ApprovalAction

Represents the actions that occur as a result of an approval process.

Field Name	Field Type	Description
action	WorkflowActionReference[]	An array of workflow actions to execute.

ApprovalStepApprover

Represents the assigned approvers for an approval step. There is a limit of 25 approvers per step.

Field Name	Field Type	Description
approver	Approver[]	An array of assigned approvers for this step of the approval process.
whenMultipleApprovers	RoutingType (enumeration of type string)	Specifies how to handle approval or rejection when multiple approvers are assigned to the step. Valid values are: `Unanimous`—(Default) Require unanimous approval from all approvers for this step. The approval request for this step is rejected if any of the approvers reject the request. `FirstResponse`—Approve or reject based on the first response.

Approver

Represents an assigned approver for an approval step.

When specifying approvers, note the following:

Make sure the assigned approver has access to read the records for the approval requests. For example, a user who does not have read access to an Expenses custom object will not be able to view expense approval requests.
You can't use email approval response with approval processes in which the assigned approver is a queue.
Approvers must have the “API Enabled” system permission to approve or reject approval requests via email.
You can assign an approval request to the same user multiple times in a single step; however, Salesforce recognizes such redundancies and only requests a single approval from the user.
After a record enters an approval step, the designated approvers for that step don't change even if the approval process returns to that step and the values of related user fields that designate the approvers have changed. For example, consider an approval process in which the first step requests approval from a user's manager. If the approval request is rejected in the second step and sent back to the first step, the user's original manager receives the approval request again even if the user's manager has changed.
When the assigned approver is a queue:

Any queue member can approve or reject an approval request that is assigned to the queue.
Approval request emails are sent to the queue email address. If the queue is set up to send email to members, then approval request emails are also sent to the queue members, except those whose approval user preferences are set to never receive approval request emails.
When an approval request is assigned to a queue, each queue member's delegated approver also receives an approval request email notification.
Because email notifications to a queue aren’t intended for an external audience, any instances of the merge field {!ApprovalRequest.External_URL} in the email template are sent as the equivalent internal URL.
Salesforce1 notifications for approval requests aren’t sent to queues. For each approval step involving a queue, we recommend adding individual users as assigned approvers, so at least those individuals can receive the approval request notifications in Salesforce1. To have both queues and individual users as assigned approvers, select Automatically assign to approver(s) instead of Automatically assign to queue in the approval step.
When an approval request is rejected and returned to the previous approver and the previous approver was a queue, the approval request is assigned to the user who approved it instead of the queue.
The Approval History related list displays the queue name in the Assigned To column and the actual user who approved or rejected the approval request in the Actual Approver column.

Note

Field Name	Field Type	Description
name	string	Identifies an assigned approver. This field is required, except when the type is one of the following and the name is ignored: `adhoc` `userHierarchyField`
type	NextOwnerType (enumeration of type string)	Combined with the specified name, this identifies an assigned approver. Valid values are: `adhoc`—The approver for the step must be selected manually. For the first step, the submitter selects the approver. For the second and later steps, the approver for the previous step selects the approver. For this value, exclude the name field. `user`—A user in your organization. For this value, enter a username for the name field. `userHierarchyField`—A user specified in a standard or custom user hierarchy field, such as the standard Manager field. For this value, exclude the name field. The user hierarchy field must be defined in the nextAutomatedApprover for the approval process. `relatedUserField`—A user specified in a user lookup field on the submitted record, such as the Last Modified By field. For this value, enter the name of the user lookup field for the name field. `queue`—Automatically assign to a queue. For this value, enter the name of the queue for the name field.

ApprovalEntryCriteria

Represents the criteria that records must meet to enter the approval process or an approval step. Specify either filter criteria or a formula, but not both.

Field Name	Field Type	Description
booleanFilter	string	Filter logic for criteriaItems. Exclude this field if you enter a formula.
criteriaItems	FilterItem[]	Filter criteria that a record must meet to enter the approval process or approval step. Approval processes don't support valueField entries in filter criteria.
formula	string	Formula that must evaluate to true for a record to enter the approval process or approval step.

ApprovalStepRejectBehavior

Represents what happens if the approver rejects the request during this approval step, unless it’s the first step in the approval process. For the first step in the approval process, the reject behavior is determined by the approval process’s final rejection actions.

Field Name	Field Type	Description
type	StepRejectBehaviorType (enumeration of type string)	Valid values are: `RejectRequest`—Automatically rejects the request completely regardless of any previous steps that were approved. Salesforce performs all rejection actions specified for this step and all final rejection actions. `BackToPrevious`—Automatically rejects the request and returns the approval request to the previous approver. Salesforce performs all rejection actions specified for this step. Not allowed in the first step of the approval process.

NextAutomatedApprover

Represents the user hierarchy field to use as the next automated approver for the approval process. If defined, the user specified in the hierarchy field can be automatically assigned as the approver in one or more approval steps.

Field Name	Field Type	Description
useApproverFieldOfRecordOwner	boolean	Required. Whether the first executed approval step should use the specified userHierarchyField in the record owner’s user record—instead of the submitter’s user record—as the approver. All remaining steps use the specified userHierarchyField in the user record of the preceding step’s approver.
userHierarchyField	string	Required. Standard or custom user hierarchy field whose value specifies which user to assign as the approver. For example, the standard Manager hierarchy field can be used to assign approvers for employee PTO (paid time off) requests. Make sure the assigned approver has access to read the records for the approval requests. For example, a user who does not have read access to an Expenses custom object will not be able to view expense approval requests.

Declarative Metadata Sample Definition

The following is an example of an ApprovalProcess component:

1<?xml version="1.0" encoding="UTF-8"?>
2<ApprovalProcess xmlns="http://soap.sforce.com/2006/04/metadata">
3    <active>false</active>
4    <allowRecall>false</allowRecall>
5    <allowedSubmitters>
6        <type>owner</type>
7    </allowedSubmitters>
8    <allowedSubmitters>
9        <submitter>USSalesRep</submitter>
10        <type>role</type>
11    </allowedSubmitters>
12    <allowedSubmitters>
13        <submitter>MarketingGroup</submitter>
14        <type>group</type>
15    </allowedSubmitters>
16    <allowedSubmitters>
17        <submitter>kcooper@example.com</submitter>
18        <type>user</type>
19    </allowedSubmitters>
20    <approvalPageFields>
21        <field>Name</field>
22        <field>Owner</field>
23        <field>MyLeadCustomField__c</field>
24        <field>Address</field>
25    </approvalPageFields>
26    <approvalStep>
27        <allowDelegate>false</allowDelegate>
28        <approvalActions>
29            <action>
30                <name>LeadApprovedTask1</name>
31                <type>Task</type>
32            </action>
33            <action>
34                <name>LeadApprovedTask2</name>
35                <type>Task</type>
36            </action>
37        </approvalActions>
38        <assignedApprover>
39            <approver>
40                <type>adhoc</type>
41            </approver>
42        </assignedApprover>
43        <label>Step1</label>
44        <name>Step1</name>
45        <rejectionActions>
46            <action>
47                <name>LeadRejectedTask</name>
48                <type>Task</type>
49            </action>
50        </rejectionActions>
51    </approvalStep>
52    <approvalStep>
53        <allowDelegate>false</allowDelegate>
54        <assignedApprover>
55            <approver>
56                <type>userHierarchyField</type>
57            </approver>
58        </assignedApprover>
59        <entryCriteria>
60            <criteriaItems>
61                <field>Lead.CreatedDate</field>
62                <operation>greaterThan</operation>
63                <value>3/25/2013</value>
64            </criteriaItems>
65            <criteriaItems>
66                <field>User.IsActive</field>
67                <operation>notEqual</operation>
68                <value>true</value>
69            </criteriaItems>
70        </entryCriteria>
71        <ifCriteriaNotMet>ApproveRecord</ifCriteriaNotMet>
72        <label>Step2</label>
73        <name>Step2</name>
74        <rejectBehavior>
75            <type>RejectRequest</type>
76        </rejectBehavior>
77    </approvalStep>
78    <approvalStep>
79        <allowDelegate>true</allowDelegate>
80        <assignedApprover>
81            <approver>
82                <name>MarketingTeamQueue</name>
83                <type>queue</type>
84            </approver>
85            <approver>
86                <name>LastModifiedBy</name>
87                <type>relatedUserField</type>
88            </approver>
89            <approver>
90                <name>awheeler@example.com</name>
91                <type>user</type>
92            </approver>
93            <whenMultipleApprovers>FirstResponse</whenMultipleApprovers>
94        </assignedApprover>
95        <entryCriteria>
96            <formula>CONTAINS( MyLeadCustomField__c , 'Salesforce')</formula>
97        </entryCriteria>
98        <label>Step3</label>
99        <name>Step3</name>
100        <rejectBehavior>
101            <type>BackToPrevious</type>
102        </rejectBehavior>
103    </approvalStep>
104    <emailTemplate>MyFolder/LeadsNewassignmentnotification</emailTemplate>
105    <enableMobileDeviceAccess>false</enableMobileDeviceAccess>
106    <entryCriteria>
107        <criteriaItems>
108            <field>Lead.AnnualRevenue</field>
109            <operation>greaterThan</operation>
110            <value>10500</value>
111        </criteriaItems>
112        <criteriaItems>
113            <field>Lead.MyLeadCustomField__c</field>
114            <operation>equals</operation>
115            <value>Salesforce</value>
116        </criteriaItems>
117    </entryCriteria>
118    <finalApprovalActions>
119        <action>
120            <name>LeadEmailContacted</name>
121            <type>Alert</type>
122        </action>
123    </finalApprovalActions>
124    <finalApprovalRecordLock>true</finalApprovalRecordLock>
125    <finalRejectionActions>
126        <action>
127            <name>ProcessRejectedMessageAction</name>
128            <type>OutboundMessage</type>
129        </action>
130    </finalRejectionActions>
131    <finalRejectionRecordLock>false</finalRejectionRecordLock>
132    <initialSubmissionActions>
133        <action>
134            <name>LeadFieldUpdate</name>
135            <type>FieldUpdate</type>
136        </action>
137        <action>
138            <name>NewLeadEmail</name>
139            <type>Alert</type>
140        </action>
141    </initialSubmissionActions>
142    <label>SampleProcess</label>
143    <nextAutomatedApprover>
144        <useApproverFieldOfRecordOwner>false</useApproverFieldOfRecordOwner>
145        <userHierarchyField>customlookupuserfield__c</userHierarchyField>
146    </nextAutomatedApprover>
147    <postTemplate>MyPostTemplate</postTemplate>
148    <recallActions>
149        <action>
150            <name>ProcessRecalledMessageAction</name>
151            <type>OutboundMessage</type>
152        </action>
153    </recallActions>
154    <recordEditability>AdminOnly</recordEditability>
155    <showApprovalHistory>false</showApprovalHistory>
156</ApprovalProcess>

Metadata API Developer’s Guide

ApprovalProcess

File Suffix and Directory Location

Version

Fields

ApprovalSubmitter

ApprovalPageField

ApprovalStep

ApprovalAction

ApprovalStepApprover

Approver

ApprovalEntryCriteria

ApprovalStepRejectBehavior

NextAutomatedApprover

Declarative Metadata Sample Definition