Join BoxWorks 2024 to discover what's possible with content and AI!

Create metadata cascade policy

post

https://api.box.com/2.0

/metadata_cascade_policies

Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to any files within that folder.

In order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to.

Related Guides

Metadata Create a metadata cascade policy

Request

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

Request Body

folder_id stringin bodyrequired

example"1234567"

The ID of the folder to apply the policy to. This folder will need to already have an instance of the targeted metadata template applied to it.

scope stringin bodyrequired

example"enterprise"

The scope of the targeted metadata template. This template will need to already have an instance applied to the targeted folder.

Value is one of global,enterprise

templateKey stringin bodyrequired

example"productInfo"

The key of the targeted metadata template. This template will need to already have an instance applied to the targeted folder.

In many cases the template key is automatically derived of its display name, for example Contract Template would become contractTemplate. In some cases the creator of the template will have provided its own template key.

Please list the templates for an enterprise, or get all instances on a file or folder to inspect a template's key.

Response

201application/jsonMetadata cascade policy

Returns a new of metadata cascade policy

400application/jsonClient error

Returns an error when any of the parameters are not in a valid format.

bad_request - Either the scope, templateKey, or folder_id are not in a valid format.

403application/jsonClient error

Returns an error when trying to apply a policy to a restricted folder, for example the root folder with ID 0.

forbidden - Although the folder ID was valid and the user has access to the folder, the policy could not be applied to this folder.

404application/jsonClient error

Returns an error when the template or folder can not be found, or when the user does not have access to the folder or template.

instance_tuple_not_found - The template could not be found or the user does not have access to the template.
not_found - The folder could not be found or the user does not have access to the folder.

409application/jsonConflict error

Returns an error when a policy for this folder and template is already in place.

tuple_already_exists - A cascade policy for this combination of folder_id, scope and templateKey already exists.

defaultapplication/jsonClient error

An unexpected client error.

post

Create metadata cascade policy

You can now try out some of our APIs live, right here in the documentation.

Request Example

cURL

curl -i -X POST "https://api.box.com/2.0/metadata_cascade_policies" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "folder_id": "12321",
       "scope": "enterprise_27335",
       "templateKey": "productInfo"
     }'

TypeScript Gen

await client.metadataCascadePolicies.createMetadataCascadePolicy({
  folderId: folder.id,
  scope: 'enterprise' as CreateMetadataCascadePolicyRequestBodyScopeField,
  templateKey: templateKey,
} satisfies CreateMetadataCascadePolicyRequestBody);

Python Gen

client.metadata_cascade_policies.create_metadata_cascade_policy(
    folder.id, CreateMetadataCascadePolicyScope.ENTERPRISE.value, template_key
)

.NET Gen

await client.MetadataCascadePolicies.CreateMetadataCascadePolicyAsync(requestBody: new CreateMetadataCascadePolicyRequestBody(folderId: folder.Id, scope: CreateMetadataCascadePolicyRequestBodyScopeField.Enterprise, templateKey: templateKey));

Swift Gen (Beta)

try await client.metadataCascadePolicies.createMetadataCascadePolicy(requestBody: CreateMetadataCascadePolicyRequestBody(folderId: folder.id, scope: CreateMetadataCascadePolicyRequestBodyScopeField.enterprise, templateKey: templateKey))

Python

folder = client.folder(folder_id='22222')
metadata_template = client.metadata_template('enterprise', 'securityClassiciation')

cascade_policy = folder.cascade_metadata(metadata_template)
print(f'Folder {cascade_policy.parent.id} has a metadata cascade policy for {cascade_policy.scope} template "{cascade_policy.templateKey}"')

.NET

BoxMetadataCascadePolicy metadataCascadePolicy = await client.MetadataCascadePolicyManager
    .CreateCascadePolicyAsync("22222", "enterprise_11111", "templateKey");

Node

var folderID = '22222';
client.metadata.createCascadePolicy('enterprise', 'testTemplate', folderID)
	.then(cascadePolicy => {
		/* cascadePolicy -> {
			id: '84113349-794d-445c-b93c-d8481b223434',
			type: 'metadata_cascade_policy',
			owner_enterprise: {
				type: 'enterprise',
				id: '11111'
			},
			parent: {
				type: 'folder',
				id: '22222'
			},
			scope: 'enterprise_11111',
			templateKey: 'testTemplate'
		}
		*/
	});

Response Example

{
  "id": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7",
  "type": "metadata_cascade_policy",
  "owner_enterprise": {
    "id": "690678",
    "type": "enterprise"
  },
  "parent": {
    "id": "1234567",
    "type": "folder"
  },
  "scope": "enterprise_123456",
  "templateKey": "productInfo"
}