I am introducing three kinds of Add-ons concerning Box Webhook, together with a sample App that monitors uploads to the specified folder.


What is Box Webhook?

In Box, an online storage service, you can set up Webhook on folders and files. Webhook 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

The Add-ons concerning Box Webhook that I am going to describe are the following three.

Create Box Webhook(folder)

Click here for download page

Config-screen of Create Box Webhook

It creates a Webhook on a folder on Box. You can set Webhook Event triggers arbitrarily. (See the official Box documentation for 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 by the following method.


Box OAuth 2.0 settings

Configuration on 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 “Authentication Method” on the next screen, select “Standard OAuth 2.0 (User Authentication)“.

After that, when you attach a name you like, the creation of the App is completed. Now, click on “View Your App”.

Once you created an App, configure the following on “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 on 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 (To Consumer secret, enter what is in “Client Secret”

Finally, click on “Get token”, then log in with the account which you set up 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” of the Add-on.


Import Add-on

First, download Add-ons respectively. 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].

Mange Add-on screen

Select the Add-on that you downloaded by “browse…” button then click on “Add” to add it. Edit “Name” and “Note” if needed.


Sample App

The following is a sample App I created incorporating Add-ons.

Workflow Diagram of Sample App

This App is separated into “Create/Delete” part (top part) and “Receive/Parse” part (bottom part). Even though it seems to be connected at the middle in appearance, the token does not move across the two swim lanes actually. It is because an error occurs if it is not connected according to the specification of Questetra BPM Suite.

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/judge whether delete or not 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

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
Filename 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 part of “Create/Delete”, creation and deletion of a Webhook are performed. At the first Step, “Set deletion”, an operator inputs “whether to delete the created Webhook or not“, and “time of deletion” in case if deletion is set.

Step of “Set deletion”

Configuration on “Create” Add-on

After finishing “Set deletion” Step, creation of Webhook isperformed by “Create” Add-on.

Config items in “Create” Add-on is 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 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 case of a folder at URL https://app.box.com/folder/1111xxxx, “1111xxxx” is the ID.
C3.Webhook URL(https) Type directly (single line) Y Enter the URL of webhook target folder. An error occurs if anything other than begins with “https” is entered. 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 triggers, enter one trigger on one line. This time, enter only a trigger (FILE.UPLOADED) which monitors 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 which output the ID of created Webhook. Thistime, specify “Webhook ID”.

Configuration on XOR gateway

At the following gateway, the flow branches according to the value in “Delete Webhook?”. Set the Split Type of as “XOR“, and Determination of the destination.

Name Conditional Expression Destination
Delete Set deletion= true (Yes) Timer Event
Don’t Delete Set deletion= farse (No) Merge
Default Flow Always move to Destination Dummy

The “Default Flow” at the bottom of the table above, is truly a dummy, so a flow never branches to this. (Since the Data Item of “Delete Webhook?” is set as Required, so the value always be either true or false.)

Configuration on “Delete” Add-on

In the case of “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 setting in the Timer intermediate Event, check on “Datetime specified by a data item” and designate “DateTime of deletion“. With this, the deletion will be executed at the time which has been specified at “Delete Webhook?” Step.

Config items in “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.

 


Receive/Parse Webhook

Flow diagram of “Receive/Parse” part

A Process of “Receive/Parse” part starts with receiving a JSON object that is sent from the Webhook at the “Message Start Event (Webhook)”. In this part, all processing is automatically performed throughout from the start to the end.

Configuration on Message Start Event (Webhook)

Set up the “Message Start Event (Webhook)” of the beginning as the following.

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 on the “Latest” version on the list of “All Versions.

Then click on the icon for “Message Start Event (Webhook)” to open its property. Go to the “Request” tab and click on the “Detail” button in Other Information.

Confirm the IP Address filter on the opened page.

If it is written “0.0.0.0/0 ” in the “Allowed Hosts/Networks” section, receiving HTTP request is allowed.

Indication for the case of allowed

If it is not so (such as “Connection from the external network is prohibited” is indicated), it is not able to receive. In such a case, please loosen the IP address filtering referring to THIS page. Even though “Communication from all IP addresses” need to be allowed according to the specification of Box, it is better to limit to configure filter as such only to this App (or node).

Configuration on “Parse” Add-on, the result

The “Parse” add-on parses the received JSON object and outputs the information into Data Items. (It is also possible to include only a part in Data Items depending on the setting of the App.)

Config items in “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 happens Event (Data Type:Single-line string) Designate String type Data Item (single line) N Specify the Data Item for saving “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 except “I1.Webhook JSON Object”. Use whatever you need depending on cases. 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 the following.

Data Items storing Parse result

Configuration on Parent folder name extraction

Regarding “All Upper Folders Name”, data in it are arranged in the order of hierarchy from the top, which means that “the last line is the folder to which Webhook has been set”. Taking advantage of that fact, extract the name of the folder that has been set up Webhook.

First, count the number of lines in “All Upper Folders Name”. Then extract the last line using that number. We are going to use Add-ons of “Line Counter” and “Specific Line Reader” respectively for that operation.

First, 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 to “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 “A” section, the “Group ID” is a unique number assigned to each organization, and “1” is for the root organization (all the users).

Regarding “B” section, data stored in Data Items can be inserted into messages by using EL (e.g. #{data[‘2’]}). There, the number contained in each expression represents particular Data Item. The following five items are used in this sample.

Item EL
Event occurrence time #{data['2']}
User name #{data['5']}
Parent folder name #{data['10']}
Filename #{data['7']}
File ID #{data['6']}

Since URL of each file is in the format of “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/#{data['6']}“. 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 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, you would better compose a more proper message in accordance with the triggers you 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, but that’s it, for today.