Let’s talk about integrating Box
As part of my job as a Platform Solutions Engineer at Box, I often hear developers and customers ask something like “…how can I integrate Box with my application…”, “…how can I surface Box content to my end users in my custom app…” , or “..can the Box API integrate with <<insert framework, identity management provider or other system here>>…”
In this article, I will outline the most common approaches to surface Box content to users in custom apps and integrations, outline the advantages and challenges with the different approaches, and discuss use cases they address. There will also be plenty of links to resources for deeper dives, GitHub repositories and code samples for those of you who wants to try it yourselves.
Before I start discussing how we can build integrations with Box, I should mention that Box actually offers about 1500 pre-built integrations, so a lot of customers will find what they need there. These integrations are designed to be configured easily by a non-developer, and the most popular integrations are Slack, Teams, Office 365, and NetSuite to name a few. These integrations are not the focus of this article but a good starting point to understand what type of integrations already exist.
In this section, I will start with the most common API driven integrations and towards the end I will show some of the ways you can integrate a Box experience directly without coding, using features available in the box.com application.
Box UI Elements
Box UI elements are where most developers start when looking at integrating Box with custom applications that have a user interface. These are React based javascript widgets that can work with most websites. Since they are loaded directly in your code, they can be interacted with to drive further functionality on the websites via a series of client side events. They are open source, and the source is available on GitHub. They are developed and maintained by Box, as well as distributed via npm.
A UI Element ‘only’ needs an access token and the Box identifier of the Box file or folder involved, the rest is managed by the widget. See this excellent post about how to get started with UI Elements and React or this for UI elements and Python.
The most common UI element is the content explorer which can be used to represent a Box folder in a custom application. It allows the user to navigate, upload, download and preview (while respecting user permissions) in a completely white labelled way if required.
So this code snippet…
…could look like this in a portal environment…
…opening a document would bring up the unique Box Previewer…
UI Elements also contain a content picker where users can select files or folders allowing integrations into wizard or step-by-step type features where a Box file or folder is part of the data flow. Finally there is an upload widget, allowing users to upload content only.
Common use cases:
- Secure Document Vault where eg. bank customers can store, retrieve and collaborate on sensitive and secure documents. See this case study for Morgan Stanley.
- Customer/vendor/contractor portals where the secure exchange and collaboration on documents is a central feature. See this case study for Broadcom.
- Loan application or onboarding scenarios where Box can be used as a single content layer avoiding content sprawl through different systems and email. See this case study for Maxwell.
- Presenting Box content in Salesforce Digital Experiences. This works well in conjunction with our standard Box for Salesforce composite app. Check out this GitHub repository to get started. Also see this case study for the Town of Cary.
Advantages
- Quick time to market
- Once UI Element are loaded on the client, all traffic including upload/download goes from the client to Box saving both CPU and network resources for the application host.
- UI Elements are maintained by Box so fixes and new features are added regularly.
- The preview UI Element allows preview of over 140 formats without the need for plugins thus avoiding time consuming downloads and allowing a more secure document sharing approach (such as preview only permissions and watermarking)
- Works with any existing identity provider. See working examples for Auth0, Okta, Cognito and AzureB2C
Challenges
- UI elements is designed for speed of implementation so overall style and functionality is mostly fixed.
Box REST API/Box SDK
The Box REST API allows a developer to access all Box content services which means that if a they need to expose content to users in a custom application it is all there. Built on top of the API are the Box SDKs, built and maintained by Box SDK Engineers and covering the most popular programming languages, as well as iOS and Android for mobile development. So a developer can present the same list of files as in the above UI Element example, but using another UI approach like Data Tables or even a Tree View just by using the ‘folder items API’ and their favorite language or direct REST calls.
Below is an example of using Data Tables to show the same list of files from the previous example including a piece of custom metadata I have added to the documents (Document Type). The API approach gives greater flexibility in terms of interacting with and displaying information and using preferred UI frameworks.
Here is another example where a tree view has been created from the output of the Box API and integrated with the Box Previewer.
Common use cases:
- The use cases are basically the same as listed for UI elements
Advantages
- Using API and Box SDKs gives the developer the choice of UI framework and ability to be very precise around the design and display.
- Works with any existing identity provider. See working examples for Auth0, Okta, Cognito and AzureB2C
Challenges
- Normally requires more development effort than using UI Elements.
Of course the Box API, Box SDKs and Box CLI can also be used to drive integrations where there is no direct user interaction required and it is primarily a question of automation and machine to machine interaction.
Authentication
Couple of words about authentication. The Box API supports two ways of API authentication: Client side 3-legged OAuth and server side authentication with JWT or Client Credentials Grant. The client side authentication is great when the users accessing the API integration are already Box users with a Box login. For scenarios where Box API is being surfaced in applications where users have already logged in via another identity management system, server side authentication works well as it avoids the user having to login twice as their user authentication would be orchestrated via API. Read more about user models and our app user concept which will allow you to integrate Box with any identity management provider easily. (This will be the focus of a future article…let’s talk about app users)
In this part I will cover some of the ways you can integrate Box without necessarily using the API. These are options offered in our main Box Web experience.
Box Embed
For customers who already use Box and want to embed a certain Box folder or file into the user experience of another app, we offer an embed widget that can be generated directly from the UI or the API. This type of embed can be configured to be open for all or require the user to authenticate and has some configuration options. The embed widget basically exposes part of the box.com experience in an iframe.
From box.com a user can configure the widget
Add the embed code to a web page
End result is a folder embedded in the portal
Common use cases:
- Showing a folder of common documents in another context such as HR portal, public internet or another application
- Showing a folder of project documents in project management portal
Advantages
- Requires no coding to create and configure
- Includes most common Box Content functionality — browse, view, upload, download, search, commenting, tasks etc.
Challenges
- Iframe embed approach means little scope for client side interaction with the embedded component mainly due to cross site scripting limitations
- Little scope for changing look and feel of the embedded component as it is always loaded from box.com and currently does not offer 100% with the user experience in box.com
- Either the content must have has open access or it requires that users have a Box account to access it.
Box File Request
With Box File Request users can create an upload page with some configuration (including logo, colors and option for mandatory metadata) to email directly to users or embed in a website. The page can be created from the Box UI or can be copied from existing File Request via API. Anyone with the link can then upload documents but do NOT have to authenticate to Box unless specified in the configuration.
From box.com a user can configure a file request on a folder
Add the link to an iframe on the site
End result is a Box File Request embedded in the portal
Use cases
- Getting documents from transient users, eg. onboarding documents, documents from partners/contractors, public evidence gathering portals for law enforcement
- Uploads that require mandatory metadata
Advantages
- Requires no coding to create and configure and no login for end users
- Integrates nicely with Box Relay
Challenges
- Iframe embed approach means little scope for client side interaction with the embedded component mainly due to cross site scripting limitations
Finally
Thanks for reading this far. I hope you now have a good understanding of how Box can be integrated into your apps. I have peppered links to valuable resources throughout the article but as ever a great place to start is developer.box.com. Enjoy the journey and see you next time for a deep dive on app users and why they are great.
