Apply metadata to an item
Apply metadata to an item
A metadata template can be applied to a file or folder using the item's id
,
the template's templateKey
and scope
, and a set of values for each field in
the template.
Apply metadata to a file
To apply an instance of a metadata template to a file, call the
POST /files/:file_id/metadata/:scope/:templateKey
API endpoint
with the file's file_id
, the template's scope
and templateKey
, and an
optional set of values for each field in the template.
curl -i -X POST "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json" \
-d '{
"audience": "internal",
"documentType": "Q1 plans",
"competitiveDocument": "no",
"status": "active",
"author": "Jones",
"currentState": "proposal"
}'
await client.fileMetadata.createFileMetadataById(
file.id,
'enterprise' as CreateFileMetadataByIdScope,
templateKey,
{
['name']: 'John',
['age']: 23,
['birthDate']: '2001-01-03T02:20:50.520Z',
['countryCode']: 'US',
['sports']: ['basketball', 'tennis'],
}
);
client.file_metadata.create_file_metadata_by_id(
file.id,
CreateFileMetadataByIdScope.ENTERPRISE.value,
template_key,
{
"name": "John",
"age": 23,
"birthDate": "2001-01-03T02:20:50.520Z",
"countryCode": "US",
"sports": ["basketball", "tennis"],
},
)
await client.FileMetadata.CreateFileMetadataByIdAsync(fileId: file.Id, scope: CreateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } });
try await client.fileMetadata.createFileMetadataById(fileId: file.id, scope: CreateFileMetadataByIdScope.global, templateKey: "properties", requestBody: ["abc": "xyz"])
// Add property "foo" with value "bar" to the default metadata properties
BoxFile file = new BoxFile(api, "id");
file.createMetadata(new Metadata().add("/foo", "bar"));
metadata = {
'foo': 'bar',
'baz': 'quux',
}
applied_metadata = client.file(file_id='11111').metadata().create(metadata)
print(f'Applied metadata in instance ID {applied_metadata["$id"]}')
var metadataValues = new Dictionary<string, object>()
{
{ "audience", "internal" },
{ "documentType", "Q1 plans" },
{ "competitiveDocument", "no" },
{ "status", "active" },
{ "author": "M. Jones" },
{ "currentState": "proposal" }
};
Dictionary<string, object> metadata = await client.MetadataManager
.CreateFileMetadataAsync(fileId: "11111", metadataValues, "enterprise", "marketingCollateral");
var metadataValues = {
audience: "internal",
documentType: "Q1 plans",
competitiveDocument: "no",
status: "active",
author: "Jones",
currentState: "proposal"
};
client.files.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues)
.then(metadata => {
/* metadata -> {
audience: 'internal',
documentType: 'Q1 plans',
competitiveDocument: 'no',
status: 'active',
author: 'Jones',
currentState: 'proposal',
'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
'$parent': 'file_11111',
'$id': '2094c584-68e1-475c-a581-534a4609594e',
'$version': 0,
'$typeVersion': 0,
'$template': 'marketingCollateral',
'$scope': 'enterprise_12345' }
*/
});
let metadata = [
"name": "John Doe",
"birthday": "2000-01-01T00:00:00Z",
"department": "Sales"
]
client.metadata.create(
forFileWithId: "11111",
scope: "enterprise",
templateKey: "personnelRecord",
keys: metadata
) { (result: Result<MetadataObject, BoxSDKError>) in
guard case let .success(metadata) = result {
print("Error adding metadata")
return
}
print("Successfully attached metadata")
}
Apply metadata to a folder
To apply an instance of a metadata template to a folder, call the
POST /folders/:folder_id/metadata/:scope/:templateKey
API endpoint
with the folder's folder_id
, the template's scope
and templateKey
, and an
optional set of values for each field in the template.
curl -i -X POST "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json" \
-d '{
"audience": "internal",
"documentType": "Q1 plans",
"competitiveDocument": "no",
"status": "active",
"author": "Jones",
"currentState": "proposal"
}'
await client.folderMetadata.createFolderMetadataById(
folder.id,
'enterprise' as CreateFolderMetadataByIdScope,
templateKey,
{
['name']: 'John',
['age']: 23,
['birthDate']: '2001-01-03T02:20:50.520Z',
['countryCode']: 'US',
['sports']: ['basketball', 'tennis'],
}
);
client.folder_metadata.create_folder_metadata_by_id(
folder.id,
CreateFolderMetadataByIdScope.ENTERPRISE.value,
template_key,
{
"name": "John",
"age": 23,
"birthDate": "2001-01-03T02:20:50.520Z",
"countryCode": "US",
"sports": ["basketball", "tennis"],
},
)
await client.FolderMetadata.CreateFolderMetadataByIdAsync(folderId: folder.Id, scope: CreateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } });
try await client.folderMetadata.createFolderMetadataById(folderId: folder.id, scope: CreateFolderMetadataByIdScope.global, templateKey: "properties", requestBody: ["abc": "xyz"])
BoxFolder folder = new BoxFolder(api, "id");
folder.createMetadata(new Metadata().add("/foo", "bar"));
metadata = {
'foo': 'bar',
'baz': 'quux',
}
applied_metadata = client.folder(folder_id='22222').metadata().create(metadata)
print(f'Applied metadata in instance ID {applied_metadata["$id"]}')
var metadataValues = new Dictionary<string, object>()
{
{ "audience", "internal" },
{ "documentType", "Q1 plans" },
{ "competitiveDocument", "no" },
{ "status", "active" },
{ "author": "M. Jones" },
{ "currentState": "proposal" }
};
Dictionary<string, object> metadata = await client.MetadataManager
.CreateFolderMetadataAsync(folderId: "11111", metadataValues, "enterprise", "marketingCollateral");
var metadataValues = {
audience: "internal",
documentType: "Q1 plans",
competitiveDocument: "no",
status: "active",
author: "Jones",
currentState: "proposal"
};
client.folders.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues)
.then(metadata => {
/* metadata -> {
audience: 'internal',
documentType: 'Q1 plans',
competitiveDocument: 'no',
status: 'active',
author: 'Jones',
currentState: 'proposal',
'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
'$parent': 'folder_11111',
'$id': '2094c584-68e1-475c-a581-534a4609594e',
'$version': 0,
'$typeVersion': 0,
'$template': 'marketingCollateral',
'$scope': 'enterprise_12345' }
*/
});
let metadata = [
"name": "John Doe",
"birthday": "2000-01-01T00:00:00Z",
"department": "Sales"
]
client.metadata.create(
forFolderWithId: "22222",
scope: "enterprise",
templateKey: "personnelRecord",
keys: metadata
) { (result: Result<MetadataObject, BoxSDKError>) in
guard case let .success(metadata) = result {
print("Error adding metadata")
return
}
print("Successfully attached metadata")
}
Request body
The body of the request can contain a value for each field in the template. To inspect what fields are present on a template, inspect a metadata metadata template.
For example, let's assume the following template.
{
"id": "8120731a-41e4-11ea-b77f-2e728ce88125",
"type": "metadata_template",
"templateKey": "productInfo",
"scope": "enterprise_1234567",
"displayName": "Product Info",
"hidden": false,
"copyInstanceOnItemCopy": true,
"fields": [
{
"id": "feed71de-41e5-11ea-b77f-2e728ce88125",
"type": "string",
"key": "name",
"displayName": "Name",
"hidden": false
},
{
"id": "02b36bb6-41e6-11ea-b77f-2e728ce88125",
"type": "enum",
"key": "category",
"displayName": "Category",
"hidden": false,
"options": [
{
"id": "06a7bcc2-41e6-11ea-b77f-2e728ce88125",
"key": "SUVs"
},
{
"id": "0a50df02-41e6-11ea-b77f-2e728ce88125",
"key": "Saloons"
},
{
"id": "0e466be0-41e6-11ea-b77f-2e728ce88125",
"key": "Cabriolets"
}
]
}
]
}
This template has 2 template fields, name
and category
. The name
field is a regular text field, and the category
is an enum.
The request body to assign this template to a file or folder can include a value for any of the fields on the template. It is possible for the body to have no values for no fields.
In this case, a valid example would be the following request body.
{
"name": "Model 3",
"category": "SUVs"
}