Skip to content

Latest commit

 

History

History
257 lines (206 loc) · 8.76 KB

metadata.md

File metadata and controls

257 lines (206 loc) · 8.76 KB
Raw

Metadata

Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key:value pairs that belong to files/folders. For example, an important contract may have key:value pairs of "clientNumber":"820183" and "clientName":"bioMedicalCorp".

Metadata that belongs to a file/folder is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields.

Each file/folder can have multiple distinct template instances associated with it, and templates are also grouped by scopes. Currently, the only scopes support are enterprise and global. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide.

In addition to enterprise scoped templates, every file on Box has access to the global properties template. The Properties template is a bucket of free form key:value string pairs, with no additional schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure.

Create Metadata Template

To create a new metadata template, call the metadata.createTemplate(templateName, fields, options, callback) method.

// Create a new template, but hide it for now until it's ready for use
client.metadata.createTemplate(
		'Vendor Contract',
		[
			{
				type: 'date',
				key: 'signed',
				displayName: 'Date Signed'
			},
			{
				type: 'string',
				key: 'vendor',
				displayName: 'Vendor'
			},
			{
				type: 'enum',
				key: 'fy',
				displayName: 'Fiscal Year',
				options: [
					{key: 'FY17'},
					{key: 'FY18'},
					{key: 'FY19'}
				]
			}
		],
		{
			hidden: true,
			templateKey: 'vcontract'
		},
		callback
	);

Get Metadata Template

Get by template scope and key

To retrieve a specific metadata template by its scope and template key, call the metadata.getTemplateSchema(scope, template, callback) method with the scope and template key.

client.metadata.getTemplateSchema('enterprise', 'vcontract', callback);

Get by ID

To get a specific metadata template by its ID, call the metadata.getTemplateByID(templateID, callback) method with the ID of the template.

client.metadata.getTemplateByID('17f2d715-6acb-45f2-b96a-28b15efc9faa', callback);

Update Metadata Template

To update a metadata template, call the metadata.updateTemplate(scope, template, operations, callback) method with the operations to perform on the template. See the API Documentation for more information on the operations available.

// 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, callback);

Get Enterprise Metadata Templates

Get all metadata templates for the current enterprise and scope by calling the metadata.getTemplates(scope, callback) method.

client.metadata.getTemplates('enterprise', callback);

Delete Metadata Template

To delete a metadata template call the metadata.deleteTemplate(scope, template, callback) method with the template scope and template name.

client.metadata.deleteTemplate('enterprise', 'testtemplate', callback);

Add Metadata to a File

Metadata can be created on a file by calling files.addMetadata(fileID, scope, template, metadata, callback) with a metadata template and an object of key/value pairs to add as metadata.

var metadata = {foo: 'bar'};
client.files.addMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES, metadata, callback);

Get Metadata on a File

Retrieve a file's metadata by calling files.getAllMetadata(fileID, callback), to retrieve all metadata, or files.getMetadata(fileID, scope, template, callback) to retrieve a single template.

client.files.getMetadata('67890', client.metadata.scopes.ENTERPRISE, 'productSpec', callback);

Update Metadata on a File

Update a file's metadata by calling files.updateMetadata(fileID, scope, template, patch, callback) with an array of JSON Patch formatted operations.

var patch = [{
	op: 'add',
	path: '/baz',
	value: 'quux'
}];
client.files.updateMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES, patch, callback);

Remove Metadata from a File

A file's metadata can be removed by calling files.deleteMetadata(fileID, scope, template, callback).

client.files.deleteMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES, callback);

Add Metadata to a Folder

Metadata can be created on a folder by calling folders.addMetadata(folderID, scope, template, metadata, callback) with a metadata template and an object of key/value pairs to add as metadata.

var metadata = {foo: 'bar'};
client.folders.addMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES, metadata, callback);

Get Metadata on a Folder

Retrieve a folder's metadata by calling folders.getAllMetadata(folderID, callback), to retrieve all metadata, or folders.getMetadata(folderID, scope, template, callback) to retrieve a single template.

client.folders.getMetadata('67890', client.metadata.scopes.ENTERPRISE, 'productSpec', callback);

Update Metadata on a Folder

Update a folder's metadata by calling folders.updateMetadata(folderID, scope, template, patch, callback) with an array of JSON Patch formatted operations.

var patch = [{
	op: 'add',
	path: '/baz',
	value: 'quux'
}];
client.folders.updateMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES, patch, callback);

Remove Metadata from a Folder

A folder's metadata can be removed by calling folders.deleteMetadata(folderID, scope, template, callback).

client.folders.deleteMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES, callback);