Configure and run a workflow with the External API activity

Adobe Campaign Standard lets you call an external REST API endpoint via an activity called external API. The purpose of this activity is to get personalization data into your campaign from a third party system that supports a REST API. So that the information you need can be brought in just as you need it. Think of this feature in terms of general data you can bring into your campaign, such as the latest offers, the latest restaurant menu or the latest weather forecast. We’ll use a simple use case to demonstrate how this functionality can be used. My use case is sending out an email to all of the profiles that have a birthday today. And this email will be personalized with a specific coupon code. The coupon code is actually coming from a third party API that I will be calling. This third party API accepts as input a list of zip codes and will provide a specific coupon for each of the zip codes provided.

So in order to start building this use case, I will start with the query activity.

Within the query activity we have some simple conditions, such as birthdays today, and zip code is not empty.

From there, the flow will divide into two paths with the upper path allowing us to generate coupon codes. Because you can have multiple zip codes that are exactly the same, I will also need to run a very simple activity to duplicate all the zip codes, so that the input list of zip codes that I get is unique.

Finally, moving onto the main activity of this workflow, which is the external API activity, I’m going to navigate to the execution tab. Here is the actual URL that I will be calling. This is your third party API URL that actually offers the service. You can authorize via key value pairs, and you can also add new headers, again in the form of key values if needed.

In terms of inbound mapping, these are the parameters that are going to be sent to my third party service. The inbound resource is actually my query activity. And from that table, I will be sending the zip code because that is what my service needs. I will also add the count parameter as that is very useful for some services. And I will also use a static field that could be used by the API endpoint. In this case to restrict this to just the California zip codes. You can see down below how the post body template looks like for my HTTP call.

For the outbound mapping, I’m going to use a sample response from my API. You’ll notice that the flattened check box is not checked. This check box is unchecked by default. It signals to the activity to expect a data array in the response, like the one I’ve highlighted. You’ll also notice that there are several non-array JSON elements in the response. These will all be ignored. We’ll show a case further on where the flattened checkbox is checked.

After we hit parse, we can navigate over to our columns definition tab to make sure our columns are set correctly.

So this is going to be my output table that I’m going to use further down the line. Finally, I will use an outbound transition if the request has failed. This transition terminates; however, it could be modified to perform an action upon receiving a failure. If the call is successful, I’m going to use an enrichment activity to join the coupons I received to the profiles from the initial query in the second branch of the fork. You’ll notice that I have a second external API activity here. We are going to use this one to grab top-level information about the offer that is the same across all coupons. Go ahead and open this activity, and we’ll navigate to the execution tab. You’ll notice that it is identical to the execution tab of the previous external API activity. If we go to inbound mapping tab, there’s no information here because we don’t need to generate additional coupon codes. For the outbound mapping, we’ll expand the window. And as before, we’ll paste in our sample response; however, this time we are going to select flatten up top.

This option essentially flattens the JSON into a single row of values, which is helpful to capture JSON elements that aren’t returned in a data array. I can also clean this JSON up in the window to capture the information I want in the JSON. So here it doesn’t really make sense to capture the coupon codes again, so we can get rid of those.

Also we don’t really need the timestamp value, so we can remove that as well. We’ll hit parse.

We’ll go to our column definitions tab to ensure that those columns are correct.

If that runs successfully, we’ll enrich the profiles with that top level data.

Finally, we’ll want to personalize our email with the information from the JSON responses. We’ll click on our content editor.

We can see that in this email, we’re inserting various elements. First name, coupon code, or even taking the offer title and for the subject of our email, the offer tagline.

Go ahead and close that.

Finally let’s execute the activity to see how this works.

As you can see, my activity’s executed successfully.

I’ll go ahead and navigate to one of the emails that was sent so we can see a final copy.

Here we’ll go to the sending logs and pull up one of those emails.

And here in the mirror page, you can see that it was personalized with the first name, with a coupon code, a description of the offer, even a redemption deadline, an offer ID. Several pieces of information to personalize this from our JSON.

As a few closing notes, the external API activity is not meant for heavy lifting of data. It is meant really to be used for very specific information that you need right as you’re executing the campaign. If large amounts of data are needed, we recommend that other data management activities such as file transfer are used, thank you. -