Force.com Actions Developer’s Guide

Introducing Actions

Use actions to add more functionality to your applications. Choose from standard actions, such as posting to Chatter or sending email, or create actions based on your company’s needs.For example, you can:

• Add features and functionality to your existing Force.com tools.
• Build dynamic modules for Force.com development into your enterprise integration tools.
• Build specialized development tools for a specific application or service.

You can batch actions to improve performance in API version 35.0 and later.Overview

Actions allow you to build custom development tools for Force.comapplications.

Actions are about “getting things done” in Salesforce. They encapsulate a piece of logic that allows a user to perform some work, such as sending email. When an action runs, it saves changes in your organization by updating the database.Actions are easy to discover and use, and also easy to understand and implement. Every button and link in Salesforce can be considered an action. A consistent Actions API and framework support the creation and distributed use of actions throughoutSalesforce. Actions are available in the REST API.The types of actions are:

Type	Description
DynamicAction	Dynamic actions, also known as invocable actions, can be invoked from a common endpoint in the REST API. They provide “describe” support – a programmatic mechanism to learn about all dynamic actions on the platform. There are two types of dynamic actions. Standard action A standard action is ready to use right away. The work it performs is predefined, along with its inputs and outputs, and they’re available in every organization. Custom action You create custom actions because these actions require a definition. For example, to use an Apexaction, create the Apex class method for the action.
QuickAction	Quick Actions, formerly known as Publisher Actions, use page layouts to make it easy for administrators to configure an action to create or update a record. The API always works with an sObject.
StandardButton	Standard buttons are URLs allowing users to either go to another page (for example, the Edit page) or accomplish some task (for example, lead conversion).
CustomButton	Custom buttons are URLs that an administrator can specify and when included on a page and clicked, will redirect a user to that URL.

To call an action from a flow, use FlowActionCall, as described in theMetadata API Developer’s Guide.The If-Modified-Since header can be used with actions, with a date format of EEE, dd MMM yyyy HH:mm:ss z. When this header is used, if the action metadata has not changed since the provided date, a 304 Not Modified status code is returned, with no response body.Invoking Actions

All actions are invoked using the same JSON body format. The following example shows two Chatter posts made with a single Post to Chatter action.{ “inputs” :
[
{
“subjectNameOrId” : “jsmith@salesforce.com”,
“type” : “user”,
“text” : “first chatter post!”
},
{
“subjectNameOrId” : “hsmith@salesforce.com”,
“type” : “user”,
“text” : “second chatter post!”
}
]
}Available Actions

The following actions are available.

Action	Description
Apex Actions	Invoke Apex methods annotated with @InvocableMethod and include custom parameters with@InvocableVariable.
Email Alert	Send emails from flows by reusing already-configured workflow email alerts.
Flow	Invoke a headless active flow that exists in the current organization.
PlatformAction	PlatformAction is a virtual read-only object. It enables you to query for actions displayed in the UI—such as standard and custom buttons, quick actions, and productivity actions—given a user, a context, device format, and a record ID.
Post toChatterActions	Posts a message to a specified feed, such as to aChatter group or a case record. The message can contain mentions and topics, but only text posts are supported.
Quick Actions	Use a quick action to create a task or a case. Invoke existing quick actions, both global and object-specific, to create records, update records, or log calls.
Refresh Metric	Update a metric’s Current Value field if it’s linked to a summary field in a Salesforce report. The refresh runs as the metric owner.
Simple Email	Send an email where you specify the subject, body, and recipients.
Submit for Approval	Submit a Salesforce record for approval if an approval process is defined for the current entity.

Action ObjectsThis is the reference for quick actions and dynamic actions. Dynamic actions are also known as invocable actions.Apex Actions

Invoke Apex methods annotated with @InvocableMethod and include custom parameters with @InvocableVariable.This object is available in API version 33.0 and later.

Supported REST HTTP Methods

URI

Get a list of available Apex actions:

/vXX.X/actions/custom/apex

Get information about a specific Apex action:

/vXX.X/actions/custom/apex/action_name

This example invokes the Apex method sampleApexAction, which takes a String parameter inputString:

/vXX.X/actions/custom/apex/sampleAction

1

{

2	"inputs" :

3

[  {

4	"inputString" : "someStringValue",

5

} ]

6

}

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Parameters

None

Notes

• When invoking an Apex action using the POST method and supplying the inputs in the request, only the following primitive types are supported as inputs:
  • Blob
  • Boolean
  • Date
  • Datetime
  • Decimal
  • Double
  • ID
  • Integer
  • Long
  • String
  • Time
• Describe and invoke for an Apex action respect the profile access for the Apex class. An error is issued if you don’t have access.
• If you add an Apex action to a flow, and then remove the @InvocableMethod annotation from the Apex class, you’ll get a run-time error in the flow.
• If an Apex action is used in a flow, packageable components that reference these elements aren’t automatically included in the package. For example, if you use an email alert, you must manually add the email template that is used by that email alert. To deploy the package successfully, manually add those referenced components to the package.
• An Apex invocable action can be declared public or global in a managed package. However, that action won’t appear in the Cloud Flow Designer’s list of available actions while building or editing a flow. These invocable actions can still be referred to by flows within the same managed package. Global Apex invocable actions in a managed package can be used in flows outside the managed package, anywhere in the organization, and appear in the CloudFlow Designer’s list of available actions to add to a flow.

Inputs

Apex actions do not have input values in the usual sense. Instead, you supply values that correspond to the InvocableVariables used by theApex InvocableMethod you’re calling. For more information, see the InvocableMethod and InvocableVariable annotations in the Force.comApex Code Developer’s Guide.

OutputsOutput values are determined by the Apex InvocableMethod you’re calling.

Email Alert Actions

Send emails from flows by reusing already-configured workflow email alerts.

The email alert is already configured with the email’s contents, recipients, and sender, so the flow only needs to provide the record ID. Email alerts are entity-specific. For more information about creating email alerts, see Creating Email Alerts for Workflow, Approvals, or Milestones in the Salesforce Help.

This object is available in API version 32.0 and later.

Supported REST HTTP Methods

URI

Get a list of available email alert actions:

/vXX.X/actions/custom/emailAlert

Get information about a specific email alert action:

/vXX.X/actions/custom/emailAlert/entity_name/action_name

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Inputs

The email alert action uses the record specified by SObjectRowId to get the information it needs. For example, if a Case was specified for the action, the action could retrieve the email address and recipient’s name from the Case object’s SuppliedEmailand SuppliedName fields, respectively.

Input	Details
SObjectRowId	Type ID Description Required. The ID of a record such as an Account.

Outputs

None.

Flow Actions

Invoke a headless active flow that exists in the current organization.

For more information about creating flows, see Creating a Flow in theSalesforce online help.

This object is available in API version 32.0 and later.

Supported REST HTTP Methods

URI

Get a list of available flow actions:

/vXX.X/actions/custom/flow

Invokes the LargeOrder flow:

/vXX.X/actions/custom/flow/LargeOrder

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Inputs

Input values vary according to the input variables specified for each flow.

Outputs

Output values vary according to the output variables specified for each flow, but Flow__InterviewStatus is available for all flows.

Output	Details
Flow__InterviewStatus	Type picklist Description The current status of the flow interview. Valid values are: Created Started Finished Error Waiting

PlatformAction

PlatformAction is a virtual read-only object. It enables you to query for actions displayed in the UI—such as standard and custom buttons, quick actions, and productivity actions—given a user, a context, device format, and a record ID.

Supported Calls

query()

Fields

Field	Details
ActionListContext	Type string Properties Filter, Group, Nillable, Restricted picklist,Sort Description Required. The list context this action applies to. Valid values are: Chatter FeedElement FlexiPage Global ListView ListViewRecord MruList MruRow ObjectHomeChart Photo Record RecordEdit RelatedList RelatedListRecord
ActionTarget	Type string Properties Nillable Description The URL to invoke or describe the action when the user invokes the action. If the action is a standard button overridden by aVisualforce page, the ActionTarget returns the URL of the Visualforce page like this:/apex/pagename. This field is available in API version 35.0 and later.
ActionTargetType	Type string Properties Filter, Group, Nillable, Restricted picklist,Sort Description The type of the target when this action is triggered. Valid values are: Describe—applies to actions with a user interface, such as quick actions Invoke—applies to actions with no user interface, such as action links or dynamic actions Visualforce—applies to standard buttons that have been overridden by aVisualforce page
ActionTargetUrl	Type string Properties Filter, Group, Nillable, Sort Description URL to invoke or describe the action when the user invokes the action. This field is deprecated inAPI version 35.0 and later. UseActionTarget instead.
Category	Type string Properties Filter, Group, Nillable, Restricted picklist,Sort Description Applies only to action links. Denotes whether the action link shows up in the feed item list of actions or the overflow list of actions. Valid values are: Primary Overflow
ConfirmationMessage	Type string Properties Filter, Group, Nillable, Sort Description Applies only to action links. The message to display before the action is invoked. Field is null if no confirmation is required prior to invoking the action.
DeviceFormat	Type string Properties Filter, Group, Nillable, Restricted picklist,Sort Description Specifies which action icon is returned by the PlatformAction query. If this field isn’t specified, it defaults to Phone. Valid values are: Aloha Desktop Phone Tablet
ExternalId	Type string Properties Filter, Group, Nillable, Sort Description The unique ID for the PlatformAction. If the action doesn’t have an ID, its API name is used.
GroupId	Type ID Properties Filter, Group, Nillable, Sort Description The unique ID of a group of action links.
IconContentType	Type string Properties Filter, Group, Nillable, Sort Description The content type—such as .jpg, .gif, or .png—of the icon for this action. Applies to both custom and standard icons assigned to actions.
IconHeight	Type int Properties Filter, Group, Nillable, Sort Description The height of the icon for this action. Applies only to standard icons.
IconUrl	Type string Properties Filter, Group, Nillable, Sort Description The URL of the icon for this action.
IconWidth	Type int Properties Filter, Group, Nillable, Sort Description The width of the icon for this action. Applies only to standard icons.
InvocationStatus	Type string Properties Filter, Group, Nillable, Restricted picklist,Sort Description The status of the action within the feed item. Applies to action links only. Valid values are: Failed New Pending Successful
InvokedByUserId	Type ID Properties Filter, Group, Nillable, Sort Description The ID of the user who most recently invoked this action within the current feed item. Applies to action links only.
IsGroupDefault	Type boolean Properties Filter, Group, Sort Description Denotes whether this action is the default in an action link group. False for other action types. Applies to action links only.
Label	Type string Properties Filter, Group, Sort Description The label to display for this action.
PrimaryColor	Type string Properties Filter, Group, Nillable, Sort Description The primary color of the icon for this action.
RelatedSourceEntity	Type string Properties Filter, Group, Nillable, Sort Description When the ActionListContext is RelatedList or RelatedListRecord, this field represents the API name of the related list to which the action belongs.
Section	Type string Properties Filter, Group, Nillable, Restricted picklist,Sort Description The section of the user interface the action resides in. Applicable only to Lightning Experience. Valid values are: ActivityComposer CollaborateComposer NotesComposer Page SingleActionLinks This field is available in API version 35.0 and later.
SourceEntity	Type string Properties Filter, Group, Sort Description Required. The object or record with which this action is associated.
Subtype	Type string Properties Filter, Group, Nillable, Sort Description The subtype of the action. For quick actions, the subtype is QuickActionType. For custom buttons, the subtype is WebLinkTypeEnum. For action links, subtypes are Api, ApiAsync, Download, and Ui. Standard buttons and productivity actions have no subtype.
Type	Type string Properties Filter, Group, Restricted picklist, Sort Description The type of the action. Valid values are: ActionLink—An indicator on a feed element that targets an API, a web page, or a file and is represented by a button in the Salesforce Chatter feed UI. CustomButton—When clicked, opens a URL or a Visualforce page in a window or executes JavaScript. InvocableAction ProductivityAction—Productivity actions are predefined by Salesforce and are attached to a limited set of objects. You can’t edit or delete productivity actions.. QuickAction—A global or object-specific action. StandardButton—A predefinedSalesforce button such as New, Edit, and Delete.

Usage

PlatformAction can be described using describeSObject().

You can directly query for PlatformAction. For example, this query returns all fields for actions associated with each of the records of the listed objects:

1	SELECT ExternalId, ActionTargetType, ActionTargetUrl, ApiName, Category,

2	ConfirmationMessage, ExternalId, GroupId, UiTheme, IconUrl, IconContentType,

3	IconHeight, IconWidth, PrimaryColor, InvocationStatus, InvokedByUserId,

4	IsGroupDefault, Label, LastModifiedDate, Subtype, SourceEntity, Type

5	FROM PlatformAction

6	WHERE SourceEntity IN ('001xx000003DGsH', '001xx000003DHBq', ‘Task’, ‘Global’) AND

7	ActionListContext = ‘Record’;

To query PlatformAction, you must provide the ActionListContext andSourceEntity. If you query forActionListContext with a value of RelatedList, and don’t specify a RelatedSourceEntity, the query returns the API name of the related list.

This query uses multiple ActionListContext values in its WHERE clause to return all actions in the Lightning Experience user interface (DeviceFormat = ‘Desktop’) for the specified object:

view source

https://developer.salesforce.com/resource/flash/clipboard.swf

print?

1	SELECT ActionListContext, Label, Type, Subtype, Section, SourceEntity,

2	RelatedSourceEntity, ActionTarget, ActionTargetType, ApiName, Category,

3	ConfirmationMessage, DeviceFormat, ExternalId, GroupId, IconContentType,

4	IconHeight, IconUrl, IconWidth, Id, InvocationStatus, InvokedByUserId,

5	IsGroupDefault, LastModifiedDate, PrimaryColor

6	FROM PlatformAction

7	WHERE ActionListContext IN ('Record','Chatter','RelatedList') AND

8	SourceEntity = '001xx000003DlvX' AND

9	DeviceFormat = 'Desktop'

Post to Chatter Actions

Post to the feed for a specific record, user, or Chatter group.

Use a Post to Chatter action to post a message at run time to a specified feed. Post to Chatter supports @mentions and topics, but only text posts are supported.

This object is available in API version 32.0 and later.

Supported REST HTTP Methods

URI

Get a list of available post to Chatter actions:

/vXX.X/actions/standard/chatterPost

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Inputs

Input	Details
communityId	Type reference Description Optional. Specifies the ID of a community to post to. Valid only if Salesforce Communities is enabled. Required if posting to a user or Chattergroup that belongs to a Salesforce.com Community. This value is available in API version 35.0 and later.
subjectNameOrId	Type string Description Required. Reference to the user, Chatter group, or record whose feed you want to post to. To post to a user’s feed, enter the user’s IDor Username. For example:jsmith@salesforce.com To post to a Chatter group, enter the group’s Name or ID. For example: Entire Organization To post to a record, enter the record’s ID. For example: 001D000000JWBDx
text	Type string Description Required. The text that you want to post. Must be a string of no more than 10,000 characters. To mention a user or group, enter @[reference], where reference is the ID for the user or group that you want to mention. The reference can be a literal value, a merge field, or a flow resource. To add a topic, enter #[string], where string is the topic that you want to add. For example, the string Hi @[005000000000001] check this out #[some_topic]. is stored appropriately as Hi @Joe, check this out #some_topic. where “@Joe” and “#some_topic” are links to the user and topic, respectively.
type	Type picklist Description Required only if subjectNameOrId is set to a user name or a Chatter group name. The type of feed that you want to post to. User—Enter this value if subjectNameOrId is set to a user’s Username. Group—Enter this value if subjectNameOrIdis set to a Chatter group’s Name.
visibility	Type picklist Description Optional. Valid only if Salesforce Communities is enabled. Specifies whether this feed item is available to all users or internal users only. Valid values are: allUsers internalUsers This value is available in API version 35.0 and later.

Outputs

Output	Details
feedItemId	Type reference Description The ID of the new Chatter feed item.

Quick Actions

Use a quick action to create a task or a case. Invoke existing quick actions, both global and object-specific, to create records, update records, or log calls.

For more information about creating global quick actions, see Create Global Quick Actions, and for more information on object-specific quick actions, see Create Object-Specific Quick Actions, in the Salesforceonline help.

This object is available in API version 32.0 and later.

Supported REST HTTP Methods

URI

Get a list of quick actions:

/vXX.X/actions/custom/quickAction

Get a specific quick action:

/vXX.X/actions/custom/quickAction/quick_action_name

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Notes

The only type of quick actions that can be invoked are create, update, and logACall.

Inputs

All quick actions have the contextId input parameter. It’s a reference to the related record for the quick action. Other inputs vary according to the layout of the quick action. To determine inputs for a specific quick action, use the describe feature. For example, perform a GET with /services/data/vXX.X/actions/custom/quickAction/Task/deferTask to see the inputs for the quick actiondeferTask.

Refresh Metric Actions

Update a metric’s Current Value field if it’s linked to a summary field in a Salesforce report. The refresh runs as the metric owner.

This object is available in API version 34.0 and later.

Supported REST HTTP Methods

URI

Get a list of metric refresh actions:

/vXX.X/actions/standard/metricRefresh

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Inputs

Input	Details
metricId	Type string Description Required. The metric linked to a Salesforce report.

Outputs

Output	Details
resultingMessage	Type string Description The message that indicates the results of the metric refresh.

Simple Email Actions

Send an email where you specify the subject, body, and recipients.

This object is available in API version 32.0 and later.

Supported REST HTTP Methods

URI

Get a list of available simple email actions:

/vXX.X/actions/standard/emailSimple

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Inputs

Input	Details
emailAddresses	Type string Description Required if emailAddressArray isn’t used. The email recipients specified as a comma-separated list. The number of email recipients must be five or less. If emailAddressArray is also used, the combined number of recipients must be five or less.
emailAddressesArray	Type string Description Required if emailAddress isn’t used. Up to five email recipients, specified as a collection of strings. IfemailAddress is also used, the combined number of recipients must be five or less.
emailBody	Type textarea Description Required. The body of the email in plain text.
emailSubject	Type string Description Required. The email’s subject.
senderAddress	Type string Description Optional. The organization-wide email address to be used as the sender. Required only ifsenderType is set to OrgWideEmailAddress.
senderType	Type string Description Optional. Email address used as the email’s From and Reply-To addresses. Valid values are: CurrentUser—Email address of the user running the flow. This is the default setting. DefaultWorkflowUser—Email address of the default workflow user. OrgWideEmailAddress—The organization-wide email address that is specified insenderAddress.

Outputs

None.

Submit for Approval Actions

Submit a Salesforce record for approval if an approval process is defined for the current entity.

For more information about creating submit for approval actions, seeCreating Approval Actions, and to learn more about approval processes, see Approval Process Overview, in the Salesforce online help.

This object is available in API version 32.0 and later.

Supported REST HTTP Methods

URI

Get a list of actions:

/vXX.X/actions/standard/submit

Formats

JSON, XML

HTTP Methods

GET, HEAD, POST

Authentication

Authorization: Bearer token

Inputs

Input	Details
comment	Type string Description Optional. Comments that accompany the Approval submission.
nextApproverIds	Type reference Description Optional. An array of one ID of the next approver, which can be a user or a group. This input is optional because some approval processes have the next approver specified in the approval process definition. You can’t specify more than 2,000 approvers.
objectId	Type reference Description Required. The ID of the record being submitted for approval.
processDefinitionNameOrId	Type string Description Optional. The ID or name of the approval process to run against the record. If none is specified, the first approval process whose entry criteria the record satisfies is used. Names can’t be longer than 120 characters.
skipEntryCriteria	Type boolean Description Optional. A Boolean value controlling whether the entry criteria for the specified approval process should be evaluated for the record (true) or not (false). If set to true, also specifyprocessDefinitionNameOrId.
submitterId	Type string Description Optional. The ID of the user submitting the record for approval. If none is specified, the submitter is the current user.

Outputs

Output	Details
actorIds	Type reference Description An array of the IDs of the next approvers.
entityId	Type reference Description The ID of the record submitted for approval.
instanceId	Type reference Description The ID of the approval process instance.
instanceStatus	Type string Description The status of the approval. The valid values are Approved Pending Rejected Removed
newWorkItemIds	Type reference Description An array of the IDs of the work items created for the next step in this approval process.