Starting a Process by Curl Commands or External Program
When you want to Start a new Process, you follow the procedure such as, log in, then open the “Start” page…and so on. However, if you set a “Message Start Event (HTTP)” in the Workflow App, you can start a Process by sending an HTTP request from the curl command or your own program. This makes it possible to automatically Start a Process without human intervention, and to build cooperation between systems.
The Message Start Event (HTTP) is, just like a normal Start Event, placed and used in the Workflow diagram. A user Starts a new Process by clicking the “Start New” button manually for a “Start Event”, whereas on a |Message Start Event (HTTP)”, a Process will be started when it receives an HTTP request from the external system. An “endpoint” is given to each Message Start Event (HTTP), and it can be used from an external system.
In this series of posts, I will deal with the following contents.
- Settings of Message Start Event
- Settings of IP Adress Filter
- Simple Process Start by GET Request Transmission from Browser
- Starting a Process using Curl Command
- Starting a Process using Python
In this post, I will describe until “Simple Process Start by GET Request Transmission from Browser”.
Settings of Message Start Event (HTTP)
To see how a Message Start Event (HTTP) works, let’s create a simple App. Create a new App, then draw a Workflow diagram likewise the following figure. The Message Start Event (HTTP) icon is listed in the “Start Event” category on the advanced palette.
Concerning Data Items, only a “Title” is enough for the moment. And for Data editing permission, set the Message Start Event (HTTP) to “Editable”, and “Check” Task to “Only display”.
For the Swimlane setting, leave as default which is “your” account.
After finishing the setting so far, save the App and “Release” it. By doing this, the endpoint is determined. In the Workflow diagram on the App details screen, open the property of Message Start Event (HTTP). It is supposed to be that the “URL / Parameter Details” button has become clickable. Click it to open the “Message Start Event (HTTP) Detail” screen where you can confirm the endpoint URL and the Parameter names, so remember.
Simple Process Start by GET Request Transmission from Browser
First, let’s try Starting a new Process by accessing a particular URL with a browser. Leave the “Message Start Event (HTTP) Detail” screen open since you will need the endpoint URL, etc. of the Message Start Event (HTTP) that you placed on the created App.
For this trial, we are going to send a content to be input to the Data Item of “Title” at the time Starting a Process. By appending parameters to the end of the endpoint URL, you can pass the data you want to send to the App. It will be the following form when you want to set the title to, for example, “test”.
Put a question mark (?) at the end of the endpoint URL, and following it, append data in a format “name=content“. “API key is mandatory. As it is written in the list of Reception Parameter on the “Message start event (HTTP) details” screen, copy it from there and paste. Reception Parameter Names are also listed in the same list.
When you finish composing the URL, access it with a browser. I suppose 403 error will return. That is because the access was blocked by IP address filtering function of Questetra BPM Suite. When using the API from the external network, it is necessary to relax the IP address restriction appropriately on Questetra BPM Suite side.
Setting of IP Address Filter
Let’s learn how to register the IP address to access the endpoint to Questetra BPM Suite. With the default setting, all access to Message Start Event (HTTP) from the external network is denied.
To go to the IP address filter setting, click the button on left menu Security in System Setting. Let’s set the access permission for the Message Start Event (HTTP) of the App you created earlier.
Specifying Path Prefix
You can set IP address filter for each path prefix. To apply a filter by an IP address to a specific Message Start Event (HTTP), add an item of [Message Start Event (HTTP) – a specific node]. You can select it in the pull-down in Path Prefix in “Message Start Event/Catching Message Intermediate Event Configuration”. A Path Prefix specifying a particular node is as the following.
The part of “processModelInfold” refers to the number assigned to each application, and “nodeNumber” refers to the number assigned to each node on the workflow diagram. Since these two numbers are also included in the endpoint URL of the Message Start Event (HTTP), so I recommend you to confirm there. In a case if the endpoint URL is, for example;
the “processModelInfold” is “8“, and the “nodeNumber”is “0“. To confirm the endpoint URL, as aforementioned, see the “Message Start Event (HTTP) Detail” through the Workflow diagram.
As another way, to confirm in the App ID is available since a “processModelInfold” is equal to a number of an App ID without “m”. For the “nodeNumber”, it is indicated on each property screen of nodes on the Workflow diagram.
Specifying IP addresses to permit access
You can specify IP address to permit for each Path Prefix. Please enter IP address in the following manner.
- Enter with global IP address.
- Please use IPv4. IPv6 is not supported.
- Specification of IP address can be both single and ranged.
- Please use Subnet Mask for ranged specification. (e.g. 220.127.116.11/22)
- Access from all global IP addresses is permitted if 0.0.0.0/0 is specified.
- Access from all global IP addresses is denied if nothing is specified (blank).
In addition, those with a longer Path Prefix is preferentially applied to the IP address filter setting. For example, even if 0.0.0.0/0 is permitted for “Global Configuration” and for Path Prefix “/System/”, if stricter IP address filter is set for a specific node, the setting to that node will be applied. The order of the setting items does not affect the priority. Let’s try setting a narrow range of access permission such as a single IP address to the Message Start Event (HTTP) of the App you created earlier. Then open the “Message Start Event (HTTP) Details” through the Workflow diagram and confirm the “Allowed Hosts/Networks”. You see that the setting value has been applied preferentially since the Path Prefix is longer than the other setting items.
Retrying of Process Start from Browser
After registering the IP address you use for accessing the endpoint, let’s try accessing the Message Start Event (HTTP) from the browser again. This time, I suppose a page on which only a number is displayed has opened, but you just ignore that. When you log in to Questetra BPM Suite with “your” account (Operator of the Swimlane), you see that a Process has been Started and the “Confirmation” Task has been allocated to you. Also, confirm whether its title is the same one you passed to the parameter.
In this way, you can Start a Process without opening Questetra BPM Suite. In the next post, I will mention on methods of Starting a Process, even without a browser, from a command line using Curl command.
Appendix: Details of IP address filtering settings
Enabling/disabling of IP address filtering
It can be set on the checkbox of “Enable IP Address Filtering”. When you uncheck to disable, the following setting items will vanish since filtering is not performed. Basically, please do not disable it.
You can specify an accessible IP address for the entire your Questetra BPM Suite environment. The access permission here also applies to other than Message Start Event/Catching Message Intermediate Event.
Message Start Event/Catching Message Intermediate Event Configuration
You can specify the access permission to a range finer than the Global Configuration. As we use “Message Start Event (HTTP)” in this article, you select either from;
- Message Start Event (HTTP) – all apps
- Message Start Event (HTTP) – a specific app
- Message Start Event (HTTP) – a specific node
The Path Prefix will not be determined until the target App is created if using “- a specific app”, and until the App is Released if using ” – a specific node”. The format of Path Prefix is as the following.
|Access Permission Range||Path Prefix|
|– all apps||/System/Event/MessageStart/|
|– a specific app||/System/Event/MessageStart/(processModelInfoId)/|
|– a specific node||/System/Event/MessageStart/(processModelInfoId)/(nodeNumber)/|