Automating Metadata Management using Box Cascade Policies

Published in

Box Developer Blog

6 min readMar 21, 2023

As a Box administrator (or any user with editor permissions), you can use the metadata cascade policy to set metadata at a folder level and have it automatically propagate through the content.

If you are curious how we got here check out our previous article on "Getting started with Box Metadata Administration".

Metadata Cascade Policy

The metadata cascade policy allows you to set metadata at a folder level and have it automatically propagate through the content.

Not only it will associate a specific template to the content, but can also populate its attributes with the same values from the folder it was applied.

This way, as users upload or move content into the folders subjected to a metadata cascade policy, the metadata is automatically populated.

Sample Use Case

Suppose you have requests from multiple departments to quickly locate invoices and contracts stored at Box.

These have often cryptic names, the normal search by text returns too many unrelated items, and users complain it takes a lot of effort in to identify the correct item.

Customer Success want to be able to locate contracts and invoices by customer name.
Finance wants to locate all invoices, independent of customer.
Legal wants to locate all contracts.
You want to keep a single copy of each document in one place using the original name.

You have a "Customers" folder, with folders "ACME Corp" and "Stark Industries" inside.

For each customer you have another set of folders "Contracts" and "Invoices".

You want to create a metadata cascading policy that automatically stamps each file with the customer name (ACME, Stark, etc), and the document type (Invoice or Contract).

Administration tools

Although everything presented in this article can be accomplished in the Box app, we are always thinking about scale, and if you want to do this at scale (think hundreds of items) the best tool for a Box Administrator is the Box CLI.

Check out our Box CLI guides on how to get started.

Implementation

First let's create a metadata template using the CLI. This represents the metadata structure we want to use.

For this example we simply want a text field to hold the customer name and a single select field to hold the document type for "Contract" or "Invoice":

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

Resulting int this output:

ID: 56ea51b8-ce40-4aed-852b-a176d076896c
Type: metadata_template
Template Key: customerData
Scope: enterprise_877840855
Display Name: Customer data
Hidden: false
Copy Instance On Item Copy: false
Fields:
    -
        ID: a98b2412-dcd9-46ad-bc1f-6da24877ec14
        Type: string
        Key: customerName
        Display Name: Customer Name
        Hidden: false
    -
        ID: b1eedd5e-bb95-4a6b-9032-e40cabc448d1
        Type: enum
        Key: documentType
        Display Name: Document Type
        Hidden: false
        Options:
            -
                ID: 4e317f48-b3c2-4c1a-a3b6-67eb4026b18c
                Key: Contract
            -
                ID: d2570209-f92c-465e-b1a1-9e04ccf2c9f9
                Key: Invoice

Now let's identify the folders under the "Customers" (195808887286) folder. I'm using --csv --fields type,id,name flags to make it easier to display:

❯ box folders:items 195808887286 \
--as-user 18622116055 \
--csv --fields type,id,name
### output ###
type,id,name
folder,195812577701,Acme Corp
folder,195808702433,Stark Industries

❯ box folders:items 195812577701 \
--as-user 18622116055 \
--csv --fields type,id,name,parent
### output ###
type,id,name,...,parent.name
folder,195811920048,Contracts,...,Acme Corp
folder,195811116086,Invoices,...,Acme Corp

❯ box folders:items 195808702433 \
--as-user 18622116055 \
--csv --fields type,id,name,parent
### output ###
type,id,name,...,parent.name
folder,195809191381,Contracts,...,Stark Industries
folder,195813852815,Invoices,...,Stark Industries

Next we apply the metadata to the "Acme Corp/Contracts" (195811920048) folder using:

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

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

We can check the folder metadata:

❯ box folders:metadata:get 195811920048 --template-key customerData \
--as-user 18622116055  --csv
### output ###
customerName,documentType,...
Acme Corp,Contract,...

Finally we turn on the cascade metadata policy:

❯ box metadata-templates:cascade customerData --folder 195811920048 \
--as-user 18622116055 --csv
### output ###
id,,,,parent.type,parent.id,scope,
MTk1ODExOT...YTkyMDFkNw,,,,folder,195811920048,enterprise_877840855,

In the Box app, the metadata for the folder is now associated with the template, the attributes are set, and the cascade policy is turned on:

In our example the folders were just created and are empty. However you may need to force apply the cascade policy to the existing items.

If the items were already associated with the template, you must decide on a conflict resolution between none or overwrite meaning, keep the existing template attribute values or overwrite any existing value with the new ones:

❯ box metadata-cascade-policies:force-apply MTk1ODExOT...YTkyMDFkNw \
--conflict-resolution overwrite \
--as-user 18622116055 --csv
### output ###
Successfully applied policy MTk1ODExOT...YTkyMDFkNw

Using the example above let's implement the metadata cascade policy to the other folders. You can even build a simple shell script to automate these steps.

Folder "Acme Corp/Invoices":

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

❯ box metadata-templates:cascade customerData --folder 195811116086 \
--as-user 18622116055 --csv
...,owner_enterprise.id,parent.type,parent.id,scope,templateKey
...,877840855,folder,195811116086,enterprise_877840855,customerData

Folder "Stark Industries/Contracts":

❯ box folders:metadata:add 195809191381 \
--template-key customerData \
--data "customerName=Stark Industries" \
--data documentType=Contract \
--as-user 18622116055 --csv
### output ###
customerName,documentType,...
Stark Industries,Contract,...

❯ box metadata-templates:cascade customerData --folder 195809191381 \
--as-user 18622116055 --csv
### output ###
...,owner_enterprise.id,parent.type,parent.id,scope,templateKey
...,877840855,folder,195809191381,enterprise_877840855,customerData

Folder “Stark Industries/Invoices:

❯ box folders:metadata:add 195813852815 \
--template-key customerData \
--data "customerName=Stark Industries" \
--data documentType=Invoice \
--as-user 18622116055 --csv
customerName,documentType,...
Stark Industries,Invoice,...

❯ box metadata-templates:cascade customerData --folder 195813852815 \
--as-user 18622116055 --csv
### output ###
...,owner_enterprise.id,parent.type,parent.id,scope,templateKey
...,877840855,folder,195813852815,enterprise_877840855,customerData

And we upload some files into the folders:

❯ box files:upload --parent-id 195811920048 \
./acme_contract.txt \
--as-user 18622116055 --csv
### output ###
type,id,name
file,1147571642464,acme_contract.txt


❯ box files:upload --parent-id 195811116086 \
./acme_invoice.txt \
--as-user 18622116055 --csv --fields type,id,name
### output ###
type,id,name
file,1147572999246,acme_invoice.txt


❯ box files:upload --parent-id 195809191381 \
./stark_contract.txt \
--as-user 18622116055 --csv --fields type,id,name
### output ###
type,id,name
file,1147578288128,stark_contract.txt


❯ box files:upload --parent-id 195813852815 \
./stark_invoice.txt 
--as-user 18622116055 --csv --fields type,id,name
### output ###
type,id,name
file,1147575581165,stark_invoice.txt

Your users will now see the metadata automatically being applied to the files just uploaded.

metadata was automatically applied to the file

And now all your users can find exactly what they are looking for:

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:

Legal wants all contracts:

Sales heard about this new possibility, and also wants to use it to locate the contract for "Stark Industries":

No files were changed, copied, moved or renamed in this process. You were able to improve your users efficiency and kept the original structure of the content.

References

If you want to learn more about Box Metadata check out these links:

Articles in this series: