Andy in the Cloud

From BBC Basic to Force.com and beyond…

Introduction to the Platform Action API

16 Comments

shutterstock_159003926.jpg

Actions are Salesforce’s general term for tasks users can perform either through buttons throughout various UI’s on desktop, mobile, tablet etc or in fact via non-UI processes such those built via via Process Builder or Automation Flows.

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. More here.

Over the years we’ve had many terms and ways to define these. Custom Button and Custom Link are perhaps the most obvious ones, which i’ve covered here in the past. Quick Actions (previously Publisher Actions) and more recently we’ve had Action Link‘s, which i covered in a past blog. Then of course the Standard Buttons, Edit, Delete, Follow, Submit for Approval etc provided by the platform. Such actions appear in various places Record layouts, List Views, Related Lists, Chatter and more recently Flexi Pages (aka Lighting Pages).

You might wonder then, if you had the task as developer to build your own UI or tool that wanted to expose some or all of the above actions, it would be quite a challenge to find them all. Indeed in some cases you may have had to resort to URL hacking to invoke some of them. Well worry not no longer, Salesforce’s clever architects now have you covered! Enter a new virtual SObject known as PlatformAction! Before we get onto what exactly virtual means, lets review some Actions and some SOQL queries…

Consider this Account Record detail page in the Classic (or Aloha) UI

PlatformActionAccount.png

Note down your record ID and use it in a query like the one below…

SELECT DeviceFormat, Label, Type, Section,
       ActionTarget, ActionTargetType, ActionListContext
  FROM PlatformAction
  WHERE ActionListContext = 'Record' AND
        SourceEntity = '001B000000D2V0n' AND
        Section = 'Page' AND
        DeviceFormat = 'Aloha'

In Developer Console you should see something like this…

PlatformActionQueryResults1.png

Pretty cool huh!? Check out the ActionTarget field, for the Standard Button records, thats the URL you can place on your UI’s to invoke that action, simple as that! Better still this is a supported way to get it, no more URL hacking! Now lets add a couple of Custom Buttons and re-run the query…

PlatformActionAcount2.png

We now see CustomButton records appear…

PlatformActionQueryResults2.png

This next query reveals actions shown on a List View. I did note Custom List View buttons that require record selection did not appear however. I suspect this is due to them requiring more than a simple HTTP GET URL to invoke.

SELECT DeviceFormat, Label, Type, Section,
       ActionTarget, ActionTargetType, ActionListContext
  FROM PlatformAction
  WHERE ActionListContext = 'ListView' AND
        SourceEntity = 'Account' AND
        Section = 'Page' AND
        DeviceFormat = 'Aloha'

Other observations..

  • Prior to Summer’16 (out in preview as i write this), Apex SOQL was not supported, only REST API SOQL. This is due to a limitation with the internally applied LIMIT keyword. This has now been resolved in Summer’16, so Apex SOQL now works!
  • SourceEntity can also be given an SObject API name, e.g. SourceEntity = ‘Account’, the result here are object level buttons, like New or those you add to the MRU page.
  • DeviceFormat field value matters, if you leave it off, it defaults to Phone. Thus some actions will be missing from those in Desktop (Lightning Experience) or Aloha (Classic). I eventually found Custom Buttons using Visualforce pages that didn’t have the Lightning Supported checkbox set didn’t appear when querying with the Phone device type for example.
  • User context matters, actions returned are user and configuration sensitive, meaning the record itself, record type and associated layout all contribute to the actions returned. Custom Buttons for example need to be on the relevant layout.
  • Label and Icon information, there are also fields that allow you to render appropriate labels and icons for the actions.
  • Related List actions, you can also retrieve actions shown on related lists, search for RelatedList in the help topic here.
  • Describe actions? You will notice some actions have an ActionTargetType of Describe? These are invoked via an API, something i will cover in later blog.

So lets discuss the “virtual SObject” bit!?!

Your probably wondering what a virtual SObject is?

Well my best guess is its an SObject that is not backed by physical data in the Salesforce database. If you check the documentation you’ll see fields just like any other object and it supports SOQL (with some limitations). My thinking is the records for this object are dynamically generated on demand by doing all the heavy lifting internally to scan all the various historic places where actions have been defined.

Thank you Salesforce architects, this is now my #1 coolest Salesforce API!

Whats next?

  • For starters, no more URL hacking of those standard pages, no excuses now!
  • Helper class or Visualforce and/or Lighting component for actions?
  • Explore the Force.com Actions Developer Guide

16 thoughts on “Introduction to the Platform Action API

  1. @Andrew Fawcett: this is pretty cool stuff.
    Have you managed to use one of the ActionTargets to open the target page directly in Lightning?

    Using that URL in context or without context of a record always gives me a “This page isn’t available in Salesforce Lightning Experience or Salesforce1.”

  2. Can you pre-populate lookup fields?

  3. Pingback: Winter’17: Using a Lightning Component from an Action | Andy in the Cloud

  4. I agree this is an amazing API. I am trying to figure out how describe actions could be invoked from within a lightning component. At the moment I got the impression I need to make a callout in the apex controller of the component. Basically I want to query for available Actions and put a button for each in the component. Clicking a button should fire the specific action.

    • Yes, for some actions there is no clear invoke API, I have raised this to Salesforce myself. For URL actions just apply the URL behind your button.

  5. I noticed that this API does not return actions that point to Standard SalesForce.com Page. I am trying to invoke the Account Hierarchy quick action now available in Spring’17 from a lightning component but so far no luck. I was hoping this will help but record for it is not returned in SOQL.

    • Have you got the DeviceFormat field in your query? What does your query look like? Also have you got the latest API version set in your rest API URL or Apex class metadata?

      • Here is the query. Yes I’m using latest API Version.

        SELECT DeviceFormat, Label, Type, Section,
        ActionTarget, ActionListContext
        FROM PlatformAction
        WHERE ActionListContext = ‘Record’ AND
        SourceEntity = and DeviceFormat=’Desktop’

      • You need to include the record Id’s in the Where clause also. Because the API needs to determine record types and thus layouts and thus the appropriate buttons.

      • I have “SourceEntity” in the where clause. Here it is below with the id.

        SELECT DeviceFormat, Label, Type, Section, ActionTarget, ActionListContext FROM PlatformAction WHERE ActionListContext = ‘Record’ AND SourceEntity = ‘0013300001gQDQQAA4′ AND DeviceFormat=’Desktop’

      • This looks good to me, it can only be a missing feature of this API. If you have case access it’s worth raising one to confirm.

      • Thanks Andrew! I will open a case with SalesForce.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s