There may be cases where you want to use master data managed by external systems also 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 figure below shows the outline of the mechanism of what I am going to realize.

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

Whereas, in the App in which you want to use customer data retrieved from Salesforce as options, you specify the aforementioned “Options master” in the Choice setting 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 Options Master. The App I created as an example is as the following.

The following are the outline of it.

    1. At the Step of “Connect to API” which is a Throwing Message Intermediate Event (HTTP) connect to Salesforce APIs. Acquire customer data and store it in String type Data Item.
    2. At the Step of “Parse response” 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 Select type Data Items that have been composed at #2 is saved as an Options Master.

There are two human Tasks. The first Task is to Start the Process. And the one in the middle “Confirmation” 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 major setting of the App. The necessary Data Items are as follows.

Number 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 Salesforce Platform using a Throwing Message Intermediate Event (HTTP) and retrieve 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. By 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 Salesforce API from Questetra BPM Suite with OAuth 2.0, you need to make 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 as 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 of this setting.
Enable OAuth Settings Check
Callback URL https://*****.questetra.net/oauth2callback Copy the value described in the OAuth 2.0 setting 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 property screen of the Throwing Message Intermediate Event (HTTP), check on “Connect with OAuth 2.0” and click on the “Set up OAuth 2.0 from here.” button to open the OAuth 2.0 setting screen. Add a OAuth 2.0 setting in the 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 value of what is indicated as “Consumer key”.
Consumer Secret On the connection application screen of Salesforce Platform, copy the value of what is indicated as “Consumer Secret”.

After saving the setting, click on “Get Token” button to start the processing of acquiring OAuth 2.0 Token from Salesforce. If the settings are correct, the processing is completed 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 on API response

Using the Script Task, 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 of the Select type Data Item. The format of the API response is as the following.

{"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"
  },{
   ...
  }]
}

We compose this response as to be choices for the Select type Data Item of “Customer data”. Since the Data Item is configured to use the values of two String type Data Items as its options, so in the Script Task, a list of IDs and a list of customer names are to be stored respectively 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 is proper up until this point, the customer data acquired from Salesforce should be displayed as choices of Select type Data Item, “Customer data”, on the Task of “Confirmation” operating screen.

3. Saving to Options Master

In the end, we do setup the “Service Task (Choices update)” for saving data to the Options Master. Specify a select type Data Item we composed at #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 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.

At the last, I attach the App I created in this post. (*) Since the OAuth 2.0 setting is not included in the archive, you need to set this part properly. In addition, the API used in this post has an upper limit on the number 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 filename extension “.zip”. Please change the extension to “.qar” before using.

(Appendix) Display Salesforce Web Site upon Using Choices

Although, it incorporates only Ids and Customer names for the Options Master, there are 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 by describing HTML in a Guide panel type Data Item. It is designed that when you select a customer in the Select-box of Select type Data item and clicking the button, a page of Salesforce in which the relevant customer information is contained will be displayed.

I will explain with the example App. I omit 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 of 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 Select type Item and opens a page of 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 URL of Salesforce in the Javascript in #2;

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

appropriately according to the organization which uses Salesforce.

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 Salesforce API and copy it to the Data Item in Questetra BPM Suite. I will show it to you on another chance.