I am introducing three kinds of add-ons concerning Box Webhook, together with a sample App that monitors uploads to a specified folder.
What is a Box Webhook?
In Box, an online storage service, you can set up Webhooks for folders and files. The webhook then sends information regarding the operation to the specified URL when the specified operation (preview, download, delete, etc.) is performed on the target file/folder. The transmitted information can be received and utilized by various applications. (Questetra BPM Suite is, of course, capable of receiving it as well.)
Webhook settings on folder/file units are usually implemented using a command line or scripts, etc. While in Questetra, you can create or delete Webhooks on folders using add-ons.
Description regarding Add-ons
There are three types of add-ons concerning Box webhooks that I am going to describe here.
Create Box Webhook(folder)
It creates a webhook for a folder on Box. You can set webhook Event triggers arbitrarily. (See the official Box documentation concerning types of triggers.)
Information on the created webhook is output to the automatic processing log of the execution result.
Delete Box Webhook
It deletes a webhook set on a folder on Box.
Parsing Box Webhook JSON
It parses the JSON object sent by the webhook and saves the information on the Event in the corresponding Data Item.
To use these three add-ons you need to set up OAuth 2.0 and to import the add-on into the App. Please set it using the following method.
Box OAuth 2.0 settings
Configuration of the Box side
First, let’s sign in to a Box Developer account and create a new App.
On the Box Dev console click on Create New App and select Custom App from the menu that follows.
As you are asked to select the Authentication Method on the next screen, select Standard OAuth 2.0 (User Authentication).
After that, when you have attached a name you like, the creation of the App will be complete. Now click on View Your App.
Once you have created an App, configure the following on the Configuration menu.
- Take a note of Client ID and Client Secret (for later use)
- In OAuth 2.0 Redirect URI enter the callback URL (see figure 2 below) written on the OAuth 2.0 setting page of Questetra
- Check the Manage webhook checkbox in the Application Scopes section
* Since the callback URL differs depending on the environment you are using, please use the one on the screen of the actual App, not the one shown in figure 2 above.
Configuration of the Questetra side
Next, go to Questetra then open the OAuth 2.0 setting of the App (screen as figure 2 above) and click on [+ Add].
Configure the following on the displayed screen.
| Items | Setting contents |
|---|---|
| Name | Attach a descriptive name (to be used when the Add-on gets authentication information) |
| Authorization Endpoint URL | https://account.box.com/api/oauth2/authorize |
| Token Endpoint URL | https://api.box.com/oauth2/token |
| Scope | Leave blank |
| Client ID/ Consumer Secret | Enter what is shown on the Configuration menu of Box (for Consumer secret, enter what is in Client Secret) |
Finally, click on Get token, then log in with the account with which you set up the webhook on the folder and get the token. This completes the setting.
When configuring the add-on, input the name which you have attached at the time of the OAuth 2.0 configuration into C1.OAuth setting name in the add-on.
Import Add-on
First, you need to download each add-on. The links to the download page are in the “Description regarding Add-ons” section above.
Next, open Manage Add-ons on the App Details screen.
Then switch the tab to Definition of service task (beta version) and click on [+Add].
Select the add-on that you have downloaded using the Choose file button then click on Add to add it. Edit the name and notes if necessary.
Sample App
The following is a sample App I created incorporating the add-ons.
This App is separated into the Create/Delete part (the top part) and the Receive/Parse part (the bottom part). Even though it appears to be connected in the middle, the token does not actually move across the two Swimlanes. Because an error occurs if the Swimlanes are not connected according to the specification of Questetra BPM Suite this link is necessary, but it is superficial.
Data Items in the App are as follows.
| Data Item Name | Data-type | Required | Permission at Task | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Title | – | – | Editable | The Title of the Process | ||||||||||
| Those to be used for “Create/Delete” part | ||||||||||||||
| Delete Webhook? | Select (Radio button) | Y | Editable | To be used to select and decide whether or not to delete the webhook | ||||||||||
Choices Setting
|
||||||||||||||
| DateTime of deletion | DateTime | N | Editable | Set when to delete the Webhook | ||||||||||
Initial setting
processInstanceStartDatetime.addDays(1) |
||||||||||||||
| Webhook ID | String single line | N | No display | “Create” Add-on stores the Webhook ID, “Delete” Add-on reads it | ||||||||||
| Those to be used for “Receive/Parse” part | ||||||||||||||
| JSON | String multiple lines | N | No display | Stores sent JSON object | ||||||||||
| Event occurrence time | DateTime | N | No display | Stores event occurrence time extracted from JSON | ||||||||||
| User name | String single line | N | No display | Stores user name extracted from JSON | ||||||||||
| File ID | String single line | N | No display | Stores file ID extracted from JSON | ||||||||||
| File name | String single line | N | No display | Stores filename extracted from JSON | ||||||||||
| Super-directories names | String multiple lines | N | No display | Stores super-directories names extracted from JSON | ||||||||||
| Parent folder name | String single line | N | No display | Stores the Parent folder name extracted from “Super-directories names” | ||||||||||
| Hierarchy of the parent folder | Numeric | N | No display | Stores the hierarchy of the parent folder among the “Super-directories names” as a number。 | ||||||||||
Create/Delete Webhook
In the Create/Delete section, creation and deletion of webhooks are performed. At the first Step, Set deletion, an operator inputs whether to delete the created webhook or not, and the time of deletion if deletion is selected.
Configuration of the Create Webhook Add-on
After finishing the Set deletion Step, creation of a webhook is performed by the Create add-on.
Config items in the Create add-on are as follows.
| Item name | format | Required | Description |
|---|---|---|---|
| C1.OAuth Setting Name | Type directly (single line) | Y | Enter the name that you attached at the (aforementioned) configuration of OAuth 2.0 |
| C2.Folder ID(Number) | Type directly (single line) | Y | Enter the ID of the webhook target folder. An error occurs if anything other than numbers is entered. The folder ID is included in the display URL of the folder. e.g. In the case of a folder with a URL of https://app.box.com/folder/1111xxxx, “1111xxxx” is the ID. |
| C3.Webhook URL(https) | Type directly (single line) | Y | Enter the URL of the webhook target folder. An error occurs if it doesn’t start with “https”. In this sample, enter the receiving URL of the Message Start Event (Webhook) in the “Receive/Parse” part. |
| C4.Webhook Trigger(only one on each line) | Type directly (multiple lines) | Y | Enter the webhook Event trigger you want. In case you want to set more than one trigger enter one trigger per line. This time, enter only a trigger (FILE.UPLOADED) which monitors the uploading of files to the specified folder. |
| O1.Webhook ID Output(Data Type:Single-line string) | Designate String type Data Item (single line) | Y | Specify a Data Item to output the ID of the created webhook. This time Webhook ID will be used. |
Configuration on XOR gateway
At the following gateway the flow branches according to the value in the Delete Webhook Task. Set the Split Type as XOR and the destination Transition conditions as follows.
| Name | Conditional Expression | Destination |
|---|---|---|
| Delete | Set deletion= true (Yes) | Timer Event |
| Don’t Delete | Set deletion= false (No) | Merge |
| Default Flow | Always move to Destination | Dummy |
The Default Flow at the bottom of the table above is just a dummy, so a Process will never go down this branch. (Since the Data Item Delete Webhook is set as Required the value will always be either true or false.)
Configuration of the Delete Add-on
In the case that Delete Webhook is true (that means deletion is set at the beginning), it flows to the following Timer Intermediate Event where it stands by until the specified time, then executes deletion.
For the settings in the Timer intermediate Event check Datetime specified by a data item and select DateTime of deletion. With this, the deletion will be executed at the time which has been specified at the Delete Webhook Step.
Config items in the Delete add-on are as follows.
| Config Item | Format | Required | Description |
|---|---|---|---|
| C1.OAuth Setting Name | Type directly (single line) | Y | Enter the name that you attached at the (aforementioned) configuration of OAuth 2.0 |
| I1.Webhook ID(Data Type: Single-line string) | Designate String-type Data Item (single line) | Y | Specify the Data Item storing the ID of the target webhook. Select “Webhook ID” in this sample. |
Since the Create add-on saves the ID of the created webhook in the Data Item, we will utilize it as the ID of the target Webhook is required for deletion.
In case Delete Webhook is false (that is, the deletion has not been set at first Step) it ends as it is without deleting anything.
Receive/Parse Webhook
The Receive/Parse Process starts by receiving a JSON object that is sent from the Webhook at the Message Start Event (Webhook). In this part, all processing is performed automatically throughout from start to finish.
Configuration of the Message Start Event (Webhook)
Set up the Message Start Event (Webhook) at the beginning as follows.
| Item | Setting |
|---|---|
| Content-Type of receiving HTTP request | application/json |
| String type data item that will save the request body | Designate “JSON” |
In addition, it is necessary to check whether it is allowed to receive HTTP requests from Box.
First, click on the [Detail] button of the latest version on the All Versions list.
Then click on the icon for the Message Start Event (Webhook) to open its properties and click on the Other Information, such as IP address filtering button.
Confirm the IP Address filter on the opened page.
If “0.0.0.0/0” is written in the Allowed Hosts/Networks section, receiving an HTTP request is allowed.
Otherwise (such as in the case that “Connection from the external network is prohibited” is displayed) it is not able to receive. In such cases please relax the IP address filtering referring by to THIS page. Even though communication from all IP addresses must be allowed according to the specification of Box, it is better to limit the configuration filter to only apply to this App (or node).
Configuration and Results of the Parse Add-on
The Parse add-on analyses the received JSON object and outputs the information into Data Items. (It is also possible to include only a section in the Data Items depending on the settings of the App.)
Config items in the Parse add-on are as follows.
| Config name | Format | Required | Description |
|---|---|---|---|
| I1.Webhook JSON Object (Data Type: Multiple-lines string) | Designate String-type Data Item (multiple line) | Y | Specify the Data Item storing the JSON object. Select “JSON” in this sample. |
| O1.Event happened time (Data Type: Date Time) | Designate Datetime-type Data Item | N | Specify the Data Item for saving the date and time of event occurrence. Select “Event occurrence time” in this sample. |
| O2.User who caused Event (Data Type: Single-line string) | Designate String-type Data Item (single line) | N | Specify the Data Item for saving the User who caused the event. Select “User name” in this sample. |
| O3.Webhook Trigger (Data Type: Single-line string) | Designate String-type Data Item (single line) | N | Specify the Data Item for saving the “triggers”. No Data Item is prepared in this sample App. |
| O4.Target File or Folder ID (Data Type: Single-line string) | Designate String-type Data Item (single line) | N | Specify the Data Item for saving the ID of the folder/file to be the target of the event. Select “File ID” in this sample. |
| O5.Target File or Folder Name (Data Type: Single-line string) | Designate String-type Data Item (single line) | N | Specify the Data Item for saving the name of the folder/file to be the target of the event. Select “File name” in this sample. |
| O6.All Upper Folders ID (Data Type: Multiple-lines string) | Designate String-type Data Item (multiple line) | N | Specify the Data Item for saving the ID of all folders above the target file/folder. No Data Item is prepared in this sample App. |
| O7.All Upper Folders Name (Data Type: Multiple-lines string) | Designate String-type Data Item (multiple line) | N | Specify the Data Item for saving the name of all folders above the target file/folder. Select “Super-directories names” in this sample. |
In the Parse add-on you do not have to set anything except the I1.Webhook JSON Object. Use whatever you need depending on each case. Even in this sample Webhook Trigger and All Upper Folders ID are not used.
When parsing is performed, the result is saved in the Data Items as follows.
Configuration of Parent folder name extraction
Regarding “All Upper Folders Name”, data in it is arranged in the order of hierarchy from the top, which means that the last line is the folder where the webhook has been set.
First, count the number of lines in All Upper Folders Name. Then extract the last line using that number. We are going to use the add-ons Line Counter and Specific Line Reader respectively for that operation.
Measure the number of lines in All Upper Folders Name with Line Counter and store the result in Hierarchy of the parent folder.
Then, with Specific Line Reader extract the line of the number stored in Hierarchy of the parent folder (that is, the last line) from All Upper Folders Name, and store it in Parent folder name.
Configuration of Open Chat Post
Finally, post the information which has been obtained by parsing to Open Chat together with the folder name stored in Parent folder name. (We use an old version of the add-on for using EL (Expression Language).)
Regarding section A, the Group ID is a unique number assigned to each organization, and “1” is for the root organization (all the users).
Regarding section B, data stored in Data Items can be inserted into messages by using EL (e.g. #{#q_string5}). There, the number contained in each expression represents a particular Data Item. The following five items are used in this sample.
| Item | EL |
|---|---|
| User name | #{#q_string5} |
| Filename | #{#q_string7} |
| Parent folder name | #{#q_string10} |
| Event occurrence time | #{#q_datetime4} |
| File ID | #{#q_string6} |
Since the URL of each file is in the format https://app.box.com/file/(file ID) in BOX, the URL of the target file to be posted can be expressed as https://app.box.com/file/#{#q_string6}. However, since only the owner of the file and those who are invited and have the viewing authority can access with this URL, it may be better to write that fact in the post when practically using it.
By setting it like this, the actual post will be as follows.
Since it is only for monitoring uploads in this article the message is simple as above, but for practical use it would be better to compose a more appropriate message in accordance with the triggers you have set. (Since the triggers are also included in the information obtained by parsing as described above, it will be possible to process multiple triggers.)
It became a little longer than I expected, but that’s it for today.