Let’s talk about using Box Platform for Box.org

Recently, I had a chance to work with Box.org, which is the part of Box where we (as Boxers) can drive social impact and change through our work. It is an all around brilliant and essential part of Box. Previous to now, they had an application process for Box Impact Fund with some time consuming steps like manual data input. So, I produced a script using one of our SDKs to analyze and extract the data into a CSV, allowing the administrators to add new entries to a tracking Google Sheet shared across the Box.org team. In this article, I outline the solution and also provide ideas and prototypes on how other parts of the Box API Platform could be helpful in managing the process and reducing manual steps.

The basic flow of the application process is as follows.

1. Charities can apply for a Box Impact Fund grant by submitting an application to Box. This is done via a File Request Link which can be configured and setup by any Box user and provides a great way of securely and easily receiving content from people who are not part of your organization.
2. With the application, an applicant submits a short video to provide further context about their charity, as well as how they would put a potential Box grant to good use. This is stored along side the video in a Box Metadata Template in a designated Box Folder. A task is automatically created for the application.
3. A select team of Boxers screen the applications based on the task generated in step 2, moving the best to the next stage where a deeper evaluation will narrow it down to twelve finalists.
4. A judging panel made up of industry experts and several Boxers selects the final six that receive a grant. Read more about Box Impact Fund and judging panel

The screening and approval tasks are all done via Box Relay, the intuitive workflow tool, where workflows can be configured configured by a Box user directly in the Box Webapp. The Relay workflow is configured to create a task when a user uploads via a File Request link.

Screen shot of Relay

Along side the Relay tasks a Google Sheet stored in Box is used to allow the Box.org members to see all the applications (including associated metadata). It also lets them jump to each application and simultaneously review and also score applications as Box fully supports co-authoring on Google Sheets.

The process looks like this today:

Script to extract applications

This is where I first got the help out. The Box.org team needed to get the documents and metadata from the applicants into the tracker Google Sheet and needed this automated. Given the tight deadline at the time I created this script that generates a CSV file for Box.org admins to transfer new applications to the tracker Google Sheet. Although the application process asks for a single file, some applicants will upload multiple files, so this script creates a CSV of the unique applications in the application folder. It is written using our Java SDK and created as simple jar that can be invoked from the command line allowing the administrator in charge flexibility to decide when they want to extract new applications.

The file request that is used for collecting applications stores all application video files with relevant metadata in a Box landing folder. This script iterates all files in that folder and outputs one line per unique applicant (based on email address), includes metadata and a link to open the application in Box.

This GitHub repo has a maven project that allows you to setup, build and execute the jar file.

This is a sample of what the output would look like. This can then be pasted direcly to the tracker spreadsheet.

Future -> Box Metadata Query UI

The next step for the supporting the overall process would be to provide a UI based approach to viewing the applications and processing tasks. I also added an option to export the CSV file for the tracker instead of the Box.org admin team having to use the terminal to do this.

To achieve this, I build a prototype metadata query filter UI using our Box UI elements. Box metadata query API allows you to query for all files based on metadata criteria and allow filtering (via query parameters) which is used in this prototype. Box UI elements are javascript widgets that provides easy access to Box functionality from custom applications. Check out these great articles for more info: UI Elements workshop, UI Elements with React, Metadata Query API and Metadata Query with UI Elements

The prototype also provides functionality to export of the CSV directly from the interface rather than having to go the command line terminal to export. This is done by providing a button that when clicked will run the current query and export the results to a dynamically generated CSV file.

The buttons across the top will allow a user to filter on stage of the application — ‘Not Screened’, ’Rejected’, ’Second Stage’ and ‘Finalists’ and the results window provides direct preview the application videos and interact with the Box Relay tasks from the same window. This is useful when a user wants a quick overview by filtering the existing applications without opening the main GSheet tracker.

To get a metadata query to load in a UI element I define the metadata fields I want the query to return, the query definition itself and the fields I want the user to see in the app.

The fields can be both file properties and specific metadata fields from a single metadata template. In the below example “created_at”, “name” and “uploader_display_name” are basic file properties where as the fields starting with “metadata…” are metadata fields filled in by the applicant who submitted the application via the File Request. (The EID is a reference to the unique ID of the Box instance the API is connecting to. You can get this from the Box developer console under your apps General Settings).

fields=[
"created_at",
"name",
"uploader_display_name",
"metadata.enterprise_<eid>.boxImpactFundApplication.applicantName",
"metadata.enterprise_<eid>.boxImpactFundApplication.approvalStage","metadata.enterprise_47757585.boxImpactFundApplication.organizationName",
"metadata.enterprise_<eid>.boxImpactFundApplication.organisationCategory",
"metadata.enterprise_<eid>.boxImpactFundApplication.totalBudgetFromLastYear",
"metadata.enterprise_<eid>.boxImpactFundApplication.regions"]

The query definition looks like the below. It defines the metadata template to use, the query string , the folder to base the query in and the fields defined above.

  mdQuery = {
    //The from field specifies the metadata template to query
    from: "enterprise_<eid>.boxImpactFundApplication",
    //The query filters the results
    query: "approvalStage1=:approvalStageArg",
    //Limit the number of results returned (more results can be fetched using marker based pagination)
    limit: 100,
    //The query parameters for the query filter - in this case approval stage
    query_params: {"approvalStageArg":approvalStage},
    //The Box Folder id of the application folder
    ancestor_folder_id: <folder to start the query from>,
    //An array of fields to fetch 
    fields: fields
};

To get the UI element to show the results of the query I define which fields to show — note any field referenced here must be defined in the fields data above. Here I can add both file properties and metadata fields, provide display names and even allow inline editing of the fields. Not something this prototype requires but handy for lots of use cases.

const fieldsToShow = [
  { key: 'created_at', displayName:'Submission Date',canEdit: false },
  { key: 'uploader_display_name', displayName:'Email',canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.applicantName',displayName:'Applicant Name', canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.organizationName',displayName:'Organization Name',  canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.organisationCategory',displayName:'Organization Category',  canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.totalBudgetFromLastYear',displayName:'Last years budget',  canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.regions',displayName:'Regions',  canEdit: false },
];

Putting the above parts together to make the display I use the Content Explorer UI element. This will normally display contents of a folder but by configuring the ‘defaultView’ to ‘metadata’ I can show the results of a metadata query instead of the contents of folder.

const defaultView = "metadata";
  contentExplorer.show(boxId, token, {
    container: '#nav-container',
    metadataQuery: mdQuery,
    defaultView: defaultView,
    fieldsToShow:fieldsToShow,
    contentPreviewProps: {
        contentSidebarProps: {
            hasActivityFeed: true,
            hasMetadata: true
        }
    }

Here is a link to the repository in GitHub with step by step instructions for setting up the page, the authentication and the web app integration feature.

Putting it all together

This flow shows how the process would look with the new features added where both Admins and Screener can use the custom app to access, review and process applications. Since there is logic in the Gsheet tracker around the scoring of applications I have left this as is for the last part of the process.

It was a pleasure working with the Box.org team to help them streamline their processes and hopefully I can improve the process even more for this year.

Thoughts? Comments? Feedback?

Drop us a line on our community forum.