Join BoxWorks 2024 to discover what's possible with content and AI!
Register now!Updates a piece of metadata on a file.
The metadata instance can only be updated if the template has already been applied to the file before. When editing metadata, only values that match the metadata template schema will be accepted.
The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed.
12345
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL https://*.app.box.com/files/123
the file_id
is 123
.
global
The scope of the metadata template
Value is one of global
,enterprise
properties
The name of the metadata template
A JSON-Patch specification for the changes to make to the metadata instance.
The changes are represented as a JSON array of operation objects.
"/nextState"
The location in the metadata JSON object to move or copy a value
from. Required for move
or copy
operations and must be in the
format of a JSON-Pointer.
"add"
The type of change to perform on the template. Some of these are hazardous as they will change existing templates.
Value is one of add
,replace
,remove
,test
,move
,copy
"/currentState"
The location in the metadata JSON object to apply the changes to, in the format of a JSON-Pointer.
The path must always be prefixed with a /
to represent the root
of the template. The characters ~
and /
are reserved
characters and must be escaped in the key.
"reviewed"
The value to be set or tested.
Required for add
, replace
, and test
operations. For add
,
if the value exists already the previous value will be overwritten
by the new value. For replace
, the value must exist before
replacing.
For test
, the existing value at the path
location must match
the specified value.
Returns the updated metadata template instance, with the custom template data included.
Returns an error when the request body is not valid.
bad_request
- The request body format is not an array of valid JSON
Patch objects.Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.
An unexpected client error.
curl -i -X PUT "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json-patch+json" \
-d '[
{
"op": "test",
"path": "/competitiveDocument",
"value": "no"
},
{
"op": "remove",
"path": "/competitiveDocument"
},
{
"op": "test",
"path": "/status",
"value": "active"
},
{
"op": "replace",
"path": "/status",
"value": "inactive"
},
{
"op": "test",
"path": "/author",
"value": "Jones"
},
{
"op": "copy",
"from": "/author",
"path": "/editor"
},
{
"op": "test",
"path": "/currentState",
"value": "proposal"
},
{
"op": "move",
"from": "/currentState",
"path": "/previousState"
},
{
"op": "add",
"path": "/currentState",
"value": "reviewed"
}
]'
await client.fileMetadata.updateFileMetadataById(
file.id,
'global' as UpdateFileMetadataByIdScope,
'properties',
[
{
op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
path: '/abc',
value: newValue,
} satisfies UpdateFileMetadataByIdRequestBody,
],
);
client.file_metadata.update_file_metadata_by_id(
file.id,
UpdateFileMetadataByIdScope.GLOBAL.value,
"properties",
[
UpdateFileMetadataByIdRequestBody(
op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE.value,
path="/abc",
value=new_value,
)
],
)
await client.FileMetadata.UpdateFileMetadataByIdAsync(fileId: file.Id, scope: UpdateFileMetadataByIdScope.Global, templateKey: "properties", requestBody: Array.AsReadOnly(new [] {new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/abc", Value = newValue }}));
try await client.fileMetadata.updateFileMetadataById(fileId: file.id, scope: UpdateFileMetadataByIdScope.global, templateKey: "properties", requestBody: [UpdateFileMetadataByIdRequestBody(op: UpdateFileMetadataByIdRequestBodyOpField.replace, path: "/abc", value: newValue)])
BoxFile file = new BoxFile(api, "id");
file.updateMetadata(new Metadata("templateScope", "templateKey").add("/foo", "bar"));
file_obj = client.file(file_id='11111')
file_metadata = file_obj.metadata(scope='enterprise', template='myMetadata')
updates = file_metadata.start_update()
updates.add('/foo', 'bar')
updates.update('/baz', 'murp', old_value='quux') # Ensure the old value was "quux" before updating to "murp"
updated_metadata = file_metadata.update(updates)
print('Updated metadata on file!')
print(f'foo is now {updated_metadata["foo"]} and baz is now {updated_metadata["baz"]}')
var updates = new List<BoxMetadataUpdate>()
{
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.test,
Path = "/competitiveDocument",
Value = "no"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.remove,
Path = "/competitiveDocument"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.test,
Path = "/status",
Value = "active"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.replace,
Path = "/competitiveDocument",
Value = "inactive"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.test,
Path = "/author",
Value = "Jones"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.copy,
From="/author",
Path = "/editor"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.test,
Path = "/currentState",
Value = "proposal"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.move,
From = "/currentState",
Path = "/previousState"
},
new BoxMetadataUpdate()
{
Op = MetadataUpdateOp.add,
Path = "/currentState",
Value = "reviewed"
}
};
Dictionary<string, object> updatedMetadata = await client.MetadataManager
.UpdateFileMetadataAsync("11111", updates, "enterprise", "marketingCollateral");
var updates = [
{ op: 'test', path: '/competitiveDocument', value: 'no' },
{ op: 'remove', path: '/competitiveDocument' },
{ op: 'test', path: '/status', value: 'active' },
{ op: 'replace', path: '/status', value: 'inactive' },
{ op: 'test', path: '/author', value: 'Jones' },
{ op: 'copy', from: '/author', path: '/editor' },
{ op: 'test', path: '/currentState', value: 'proposal' },
{ op: 'move', from: '/currentState', path: '/previousState' },
{ op: 'add', path: '/currentState', value: 'reviewed' }
];
client.files.updateMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", updates)
.then(metadata => {
/* metadata -> {
audience: 'internal',
documentType: 'Q1 plans',
status: 'inactive',
author: 'Jones',
'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
'$parent': 'file_11111',
'$id': '2094c584-68e1-475c-a581-534a4609594e',
'$version': 1,
'$typeVersion': 0,
editor: 'Jones',
previousState: 'proposal',
currentState: 'reviewed',
'$template': 'marketingCollateral',
'$scope': 'enterprise_12345' }
*/
});
client.metadata.update(
forFileWithId: "11111",
scope: "enterprise",
templateKey: "personnelRecord",
operations: [
.test(path: "/department", value: "Sales"),
.replace(path: "/department", value: "Marketing")
]
) { (result: Result<MetadataObject, BoxSDKError>) in
guard case let .success(metadata) = result {
print("Error updating metadata")
return
}
print("Employee department updated to \(metadata.keys["department"])")
}
{
"$canEdit": true,
"$id": "01234500-12f1-1234-aa12-b1d234cb567e",
"$parent": "folder_59449484661,",
"$scope": "enterprise_27335",
"$template": "marketingCollateral",
"$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
"$typeVersion": 2,
"$version": 1
}