Box lets you associate metadata with files stored in their cloud storage platform. This short tutorial will help you integrate your GoFormz templates with Box metadata.
The concept is simple. You can set up workflow rules in GoFormz to automatically create metadata attributes in Box, which will populate with actual data captured when a user completes a form in GoFormz.
 Why use metadata in Box?
 Using Metadata Templates
 Setting up the Metadata Template in Box
 Configuring Metadata Templates in GoFormz
 Using Custom Metadata
 Troubleshooting your Metadata setup


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 major 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.

Using Metadata Templates

Configuring Box metadata in GoFormz is part of the workflow for setting up your GoFormz template to upload to Box whenever a form is completed. This workflow is described here. We only describe the metadata portion of the workflow here, so please refer to the other document for more on the workflow as a whole.

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 here, 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 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, as well as the generic [USERNAME] GoFormz field; we’ll come back to that in the next section.

The following two details are key for 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. Each of these supports a different set of GoFormz field types, mapping to GoFormz fields as follows:

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 the template name in the URL. You will need this to identify the template in GoFormz. In this example, the template name is “Acme Data”, but the name that appears in the URL is “acmeData” — the capitalization and spacing are a bit different. Make sure to use the name from the URL in GoFormz.

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 “acmeData”, rather than “Acme Data”.
In the Metadata Template Attributes field, enter your Box metadata attributes, along with the GoFormz data 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 template where users will enter the customer name. This syntax tells GoFormz that the “Customer” attribute of the “acmeData” 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 generic GoFormz fields 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 button at the bottom of the Template Events dialog, and you’re done!
To test out the functionality, simply 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 could 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, there is no need to set anything up in Box 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, with the exception that the name of the Box attribute can be anything — there are no restrictions on the attribute name.
As stated earlier, 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 GoFormz 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 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.
  • Look at your email notifications. Check any email inbox specified in the “Error Notification Emails” section of the Box workflow setup to see if you got an error notification.
Did this answer your question?