Create Metadata Templates with Box CLI

There seems to be a lack of documentation around the Box CLI and I recently had a request to build a Metadata Template that had a dozen fields and a few of the multiSelect fields needed over 100 values. If you've ever created a Box Metadata Template in the Box Admin web-interface, you know that repeatedly clicking the "Add Option" button and having to fill in the text for each option is painful if you have more than just a few options...thus my immediate move to the CLI.

I have seen the --bulk-file-path option many times but I cannot find ANY documentation on how to use it. One would think that the json output from the API or even the CLI with: box metadata-templates:get [templatekey] --json would be the correct format for creating a new template. So using this layout, I went to work creating this massive template and after checking my json with jsonlinter, I attempted to create the template.

I ran: box metadata-templates:create --bulk-file-path=[pathtotemplate].json -v

The first error:

TypeError: Expected input file to contain an array of input objects, but none found

So I took the json object and wrapped it with an array by adding square brackets [ ] around it. Now it works! Somewhat.

The template was created, but the template displayName was set to the displayName of the last of the "fields" and there were no fields created in the template.

I then completely tore apart the json down to the most basic form and tried a simple test template I named "temp.json"

[{
    "type": "metadata_template",
    "templateKey": "testing",
    "scope": "enterprise",
    "displayName": "Testing Template",
    "hidden": false,
    "fields": [
        {
            "type": "string",
            "key": "department1",
            "displayName": "Department",
            "hidden": false
        },
        {
            "type": "string",
            "key": "documentType",
            "displayName": "Document Type",
            "hidden": false
        },
        {
            "type": "string",
            "key": "fiscalYear",
            "displayName": "Fiscal Year",
            "hidden": false
        }
    ]
}]

Then I ran the create again on the temp.json file: box metadata-templates:create --bulk-file-path=temp.json -v

And here is what the template looks like:

ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type: metadata_template
Template Key: testing
Scope: enterprise_xxxxxx
Display Name: Fiscal Year
Hidden: false
Fields: []

None of the fields loaded, and for some reason the "Display Name" of the template is set to "Fiscal Year" ???

Looking at the verbose output you can see this:

box-cli:execute Executing in bulk mode argv: [
  box-cli:execute   '--verbose',
  box-cli:execute   '--scope=enterprise',
  box-cli:execute   '--template-key=testing',
  box-cli:execute   '--scope=enterprise',
  box-cli:execute   '--display-name=Testing Template',
  box-cli:execute   '--no-hidden',
  box-cli:execute   '--display-name=Department',
  box-cli:execute   '--no-hidden',
  box-cli:execute   '--display-name=Document Type',
  box-cli:execute   '--no-hidden',
  box-cli:execute   '--display-name=Fiscal Year',
  box-cli:execute   '--no-hidden'
  box-cli:execute ] +0ms

It just appears to be overwriting the --display-name and it never creates the fields at all.

Am I missing something? Has anyone had any success with creating a Metadata Template using --bulk-file-path?

On a hunch, I decided to try the API so I did: box tokens:get and used the generated token with a curl call to the Box API.

curl -X POST "https://""api.box.com/2.0/metadata_templates/schema" \
     -H "Authorization: Bearer $(box tokens:get)" \
     -H "Content-Type: application/json" \
     -d '{
    "type": "metadata_template",
    "templateKey": "testing",
    "scope": "enterprise",
    "displayName": "Testing Template",
    "hidden": false,
    "fields": [
        {
            "type": "string",
            "key": "department1",
            "displayName": "Department",
            "hidden": false
        },
        {
            "type": "string",
            "key": "documentType",
            "displayName": "Document Type",
            "hidden": false
        },
        {
            "type": "string",
            "key": "fiscalYear",
            "displayName": "Fiscal Year",
            "hidden": false
        }
    ]
}'

Boom! This works just fine and I then tried it on my jumbo template and it worked as well!

So at least I do have a work-around whenever I need to create a big Metadata Template, but it would be nice if the CLI worked and if there was some documentation around these more advanced functions.

Also --bulk-file-path also says it accepts a .csv?? Without some guidance, I can't even imagine how to create a 1-many relationship for a template with many fields each having many values in a CSV. This would be great to know, however, because it could be much easier for my users to have a template that they can enter the data themselves and I could just import it instead of having to massage the data into a json object.

If nothing else. Hopefully this helps save someone the time I wish I could get back! 😉