Hi Questetra users! I’m Hatanaka, Questetra’s CTO.

This post is a continuation of the blog post below.

In that post I changed the Throwing Message intermediate Event (HTTP), which is for making the request to Twilio‘s API, into a Script Task.

With Questetra BPM Suite you can extract the processing that is done in a Script Task as a unique automated Step. In the previous blog post I made the processing part for SMS transmission using Twilio’s API into a Script Task. I would like to remake that part into a unique auto-step. The auto-step that we will create can be reused in other Workflow Apps.

M416: Create your own Auto-Step for Business Process Definition

The Workflow diagram will eventually be changed to the following. It will be substituted with a unique auto-step.

To start with, I would like to consider the config items of the auto-step. If the SMS destination and message body can be changed depending on the settings, it will be convenient. I would like to aim for the settings screen to be as follows.

The config items are:

  • C1. ACCOUNT SID
  • C2. AUTH TOKEN
  • C3. From Telephone Number
  • I1. To Telephone Number
  • I2. SMS body

Although there is also a config item “Token will move to Error Boundary Event when processing fails”, it is configured as a standard so you can’t control it.

The definition file for realizing this auto-step is as follows.

<?xml version="1.0" encoding="UTF-8"?>
<service-task-definition>
<engine-type>2</engine-type>
<last-modified>2018-07-24</last-modified>
<label>Sending SMS by Twilio</label>
<label locale="ja">SMS 送信 by Twilio</label>
<configs>
<config name="AccountSid" required="true">
<label>C1. ACCOUNT SID</label>
<label locale="ja">C1. アカウント SID</label>
</config>
<config name="AuthToken" required="true">
<label>C2. AUTH TOKEN</label>
</config>
<config name="From" required="true">
<label>C3. From Telephone Number (You got at Twilio) ex. +180XXXXXXXX</label>
<label locale="ja">C3. 送信用の電話番号 ex. +180XXXXXXXX</label>
</config>
<config name="To" form-type="SELECT" select-data-type="STRING_TEXTFIELD" required="true">
<label>I1. To Telephone Number (Data: Singlie-line String)</label>
<label locale="ja">I1. 送信先の電話番号 (指定: 単一行文字型データ)</label>
</config>
<config name="Message" form-type="SELECT" select-data-type="STRING" required="true">
<label>I2. SMS body (Data: String)</label>
<label locale="ja">I2. SMS 本文 (指定: 文字型データ)</label>
</config>
</configs>
<script><![CDATA[
main();
function main(){
const accountSID = configs.get("AccountSid");
const authToken = configs.get("AuthToken");
const fromPhone = configs.get("From");
const apiUrl = 'https://api.twilio.com/2010-04-01/Accounts/&#39; + accountSID + '/Messages.json';
const toPhone = engine.findDataByNumber(configs.get("To"));
const message = engine.findDataByNumber(configs.get("Message"));
const apiRes = httpClient.begin()
.basic(accountSID, authToken)
.formParam('From', fromPhone)
.formParam('To', toPhone)
.formParam('Body', message)
.post(apiUrl);
const responseCode = apiRes.getStatusCode();
const responseBody = apiRes.getResponseAsString();
engine.log("response: " + responseCode);
engine.log(responseBody);
if (responseCode != 201) {
throw "response is not 201: " + responseCode;
}
}
]]></script>
<icon>iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAPHSURBVHhe7ZvdUdwwEMchBWQmlSR0EF7yDB1A
B6GS0EHoAJ7zAh2QdJJJA+S/vpVH1lnSfsnHDfxmbqTzSd7dv2R92L6Td944p5wO59/nbz+RXO2+
dbn7+OfXNeeHMkwABPwDyffdNze3EOSG86GEC4DAXzg7BAgR6nPYyUYHXhIlhPskWwde4hXCXBmB
f0HyvPt2cM4gxG/OqzAJcOhWr2HpDeoKrzX4hFYEVeGA4G/g4C3nV4ENmjppCjWjEUFc0Bq8pVvm
jLYrKmRxwht4ySgfugW0hqMDL4n25wOnq8AYTXViRgdPaG30YmgKAKTz/PUWwSfYlnSz1Iyh6rSi
q32CQ385vyncuqJGqjVQrwf0oJY/SPAEbNPqz7VtXlVF2vo1VRM4zz2SC3yeUPZ8OigEdR+RfMXn
AXUvp4MVPP6aBWgF36ovEM1U1+rz3oGRwSdq9Q9h2zsGLJA4QKyV89T1sBAAJ++uwVstoAG2aGyY
yPMeJL6VMZY9wHwPDyemAU9DXl5V12ArZxGj6hLoKBzSikKqtrQ9NHIMeOJ0C8JszQKgW9F9ezNQ
XjXPgztOiTzfxWBrQR5r3gN6Dy1C78sjiHkFl+eD6Pk6xyq+BOBk804OgTLS62+tBUWtKrEh8TUR
OQZMCBw8R5m9a5iPNUWQBK8lXACCHS3X7/S873Qt+AT9xnXLMeGSj4cznxQDQ3OFNcqBUUjjGdID
jolhAqAFLqgVso94mqWyRd1hi6whApDTSMrl6hUHQ3v8Veg3rltOyfd8PJxwAQSOPq6JwMfoJkiV
ESKIBYDx7kZJ4eBaoM3gExIbEl8TuQC95ajrcVUJnJzHhDwfRM/XOdZZAEwLruUoghC1YEZ+nUvf
HZow2FqQxxo5BlQHtwGE2VIJAOVb198Dp1tQtdXxcY9SAPEmogTdqnnreoW8vKquwVbOIsa95a1E
wbSMLNGoX57DUzdh8T1yDKg6VrJWzlPXw+rJPL2AaNXvBWCta/XZ3AN6jrKxNFhN29xWAImsXNo2
06OxZl1J8DW8J6WHo6r7edHAT1pDdBdSNQG9YwDt2lQvUUTCtl2ryKoArS5X8MytsCls0/VuANHr
AWec9pj275wfDtuStnwzhm4rawNT9BwT0f6InLW0brQQo3wQO2lxgPAKMdquyjmrMxnH+6psIkCE
oWh7nFoA4rWKYLncTAshNiSdIreA/jBhakxTpZxD9wZr4Am3AImthfAGnggTIDFaiKjAE+ECJCAE
TWXml64KjuePkzUgCK3dpZumzf46+87b5uTkP4D50skW/Mt0AAAAAElFTkSuQmCC</icon>
</service-task-definition>
view raw twilio_sms.xml hosted with ❤ by GitHub

Hereafter, I would like to explain each section separately.

1. The Unique Name of the Auto-step

The definition file must be in XML format. The content is enclosed with <service-task-definition>. Specify “2” in <engine-type.>, and the date of creation in <last-modified> in the format of YYYY-MM-DD.

<?xml version="1.0" encoding="UTF-8"?>
<service-task-definition>

  <engine-type>2</engine-type>
  <last-modified>2018-07-24</last-modified>

  <label>Sending SMS by Twilio</label>
  <label locale="ja">SMS 送信 by Twilio</label>
  ...
</service-task-definition>

The string in between <label> will be the unique name of the auto-step and it will be displayed as the title of the Config window. Since Questetra BPM Suite supports multiple languages, in the Japanese environment the contents of <label locale="ja"> will be displayed. Although there are other languages such as "en" "de" "es", in the case of the current setting "Sending SMS by Twilio" is displayed for other languages, unless the language setting of the platform is set to Japanese.

2. Config Items

Each item in between <config> in <configs> corresponds to each one of the config items in the config window. Using this setting the config items like in the above figure are displayed.

<configs>
  <config name="AccountSid" required="true">
    <label>C1. ACCOUNT SID</label>
    <label locale="ja">C1. アカウント SID</label>
  </config>
  <config name="AuthToken" required="true">
    <label>C2. AUTH TOKEN</label>
  </config>
  <config name="From" required="true">
    <label>C3. From Telephone Number (You got at Twilio) ex. +180XXXXXXXX</label>
    <label locale="ja">C3. 送信用の電話番号 ex. +180XXXXXXXX</label>
  </config>
  <config name="To" form-type="SELECT" select-data-type="STRING_TEXTFIELD" required="true">
    <label>I1. To Telephone Number (Data: Singlie-line String)</label>
    <label locale="ja">I1. 送信先の電話番号 (指定: 単一行文字型データ)</label>
  </config>
  <config name="Message" form-type="SELECT" select-data-type="STRING" required="true">
    <label>I2. SMS body (Data: String)</label>
    <label locale="ja">I2. SMS 本文 (指定: 文字型データ)</label>
  </config>
</configs>

<label> in <config> represents the label of the config item. It also supports multiple languages.

The name attribute is to specify the item name. This is used to retrieve the setting value from the script. I will explain it later.

The form-type attribute is to specify the input type of the config item. If not specified, it shows a text field. “SELECT” is an input type that lets the user select one of the Data Items in the Workflow App. With the select-data-type attribute, specify the type of the Data Item to be selected. When “STRING_TEXTFIELD” is specified the Data Items of String-type single line will be selected. And if it’s “STRING”, a String-type Data Item will be selected regardless of whether it’s single line or multiple lines. Thus, one String-type Data Item single line in the Workflow App is to be selected for “I1.To Telephone Number”.

The required attribute is to specify whether the config item is mandatory. On the editing screen of the Workflow App if a config item set to required="true" was blank it throws validation error, so those must be input for sure. In this auto-step all five setting items are mandatory, and none of them can be left empty.

With these settings, the config items like in the screen I mentioned previously will be displayed.

3. Script and Icon

The <script> tag is for describing processing that will be performed at the auto-step in a scripting language. In this case, I made it a structure in which a main() function is defined and the function is to be invoked. The <script> tag is always required in the definition file. The contents of the script will be explained in detail later.

The <icon> tag is to specify the small icon displayed at the lower right of the corresponding item icon on the workflow diagram. If not specified, the icon is not displayed. In the <icon> tag, text obtained by an image data encoded in base64 is specified. Only images smaller than 64 x 64 in JPEG/GIF/PNG are supported.

? <script><![CDATA[
main();

function main(){
  ...
}
]]></script>

<icon>iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
...
uePkzUgCK3dpZumzf46+87b5uTkP4D50skW/Mt0AAAAAElFTkSuQmCC</icon>

4. Details of the Script

I will explain the contents of the main() function in the <script> tag. First, regarding the first half.

? const accountSID = configs.get("AccountSid");
  const authToken = configs.get("AuthToken");
  const fromPhone = configs.get("From");
  const apiUrl = 'https://api.twilio.com/2010-04-01/Accounts/' + accountSID + '/Messages.json';

  const toPhone = engine.findDataByNumber(configs.get("To"));
  const message = engine.findDataByNumber(configs.get("Message"));

The configs.get(***) is to retrieve the value that has been set in config items earlier. In its argument, the value of name attribute in <config> will be specified. The values to be set in “C1. ACCOUNT SID”, “C2. AUTH TOKEN”, and “C3. From Telephone Number” will be retrieved respectively using item names such as “AccountSid”, “AuthToken”, and “From”.

In the captured image above, variables such as ${var[AccountSID]} have been input to the config items. Since the value will be passed to the script after expansion, you do not need to be aware of variables in scripts.

engine.findDataByNumber() is a function that searches for Data Items by the number and returns the value in that Data Item. In the config item with the form-type="SELECT" attribute contains the number of the selected Data Item. Thus, it is possible to retrieve the value of the specified Data Item in the format engine.findDataByNumber(configs.get(***));. In this automatic process, the values of the data items set in “I1. To Telephone Number” and “I2. SMS body” are acquired in order.

Regarding the last half of the script, it is the same content as the previous blog post. Using the set value, it accesses the Twilio API and sends an SMS. It detects success or failure by the response from the API. Please refer to the previous post for the details.

? const apiRes = httpClient.begin()
    .basic(accountSID, authToken)
    .formParam('From', fromPhone)
    .formParam('To', toPhone)
    .formParam('Body', message)
    .post(apiUrl);

  const responseCode = apiRes.getStatusCode();
  const responseBody = apiRes.getResponseAsString();
  engine.log("response: " + responseCode);
  engine.log(responseBody);

  if (responseCode != 201) {
    throw "response is not 201: " + responseCode;
  }

5. Registration of Definition file and Utilization in Workflow App

By registering the created definition file to Questetra BPM Suite you will be able to create a Workflow App in which the registered auto-step icon is used. Register the file by clicking on “Manage Add-ons” on the pull-down menu shown by clicking the ▼App button on the App details page.

Once registration is successful a new icon will be displayed in the palette of the Workflow diagram in Modeler.

The icon rightmost on the second row is what you have registered. Make the Workflow diagram like the following by replacing the Script Task icon using the new icon. In the screen capture image above another registered icon is displayed. The only remaining task is to set up the auto-step that you replaced, then it will be complete.

By using this function, reusability of automatic processing will be improved. There is also the advantage that you can hide the script processing described in the Script Task. I hope you will utilize this when you get the chance.

That’s it for today! See you around.

1 thought on “Sending a Text Message in the Middle of Workflow Using SMS – Service Task Add-on version”

  1. Pingback: RPA is Not the Only Automation! Various Examples of Automation by Cloud-based Workflow - Questetra

Comments are closed.

%d