Box Developer Blog
Published in

Box Developer Blog

Getting started with Box Metadata Administration

This article explains how metadata is a critical tool for bringing data into focus and making it useful to users in Box. Check the references below for links to the documentation.

As a Box administrator, you can define the structure of the metadata you want to associate with the content by creating a metadata template, and then associate it with the content, creating a metadata instance.

With the right metadata, data can be transformed into actionable information, and metadata search enhances the search by metadata attributes, making it specific to users’ needs.

Metadata is a critical tool for bringing data into focus and making it useful to your users. It provides context to data by giving information about its source, purpose, and meaning.

With the right metadata, content can be transformed into actionable information.

Metadata can include descriptions, tags, labels, and other attributes that help make data meaningful. It can also include identifiers, classifications, and other information that can help you integrate with other systems.

How does it work

Box metadata components

As an administrator, your first task is to define the structure of the metadata you want to associate with the content, creating a metadata template.

Then the template can be associated with the content, creating a metadata instance.

Finally your users, a service or even programmatically, can populate the metadata attributes for the specific content.

Metadata Templates

Templates represent the structure of the metadata you want to capture. You can have many and apply multiple templates to your data.

Each template can have attributes representing text, date, numbers, single selection and multiple selection.

To create a template, navigate to your administration console, content, and metadata.

creating a metadata template

When used for search, text types allows for partial matches, while date and numbers allow for interval searches.

The single select dropdown allows choosing one option from the list with the possibility to have none selected. The options can be custom sorted.

configuring a single select dropdown attribute

The multi select dropdown, works the same way, but allows for multiple selections.

configuring a multi select dropdown attribute

You can custom sort the attributes and even hide the template. This is useful if you want the template to be exclusively used by a service or integration, hiding the template and the metadata from your users.

You can create templates programmatically by using the Box CLI, the REST API or one of our SDK's.

Here is an example using the CLI:

❯ box metadata-templates:create --display-name "Customer data" \
--string "Customer Name" \
--enum "Document Type" --option Contract --option Invoice

The above command is creating a metadata template named "Customer Data" with a text attribute "Customer Name", and a single select dropdown "Document Type" with "Contract" and "Invoice" as options.

If you plan for your users to be the ones filling in the metadata, consider how creative user can be with free text, and also how many attributes they have to populate.

Inconsistent or empty metadata will reduce the efficiency of having a bulk process depending on it, or even the enhanced metadata search of Box.

Metadata Instances

A metadata instance represents the association of a metadata template with a content item, e.g. a file or folder in Box. An item can have multiple instances as long as they are from different templates.

a document with two metadata instances from two different templates

The above image is how a user would create a metadata instance in Box, however this can also be done in bulk or programmatically.

For example, using the Box CLI to associate the template "Customer Data" to the folder with id=195811920048 :

❯ box folders:metadata:add 195811920048 \
--template-key customerData \
--data "customerName=Acme Corp" \
--data documentType=Contract \
--as-user 18622116055 \
### output ###
Acme Corp,Contract,folder_195811920048,...

The above command, not only associated the metadata template to the folder, but also populated the metadata attributes customerName and documentType at the same time.

Resulting in:

Like before you can further automate this process.

For example, in this article, we demonstrated how to use an external service to automatically fill in the metadata of media files with 50+ attributes.

In a future article, we will discuss how to populate metadata using Box metadata cascading policies. Be sure to check it out.

Metadata Search

Once you have metadata on your content, the immediate out-of-the-Box benefit is the enhanced search by metadata.

The normal search looks for a string in the name, description, tag, content, and is a "fuzzy" search. It often return too many results forcing the users to put some effort in finding what they want in the search results.

On the other hand a metadata search, aka metadata filters, is specific to the metadata attributes.

Consider this scenario, you have customers folders with invoices and contracts documents.

These documents typically have cryptic names that may mean something to the company who issue them, but mean nothing to your users. Also their content is fairly common, making it hard to distinguish between them in the search.

Now imagine some of your users want all content by customer name, others want all invoices and yet another group wants all contracts.

To demonstrate this, I've created a simple template with customer name and document type, let's see the search working:

Sample document metadata:

document with customer metadata populated

Customer Success wants all invoices and contracts related with “Acme Corp”:

both contract and invoice show up for “Acme Corp”

Finance wants all invoices independent of company:

all invoices are located

It is not uncommon for Box admins to facilitate further integrations using metadata. Consider you can have references or unique identifiers in metadata and easily integrate with other apps or databases.


If you're looking for more information on metadata, be sure to check these links:

Articles in this series:



News and stories for working with the Box APIs

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store