Skip to main content
Developer Portal
Mendix

Box Connector Plus

This module allows integration between Mendix applications and Box.

Documentation
Implementation

Description

Box Connector Plus allows the user to upload files to Box. It is an extension of the Box Connector module and has all the same Java actions and microflows in it. It then adds a few microflows that abstract some of the functionality of the original module to make it easier to implement.

Typical Usage Scenario

This module is used to implement various actions using the Box API. It can be used to upload files to Box, download files from Box, and soon to be more calls implemented. It is used if you need a simpler way of using the Java actions found in the original Box Connector module. Mendix already has a way to store files, but it can be costly. Using this module allows storage in Box, which allows unlimited storage for free. Implementing Box as a storage back-end is cheaper, but setup is more complicated.

Features and Limitations

Currently, this module offers an administration interface for configuring your application on your site, and a few microflows that use the Box API to complete tasks such as uploading files.

  1. The administration interface has two different setting menus thus far:
    1. Box application
      • In this menu, you can add the information of your Box application. Right now, it only supports applications that authenticate through a JWT. You can also create a Box application in the site’s database by copying and pasting the contents of the config.json file that Box gives you when creating the application in their developer portal.
    2. Storage settings
      • Here you can set the folder that you want to serve as the upload location of the files uploaded to your site. When you choose your folder, you can navigate through the folders that exists on that application’s account. You can also create new folders if you need to. In the future, there will be an option added to sharing the specified upload folder with an admin, so that the admin can go to that folder in the Box console to manage files if necessary.
  2. This module also offers a few microflows that abstract some of the functionality in the original Box Connector module. It has three microflows thus far:
    1. Uploading a file
      • You can put this microflow as the action for the save button for your FileDocument specializations, and it will upload the file to Box instead of saving it in your Mendix application.
    2. Downloading a file
      • You can put this microflow as the action for a button that you pass in the BoxFile object you want downloaded. Then it will download that file from box.
    3. Deleting a file
      • Simply give that microflow the BoxFile object you want deleted, and it will move that file to Box’s trash. (Note: this does not delete it permanently. The Box API has a function for deleting items permanently, but it has not been implemented in this module yet.)

How to Use

The Box Connector Plus module is there to fix a lot of the problems we had with the existing Box Connector module. It also provides some abstraction to the functionality that is in the original Box Connector module. All the same Java actions and microflows from the Box Connector module are still there.

Getting Started

  1. You will need to access the administration interface provided
    1. This is found under _USE ME > Administration > General > Pages > Box_Administration. This will give your site a settings page to configure everything related to Box and your site.
  2. Add a Box Application
    1. Currently, the administration interface has a page for configuring your Box Applications, and a page for configuring where you want to store uploads to Box. In the Applications Overview page, you can currently only add applications that use JWT as its authentication method. Adding applications that use plain OAuth 2 is under investigation. (The problem is on how to implement DeepLink properly.)
    2. To add a new application, you can either enter all the fields manually by clicking "New," or you can just copy and paste the contents of the config.json file that Box gives you when creating the Application by clicking "New (with JSON)."
  3. After you have added a Box Application, you can go ahead and configure your storage settings.
    1. At this point in time, you can only change the folder where all files go when you upload to Box from your site. You can manually enter in the folder ID, or you can just pick the folder by clicking the "Choose Folder" button. 
  4. When you click that button, a pop-up will come up with the folders in the Box Application's root directory (if you haven't already configured the storage settings.) You can navigate through the folders by double-clicking the folder you wish to navigate to. Unfortunately, there isn't a way to go back one folder yet, so you have to go all the way back to the root folder if you went too deep into the folder structure.
    1. If you're having problems seeing anything, change the Upload folder ID to 0, and that should fix your problem.
  5. When you find the folder you want, select it and click on "Use Folder."
    1. As a side note, you also have the option to create folders as you choose a folder if you want to. Now all the uploaded files will go to this directory.
    2. Note: If you want to come back later and change the upload directory, when you click "Choose Folder," it will automatically populate the list of folders with the folders inside the folder you have chosen for your upload location.
  6. After you've configured this, you can go and use the microflows under _USE ME > User. Here you will find microflows that will add the ability to use Box in your Mendix application.

Files and Folders
A lot of the microflows require a file or folder ID, and it isn't exactly intuitive where you can find these. If a microflow returns a BoxFile, BoxFolder, or a BoxItem object, the file or folder ID will be found in the _id attribute of that object. Also, if you want to find the id to a specific file or folder, navigate to that file or folder in the Box console, and the id will be the last part of the URL. It will be of the form byu.app.box.com/something/123456789. Also note, that the root folder ID will always be 0.)

Folder Structure

It's easy to get lost in the folder structure of the module, so I'll make sure to be as clear as I can about where all the Mendix resources are located in the module.

_USE ME

This is where all the abstracted functionality will be located in the form of pages and microflows. Under the _USE ME folder you'll have two folders named "Administration" and "User." These are named according to the module roles that will be using them. Everything in the Administration folder is for the admin interface, or in other words, it contains all the settings that the administrator would need to be able to control. Everything in the User folder is all the functionality that will be user-facing.

The only thing you'll really ever need to touch in the Administration is folder is the one page in the General folder located in the Pages folder under that General folder. It is named Box_Administration, and it provides a settings page where you can play with the Box Application settings or the Box Storage settings for your site. The other two folders, "Applications" and "Storage" both have the microflows and pages for those settings if you want to tweak those at all.

Under the User folder, there are only microflows that correspond to the various API calls you can make with the Box API. Currently there are only three microflows that can upload, download, or delete a file. Documentation on how to use a microflow is provided in the microflow in an annotation. It won't be in the microflow properties under documentation, because it's not very visible.

API Actions

This folder contains all the Java actions from the original Box Connector Plus module. You can check out more on how these work in the API Examples folder of this documentation.

Demo

This folder contains a small demo for uploading a file. If you want to use this demo for something, then call the ACT_OpenDemo microflow in it in order to open it.

Implementation

This contains all the other resources required for the module to work, such as microflows, rest mappings, constants, and so on. 

  • The API folder contains the microflows that the Java actions in the API actions folder will call in order to complete the API call. 
  • The Common folder has the resources necessary for authentication, such as microflows that will retrieve an access token, or a java action that creates a JWT assertion to request an access token.
  • The Constants folder has constants for all the different Box API endpoints. You can use these if you want to make REST calls yourself. It also has a constant for the log node that this module uses.
  • The Enumerations folder contains the enumerations that various objects in the domain model use.
  • The RestMappings folder contains all the rest mappings that this module uses to convert the API responses into Mendix objects that you can use. They are organized roughly by the different kinds of API calls they're associated with.

Additional Resources

More documentation can be found in Box. This has more documentation on how to use the Java actions found in the API Examples folder.

Dependencies

Installation

  1. Download the module here. It will save as BoxConnectorPlus.mpk
    1. Note: If you are using Mendix Studio Pro 8.8.* or 8.9.* downloading private app store modules/widgets was turned off due to security concerns. All the BYU Private App Store content can still be downloaded from the Company Content page in the Mendix App Store and then imported into those versions of Studio Pro. Upgrading to a newer version of Mendix Studio Pro fixes the problem.
  2. After the download finishes, import Box Connector Plus into your project.
    1. Right click on your Project Explorer
    2. Select Import Module Package
    3. Select the module you just downloaded and click Open

Setup

Before you begin, make sure you have completed all of the setup in the documentation tab. If your app is not correctly configured on developer.box.com, then box will not grant you permissions to read and write to the box applications.

All actions specified below are done through the microflow accessible java action calls. The included microflows with the module are also functional.

Writing Custom Uploads And Retrieval

There are a lot of actions included in the module. Here we will walk you through how to use the main ones.

  1. Uploading a file
    1. This is handled by the box file uploader generally, however if you need this to be part of an automated process there is a microflow action for it.
    2. To implement this, you need:
      1. BoxFolder - this is a box connector entity specifically for use in box actions. All that you need to specify in it is the _id of the folder that you want, and then retrieve the folder you need form box.
      2. System.FileDocument - You should make a generalization of this entity, this will be your upload, which you can get through the file uploader or generated through an automated process.
    3. Use the Upload File action and put both of these in. It should be noted that this is not a chunked upload, and large files will use a lot of your system resources. See Box File Uploader below for our alternative.
  2. Folders
    1. Finding a folder
      1. This is done through the Get Folder Info action
      2. All this required is the _id in a boxFolder entity. Pass this into the action and it will return all of the folder information on that folder. If not folder exists, it will return empty
    2. Creating a Folder
      1. This is done through the Create Folder action
      2. For this you need:
        1. A folder name - This can either be from an entity or manually set in the microflow as a string.
        2. Box Folder Param - This is a boxfolder (found through the above action) that will act as the parent folder for your application.
      3. It is important to not have duplicate names in the same folder, or the box API will return an error when making the second folder. You can avoid this by using the Get Folder Items Action
    3. Get Items in a Folder
      1. This is done through the Get Folder Items Action
      2. All that is required is a full parent box folder that we wish to search. The action itself allows for you to limit how many items are retrieved and the offset of your retrieve, but it is not required.
      3. This will return a list of BoxItems, which can be any type of entity, including a folder.
        1. When checking to see if a folder name exists, check against the 'name' field of this entity, and then save any matches. You cannot use this as a folder, so you will need to use the id from this to get the folder's info.
  3. Collaboration
    1. By default, no user will have access to the folders you created or the application in box. You can grant access to a user through the CreateCollaboration action.
    2. To do this, you will need:
      1. BoxUser - For this parameter, all that needs to be specified is the email of the user you wish to share with, placed in the login field
      2. BoxItem - This is what you want to share with the user. It can be a folder or an individual folder item. Make sure you use a box action to retrieve this and do not make it manually. If you share the parent folder, a user will have access to every upload from your application.
      3. Collaboration Role - This dropdown determines the permissions a user will have when accessing any files from the box site.

Box File Uploader

Because the module does not do chunked upload by default, the box connector plus module has a custom file uploader included when you download the module, which should be accessible from any page. To configure it:

  1. In a microflow, create a ClientUploadInfo. It needs to have the folderId specified for the folder you want to upload into. (If you chose to upload everything into the main folder, this will just be 0)
  2. Pass ClientUploadInfo into a dataview
  3. Place the box file uploader into the dataview
  4. For 'Destination Folder ID' designate the clientuploadinfo/destinationFolder (you can use any entity where you have a folderId saved). Then specify the FileId as where to save the Id of the file you uploaded (this will be important for storing the file location)
  5. Designate what happens after the upload. By default nothing will be saved to your system, it is recommended that your store the Id's of files you want to recall later.