Newer Version Available

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

Workflow

Represents the metadata associated with a workflow rule. A workflow rule sets workflow actions into motion when its designated conditions are met. You can configure workflow actions to execute immediately when a record meets the conditions in your workflow rule, or set time triggers that execute the workflow actions on a specific day. Use this metadata type to create, update, or delete workflow rule definitions.

For more information, see Workflow in Salesforce Help. This type extends the Metadata metadata type and inherits its fullName field.

When using a manifest file, retrieve all workflow components using this code.

1<types>
2    <members>*</members>
3    <name>Workflow</name>
4</types>

Declarative Metadata File Suffix and Directory Location

Workflow files have the suffix .workflow. There’s one file per standard or custom object that has workflow. These files are stored in the workflows directory of the corresponding package.

Version

Workflow rules are available in API version 13.0 and later.

Workflow

This metadata type represents the valid types of workflow rules and actions associated with a standard or custom object.

Field Name Field Type Description
alerts WorkflowAlert[] An array of all alerts for the object associated with the workflow.
fieldUpdates WorkflowFieldUpdate[] An array of all field updates for the object associated with the workflow.
flowActions WorkflowFlowAction[] An array of flow triggers for the object associated with the workflow. Available in API version 30.0 and later.

The pilot program for flow trigger workflow actions is closed. If you already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn’t enable the pilot, use Flow Builder to create a record-triggered flow, or use Process Builder to launch a flow from a process.

fullName string The developer name used as a unique identifier for API access. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
knowledgePublishes WorkflowKnowledgePublish[] An array of Salesforce Knowledge Workflow Publishes associated with the workflow. Available in API version 27.0 and later.
outboundMessages WorkflowOutboundMessage[] An array of all the outbound messages for the object associated with the workflow.
rules WorkflowRule[] An array of all the objects associated with the workflow.
tasks WorkflowTask[] An array of all the tasks for the object associated with the workflow.

WorkflowActionReference

WorkflowActionReference represents one of the workflow actions.

Field Name Field Type Description
name string Required. The name of the workflow action.
type WorkflowActionType (enumeration of type string) Required. Available types of workflow actions:
  • Alert
  • FieldUpdate
  • FlowAction—Available in API version 30.0 and later
  • OutboundMessage
  • Task

The pilot program for flow trigger workflow actions is closed. If you already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn't enable the pilot, use Flow Builder to create a record-triggered flow, or use Process Builder to launch a flow from a process.

WorkflowAlert

WorkflowAlert represents an email alert associated with a workflow rule.

Field Name Field Type Description
ccEmails string[] Additional email addresses. This field is similar to the CC field in email clients.

For the email to be sent successfully, set a value for ccEmails or recipients. You can set values for both fields. The value of ccEmails can include up to 5 different email addresses.

description string Required. A description of the email alert. Available in API version 16.0 and later.
fullName string Required. The developer name used as a unique identifier for API access. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
protected boolean Required. Indicates whether this component is protected (true) or not (false). Protected components can’t be linked to or referenced by components created in the installing organization.
recipients WorkflowEmailRecipient[] The recipients for the email.

For the email to be sent successfully, set a value for ccEmails or recipients. You can set values for both fields.

senderAddress string The address in the From field for the email alert. With this address, you can use a standard global email address for your organization, such as support@company.com, instead of the default From field, which is the email address of the person who updates the record. You can only specify a value in this field if the senderType is set to OrgWideEmailAddress. See Organization-Wide Email Addresses in Salesforce Help.
senderType ActionEmailSenderType (enumeration of type string) The email used as the sender’s From and Reply-To addresses. These values are valid.
  • CurrentUser—The email address of the person updating the record. This value is the default setting.
  • DefaultWorkflowUser—The email address of the default workflow user. If the email alert is installed from a package, this field value is changed to CurrentUser.
  • OrgWideEmailAddress—A verified global email address for your organization, such as support@company.com.
template string Required. Named reference to an EmailTemplate. This email template isn’t required to exist in the zip file, but it must exist in Metadata API.

Lightning email templates aren’t packageable. We recommend using a Classic email template.

WorkflowEmailRecipient

WorkflowEmailRecipient represents a recipient for an email alert associated with a workflow rule.

Field Name Field Type Description
field string Name of the field referenced in type. The field named is of the type specified in type.
recipient string The recipients for the email. Depending on the type selected, this field is required.
type ActionEmailRecipientTypes (enumeration of type string) Named reference to an EmailTemplate component. Valid values are:
  • accountOwner—The email is sent to the record’s account owner. For example, the Account owner for an Opportunity.
  • accountTeam—Only applicable on the Account object. The email is sent to everyone on that Account’s account team.
  • campaignMemberDerivedOwner—Emails are sent to lead and contact owners when contacts are added to a campaign or in response to a campaign.
  • contactLookup—The email is sent to a contact whose value is looked up from a field on the record. For this value, the field field must reference a Contact.
  • creator—The email is sent to the record’s creator.
  • customerPortalOwner—The email is sent to a specific self-service portal user. For this value, the recipient field must reference a self-service portal user by their username.
  • email—The email is sent to an email address whose value is looked up from a field on the record. For this value, the field field must reference an email field.
  • group—The email is sent to all users in a group. For this value, the recipient field must reference a group by group name.
  • opportunityTeam—Only applicable on the Opportunity object. The email is sent to everyone on that Opportunity’s opportunity team.
  • owner—The email is sent to the record’s owner.
  • partnerUser—The email is sent to a specific partner user. For this value, the recipient field must reference a partner user by username.
  • portalRole - Like role, but for portal roles only.
  • portalRoleSubordinates - Like roleSubordinates, but for portal roles only.
  • role—The email is sent to all users in a role. For this value, the recipient field must reference a role name in the role hierarchy.
  • roleSubordinates—The email is sent to all users in a role subordinate. For this value, the recipient field must reference a role.
  • roleSubordinatesInternal—Like roleSubordinates, but for internal portal roles only.
  • user—The email is sent to a specific user. For this value, the recipient field must reference a user by username.
  • userLookup—The email is sent to a user whose value is looked up from a field on the record. For this value, the field field must reference a user foreign key field.

WorkflowFieldUpdate

WorkflowFieldUpdate represents a workflow field update. With field updates, you can automatically update a field value to one that you specify when a workflow rule is triggered.

Field Name Field Type Description
description string The description of the field update. This information is useful to track the reasoning for initially configuring the field update.
field string Required. The field on the object for the workflow to be updated.
formula string If the operation field value is Formula, the formula used to compute the new field value.
fullName string Required. The developer name used as a unique identifier for API access. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
literalValue string If the operation field value is Literal, the literal value for the field.
lookupValue string If the operation field value is lookupValue, the lookup value that is referenced.
lookupValueType LookupValueType (enumeration of type string) The type of object that the lookupValue field value is referencing. The valid values are:
  • Queue
  • RecordType
  • User
name string Required. A name for the component. Available in version API 16.0 and later.
notifyAssignee boolean Required. Notify the assignee when the field is updated.
operation FieldUpdateOperation (enumeration of type string) Required. The operation that computes the value with which to update the field. Valid values are:
  • Formula—Indicates the field is set to a formula. If set, the formula must be a valid formula.
  • Literal—Indicates the field is set to a literal value. If set, the literalValue must be a valid literal value for this field.
  • LookupValue—Similar to Literal, but for an object reference, such as a contact, user, or account. If set, the lookupValue element must be set. Only User is supported in the current API.
  • NextValue—Indicates that the field will be set to its next value. Only allowed when the field update references a picklist.
  • Null—Indicates that the field is set to null.
  • PreviousValue—Indicates that the field is set to its previous value. Only allowed when the field update references a picklist.
protected boolean Required. Indicates whether this component is protected (true) or not (false). Protected components can’t be linked to or referenced by components created in the installing organization.
reevaluateOnChange boolean When set to true, if the field update changes the field’s value, all workflow rules on the associated object are reevaluated. Any workflow rules whose criteria are met as a result of the field value change are triggered.

If any of the triggered workflow rules result in another field update that’s also enabled for workflow rule reevaluation, a domino effect occurs, and more workflow rules can be reevaluated as a result of the newly triggered field update. This cascade of workflow rule reevaluation and triggering can happen up to 5 times after the initial field update that started it.

targetObject string Object set if the change is detected on a child record. If set, the object points to the foreign key reference on the child object that points to the parent. For example, if EmailMessage child record is changed, EmailMessage.ParentId points to the Case parent. This field is named sourceField before version 14.0. The field name change is automatically handled between versions and doesn’t require any manual editing of existing XML component files.

WorkflowFlowAction

Represents a flow trigger, which is a workflow action that launches a flow. Available in API version 30.0 and later. For more information, see these topics in Salesforce Help.
  • Define a Flow Trigger for Workflow (Pilot)
  • Flow Trigger Considerations (Pilot)
  • The pilot program for flow trigger workflow actions is closed. If you already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn’t enable the pilot, use Flow Builder to create a record-triggered flow, or use Process Builder to launch a flow from a process.
  • Test mode for flow triggers isn’t supported in the Metadata API. If you want a flow trigger to run the latest flow version when an administrator causes the workflow rule to fire, enable test mode via the user interface after deployment.

Note

Field Name Field Type Description
description string Describes the flow trigger.
flow string Required. API name of the flow that this workflow action launches.
flowInputs WorkflowFlowActionParameter[] An array of values to pass into flow variables when launching the flow.
label string Required. Name of the flow trigger.
language string Reserved for future use.
protected boolean Reserved for future use.

WorkflowFlowActionParameter

Represents a value specified in the flow trigger that is passed into a variable when launching the flow.

The pilot program for flow trigger workflow actions is closed. If you already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn’t enable the pilot, use Flow Builder to create a record-triggered flow, or use Process Builder to launch a flow from a process.

Note

Field Name Field Type Description
name string Required. API name of the flow variable.

The flow variable must have isInput set to True.

value string Required. Value to assign to the flow variable when launching the flow.
If the variable's data type is sObject, value must be a merge field that identifies a record—or a lookup relationship field that references a record—of the same object type as the variable. For example:
  • {!this}—Identifies the record that fired the workflow rule.
  • {!Contact}—Identifies the contact associated with the record that fired the workflow rule.
  • {!Asset.Account}—Identifies the account associated with the asset that is associated with the record that fired the workflow rule.
  • {!SomeObject__r}—Uses a lookup relationship field to identify a custom object record associated with the record that fired the workflow rule.

For variables of other data types, you can enter a merge field or a literal value. Manually enter a literal value when the variable requires the same value every time the flow is launched, regardless of which record fired the workflow rule. For example, you can enter true or false for a variable of type Boolean.

Supported merge fields identify a global variable or a field of the same data type as the flow variable. For example:
  • {!Id}—ID of the record that fired the workflow rule.
  • {!Account.Owner.Email}—Email address of the account owner for the account associated with the record that fired the workflow rule.
  • {!$Organization.Country}—Country of the organization.

WorkflowKnowledgePublish

WorkflowKnowledgePublish represents Salesforce Knowledge article publishing actions and information. Available in API version 27.0 and later.

Field Name Field Type Description
action KnowledgeWorkflowAction (enumeration of type string) Required. The article publishing actions available when this rule fires. Valid values are:
  • PublishAsNew—Publishes the article as a new article.
  • Publish—Publishes the article as a version of a previously published article.
description string A brief article description.
label string

Required. Label that represents the article throughout the Salesforce user interface.

language string The language of the article.
protected boolean Required. Indicates whether this component is protected (true) or not (false). Protected components can’t be linked to or referenced by components created in the installing organization.

WorkflowOutboundMessage

WorkflowOutboundMessage represents an outbound message associated with a workflow rule. Outbound messages are workflow and approval actions that send the information you specify to an endpoint you designate, such as an external service. An outbound message sends the data in the specified fields in the form of a SOAP message to the endpoint. For more information, see Outbound Message Actions in Salesforce Help.

Field Name Field Type Description
apiVersion double Required. The API version of the outbound message. Automatically set to the current API version when the outbound message is created. Valid API versions for outbound messages are 8.0 and 18.0 or later.

This API version is used in API calls back to Salesforce using the enterprise or partner WSDLs. The API Version can only be modified by using Metadata API. It can’t be modified using the Salesforce user interface. This field is available in API version 18.0 and later.

If you change the apiVersion to a version that doesn’t support one of the fields configured for the outbound message, the messages fail until you update your outbound message listener to consume the updated WSDL.

To monitor the status of outbound messages, from Setup, in the Quick Find box, enter Outbound Messages, and then select Outbound Messages inSalesforce.

Warning

description string Describes the outbound message.
endpointUrl string Required. The endpoint URL to which the outbound message is sent.
fields string[] The named references to the fields to be sent.
fullName string Required. The developer name used as a unique identifier for API access. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
includeSessionId boolean Required. Set if you want the Salesforce session ID included in the outbound message. Useful if you intend to make API calls and you don’t want to include a username and password.
integrationUser string Required. The named reference to the user under which this message is sent.
name string Required. A name for the component. Available in version API 16.0 and later.
protected boolean Required. Indicates whether this component is protected (true) or not (false). Protected components can’t be linked to or referenced by components created in the installing organization.
useDeadLetterQueue boolean This field is only available for organizations with dead letter queue permissions turned on. If set, this outbound message uses the dead letter queue if normal delivery fails.

WorkflowRule

This metadata type represents a workflow rule. This type extends the Metadata metadata type and inherits its fullName field.

Field Name Field Type Description
actions WorkflowActionReference[] An array of references for the actions that happen when this rule fires.
active boolean Required. Determines if this rule is active.
booleanFilter string For advanced criteria filter, the boolean formula. For example, (1 AND 2) OR 3.
criteriaItems FilterItem[] An array of the boolean criteria (conditions) under which this rule fires. Either criteriaItems or formula must be set.
description string The description of the workflow rule.
failedMigrationToolVersion string The API version in which a migration fails. Used as a reference to admins to retry the migration when the next version is released.

Available in API version 54.0 and later.

formula string The formula condition under which this rule first must be set, either formula or criteriaItems.
fullName string The developer name used as a unique identifier for API access. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
triggerType WorkflowTriggerTypes (enumeration of type string) Under what conditions the trigger fires. Valid values are:
  • onAllChanges—The workflow rule is considered on all changes.
  • onCreateOnly—The workflow rule is considered only on create.
  • onCreateOrTriggeringUpdate—The workflow rule is considered on create and triggering updates.
workflowTimeTriggers WorkflowTimeTrigger Represents a set of Workflow actions, including Field Updates, Email Alerts, Outbound Messages, and Tasks, that executes before or after a specified interval of time.

WorkflowTask

This metadata type references an assigned workflow task.

Field Name Field Type Description
assignedTo string Specifies the user, role, or team to which the workflow rule or action is assigned. The field corresponding to the value specified here must be the same as the specified assignedToType.
assignedToType ActionTaskAssignedToTypes (enumeration of type string) Valid string values for this type are:
  • accountCreator—When set, the task is assigned to the record’s account's creator.
  • accountOwner—When set, the task is assigned to the record’s account owner (Opportunity).
  • accountTeam—Same as WorkflowAlert type
  • creator—When set, the task is assigned to the record’s creator.
  • opportunityTeam—Same as WorkflowAlert type
  • owner—When set, the task is assigned to the record’s owner.
  • partnerUser—When set, the assignedTo field references a partner user by username.
  • portalRole—When set, the assignedTo field references a Role by role name, a portal role.
  • role—When set, the assignedTo field references a Role by role name.
  • user—When set, the assignedTo field references a User by username.
description string The description of this workflow task.
dueDateOffset int Required. The offset, in days, from either the trigger date, or the date specified in the (optional) offsetFromField. The offset can be a negative number.
fullName string Required. The developer name used as a unique identifier for API access. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
notifyAssignee boolean Required. Set to send an email notification when the task is assigned.
offsetFromField string Optional field reference of the date field from which the dueDate is computed.
priority string Required. The priority to assign the created task.
protected boolean Required. Indicates whether this component is protected (true) or not (false). Protected components can’t be linked to or referenced by components created in the installing organization.
status string Required. The status to assign the created task.
subject string Required. A subject for the workflow task that’s used if an email notification is sent when the task is assigned. Available in API version 16.0 and later.

WorkflowTimeTrigger

Represents a set of Workflow actions, including Field Updates, Email Alerts, Outbound Messages, and Tasks, that execute before or after a specified interval of time.

Field Name Field Type Description
actions WorkflowActionReference[] An array of references for the actions that happen when this trigger fires.
offsetFromField string The date type field name that the time-based workflow triggers from, such as Created Date, Last Modified Date, Rule Trigger Date, or a custom date field on the object for which the workflow rule is defined.
timeLength string The numeric value of the time after or before the workflow triggers. A negative value represents the time length before the trigger fires. The timeLength is measured in either hours or days, as specified by workflowTimeTriggerUnit.
workflowTimeTriggerUnit WorkflowTimeUnits (enumeration of type string) The unit of time before or after which the time-based workflow triggers. Valid string values are:
  • Hours
  • Days

Declarative Metadata Sample Definition

Here’s the definition of a workflow rule.

1<?xml version="1.0" encoding="UTF-8"?>
2<Workflow xmlns="http://soap.sforce.com/2006/04/metadata">
3    <alerts>
4        <fullName>Another_alert</fullName>
5        <description>Another alert</description>
6        <protected>false</protected>
7        <recipients>
8            <type>accountOwner</type>
9        </recipients>
10        <recipients>
11            <field>Contact__c</field>
12            <type>contactLookup</type>
13        </recipients>
14        <recipients>
15            <field>Email__c</field>
16            <type>email</type>
17        </recipients>
18        <template>TestEmail/Email Test</template>
19    </alerts>
20    <fieldUpdates>
21        <fullName>Enum_Field_Update</fullName>
22        <description>Blah</description>
23        <field>EnumField__c</field>
24        <name>Enum Field Update</name>
25        <notifyAssignee>true</notifyAssignee>
26        <operation>NextValue</operation>
27        <protected>false</protected>
28    </fieldUpdates>
29    <fieldUpdates>
30        <fullName>Enum_Field_Update2</fullName>
31        <description>Blah</description>
32        <field>EnumField__c</field>
33        <literalValue>PLX2</literalValue>
34        <name>Enum Field Update2</name>
35        <notifyAssignee>true</notifyAssignee>
36        <operation>Literal</operation>
37        <protected>false</protected>
38    </fieldUpdates>
39    <fieldUpdates>
40        <fullName>Field_Update</fullName>
41        <description>TestField update desc</description>
42        <field>Name</field>
43        <formula>Name &amp; &quot;Updated&quot;</formula>
44        <name>Field Update</name>
45        <notifyAssignee>false</notifyAssignee>
46        <operation>Formula</operation>
47        <protected>false</protected>
48    </fieldUpdates>
49    <fieldUpdates>
50        <fullName>Lookup_On_Contact</fullName>
51        <field>RealOwner__c</field>
52        <lookupValue>admin@acme.com</lookupValue>
53        <name>Lookup On Contact</name>
54        <notifyAssignee>false</notifyAssignee>
55        <operation>LookupValue</operation>
56        <protected>false</protected>
57    </fieldUpdates>
58    <outboundMessages>
59        <fullName>Another_Outbound_message</fullName>
60        <description>Another Random outbound.</description>
61        <endpointUrl>http://www.test.com</endpointUrl>
62        <fields>Email__c</fields>
63        <fields>Id</fields>
64        <fields>Name</fields>
65        <includeSessionId>true</includeSessionId>
66        <integrationUser>admin@acme.com</integrationUser>
67        <name>Another Outbound message</name>
68        <protected>false</protected>
69    </outboundMessages>
70    <rules>
71        <fullName>BooleanFilter</fullName>
72        <active>false</active>
73        <booleanFilter>1 AND 2 OR 3</booleanFilter>
74        <criteriaItems>
75            <field>CustomObjectForWorkflow__c.CreatedById</field>
76            <operation>notEqual</operation>
77        </criteriaItems>
78        <criteriaItems>
79            <field>CustomObjectForWorkflow__c.CreatedById</field>
80            <operation>notEqual</operation>
81            <value>abc</value>
82        </criteriaItems>
83        <criteriaItems>
84            <field>CustomObjectForWorkflow__c.CreatedById</field>
85            <operation>equals</operation>
86            <value>xyz</value>
87        </criteriaItems>
88        <triggerType>onCreateOrTriggeringUpdate</triggerType>
89    </rules>
90    <rules>
91        <fullName>Custom Rule1</fullName>
92        <actions>
93            <name>Another_alert</name>
94            <type>Alert</type>
95        </actions>
96        <actions>
97            <name>Enum_Field_Update2</name>
98            <type>FieldUpdate</type>
99        </actions>
100        <actions>
101            <fullName>Field_Update</name>
102                <type>FieldUpdate</type>
103        </actions>
104        <actions>
105            <name>Another_Outbound_message</name>
106            <type>OutboundMessage</type>
107        </actions>
108        <actions>
109            <name>Role_task_was_completed</name>
110            <type>Task</type>
111        </actions>
112        <active>true</active>
113        <criteriaItems>
114            <field>CustomObjectForWorkflow__c.Name</field>
115            <operation>startsWith</operation>
116            <value>ABC</value>
117        </criteriaItems>
118        <description>Custom Rule1 desc</description>
119        <triggerType>onCreateOrTriggeringUpdate</triggerType>
120    </rules>
121    <rules>
122        <fullName>IsChangedFunctionRule</fullName>
123        <active>true</active>
124        <description>IsChangedDesc</description>
125        <formula>ISCHANGED(Name)</formula>
126        <triggerType>onAllChanges</triggerType>
127    </rules>
128    <tasks>
129        <fullName>Another_task_was_completed</fullName>
130        <assignedToType>owner</assignedToType>
131        <description>Random Comment</description>
132        <dueDateOffset>20</dueDateOffset>
133        <notifyAssignee>true</notifyAssignee>
134        <priority>High</priority>
135        <protected>false</protected>
136        <status>Completed</status>
137        <subject>Another task was completed</subject>
138    </tasks>
139    <tasks>
140        <fullName>Role_task_was_completed</fullName>
141        <assignedTo>R11</assignedTo>
142        <assignedToType>role</assignedToType>
143        <dueDateOffset>-2</dueDateOffset>
144        <notifyAssignee>true</notifyAssignee>
145        <offsetFromField>CustomObjectForWorkflow__c.CreatedDate</offsetFromField>
146        <priority>High</priority>
147        <protected>false</protected>
148        <status>Completed</status>
149        <subject>Role task was completed</subject>
150    </tasks>
151    <tasks>
152        <fullName>User_task_was_completed</fullName>
153        <assignedTo>admin@acme.com</assignedTo>
154        <assignedToType>user</assignedToType>
155        <dueDateOffset>-2</dueDateOffset>
156        <notifyAssignee>true</notifyAssignee>
157        <offsetFromField>User.CreatedDate</offsetFromField>
158        <priority>High</priority>
159        <protected>false</protected>
160        <status>Completed</status>
161        <subject>User task was completed</subject>
162    </tasks>
163</Workflow>

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.