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 Mac and Linux terminals without installation. Although there are several ways to use the curl command on Windows, this article will proceed assuming that you are 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"

Check the Message Start Event (HTTP) details and replace the endpoint URL and API key. If it has been entered correctly the process will be started as if accessing the endpoint from a browser.

Sending a variety of data

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

App Setting

Add Data Items as follows; checking the “Required” box is not necessary for any of them. Regarding Data editing permissions, set all items as “Editable” on the Message Start Event (HTTP) and “Only display” on the 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 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”. You can pass the data in the same way as the Title, but parameter names such as “data [1] .usdecimal” are a little hard to understand. Since it is possible to change the parameter name let’s change it to a more meaningful name before actually using it.

As each Data Item has a 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 the Data Item tab in the 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” in the settings screen of each Data Item, enter it there. In this tutorial, we will assume they are named 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. Check the Message Start Event (HTTP) detail. Are the Reception Parameter names as you set up?

Sending non-File-types by curl

Now, let’s try sending the added Data Items with curl as well. Since the method for File-type Data Items is somewhat different I will cover that in another section.

To send to multiple Data Items you can write 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 where “test” is the Title and “1.23” has been entered in the Numeric data (q_float).

$ 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 examples 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 settings.
(256 characters or less by default)
String single-line Any character string q_str=aeiou Character number limit and others depend on Data Item settings.
Numeric Any numeric value q_float=1.23 Range limit of input value, Number of the decimal place, etc. depends on the Data Item settings.
(Error if the number of decimal place of the input value is larger than the limit.)
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 settings.
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 settings.
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 use the following format you can start a Process while uploading ques-kun.png and 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 be passed to the File-type/User-type Data Items respectively.

  • For ques-kun-01.png/ques-kun-02.png, replace with an appropriate file name
  • For, replace with an 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 that looks like the image below.

In this case, there is a file to upload so I used the -F option. As I mentioned before, it is better to use the –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 widen the range of automation. Please be creative and take advantage of the the Message Start Event (HTTP). Next time, I will show you code examples for sending HTTP requests from Python.

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