Many organizations use Box as the enterprise storage and collaboration solution for all their documents — including any completed forms. The GoFormz-Box integration automates the process of uploading your completed form PDFs and images to the appropriate folders in your Box account, and lets you associate metadata with these files to make it easier to find the forms you are looking for in the future. 

In this document, we go over the following:

CREATING A NEW BOX CONNECTION

Before you begin, make sure that you have an existing Box account and you know the credentials for the account. To create an Box app connection, do the following:

1. Select Connected Apps from the More dropdown at the top of the GoFormz web app to navigate to the App Connections screen.

2. Click Add Connection next to the Box application block to bring up the Box Authorization window. 

3. Enter your Box credentials (username and password) and click Authorize. This step is omitted if you are already logged into your Box account.

4. On the next screen, click Grant access to Box to complete the integration. This will allow GoFormz to read and write files to your Box account. GoFormz will not manage any of your Box settings.

The new connection will appear on your connections list with a generic name like “Box Connection 3”. We recommend renaming your connection with a more descriptive name (e.g. including your Box username in the connection name), especially if you plan to use multiple Box connections. This will make it much easier to tell your connections apart from each other.

AUTO-UPLOADING FORMS TO BOX

The Box integration works a little bit differently from other GoFormz integrations. Instead of leveraging the Workflow Tab, it uses the Template Events window in the Template Editor. To set up a Box integration that will automatically upload PDFs of your completed forms to your Box account, do the following.

1. Navigate to the Templates Tab and click the form template for which you want to set up automatic Box uploads. The Template Editor will launch.

2. Click the Manage Events link at the top of the editor to open the Template Events window.

3. Click the Add Trigger button to create a new event, or select an existing event to edit it. The event's settings will appear on the right side of the window.

4.  In the When this Happens section, configure the event trigger by selecting a User and a Trigger from the dropdowns. In this example, the event will trigger whenever a user in the Managers group completes a form. Use the Do not run again after form has been reopened checkbox if you only want the upload to occur the first time that the form is completed. See here for more on configuring triggers, including further detail about these settings.

5.  Select Save to Box from the dropdown under Do the Following. The Box integration configuration fields will appear underneath.

6.  Configure the Box integration using the next several fields:

  • Connection: Choose the Box connection that you want to use. This tells GoFormz which Box account will be used for this integration. See above for more on setting up a connection.
  • Pages to Include in PDF: Choose which pages of the form PDF should be sent to Box. You can choose to export All Pages, or a subset of pages that you have previously configured via the Print Configs option in the Template Editor.
  • Destination Folder: Type in the Box folder where your forms should be saved.  If this field is left blank, your forms will be saved directly to the root folder. This field supports GoFormz template variables, which allow you to use form responses to drive the name of the folder where your forms are stored. In the example below, the destination folder is "Work Orders/GoFormz/[Customer Name]", which means that the new form will be stored in a subfolder determined by the customer's name as specified in the form's [Customer Name] field, within the "Work Orders/GoFormz/" folder. If a subfolder with that name does not already exist, GoFormz will automatically create it, effectively building out a folder hierarchy in Box over time.

**Note: It takes several minutes for the Box API to pick up a newly created folder. During those few minutes, upload attempts to the new folder will fail. For instance, in this example, suppose “Company1” is a first-time customer, with no folder configured in Box. With the above setup, when you complete a form with this customer name, it will create the “Company1” folder in Box, and upload the form. However, if you try to upload another form within several minutes of the first, that upload will fail.

7. Optionally, configure any metadata that you wish to associate with your uploaded PDFs. Metadata makes it easier to organize, sort, and filter your forms in Box. There are two ways to add metadata to your Box uploads — Metadata Templates or Custom Attributes. We describe each briefly here. For a more detailed explanation of how to integrate GoFormz templates with Box metadata, read the Using metadata with Box section of this document, which goes over how to set up Box metadata templates, how to make your form fields compatible with them, and some examples.

  • Metadata Template. In the Metadata Template field, enter the name of a metadata template that you created in Box. Then in the Metadata Template Attributes area, enter your Box metadata attributes along with the GoFormz variables that should provide the data for those attributes. The syntax for entering this information is fairly simple. In the example below, we use the “workorderData” template, and we assign the contents of the [Customer Name] and [Work Order Number] form fields to the “Customer” and “Work Order” metadata attributes, respectively.
  • Custom Attributes. In the Custom Metadata Attributes field, enter the desired Box metadata attributes along with the GoFormz variables that should provide the data for those attributes. The syntax is the same as for Metadata Template Attributes. In the example below, we assign the name of the user who completed the form ([USERNAME]) and the contents of the form’s [Date] field to the “User” and “Work Date” metadata attributes, respectively.

11.  Click the Save Changes button at the top to finish setting up the Box PDF upload integration.

APPENDIX: USING METADATA WITH BOX

Box lets you associate metadata with files stored in their cloud storage platform, and the GoFormz-Box integration automates the process of associating metadata attributes with uploaded forms. The metadata can include the actual data captured when a user completes a form in GoFormz.

This short tutorial will walk you through the details of associating Box metadata with your uploaded forms.
 
 Prerequisites
 Why use metadata in Box?
 Setting up the Metadata Template in Box
 Configuring Metadata Templates in GoFormz
 Using Custom Metadata
 Troubleshooting your Metadata setup

Prerequisites

Before you can use the metadata functionality, you must do the following:

We also recommend that you familiarize yourself with the Sample Work Order template, which is a demo template that comes with your GoFormz account. The explanation below will use this template as an example.

Why use metadata in Box?

Metadata lets you associate custom attributes with your forms in Box. These attributes make it easier to organize, sort, and filter your forms. For instance, you may have metadata fields for the name of the employee who submitted a form, and the name of the customer. This allows you to filter your forms in Box based on the user name and/or the customer name — so if you want to pull up all forms filled out by John Smith for Acme, Inc, you can easily do so.
 
There are two ways that you can use metadata with Box — Metadata Templates, and Custom Metadata. We go over both methods here, but we recommend using Metadata Templates.

  • The advantage of Metadata Templates is that you can filter on attribute values from a Metadata Template, whereas you cannot filter on Custom Metadata attributes. Since filtering is one of the main reasons to use metadata, this is a major advantage.
  • The drawback of Metadata Templates is that there is a little bit of extra work that needs to be done in Box in order to set up a template. For Custom Metadata, no setup is needed in Box. However, this is a one-time setup, so this drawback is minor.

For this reason, we recommend using Metadata Templates rather than Custom Metadata.

Setting up the Metadata Template in Box

Setting up a Metadata Template in Box is easy, and Box has some good documentation on template creation here. We will skip the details of template creation and go over the final result, as well as two key details that pertain to the GoFormz integration. Note that you do have to be an admin in your Box account in order to create a Metadata Template.
 
Below is a screenshot of what a simple Box Metadata Template might look like. This template has just three attributes — Customer, Work Order, and User. These are meant to correspond to the [Customer Name] and [Work Order Number] fields from the Sample Work Order template in GoFormz, and the [USERNAME] GoFormz variable; we’ll come back to that in the next section.

The following two details are key when setting up the GoFormz integration:

1. Make sure to use the appropriate Format for each attribute. Box Metadata Templates have 4 attribute Format types — Text, Number, Date, and Dropdown. The Text attribute will work with all GoFormz fields, so use that when in doubt — but if you want enhanced filtering functionality, you may want to use other Format types. For instance, with a Date attribute, you will be able to find all forms within a particular date range in your Box account. You would not be able to do this with a date that is stored as text in a Text attribute.

Below is a list of all Box Format Types and the GoFormz Fields supported by each one.

Box Format Type: Text

  • Supported GoFormz Fields: Text Box, Date, Date Time, Time, Checkbox, Checkbox Group, Database, Drop Down, Number, Auto Number, Location
  • Note:  For Location, only text display of latitude/longitude is supported at this time.

Box Format Type: Number

  • Supported GoFormz Fields: Number, Auto Number
  • Note:  Only numeric characters are supported — no special characters.

Box Format Type: Date

  • Supported GoFormz Fields: Date, Date Time
  • Note:  For Date Time, only the date will be recorded to Box; the time will be dropped.

Box Format Type: Dropdown

  • Supported GoFormz Fields: Drop Down, Checkbox Group, Database
  • Note:  Your Box Dropdown option text must match the value of the GoFormz field exactly in order for this to work.

2. Note down your template name from the URL. You will need this to identify the template in GoFormz. In the example image above, the template name is “Work Order Data”, but the name that appears in the URL is “workOrderData” — the capitalization and spacing are a bit different. Make sure to use the name from the URL when setting up the GoFormz integration.

Configuring Metadata Templates in GoFormz

When setting up your GoFormz template to upload to Box using the Template Events dialog (see below), you will see two optional fields — Metadata Template, and Metadata Template Attributes. If you do not see these fields, please submit a request to GoFormz Support to activate metadata for you.

In the Metadata Template field, enter the name of your Box Metadata Template as it appears in the URL — which will often differ slightly from the name that you gave it. In this example, it’s “workOrderData”, rather than “Work Order Data”.
 
In the Metadata Template Attributes field, enter your Box metadata attributes, along with the GoFormz form fields that should provide the data for those attributes. The syntax for entering this information is very simple. Consider the following example:

Customer=[Customer Name]

“Customer” before the “=” sign is the name of your Box template attribute (see the previous section on “Setting up the Metadata Template in Box”). “Customer Name”, in brackets after the “=” sign, is the name of the GoFormz field in the Sample Work Order form template where users will enter the customer name. This syntax tells GoFormz that the “Customer” attribute of the “workOrderData” Metadata Template in Box should receive its value from the “Customer Name” field of your form.

If you have multiple attributes in your template — as you typically will — you can simply replicate the syntax above and separate the values with a pipe symbol — “|”. For example, we can add the “Work Order” attribute, as follows:

Customer=[Customer Name]|Work Order=[Work Order Number]

You can also use GoFormz form metadata variables like [USERNAME] and [COMPLETEDDATE] to create Box metadata tags. To complete our Box template example, let’s add the username:

Customer=[Customer Name]|Work Order=[Work Order Number]|User=[USERNAME]

Once you enter the metadata, simply click the Save Changes button at the bottom of the Template Events screen, and you’re done!
 
To test out the functionality, launch the GoFormz mobile app, select the Sample Work Order template, fill out the form, and click Complete when done. Then go to Box, and you should see the metadata associated with the form, as shown below.

This metadata information can be used to power advanced document searching/filtering as part of your Box workflow. This is a simple, yet powerful, example of how to implement metadata within your Box account.

Using Custom Metadata

To configure a GoFormz template to send Custom Metadata to Box, simply fill in the optional Custom Metadata Attributes field in the Template Events dialog when going through the Box upload workflow. This is shown in the screenshot below. Unlike with Metadata Templates, no advance setup in Box is required when using Custom Metadata.

The syntax for specifying the mapping of Box attributes to GoFormz fields is exactly the same as for the Metadata Template Attributes field (see "Configuring Metadata Templates in GoFormz" section above), with the exception that the name of the Box attribute can be anything — there are no restrictions on the attribute name, since there is not template that it must match.
 
Remember that Custom Metadata fields cannot be used to filter/search documents in Box. For this reason, we recommend using Metadata Templates rather than Custom Metadata for most use cases.

Troubleshooting your Metadata setup

If your Box metadata fields are not populating, here are a few common gotchas to look for:

  • Make sure your Metadata Template name is correct. The template name you specify in the GoFormz Template Event should be the name that appears in the Box template URL — NOT the Box template name!
  • Make sure your template attribute names are correct. The names of the Box template attributes you specify in GoFormz should match exactly the names of the attributes in your Box Metadata Template.
  • Make sure your GoFormz field names are correct. The field names that you specify in your metadata mapping are case-sensitive and should exactly match the GoFormz field names.
Did this answer your question?