How to Use Customer Data in Salesforce as Options

There may be cases where you want to use master data managed by external systems in Questetra BPM Suite. In this post I am going to work on incorporating customer data managed in Salesforce into Questetra BPM Suite and using it as the options for a Select-box.

The diagram below shows the overview of the mechanism that I am going to realize.

First, retrieve the customer data in Salesforce via APIs. Then, import the data to Questetra BPM Suite as an “Options Master”, using the new function “Service Task (Choices update)” which has been added at version 9.9.0. I will implement these procedures in a single App.

In the App in which you want to use customer data retrieved from Salesforce as options, you specify the aforementioned Options Master in the settings of the Select-type Data Item.

In this post I will explain the first half of the process mentioned above, which is how to create an App that retrieves customer data in Salesforce as the Options Master. The App I created as an example is as follows.

Here is the general outline.

1. 1. At the “API connect” Step, which is a Throwing Message Intermediate Event (HTTP), connect to the Salesforce APIs. Acquire customer data and store it in a String-type Data Item.
   2. At the “Response parsing” Step, which is a Script Task, it parses the response text (JSON) acquired at #1 and puts it in a state which can be used as a Select-type Data Item.
   3. At the “Master update”, which is a Service Task (Choices update), the data of choices for the Select-type Data Items that have been composed at #2 are saved as an Options Master.

There are two Human Tasks. The first Task is to Start the Process and the Confirm Task in the middle is a Step for checking the options data composed at #2. The Gateway (split) is for aborting subsequent processing if there was an error in accessing the Salesforce API.

I will explain the main settings of the App. The necessary Data Items are as follows.

Number	Data Item Name	Data-type	Description
0	Normal response	String-type multiple lines	Response when acquiring customer data from Salesforce Platform
1	Error	String-type multiple lines	Error contents if an error occurred when acquiring customer data from Salesforce Platform
2	Customer ID list	String-type multiple lines	A string storing the customer IDs list as a result of parsing the JSON response
3	Customer name list	String-type multiple lines	A string storing the customer names list as a result of parsing the JSON response
4	Customer data	Select-type Radio button	Data Item to be used in Service Task (Choices update)

1-1. Retrieving customer data from Salesforce Platform

Call the API of the Salesforce Platform using a Throwing Message Intermediate Event (HTTP) and retrieve the customer data. The API we use is the Lightning Platform REST API Query.

Configuration name	Value	Description
Access URL	https://na10.salesforce.com/services/data/v29.0/query/
HTTP Method	GET
String-type data item that will contain error details when an error occurred	Error	Specify the String-type Data Item multiple lines of Number 1.
Security
	Connect with OAuth 2.0
Setting name	Force.com	It can be any value but must match the OAuth 2.0 Configuration name. The details of OAuth 2.0 setting will be described later.
Response
Save the response	Check
Data item to save the response	Normal response	Specify the String-type data items multiple lines of Number 0.

The Send parameters are as follows.

Parameter name	Value	Description
q	SELECT Id, Name from Account

In this API a query referred to as SOQL (Salesforce Object Query Language), which is similar to SQL, is executed and the resulting object is acquired. With the query referred to as “SELECT Id, Name From Account”, the ID attribute and the Name attribute are acquired from the Account object. The Account object is a standard object of Salesforce that represents customer data. In the Object Reference you can see what kind of objects there are.

1-2. Setting up OAuth 2.0 in Salesforce

In order to connect to the Salesforce API from Questetra BPM Suite with OAuth 2.0 you need to configure the settings on the Salesforce side. Create a new “Connected App” at “App” < “Create” < “App Setup”. The contents of the settings are described below. Although there are many setting items in Salesforce, you can leave items not included in the information on the list below blank.

Configuration name	Value	Description
Connected App Name	Questetra BPM Suite	It can be any value
API Name	QBPMS	Any value can be set, but white spaces and symbols cannot be used.
Contact Email		Set the email address of the person responsible for this setting.
Enable OAuth Settings	Check
Callback URL	https://*****.questetra.net/oauth2callback	Copy the value described in the OAuth 2.0 settings of Questetra BPM Suite and paste it.
Selected OAuth Scopes	Access and manage your data (API), Perform requests on your behalf at any time (refresh_token, offline_access)	Add these two to Selected OAuth Scopes

1-3. Setting up OAuth 2.0 in Questetra BPM Suite

In the Security tab on the properties screen of the Throwing Message Intermediate Event (HTTP), check the “Connect with OAuth 2.0” box and click on the “Set up OAuth 2.0 from here” button to open the OAuth 2.0 setting screen. Add the OAuth 2.0 settings in this screen.

Configuration name	Value	Description
Name	Force.com	It must be the same as the Configuration name specified in the Throwing Message Intermediate Event (HTTP).
Authorization Code Request URL	https://login.salesforce.com/services/oauth2/authorize
Access Token Request URL	https://login.salesforce.com/services/oauth2/token
Scope		You can leave it empty.
Client ID		On the connection application screen of Salesforce Platform copy the Consumer key value.
Consumer Secret		On the connection application screen of Salesforce Platform copy the Consumer secret value.

After saving the settings click on the “Get Token” button to start the process of acquiring the OAuth 2.0 Token from Salesforce. If the settings are correct the processing will complete through the screen as shown below, which is asking whether to allow Questetra BPM Suite to connect to Salesforce. If a Token has been acquired successfully, a circle mark is indicated in the column “Have a Token?”

2. Parsing API responses

Using the Script Task to parse the JSON text which is the response from the API, parse the JSON text and temporarily put it in a state which can be used as choices for the Select-type Data Item. The format of the API response is as follows.

{"totalSize":16,
 "done":true,
 "records":[
  {
   "attributes":{
    "type":"Account",
    "url":"/services/data/v29.0/sobjects/Account/001A0000002wEMkIAM"
   },
   "Id":"001A0000002wEMkIAM",
   "Name":"United Oil & Gas, UK"
  },{
   "attributes":{
    "type":"Account",
    "url":"/services/data/v29.0/sobjects/Account/001A0000002wEMlIAM"
   },
   "Id":"001A0000002wEMlIAM",
   "Name":"United Oil & Gas, Singapore"
  },{
   ...
  }]
}

This response is configured to use the values of the two String-type Data Items as choices for the Select-type Data Item “Customer Data”, so the Script Task should store a list of IDs and a list of customer names in these two String-type Data Items.

Configuration name	Value	Description
	Specify options by String-type Data Item
Choice ID	Customer ID list	Specify the String-type Data Item which stores Customer ID list by the Script Task
Label	Customer name list	Specify the String-type Data Item which stores Customer name list by the Script Task

The following is the code included in the Script Task.

var text = engine.findDataByNumber("0");
var result = JSON.parse(text); // Parsing JSON

var ids = "";
var labels = "";
for (var i = 0; i < result.records.length; i++) {
  var account = result.records[i];
  ids += account.Id + "\n"; // Acquire ID
  labels += account.Name + "\n"; // Acquire Name
}
 
engine.setDataByNumber("2", ids);
engine.setDataByNumber("3", labels);

If everything has worked correctly until this point the customer data acquired from Salesforce should be displayed as the choices of the Select-type Data Item “Customer data” on the Confirm Task operating screen.

3. Saving to Options Master

In the end, we do set up the Service Task (Choices update) for saving data to the Options Master. Specify the Select-type Data Item we created in #2.

Configuration name	Value	Description
User who updates Options (must be System Administrator)	(You)	Only the user who is editing this App (that is you) can change it. If you do not have System Administration authority, ask someone who has the necessary authorization to set it up.
Select-type Data Item whose choices will be saved as “App-shared add-on”	Customer data
Name when saving as App-shared add-on	Customer Master	Any value can be used.

Executing a Process on this App, the customer data in the Salesforce Platform will be saved as an Options master. You can confirm the saved Options master at the App-shared add-on function in the App menu on the left.

Finally, I attach the App I created in this post. (*) Since the OAuth 2.0 settings are not included in the archive, you need to configure this. In addition, the API used in this post has an upper limit on the amount of data that can be acquired. It is possible to acquire the rest of the data even if the upper limit is exceeded, but this App does not support that.
(*) The file will be downloaded with the .zip filename extension. Please change the extension to .qar before using it.

(Appendix) Display Salesforce Web Site upon Using Choices

Although it incorporates only IDs and Customer names for the Options Master, there is lots more data stored in Salesforce. Therefore, there may be cases where you would like to check other data when selecting a customer on the Operating screen. So let’s place a button to display the Salesforce customer data page when clicked, so that you will be able to check other data.

There, a Select-type Data Item and a Browse button are placed side by side. That Browse button has been placed to describe the HTML in a Guide panel-type Data Item. It is designed that when you select a customer in the select box of a Select-type Data Item and click the button, a Salesforce page in which the relevant customer information is contained will be displayed.

I will explain with the example App. I have omitted its Process diagram since it has only one Task.

1. Select-type Data Item

Add a Select-type Data Item – Select Box.
You may do the same thing with a Radio Button or Search Select Box, but the contents of the following Guide Panel setting will be different. So please specify Select Box.

Configuration name	Value	Description
	Options Master (App-shared Add-on)
Filename	Customer Master	Specify the filename of the Options Master in which customer data from Salesforce is stored.

2. Browse button

The Browse button is configured with Guide Panel-type Data Item. Specify the following HTML in the Description section of the Data Item.

<br>
<button onclick="jumpToSalesforce();" type="button">Browse</button>

<script type="text/javascript">
function jumpToSalesforce() {
  var id = jQuery("select[name='data[0].selects']").val(); // Retrieve the value of Select type

  if (id == '') return;

  window.open('https://****.salesforce.com/' + id); // Open Salesforce page
}
</script>

The Javascript which defines the function “jumpToSalesforce()” is the point. With that, it retrieves the value of the Select-type Item and opens a page in Salesforce. This is possible because Salesforce is designed so that the relevant data can be referenced with the URL

https://****.salesforce.com/(ID)

Naturally, if you do not have an account in Salesforce, you can not see the data.

Here, I have attached the example App. Please change the part “****” in the Salesforce URL in the Javascript in #2 appropriately according to the Organization which is using Salesforce.

https://****.salesforce.com/(ID)

I introduced a tiny tip for using Salesforce’s customer data as options. As long as you know the ID of the data, you can also retrieve data other than the customer name via the Salesforce API and copy it to a Data Item in Questetra BPM Suite. I will show it to you another time.