I had some great conversations with customers and partners at Connections this year, as well as through the MC Account Engagement Trailblazer Community, regarding Account Engagement External Actions. One question kept coming up: “How do I get started with External Actions?” In this post, you will learn what External Actions are, how to set them up, and how to test them. Additionally, tune in to an upcoming codeLive session on July 20 at 10 a.m. PT, where I’ll be holding a live coding demonstration to show you how to create an external action and answer your questions.

What are External Actions?

External Actions is a key part of Marketing App Extensions, providing a way to trigger an action in an external system. The other component is External Activities, which provides a way to trigger Account Engagement automation based on an engagement event happening in an external system. Think of it as two sides of a coin, actions trigger out, activities trigger in. Combined, they make up an automation extensibility app for a service, so you may have an SMS marketing app extension for example.

Diagram showing External Activities going into Account Engagement and Actions going out.

For this reason, external actions are packaged in a marketing app extension. At the time of writing, External activities can not be packaged yet, but will eventually be packaged in the marketing app extension as well.

If you want to connect a third-party app to automate running a prospect action in that system, then this is definitely the feature for you. In this post, we’ll be going deep into the External Action side of Marketing App Extensions.

What are some good use cases for External Actions?

Well, if you ask me, I would say absolutely everything! You may be thinking, “Sure, everyone says that!” Yet, the possibilities that External Actions unlock are truly expansive. If you have ever said, “I wish that when a prospect gets to this step, I could <insert wish here>,” then you wanted an external action.

You can use an external action to register for a Zoom webinar from Account Engagement (see example in GitHub). You can also use an external action to send an SMS message via Twilio, which we featured in a previous blog post. You can even use external actions with webhooks; I used Zapier’s webhook catch feature to create an external action that used a prospect as a trigger for a Zap.

What makes up an external action?

An external action consists of an Apex Invocable Action, Marketing App Extension metadata, External Action metadata, and a way to handle authentication. The metadata for marketing app extensions and external activities connect the invocable action to account engagement. The components to use for authentication can vary depending on what type of authentication the service supports. As OAUTH 2.0 is rather common, the component that I find myself using the most is an authorization provider and Named Credentials. Named credentials also make it easy to manage authentication in my code, with the system doing most of the work.

Structure of the marketing app extension

What skills do I need to work with External Actions?

With great flexibility comes complexity, so you will need some skills in certain areas to successfully build an external action. The following are key topics that you’ll need a basic understanding of before tackling your own external action.

Salesforce SLDC

Understanding the lifecycle of Salesforce development is very important to be successful in general. I recommend learning Visual Studio and the CLI deployment process. Mastery is not needed, just the basics to be able to get started. Trailhead offers a trail to help you set up your workspace.

REST API documentation

The pattern we talk about in this article is based on REST JSON APIs. To understand what is possible, and to gather the pertinent inputs for an external action, you need to be able to read an API specification. Check out the Account Engagement and Twilio API specifications.

Apex and Apex deployment

Apex Invocable Actions is my preferred way to code my external actions since it allows me the most flexibility and control. I would recommend, at a minimum, getting comfortable building and deploying Apex code using Trailhead’s Quick Start: Apex project. To learn more, I found the Apex Basics trailmix to be helpful. You do not need to become an expert, but you should at least be informed enough to be able to read the reference app code.

Salesforce Flow (optional)

You don’t need to know Salesforce Flow in order to learn External Actions. However, it is a very powerful testing tool for your external actions, making it easy to create a UI to control the inputs during your testing. If you are familiar with Engagement Studio, then Flow will be rather easy since it has a lot of the same concepts. I used the Build Flows with Flow Builder trail to get up to speed. Another benefit to learning Salesforce Flow is that it opens the door to building all kinds of business process automation.

How should I set up my developer environment?

It’s important to get your developer environments set up, and with the right tools, before you get started with External Actions. I use the following tools.

  • Postman — I use Postman to explore a new API, so I can learn how to simply make a request and respond. Postman also provides an easy way to generate examples.
  • Visual Studio + Salesforce CLI — I use Visual Studio to code my invocable action and deploy it to my developer org. The majority of the time, it is really just copying and pasting a previous example and editing it for my new use case.
  • Developer / Sandbox Environment — This is a safe environment to build, develop, and package your external actions. Please note that at the time of writing, we only support first-generation packaging (1GP), so don’t set up your developer org as a Dev Hub.
  • Salesforce Flow — I personally like to use ScreenFlows for testing an invocable action. It’s nice to be able to fully control the input before plugging it into external actions and ES programs.
  • Salesforce Developer Console — This allows you to quickly view the code or view logs from your Screen Flow tests.

Basic pattern for REST API calls with External Actions

While you can code external actions in many ways, there is a basic pattern that I recommend when making REST API calls.

The two tags you need to remember are InvocableVariable, which define the inputs and outputs of the invocable action, and InvocableMethod, which is the method to call when executing the invocable action. You can see how they are applied in the below code example.

I typically create two classes, one for the input and one for the API request. Separating my code into two classes makes it easy to jsonify the payload. My input class contains all the invocable variable fields that the invocable action needs on input. My API request contains the fields in the JSON request.

The InvocableMethod will construct the payload from the input, convert it to JSON, and then add it to the HTTP request. Next, you configure the rest of the HTTP request adding the URL, headers, and method. Finally, you make the API call and check the result for success, or else generate a helpful error for diagnosing an issue.

Important consideration: The External Action framework expects an error to be returned if there is a failure versus catching the error and then returning success. If an error is returned, then it will be reported in the error table.

Testing your external actions

Every once in a while, while building an external action, you will encounter errors. The more you can test as you go, the easier it will be to figure out where the problem lies. This is why I recommend adding a testing step to test in Salesforce Flow before testing in Engagement Studio. It removes the external action configuration from the picture, so if you verify it here, but it doesn’t work in Engagement Studio, then you know that the issue lies with the external action configuration.

Testing helps you identify errors, but determining the root cause and fixing them is another thing. Below are some of the techniques that I use to diagnose root causes.

  • Salesforce Developer Console — I use the dev console to run my test cases and confirm my code coverage. During exploratory testing in Flow, I keep my dev console open, so it generates logs to use in investigating errors.
  • Salesforce Log Traces – If the error happens during my Engagement Studio testing, then I put a user trace on the B2BMA Integration User, so I can see my Apex logs and diagnose the issue further. Be warned, you could end up with a lot of data. The B2BMA Integration User is the user who executes external actions.
  • Account Engagement External Action Errors — The table provides any error returned by the external action that resulted in a failure. It’s helpful to see what happened during an ES run.

TIP: If you have a Gmail account, you can use a “+” to create multiple records with your email address. For example, I can register both “example@example.com” and “example+user2@example.com” as a prospect, and any mail sent to those addresses would go to example@example.com’s mailbox. For example, I used this for testing the Zoom registration example since I didn’t want the registered email to bounce.

Common mistakes

Mistakes are going to happen, it is just life. I’ve run into a few scenarios that have caused me to almost pull my hair out.

The first one is ensuring that the external action is active. If the action is not appearing in Engagement Studio, then this is likely the cause. Remember, you have to activate both the marketing app extension and external action, plus assign it to that business unit.

The next one is to make sure your Apex class is active. The majority of the time it will already be marked as active, it is the default status when you make a new class. Which is exactly why it is easy to overlook.

Another one is to look for is marketing app extensions when packaging. I can’t tell you how many times I look for external actions, only to have a moment of confusion before I remember.

Finally, if your external action is not working, but you don’t see errors, then check that the invocable action was designed to generate an error upon failure.

The above is by no means comprehensive, and you will likely find your own joys. However, I recommend sharing them with the community if you come across some good ones.

What are you waiting for? Get started today!

Now you know pretty much everything I do about External Actions, from how the feature works to common mistakes. Remember that External Actions is your tool whenever you find yourself saying, “I would like to do something when the prospect does this,” and it will help you automate that action.

So, go get your developer environment set up, review the reference app, and start building your external action today. On July 20 at 10 a.m. PT, we’ll be doing a codeLive session on our Salesforce Developers YouTube Channel, so please join and follow along as we build a Twilio marketing app extension.

Resources

About the author

Christopher Cornett is Sr. Product Manager at Salesforce, responsible for Account Engagement’s developer experience. He has worked for Salesforce for over four years, and he has over 13 years of experience in product management, primarily working on platforms ranging from big data attribution to fraud. Christopher has helped to deliver API V5 and Marketing App Extensions, helping customers to build custom integrations to make their marketing stack work for them. He is passionate about developer experience and loves to play with all the great features to see what is possible.

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS