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)

Click here for download page

Config-screen of Create Box Webhook

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

Click here for download page

Config-screen of Delete Box Webhook

It deletes a webhook set on a folder on Box.

Parsing Box Webhook JSON

Click here for download page

Config-screen of 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.

  1. Take a note of Client ID and Client Secret (for later use)
  2. In OAuth 2.0 Redirect URI enter the callback URL (see figure 2 below) written on the OAuth 2.0 setting page of Questetra
  3. Check the Manage webhook checkbox in the Application Scopes section
Figure 1: Box App Configuration
Figure 2: Callback URL

* 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.

ItemsSetting contents
NameAttach a descriptive name (to be used when the Add-on gets authentication information)
Authorization Endpoint URLhttps://account.box.com/api/oauth2/authorize
Token Endpoint URLhttps://api.box.com/oauth2/token
ScopeLeave 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.

Menu on App Details screen

Then switch the tab to Definition of service task (beta version) and click on [+Add].

Manage Add-on screen

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.

Workflow Diagram of Sample App

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 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
Choice ID Label Initial
true Yes  
false No
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.

Set deletion Step

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 nameFormatRequiredDescription
C1.OAuth Setting NameType directly (single line)YEnter the name that you attached at the (aforementioned) configuration of OAuth 2.0
C2.Folder ID(Number)Type directly (single line)YEnter 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)YEnter 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)YEnter 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)YSpecify 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.

NameConditional ExpressionDestination
DeleteSet deletion= true (Yes)Timer Event
Don’t DeleteSet deletion= false (No)Merge
Default FlowAlways move to DestinationDummy

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.

Settings in Timer Intermediate Event

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 ItemFormatRequiredDescription
C1.OAuth Setting NameType directly (single line)YEnter 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)YSpecify 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

Flow diagram of the Receive/Parse section

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.

ItemSetting
Content-Type of receiving HTTP requestapplication/json
String type data item that will save the request bodyDesignate “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.

Settings when reception is permitted

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 nameFormatRequiredDescription
I1.Webhook JSON Object (Data Type: Multiple-lines string)Designate String-type Data Item (multiple line)YSpecify the Data Item storing the JSON object. Select “JSON” in this sample.
O1.Event happened time (Data Type: Date Time)Designate Datetime-type Data ItemNSpecify 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)NSpecify 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)NSpecify 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)NSpecify 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)NSpecify 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)NSpecify 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)NSpecify 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.

Data Items storing Parse results

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.

Settings in Line Counter Add-on
Settings in Specific Line Reader Add-on

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).)

Settings in Open Chat Post Add-on

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.

ItemEL
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.

Sample of Open Chat Post

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.

%d bloggers like this: