Box Developer Documentation
Latest version

Update metadata template

put
https://api.box.com/2.0
/metadata_templates/:scope/:template_key/schema

Updates a metadata template.

The metadata template can only be updated if the template already exists.

The update is applied atomically. If any errors occur during the application of the operations, the metadata template will not be changed.

Request

bearer [ACCESS_TOKEN]
application/json-patch+json

Path Parameters

stringin pathrequired
global

The scope of the metadata template

Value is one of global,enterprise

stringin pathrequired
properties

The name of the metadata template

Request Body

object arrayin bodyrequired

A JSON-Patch specification for the changes to make to the metadata template.

The changes are represented as a JSON array of operation objects.

associative arrayin body

The data for the operation. This will vary depending on the operation being performed.

objectin body
"Aaron Levie"

A value for each of the fields that are present on the metadata template. For the global.properties template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template.

stringin bodyoptional
"option1"

For operations that affect a single enum option this defines the key of the option that is affected.

string arrayin bodyoptional
["option1","option2","option3"]

For operations that affect multiple enum options this defines the keys of the options that are affected.

stringin bodyoptional
"category"

For operations that affect a single field this defines the key of the field that is affected.

string arrayin bodyoptional
["category","name"]

For operations that affect multiple fields this defines the keys of the fields that are affected.

stringin bodyoptional
"option1"

For operations that affect a single multi select option this defines the key of the option that is affected.

string arrayin bodyoptional
["option1","option2","option3"]

For operations that affect multiple multi select options this defines the keys of the options that are affected.

stringin bodyrequired
"addEnumOption"

The type of change to perform on the template. Some of these are hazardous as they will change existing templates.

Value is one of editTemplate,addField,reorderFields,addEnumOption,reorderEnumOptions,reorderMultiSelectOptions,addMultiSelectOption,editField,removeField,editEnumOption,removeEnumOption,editMultiSelectOption,removeMultiSelectOption

Response

application/jsonMetadata template

Returns the updated metadata template, with the custom template data included.

application/jsonClient error

The request body does not contain a valid metadata schema.

application/jsonClient error

The request body contains a scope that the user is not allowed to create templates for.

application/jsonClient error

The requested template could not be found

application/jsonClient error

An unexpected client error.

put
Update metadata template
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X PUT "https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json-patch+json" \
     -d '[
       {
         "op": "editField",
         "fieldKey": "category",
         "data": {
           "displayName": "Customer Group"
         }
       }
     ]'
TypeScript Gen
await client.metadataTemplates.updateMetadataTemplate(
  'enterprise' as UpdateMetadataTemplateScope,
  templateKey,
  [
    {
      op: 'addField' as UpdateMetadataTemplateRequestBodyOpField,
      fieldKey: 'newfieldname',
      data: { ['type']: 'string', ['displayName']: 'newFieldName' },
    } satisfies UpdateMetadataTemplateRequestBody,
  ],
);
Python Gen
client.metadata_templates.update_metadata_template(
    UpdateMetadataTemplateScope.ENTERPRISE,
    template_key,
    [
        UpdateMetadataTemplateRequestBody(
            op=UpdateMetadataTemplateRequestBodyOpField.ADDFIELD,
            field_key="newfieldname",
            data={"type": "string", "displayName": "newFieldName"},
        )
    ],
)
.NET Gen
await client.MetadataTemplates.UpdateMetadataTemplateAsync(scope: UpdateMetadataTemplateScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateMetadataTemplateRequestBody(op: UpdateMetadataTemplateRequestBodyOpField.AddField) { FieldKey = "newfieldname", Data = new Dictionary<string, object>() { { "type", "string" }, { "displayName", "newFieldName" } } }}));
Java
List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>();

String addCategoryFieldJSON = "{\"op\":\"addField\","\"data\":{"
    + "\"displayName\":\"Category\",\"key\":\"category\",\"hidden\":false,\"type\":\"string\"}}";
updates.add(new MetadataTemplate.FieldOperation(addCategoryFieldJSON));

String changeTemplateNameJSON = "{\"op\":\"editTemplate\",\"data\":{"
    + "\"displayName\":\"My Metadata\"}}";
updates.add(new MetadataTemplate.FieldOperation(changeTemplateNameJSON));

MetadataTemplate.updateMetadataTemplate(api, "enterprise", "myData", updates);
Python
template = client.metadata_template('enterprise', 'employeeRecord')
updates = template.start_update()
updates.add_enum_option('state', 'WI')
updates.edit_template({'hidden': False})
updates.edit_template({'copyInstanceOnItemCopy': False})
updated_template = template.update_info(updates=updates)
.NET
var updates = new List<BoxMetadataTemplateUpdate>()
{
    new BoxMetadataTemplateUpdate()
    {
        Op = MetadataTemplateUpdateOp.addEnumOption,
        FieldKey = "fy",
        Data = new {
            key = "FY20"
        }
    },
    new BoxMetadataTemplateUpdate()
    {
        Op = MetadataTemplateUpdateOp.editTemplate,
        Data = new {
            hidden = false
        }
    }
};
BoxMetadataTemplate updatedTemplate = await client.MetadataManager
    .UpdateMetadataTemplate(updates, "enterprise", "marketingCollateral");
Node
// Add a new option to the Fiscal Year field, and un-hide the template
var operations = [
	{
		op: 'addEnumOption',
		fieldKey: 'fy',
		data: { key: 'FY20' }
	},
	{
		op: 'editTemplate',
		data: { hidden: false }
	}
];
client.metadata.updateTemplate('enterprise', 'vcontract', operations)
	.then(template => {
		/* template -> {
			templateKey: 'vcontract',
			scope: 'enterprise_12345',
			displayName: 'Vendor Contract',
			hidden: false,
			fields: 
			[ { type: 'date',
				key: 'signed',
				displayName: 'Date Signed',
				hidden: false },
				{ type: 'string',
				key: 'vendor',
				displayName: 'Vendor',
				hidden: false },
				{ type: 'enum',
				key: 'fy',
				displayName: 'Fiscal Year',
				options: 
					[ { key: 'FY17' },
					{ key: 'FY18' },
					{ key: 'FY19' },
					{ key: 'FY20' } ],
				hidden: false } ] }
		*/
	});
iOS
client.metadata.updateTemplate(
    scope: "enterprise",
    templateKey: "personnelRecord",
    operation: .reorderEnumOptions(fieldKey: "department", enumOptionKeys: ["Marketing", "Sales", "HR"])
) { (result: Result<MetadataTemplate, BoxSDKError>) in
    guard case let .success(template) = result {
        print("Error updating metadata template")
        return
    }

    print("Updated metadata template with ID \(template.id)")
}

Response Example

{
  "id": "58063d82-4128-7b43-bba9-92f706befcdf",
  "type": "metadata_template",
  "copyInstanceOnItemCopy": true,
  "displayName": "Product Info",
  "fields": [
    {
      "description": "The category",
      "displayName": "Category",
      "hidden": true,
      "key": "category",
      "options": [
        {
          "key": "Category 1",
          "id": "45dc2849-a4a7-40a9-a751-4a699a589190"
        }
      ],
      "type": "string",
      "id": "822227e0-47a5-921b-88a8-494760b2e6d2"
    }
  ],
  "hidden": true,
  "scope": "enterprise_123456",
  "templateKey": "productInfo"
}