Fully Automate the File Management with BOX API

Improvement in Quotation Management

In “Automation on Quotation Work”, an article of records of struggles for business improvement by a Sales manager, I have created a mechanism in which;

• a quotation to be submitted is approved by the sales manager, and
• simultaneously, “a Quotation PDF file” is generated automatically

Hereafter, however, it is something to solve dissatisfaction of the sales manager (myself). Specifically, I am going to consider a mechanism that the generated “quotation PDF file” to be automatically saved in Box, which is a cloud storage service (online storage). (This is a compilation of articles which have previously published in separate short posts.)

(1-1) Advantages of Cloud storage

As a matter of course, it is possible to save files to Questetra. In addition, the viewing authority of the file stored in “File type Data Item” is highly controlled.

However, the cloud storage Box has many functions unique and only to “data storage”.

• Equipped a viewer that you can browse the contents of many types
• You can see the contents of files successively
• The content of the files can be targets of a search
• You can share the file with your stakeholders or publish it

Of course, there are so many other functions besides these, but in any case, I consider that Box’s excellent functions (including future additional functions) become available is a great value.

Incidentally, for myself (Yahagi) who is a sales manager, I wanted to use Box ‘s file viewer function since I often want to confirm the saved quotation PDF files consecutively. Since “Quotation PDF file” saved in Questetra is treated in the same way as other data such as “Company name” and “Amount of money”, so it was a bit inconvenient if you wanted to see only PDF files. Also, It is inconvenient since I cannot see the contents unless I download all the files I want to see. (as of May 2018)

(1-2) Direction of Improvement of “Quotation Approval Flow”

In this article, I will proceed with my explanations by giving improvements to “Quotation Approval flow” I created in the article “Automation on Quotation Work”.

First, I will explain about the “Quotation Approval flow” briefly. There are three human Steps in line such as

1. A salesperson enters the Company name, Total amount, etc. at the Step “1. Register quotation”
2. The sales manager gives a judgment to approve (or reject and resubmitted)) at the Step “2. Approve”
3. The salesperson enter to record the submission of the quotation and prospects etc. at the Step “3.Report result”

And the “quotation PDF file” is automatically generated immediately before the 3rd Step. In addition, as you can see from the flowchart, a quotation that is not required manager approval (such as a quotation without discounts) does not go through the “2. Approve” Step.

The first improvement is the placement of “automatic Step on which PDF files are automatically uploaded”.

(2-1) Create a destination folder in Box

We are going to log in to Box and create a folder to save quotation files.

Although the folder name to be set here may be any suitable one, the “assigned folder ID” as the result will be important in the settings of later.

Specifically, after creating a folder, click on the folder to display the contents of the folder, and note the part of *********** (folder ID) of the URL displayed in the web browser. It will be used in “(2-4) Configure the Service Task of Questetra” described later.

https://YourSubdomain.app.box.com/folder/***********

(2-2) Setting secure communication between Box/Questetra

It is necessary to allow (authorize) access to Box from Questetra beforehand.

(That is a secure communication between servers referred to as “OAuth 2.0 Authorization Code grant Method”.)

(2-2-1) Create an “app” in Box

First, log in as Box administrator user and access the following URL. When you access this URL, a screen that “Welcome to Box Platform!” appears.

https://YourSubdomain.app.box.com/developers/console

When you click on the “Create New App” button, a screen will be displayed asking you to choose which type of application to create out of three. Here, we select “Partner Integration” on the far right.

Clicking on “Next”, a screen for entering the name of the app will be displayed, so enter an appropriate name. Although in the figure below, I named “file-operation-questetra”, you can name it as you like. After you input, click on “Create App”.

When the completion screen is displayed, click on the “View Your App” button.

Details of the app will be displayed, so you enter information on OAuth2.0 setting and confirm (memorandum) on this screen.

First, enter the following value in “OAuth 2.0 redirect URI” (Also referred to as Callback URL).

Enter https://s.questetra.net/oauth2callback if you are using the paid version of Questetra, or https://f.questetra.net/oauth2callback if you are using the free version of Questetra. (You can see also on the screen of Questetra OAuth 2.0 setting which I will describe later)
(Manual reference: “M225AUTO EVENTAuto Sending of HTTP Request with Business data Inserted“)

Then respectively write down the client ID and the client confidential code (Key information when accessing from Questetra) indicated in “OAuth 2.0 Credential Information” which is located above “OAuth 2.0 Redirect URI”. These will be used in the next section “(2-2-2) Setting “OAuth 2.0 ” in Questetra’s Workflow App”.

(2-2-2) Setting “OAuth 2.0 ” in Questetra’s Workflow App

Next, log in to Questetra and make configuration of an App for collaboration with Box.

Click on “OAuth 2.0 setting” in the menu shown when clicking on the “▼ App” button, which is a bit hard to find. (“App Administrator authority” of the corresponding Workflow app is required)

Then, click on “+ Add” on the upper left side of the displayed screen, make the following entries on the displayed screen:

• Name
  • Arbitrary. There, I named it “box”. (This will be used in “(2-4) Configure the Service Task of Questetra”)
• Authorization Endpoint URL
  • https://account.box.com/api/oauth2/authorize
• Token Endpoint URL
  • https://api.box.com/oauth2/token
• Scope
  • Leave it blank
• Client ID
  • Client ID that you wrote down at Box application (OAuth 2.0 credential information)
• Consumer Secret
  • BConsumer Secret that you wrote down at Box application (OAuth 2.0 credential information)

When you finish inputting, click on the Save button and back to list of “OAuth 2.0 setting” screen. On that screen, click on the “Get Token” button.

Then Box screen as the following will be displayed, so click “Grant access to Box”. (You may be asked for an ID and password to login to Box.)

When successfully processed, the following screen will be shown, and this means that all settings related to OAuth 2.0 are completed.

(Reference: OAuth 2.0 Document for Box APIs)

(2-3) Add the Service Task (Add-on) of Questetra

There is no automatic Step such as “Service Task for uploading files to Box” as the standard function of Workflow design screen (Process Modeler).

So, first of all, we will make possible to use ‘Service Task of uploading files to Box’. Specifically, download the Add-on file “Box-upload.xml” from the official page distributing the Add-on file (Add-on XML), and upload the acquired Add-on file from the “Manage Add-ons” menu. (“Manage Add-ons” is in the “▼ App” menu.) (Manual reference: “M415AUTOMATED STEPAdding an Auto-Step to be Used for Business Process Definition“）

When you click on the Save button, the line with the name you just entered will be added to the “Definition of service task (beta version) Max 10” at the bottom of the screen.

You can now use “Service Task of uploading files to Box” on the modeling screen (screen for editing flow diagram).

(2-4) Configure the Service Task of Questetra

Return to the detail screen by clicking the “Back to details” button at the bottom of the screen, and then click the”Edit” button to launch the editor.

First, place the icon of the Add-on for uploading files to Box, onto the flow diagram. (The added Add-on can be selected by hovering the mouse cursor over Task icon in “advanced” tab.)

When you open the property screen of the “Service Task of uploading files to Box” at this state, you will see that the following items must be configured.

• A: Set OAuth2 Config Name
• B: Select STRING/SELECT for Folder ID on Box
• C: Select FILE DATA for Upload

Nonetheless, in the “Quotation Approval flow” so far, it does not have “information of folder ID on Box side” (because Box coordination was not considered). That is, there is no Data Item to be selected for “B: Select STRING/SELECT for Folder ID on Box”.

Therefore, add a String type Data Item “Box folder ID” newly. In addition, set the string which you noted previously (*********** of the URL) to its initial value. (Set the data editing permission of the all three human tasks as “no display” so that not to be edited.)

Now, open the properties again and make the configurations.

• A: Set OAuth2 Config Name
  • Enter the Name of OAuth 2.0 configuration (“box” which you have configured at “(2-2) Setting secure communication between Box/Questetra”.)
• B: Select STRING/SELECT for Folder ID on Box
  • Select the Data Item “Box folder ID” that you have added
• C: Select FILE DATA for Upload
  • Select “Quotation PDF file”

(2-5) Operation check on Automatic upload

After that, you just “Release” the Workflow App and check its operation.

If you input appropriate data into the newly released Quotation Approval flow and run it, you will confirm that the generated Quotation PDF file has been successfully saved in Box.

With this improvement, it has become that the generated Quotation PDF file is automatically uploaded to Box. I suppose this makes it possible to use powerful functions for operating files of Box, which will lead to mistake prevention and improvement of business efficiency.

(3-1) Download management function of Box

While actually using Box like every day, I noticed that I can realize the following matters.

• Files saved in Box can be published to users who are not using Box
• A setting of asking password to download files is also available
• A setting an expiration date on the file is available

Thinking carefully, I found that I can safely submit the document files uploaded to Box to the customer by combining these three. That is, I can easily create a file which is in the state where only people who know the URL and the password can download it. Moreover, the customer must download the file within the specified time limit.

If it works well, it seems to be able to construct a mechanism to submit files (quotation document) to customers in a sufficiently safe state.

• Upload the document file to Box and publish it with an expiration time limit
• Notify the download URL and the password to the customer
• The customer enters the password within the time limit and receives the document file

(3-2) Control of file sharing setting by Box API

However, if I set “password” and “expiration” manually on the Box screen, it must be nothing but inefficient. Also, I am worried about mistakes occur in operations.

Therefore, I thought that I would like to automate the setting concerning these file sharing settings (download limitation). Specifically, these are as the following.

1. To upload document files to Box
2. To make the uploaded document files downloadable
3. To ask the password upon downloading
4. To set an expiration date for downloading

I looked into the Box APIs reference while being excited about thinking that I wish I could automatize these things above, and wondering if there is an API to do so… and, bingo! I found it.

Concerning #1, to upload files, I can use the following API. It would be easy if settings for #2 to #4 could be done at this stage, but here it is just for uploading. (Reference: Box API reference “Upload File“)

Upload File: https://upload.box.com/api/2.0/files/content (POST)

To make some sort of settings to the uploaded file such as #2, #3, and #4 above, use the following API. (Reference: Box API reference “Upload File Info“)

Update File Info: https://api.box.com/2.0/files/file_id (PUT)

(3-3) Direction of “further improvement” in “Quotation Approval flow”

Thus, I am going to realize that “Automatically generated quotation PDF files” to be

• Uploaded to Box automatically and,
• In a state where the customer can download (with the password and expiration)

(4-1) Specification arrangement on Quotation submission Workflow

We are going to add a mechanism that allows customers to safely receive (download) “quotation PDF file”, by expanding the Quotation Approval flow so far. Its overview is as follows.

• When a Quotation PDF file is generated, a salesperson designates the download expiration date and a password
• Then the file is uploaded to Box, and the expiration date and the password are set
• The salesperson obtains the URL for downloading the PDF file and inform it and its password to the customer
• The customer accesses to the URL before the expiration date, enters the password and download the file

At the auto-step “Upload to Box” in the above figure, it performs the following.

• Upload quotation PDF file to Box automatically
• Configure its expiration date and password for downloading
• Retrieve URL for downloading

(4-2) Develop an automatic Step where a password is set upon uploading

Questetra BPM Suite has automatic Steps that are “Script Task” and “Service Task”. And regarding “Service Task”, there are features such as;

• which already has been equipped as the standard (e.g PDF auto-generation), or
• which become available by adding as Add-on

And regarding Add-on files, it is possible to create your own. (instead of obtaining as described in “(2-3) Add the Service Task (Add-on) of Questetra”.) (Manual reference: “M416AUTOMATED STEPCreate your own Auto-Step for Business Process Definition“)

Thus, there are the following two methods to implement auto-step which allows “server side processing on your own”.

• Place “Script Task” and paste codes in its property
• Create a “Service Task Add-on” on your own, import it, place it, and configure it

In this case, I will choose the latter, to create “Service Task Add-on” on my own, in consideration for deployment to other businesses.

(4-3) Contents of the Add-on file created by my own

I have created an Add-on file (Add-on XML) in which Scripts are written so that

• Upload quotation PDF file to Box automatically
• Set download expiration date and password
• Obtain the URL for downloading

(In this section, knowledge of programming is required.)

(For details on How to create Add-on XML files please refer to manual “M416AUTOMATED STEPCreate your own Auto-Step for Business Process Definition“. The actually created Add-on file is HERE.)

The configuration of this file is roughly divided as follows.

• <configs>…</configs> (line #14-43); Definitions for elements in property of Service Task
  • Set download expiration date and password
  • Obtain the URL for downloading
• <script>…</script> (line #45-128); Definitions for contents of processing

(4-3-1) Definition for the property of Service Task

In lines #14 – 43, the content to be set up by the Workflow App designer is defined.

The first <config> “A: Set OAuth2 Config Name” requires “text input” to the Workflow App designer. In the second and subsequent <config>, the Workflow App designer is required to select “Data Item”.

(4-3-2) Retrieving of “Service Task property” and “business data”

In lines 49 to 66, the Input information necessary for server side processing is assigned to variable.

A fixed value is assigned to the variable oauth2. In other words, the same “OAuth 2 communication permission setting” will be used each time an Issue arrives in the Service Task.

Whereas, for variables of file, download_limit, download_password, business data is dynamically retrieved and assigned each time an Issue arrives in the Service Task.

(4-3-3) Contents of concrete processing (calculation and communication)

In lines #69 – 88, calculation and communication are defined.

Here, the processing of uploading the stored file (quotation PDF) to Box is written. (Acquire access token using communication permission settingoauth2, and when file data is attached to the Issue, POST it using multipart.)

In lines #98 – 105, it prepares (creates JSON object) to set “Expiration date for downloading” and “password for downloading” in the uploaded file.

In lines #107 – 119, it sets “Expiration date for downloading” and “password for downloading” in the uploaded file.

(4-4) Placement and configuration of automatic Step created by my own

As the Add-on definition file (Add-on XML) has been completed, upload it to the Workflow App. Basically, it is the same procedure as described in “(2-3) Add the Service Task (Add-on) of Questetra”.

In this example, I uploaded from the “Manage Add-ons” screen of the Workflow App so that it can be used only in the “Quotation Approval flow”.

Confirm if the added Service Task is available.

Place the Service Task.

Configure property.

(4-5) Operation check on download limit function

As points to confirm, there are the following three.

• Whether it is possible to download the file from the URL set in String type “Download URL” without logging into Box
• At that time, whether it is possible to download by entering the password which is specified in String type “Password for Downloading”
• Whether the date that specified in the Date type “Expiration date” is set as the expiration date

Enter “Expiration date” and “password for downloading” at the third Step “3. Prepare for submission” Step.

The generated quotation PDF file has been uploaded to Box and the URL for downloading has been set in the Data Item.

Access the “URL for downloading” with a web browser that is not logged in to Box. Then a screen asking for a password is displayed. By entering the correct password, I could download the quotation PDF file, while I couldn’t when I entered an incorrect password.

Next, check whether the expiration date has been set on the uploaded file.

When logging in to Box and clicking on the uploaded file, a message as shown in the following figure, “This shared link will be disabled on MMM DD, YYYY” which indicates that the entered expiration date has been set, will be displayed.

The improvement cycle of business is “endless”.

It is truly a part of activities of Business Process Management, and I have many more improvement ideas. For example, even with “collaboration with other cloud services” (discussion on API economy) alone, countless ideas will come up. Regarding automatic generation of passwords, it could be done on the server side, or decoration of the input form will be used to create an assignment button, and so on.

However, I would like to finish this article by writing two more ideas at the end.

(5-1) Inform how to download to customers

A salesperson must inform customers about the “download URL (download expiration)” and “password” of the quotation PDF file. (The 4th Step, “4. Inform to customer”)

Therefore, we will make that a guidance email arrives at the customer immediately after uploading the Box (If it is too much mechanical or systematic, which makes it will be also risky). Incidentally, a String type Data Item “Submission destination email address” which is the destination of the email is added.

The icon for sending email is in “advanced” tab in the left menu. It is the icon that appears as “Throwing Message Intermediate Event (email)” when you hover over, as shown in the following figure.

Since I have placed two email sending events, I will make settings respectively.

When I enter Submission destination email address as a test…

Emails arrive!

(5-2) Confirm if it was actually downloaded

Using “Service Task for obtaining the number of downloads of Box file”, you can check if the quotation PDF file was viewed.

For example, it is also possible to construct a mechanism whereby “download count” and “preview count” are automatically recorded at the moment when “download expiration” is reached.

Improvement of the business process is truly profound.

That’s it, for today!