Integration Guide for Next Best Action
In this guide, we’ll walk you through all the different ways that you can connect to sources of insight from Next Best Action to generate and enhance recommendations and to pull in relevant properties for decision making. Note – the Generate and Enhance elements are new updates, shipping with the Summer ’19 Release.
There are 3 main integration points, all of which require Apex invocable actions:
- Generate
- Enhance
- External connections
The Generate element enables you to create new in-memory, on-the-fly recommendations, either from an external data source or from other Salesforce objects.
The Enhance element enables you to modify a given set of recommendations to include real-time updates, personalized information, or AI driven prediction scores.
And finally you can create an external connection to fetch properties in JSON format from external services. For example, you can connect to a Heroku endpoint to obtain a credit score for a given customer.
Let’s dive deeper into each one. You can install the strategies and invocable actions used in the examples by installing this package in your org. Note – your org must be using the Summer ’19 (or later) release.
Generate
Instead of defining recommendations manually as records in Salesforce, you can use the Generate element to dynamically create temporary, in-memory recommendations as a part of the current strategy execution. These dynamic recommendations can be sourced from external data sources like Commerce Cloud or a SQL database or from other Salesforce objects like Accounts or Products.
For example, you can build a dashboard of prioritized accounts to connect with.
Or create recommendations sourced from the Products object.
The Generate element has the following characteristics:
- It requires an Apex Action marked as Invocable Method.
@InvocableMethod( label='Related Wikipedia Pages' description='Recommend wikipages that are related to the named input wikipage')
- It can pass any number of inputs to the Apex Action, either as lists or list of lists of primitives, SObjects, and user-defined Apex objects. To provide more than one input, the input parameter MUST be a list or list of lists of a user-defined Apex object (e.g. a custom class called DataContainer).
List<String> relatedTo
OR
global class DataContainer {
@InvocableVariable
public string accountId;
}
____
global static List<List<Recommendation>> invocableMethod(List<DataContainer> inputData)
- It returns a list of recommendations. InvocableMethods support returning either a list of an SObject type or a list of lists of an SObject type. As the Enhance element operates on a list of recommendations and not a single recommendation, the method must return a List<List<Recommendation>>.
global static List<List<Recommendation>> invocableMethod(List<DataContainer> inputData)
Example: Recommend accounts the current user should follow up on today
Suppose you want to recommend the top accounts your salespeople should meet with today because the last interaction was more than 90 days ago. With the Generate element, you can call an Apex Action which does a SOQL query for Accounts where the Owner is the logged in user (the salesperson) and identify those accounts where the last contact date was more than 90 days ago. The relevant accounts can be returned in the form of recommendations.
The strategy can be as simple as the Generate element with an Output element.
In the configuration dialog of the Generate element, select Accounts to Follow Up Today as the Apex Action and pass in ‘$User.id’ as an input parameter.
The Generate element, in turn, will call the getAccounts invocable method in the Generate_GetAccountsToFollowUp Apex class. Notice how you can fetch the relevant accounts and create a new list of recommendations where the Description includes the name of the account (account.Name) and the number of days since last contact (daysSinceLastContact).
global class Generate_GetAccountsToFollowUp {
//NOTE: You can get the user id of the current user by also doing UserInfo.getUserId().
@InvocableMethod(label='Accounts to Follow Up Today'
description='Recommend accounts the current user should follow up on today')
global static List<List<Recommendation>> getAccounts(List<String> inputData){
List<List<Recommendation>> outputs = new List<List<Recommendation>>();
Integer daysSinceLastContact;
Account[] accounts = [SELECT Name, Description, LastContactDate__c, OwnerId FROM Account WHERE OwnerId = :inputData[0]];
List<Recommendation> recs = new List<Recommendation>();
for (Account account:accounts) {
if (account.LastContactDate__c != null){
daysSinceLastContact = account.LastContactDate__c.daysBetween(date.today());
if (daysSinceLastContact > 90){
Recommendation rec = new Recommendation(
Name = account.Name,
Description = 'Connect with the ' + account.Name + ' account, the last interaction was '+ daysSinceLastContact + ' days ago.',
//Pre-req: Create a screen flow with the name simpleFlow
ActionReference = 'simpleFlow',
AcceptanceLabel = 'View'
);
recs.add(rec);
}
}
}
outputs.add(recs);
return outputs;
}
}
Example: Get related Wikipedia pages as recommendations
You can also use the Generate node to create recommendations for external data sources. For example, consider a scenario where you want to show related Wikipedia pages, as recommendations, for a given topic. The Generate element enables you to call an Apex Action which in turn makes a GET request to a Wikipedia endpoint. The pages are returned in the form of recommendations.
A strategy with the Generate element can be as simple as the Generate element with an Output element.
In the configuration dialog of the Generate element, select Related Wikipedia Pages as the Apex Action and pass in ‘India’ as an input parameter.
The Generate element will call the getPages invocable method in the Generate_GetWikiPages Apex class. Notice how there is a mapping of Wikipedia articles to recommendation fields.
//Guidance around Apex class definitions: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_defining.htm
global class Generate_GetWikiPages {
//InvocableMethod Guidance: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_annotation_InvocableMethod.htm
//Input parameter must be a list or list of lists of either primitive type or Object type
@InvocableMethod(
label='Related Wikipedia Pages'
description='Recommend wikipages that are related to the named input wikipage')
global static List<List<Recommendation>> getPages(List<String> relatedTo){
List<List<Recommendation>> outputs = new List<List<Recommendation>>();
Http http = new Http();
HttpRequest request = new HttpRequest();
String urlName = relatedTo[0].replace(' ','_');
// Pre-req: Set up a Remote Site Setting for this to work.
request.setEndpoint('https://en.wikipedia.org/api/rest_v1/page/related/'+urlName);
request.setMethod('GET');
HttpResponse response = http.send(request);
if(response.getStatusCode() == 200) {
Map<String, Object> result = (Map<String, Object>)
JSON.deserializeUntyped(response.getBody());
List<Recommendation> recs = new List<Recommendation>();
for(Object item : (List<Object>)result.get('pages')) {
Map<String, Object> page = (Map<String, Object>) item;
Recommendation rec = new Recommendation(
Name = (String)page.get('displaytitle'),
Description = (String)page.get('extract'),
//Pre-req: Create a screen flow with the name simpleFlow
ActionReference = 'simpleFlow',
AcceptanceLabel = 'View'
);
recs.add(rec);
}
outputs.add(recs);
}
return outputs;
}
}
Enhance
The Enhance element allows you to modify a given set of recommendations on-the-fly, every time the strategy is executed. These recommendations could be static recommendations that live as records in Salesforce or dynamic recommendations sourced from external data sources or other Salesforce objects. For example, you can use the enhance element to calculate a discount % for your customers based on how long the account has been with your company or you can use it as a means for A-B testing two branches of recommendations.
The Enhance element has the following characteristics:
- It requires an Apex Action marked as Invocable Method.
@InvocableMethod( label='Enhance with Discounts Based on Age' description='Returns an enhanced set of recommendations with appropriate discounts')
- IMPORTANT – It can pass any number of inputs to the Apex Action. The input parameter MUST be a list or list of lists of a user-defined Apex object (e.g. a custom class called DataContainer) and the user-defined Apex object MUST include a List<Recommendation> variable. The List<Recommendation> variable will be automatically set with the recommendations flowing into the Enhance element.
global class DataContainer {
@InvocableVariable
public string accountId;
@InvocableVariable
public List<Recommendation> recommendations;
}
________
global static List<List<Recommendation>> invocableMethod(List<DataContainer> inputData)
- It returns a list of recommendations, List<List<Recommendation>>. Note – these recommendation edits are only in-memory and are not persisted after the strategy execution.
global static List<List<Recommendation>> invocableMethod(List<DataContainer> inputData)
Example: Enhance Recommendations with Discounts Based on Customer Age
Suppose you use Next Best Action to provide upsell recommendations. You’d like to reward your loyal customers by adding a 5 % discount to your product recommendations if the customer has been with your company for more than 1 year, 10% for more than 2 years, and 20% for more than 5 years. With the Enhance element, you can call an Apex Action which does a SOQL query to fetch the Account age and append it to the description of all incoming recommendations.
The strategy with the Enhance element can be as simple as Load → Enhance → Output. All recommendations retrieved or loaded by the Load element are implicitly passed as a list of recommendations to the underlying invocable method.
In the configuration dialog of the Enhance element, select Enhance with Discounts Based on Age as the Apex Action and pass in ‘$Record.id’ as the input parameter.
The Enhance element will in turn call the getDiscounts invocable method in the Enhance_GetAccountDiscount class. Notice how Description of each recommendation has a discount value appended to it (r.Description + ‘ with a 5% discount’).
global class Enhance_GetAccountDiscount {
@InvocableMethod(label='Enhance with Discounts Based on Age' description='Returns an enhanced set of recommendations with appropriate discounts')
global static List<List<Recommendation>> getDiscounts(List<DataContainer> inputData){
List<Recommendation> recommendations = inputData[0].recommendations;
List<List<Recommendation>> outputs = new List<List<Recommendation>>();
Account[] accounts = [SELECT Name, Description,CreatedDate, id FROM Account WHERE id = :inputData[0].accountId];
Double ageAccountMonths = accounts[0].CreatedDate.date().monthsBetween(date.today());
Double ageAccount = ageAccountMonths/12;
List<Recommendation> returnedRecommendations = new List<Recommendation>();
for (Recommendation r:recommendations){
if(ageAccount > 1){
r.Description = r.Description + ' with a 5% discount';
}
else if (ageAccount > 2){
r.Description = r.Description + ' with a 10% discount';
}
else if (ageAccount > 5){
r.Description = r.Description + ' with a 20% discount';
}
returnedRecommendations.add(r);
}
outputs.add(returnedRecommendations);
return outputs;
}
}
External Connections
External Connections have the following characteristics:
- Like Enhance and Generate elements, they work in tandem with an Apex Action created using by adding the Invocable Action annotation to an Apex Class.
- Unlike Enhance, External Connections do not take a set of recommendations as inputs. They return a single set of properties that can be referenced in expressions but not mapped to recommendations. Unlike Generate, External Connections do not result in the creation of new, temporary recommendations.
- They run before the strategy is processed, and not during the processing of the strategy.
- Their values are globally accessible (i.e you can use them in every element of the strategy).
- They can return a broad range of different properties (Generate and Enhance always return a List of Recommendations).
Example: Calling a Heroku endpoint to fetch a credit score
Let’s suppose that you make certain upsell offers to your customers based on their credit-worthiness. For example, you offer them a 0% refinancing only if their credit score is above 750. Credit scores aren’t typically something you would store in Salesforce because they change dynamically and frequently. Using an external connection, you can call an Apex Action which will call an external endpoint and return the credit score given some information about the user.
global with sharing class GetFranchiseeData {
@InvocableMethod
public static List<Results> getCreditScore(List<Requests> requests)
{
Http http = new Http();
HttpRequest request = new HttpRequest();
//Make sure you add the below endpoint as a remote site setting
request.setEndpoint('https://repair-service.herokuapp.com/api/creditScore?customerId='+ requests[0].custId);
request.setMethod('GET');
HttpResponse response = http.send(request);
Results curResult = new Results();
curResult.creditScore = Integer.valueOf(response.getBody());
List<Results> resultsList = new List<results>();
resultsList.add(curResult);
return resultsList;
}
global class Requests {
@InvocableVariable
global String custId;
}
global class Results {
@InvocableVariable
global Integer creditScore;
}
}
To call the above Apex Action, create an external connection and pass the Account’s External ID (If you pass values less than 4000, the API will return 550. It will return 810 for values greater than or equal to 4000.)
You can filter the Zero % Refinancing Offer based on the Credit Score by referencing the connection in the Filter node.
