Update a metadata template

Guides Metadata Metadata templates Update a metadata template

Required Guides

Update a metadata template

Updating a metadata template can be achieved by passing an array of operations to the PUT /metadata_templates/:scope/:templateKey/schema API.

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" } } }}));

Swift Gen (Beta)

try await client.metadataTemplates.updateMetadataTemplate(scope: UpdateMetadataTemplateScope.enterprise, templateKey: templateKey, requestBody: [UpdateMetadataTemplateRequestBody(op: UpdateMetadataTemplateRequestBodyOpField.addField, fieldKey: "newfieldname", data: ["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)")
}

Admin permissions required

Updating metadata templates is restricted to users with admin permission. This means that only admins, or co-admins who have been granted rights to Create and edit metadata templates for your company by the admin can use the web app or the API to manage templates.

Updates to metadata templates are performed through operations rather than directly changing the template itself. This method allows us to update any existing metadata instances that are already applied to files and folders.

Template operations update a template's details or fields. These operations are generally safe as they are applied to any template instance without much impact.

The operation editTemplate allows for editing any of the base properties of the template, like the displayName, copyInstanceOnItemCopy and more.

Parameter
`data`	An object representing the properties to change

[
  {
    "op": "editTemplate",
    "data": {
      "displayName": "Client",
      "copyInstanceOnItemCopy": true
    }
  }
]

This will update the template to have a new display name of Client.

This will affect existing instances of this template.

The operation addField adds a field to a template.

Parameter
`data`	An object representing field to add

[
  {
    "op": "addField",
    "data": {
      "displayName": "Category",
      "key": "category",
      "hidden": false,
      "type": "string"
    }
  }
]

This will add a new non-hidden string field with a displayName and key of category.

This will affect existing instances of this template.

The operation reorderFields reorders the list of fields in a template to match the requested field list.

Parameter
`fieldKeys`	The new list of field keys in the requested order

{
  "op": "reorderFields",
  "fieldKeys": ["field2", "field1", "field3"]
}

This will reorder the fields for the template to have field2 first, followed by field1, then field3.

This will affect existing instances of this template. It will reorder the fields, yet keep the values of the fields intact.

Field operations transform the schema of a template. The following is a list of operations that can be used in this API and can potentially change the data of any previously assigned templates.

These changes will be logged as template changes but not as file changes.

The operation editField edits any number of the base properties of a field like the displayName, description, key, and hidden state.

Parameter
`data`	An object representing the new properties to set for the field
`fieldKey`	The key of the field to be edited

{
  "op": "editField",
  "fieldKey": "category",
  "data": {
    "displayName": "Customer Group"
  }
}

This will update the field category to have a new display name of Customer Group. If the key is changed, existing values of the specified field are migrated to the new key. The search index will be updated, yet it may take time depending on how many files are affected by the change.

This may affect existing instances of this template.

The operation removeField removes a field from a template.

Parameter
`fieldKey`	The key of the field to remove from the template

{
  "op": "removeField",
  "fieldKey": "brand"
}

This will remove the field brand from the template as well as all instances of the template. The search index will be updated, yet it may take time depending on how many files are affected by the change.

This will affect existing instances of this template.

Both the enum and multiSelect metadata field types support some additional operations to change the options of the fields.

Operation
`addEnumOption`	Adds an option to an `enum` field
`editEnumOption`	Edits an `enum` field option
`reorderEnumOptions`	Re-orders the options on an `enum` field
`removeEnumOption`	Removes an `enum` field option
`addMultiSelectOption`	Adds an option to a `multiSelect` field
`editMultiSelectOption`	Edits a `multiSelect` field option
`reorderMultiSelectOptions`	Re-orders the options on a `multiSelect` field
`removeMultiSelectOption`	Removes a `multiSelect` field option

Related APIs

putUpdate metadata template

Related Guides

GuideCreate a metadata template

Update a metadata template

Required Guides

Update a metadata template

Admin permissions required

Operations

Template operations

Edit a template

Add a field to a template

Reorder fields

Field operations

Edit a field

Remove a field

Field Option Operations

Related APIs

Related Guides