Starting a Process from Outside of Questetra BPM Suite (curl Chapter)

Starting a Process by Curl Command

Let’s try accessing Questetra BPM Suite and Starting a Process, using curl which is a command capable of data transmission. curl command can be used on the terminal of Mac and Linux without installation. Although there are several ways to use the curl command on Windows, this article will proceed with the assumption of using curl command on Windows Subsystem for Linux.

First, let’s do the same thing as the previous article with curl command. Execute the following command.

$ curl{processModelInfoId}/{nodeNumber}/start --data-urlencode "key={API key}" --data-urlencode "title=test"

Confirm “Message Start Event (HTTP) details” and replace the endpoint URL and API key according to it. If it has entered correctly, the process will be Started like the same way as when accessing the endpoint from the browser.

Sending various data

Now, how do you send data other than the Title? Many types of Data Items such, as String or User, are prepared, and you can send most of them in the same way as the Title. Let’s see how it works by adding Data Items of the App.

App Setting

Add Data Items as the following. Checking on “Required” is not necessary for any of them. Regarding Data editing permission, set “Editable” on “Message Start Event (HTTP)”, and “Only display” on “Check” Task.

Item name Data type Optional setting
String0 String type single-line
Numeric1 Numeric
  • Range of decimal digits: 2
Select2 Select (Select box)
  • Leave choices as default
    • Choice ID of the first one: true
    • Choice ID of the second one: false
    • Initial: true
Date3 Date (Y/M/D)
Datetime4 Datetime
File5 File
User6 User (Search select box)
Organization7 Organization

Let’s save and Release the App in this state once, and see how the parameters appear. When you open the Message Start Event (HTTP) detail, the added Data Items should be listed as “Reception Parameters”. Even though you can pass the data as it is, just like the Title, parameter name such as “data [1] .usdecimal” is hard to understand a little. Since it is possible to set the parameter name to your own, let’s change it to a meaningful name before actually using it.

As each Data Item possesses “Field Name”, if it has been set in advance, that name will be applied to the parameter name for API. You can edit Field names on Data Item tab on Process Modeler. The rules concerning naming are as follows.

  • Starting with “q_”
  • Alphabets, numbers, underscores are available
  • Within 64 characters

As there is a text box with the title “Field Name” at the bottom of the setting screen of each Data Item, enter it there. In this tutorial, we assume that we named it as follows.

Item name Field Name
String0 q_str
Numeric1 q_float
Select2 q_selects
Date3 q_date
Datetime4 q_datetime
File5 q_file
User6 q_email
Organization7 q_group

After editing the field name, save the App and Release it. Let’s see the “Message Start Event (HTTP) detail”. Do you confirm the Reception Parameter names are as you set up?

Sending by curl other than File

Now, let’s try sending the added data item with curl as well. Since only the method for the File type is somewhat different, so I will cover in another section.

To send to multiple Data Items, you can write as the following.

$ curl{processModelInfoId}/{nodeNumber}/start \
> --data-urlencode "key={API key}" \
> --data-urlencode "name1=content1" \
> --data-urlencode  "name2=content2" \
> ...

With the following command, for example, you can Start a Process in the state where “test” in the Title, “1.23” in the Numeric data (q_float) has been entered.

$ curl{processModelInfoId}/{nodeNumber}/start \
> --data-urlencode "key={API key}" \
> --data-urlencode "title=test" \
> --data-urlencode "q_float=1.23"

Please refer to the following table for concrete input example for each Data type.

list of input method for each Data type
Data Item Subtype Format Example Remark
API key key={API key} API key is written in Event detail.
Title Any character string title=test Character number limit and others depend on data item setting.
(256 characters or less by default)
String single-line Any character string q_str=aeiou Character number limit and others depend on data item setting.
Numeric Any numeric value q_float=1.23 Range limit of input value, Number of the decimal place, etc. depends on the Data Item setting.
(Error if the number of decimal place of the input value is larger than the setting.)
The decimal point is “.” (Period)
No delimiter
Select radio button Choice ID q_selects=true The Choice ID corresponding to each option depends on the data item setting.
selct box
search select box
check box Choice ID
(Multiple transmission possible)
q_selects=Monday The Choice ID corresponding to each option depends on the data item setting.
To select multiple options, send multiple times with the same parameter name.
Date Y/M/D yyyy-mm-dd q_date=2018-11-01
Y/M yyyy-mm q_date=2018-11
M/D mm-dd q_date=11-01
Y yyyy q_date=2018
Datetime yyyy-mm-dd HH:MM q_datetime=2018-11-01 10:00
File File path q_file=@ques-kun.png For file uploading, the -F option is required. (described later)
To upload multiple files, send multiple times with the same parameter name
User select box Email address of the User
search select box
Organization Organization name q_group=10 Management

Sending Files

As noted above, if you do not send data to File type Data Items, POST with the option, --data-urlencode, is recommended. However, the --data-urlencode option, which sends data in application/x-www-form-urlencoded format, is not capable of dealing with files. Therefore, when dealing with File type Data Items, you need to use the -F option to send data in the multipart/form-data format. And you cannot use the --data-urlencode option and the -F option at the same time.

$ curl{processModelInfoId}/{nodeNumber}/start \
> -F "key={API key}" \
> -F "{PARAMETER of File type Data Item}=@{FILE PATH}" \
> -F "name1=content1" \
> ...

For example, if you write as follows, you can Start a Process with uploading ques-kun.png and with setting the Title as “TEST”.

$ curl{processModelInfoId}/{nodeNumber}/start \
> -F "key={API key}" \
> -F "title=TEST" \
> -F "q_file=@ques-kun.png"

To summarize the contents so far, you can also write the following commands.

$ curl{processModelInfoId}/{nodeNumber}/start \
> -F "key={API key}" \
> -F "title=TEST" \
> -F "q_str=This is testing for Process Start." \
> -F "q_float=1.23" \
> -F "q_selects=false" \
> -F "q_date=2018-04-01" \
> -F "q_datetime=2018-04-01 12:34" \
> -F "q_file=@ques-kun-01.png" \
> -F "q_file=@ques-kun-02.png" \
> -F "" \
> -F "q_group=10 Management Department"

Before you execute the example command, please replace the values to pass to File type/User type Data Items respectively as the following.

  • For ques-kun-01.png/ques-kun-02.png, replace with the file name of what you want to upload
  • For, replace with the email address which has been registered to the Questetra system you are using, e.g. your email address.

When this command is executed, a Process will be Started as the image below.

In this case, I use -F option, since to upload files. As I mentioned before, it is better to use --data-urlencode option if not dealing with files.
When sending a character string including non-ASCII characters such as Japanese to the Message Start Event (HTTP), the character code must be UTF-8. If you encounter problems such as garbled texts, please check the character code setting of your terminal.

In this way, you can use the curl command to Start a Process. The use of “shell scripts” or “cron”, etc. will widens the range of automation. Please devise various means and utilize the Message Start Event (HTTP). Next time, I will show you examples of code for sending HTTP requests from Python.

Next: Starting a Process from Outside of Questetra BPM Suite (Python Chapter)

%d bloggers like this: