HI, Questetra users! I’m HATANAKA, Questetra CTO.

This post is the continuation of the blog post below.

Sending a Text Message in the Middle of Workflow Using SMS – Script Task version

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 to be made can be reused in other Workflow Apps.

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

The Workflow diagram will be changed as follows, eventually. 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 setting, it will be convenient. I would like to aim for the setting screen as the following to be.

The config items are as follows.

  • 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 cannot take control of it.

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

Hereafter, I would like to explain 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 “1” to <engine-type.>, and the date of creation to <last-modified> in the format of YYY-MM-DD.

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

  <engine-type>1</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 dialogue. Since Questetra BPM Suite supports multiple languages, in Japanese environment the contents of locale = "ja" is displayed. Although there are other languages such as "en" "de" "es", in the case of the current setting, "Sending SMS by Twilio" is displayed in other languages, except if 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 config item in the config dialog. By 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 describe 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 let the user select one from 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 the choices to be selected. And if it's "STRING", a String type Data Items are to be selected regardless of single line/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 will be input for sure. In this Auto-step, all five setting items are mandatory, and none of them will be allowed to empty.

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

3. Script and Icon

The <script> tag is for describing processing to 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. Images smaller than 64 x 64 in JPEG/GIF/PNG is only 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 to "C1. ACCOUNT SID", "C2. AUTH TOKEN", and "C3. From Telephone Number" will be retrieved respectively using the item name such as "AccountSid", "AuthToken", and "From".

In the captured image above, variables such as ${var[AccountSID]} has been input to 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 form-type="SELECT" attribute contains the number of the selected Data Item. Thus, it is possible to retrieve the value of 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 Twilio API and sends 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 at on the page you go by clicking on "Manage Add-ons" on the pull-down menu shown by clicking "▼App" button on the App detail 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 as the following by replacing the Script Task icon using the new icon. In the screen capture image above, another registered icon is displayed. The rest is, you set up the replaced Auto-step then it will be completed.

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.