Assign retention policy
Assigns a retention policy to an item.
Request
Request Body
The item to assign the policy to
"6564564"The ID of item to assign the policy to.
Set to null or omit when type is set to
enterprise.
"metadata_template"The type of item to assign the policy to.
Value is one of enterprise,folder,metadata_template
If the assign_to type is metadata_template,
then optionally add the filter_fields parameter which will
require an array of objects with a field entry and a value entry.
Currently only one object of field and value is supported.
"a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4"The metadata attribute key id.
"0c27b756-0p87-4fe0-a43a-59fb661ccc4e"The metadata attribute field id. For value, only enum and multiselect types are supported.
"173463"The ID of the retention policy to assign
"upload_date"The date the retention policy assignment begins.
If the assigned_to type is metadata_template,
this field can be a date field's metadata attribute key id.
Response
Returns a new retention policy assignment object.
Returns an error if an id is specified while assigning the
retention policy to an enterprise.
Returns an error if start_date_field is present but assign_to.type
is not metadata_template
Returns an error if start_date_field is present, but belongs to a
different metadata template than the one specified in assign_to.id
Returns an error if start_date_field is present, but the
retention_policy has a retention_length of "indefinite"
Returns an error if start_date_field is present, but cannot be resolved
to a valid metadata date field.
Returns an error if no retention policy with the given policy_id exists.
Returns an error if a retention policy of equal or greater length has already been assigned to this item.
An unexpected client error.
Request Example
curl -i -X POST "https://api.box.com/2.0/retention_policy_assignments" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json" \
-d '{
"policy_id": "173463",
"assign_to": {
"type": "folder",
"id": "6564564"
}
}'await client.retentionPolicyAssignments.createRetentionPolicyAssignment({
policyId: retentionPolicy.id,
assignTo: {
type: 'folder' as CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField,
id: folder.id,
} satisfies CreateRetentionPolicyAssignmentRequestBodyAssignToField,
} satisfies CreateRetentionPolicyAssignmentRequestBody);client.retention_policy_assignments.create_retention_policy_assignment(
retention_policy.id,
CreateRetentionPolicyAssignmentAssignTo(
type=CreateRetentionPolicyAssignmentAssignToTypeField.FOLDER, id=folder.id
),
)await client.RetentionPolicyAssignments.CreateRetentionPolicyAssignmentAsync(requestBody: new CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.Id, assignTo: new CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.Folder) { Id = folder.Id }));try await client.retentionPolicyAssignments.createRetentionPolicyAssignment(requestBody: CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.id, assignTo: CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.folder, id: folder.id)))// Assign the policy to the entire enterprise
BoxRetentionPolicy policy = new BoxRetentionPolicy(api, policyID);
policy.assignToEnterprise();
// Assign the policy to a single folder
BoxFolder folder = new BoxFolder(api, folderID);
policy.assignTo(folderID);
// Assign the policy to all items with metadata template
String metadataTemplateID = "f0dce190-8106-43ca-9d67-7dce9b10a55e";
policy.assignToMetadataTemplate(metadataTemplateID);
// You can also pass an optional `startDateField` parameter containing the ID of the metadata template's `date` field
String dateFieldID = "fb523725-04b1-4502-b871-eac305274533";
policy.assignToMetadataTemplate(metadataTemplateID, dateFieldID);folder = client.folder(folder_id='1111')
assignment = client.retention_policy(retention_id='12345').assign(folder)
print(f'Assignment ID is {assignment.id} and it is assigned by {assignment.assigned_by.name}')var assignmentParams = new BoxRetentionPolicyAssignmentRequest()
{
PolicyId = "11111",
AssignTo = new BoxRequestEntity()
{
Type = BoxType.folder,
Id = "22222"
}
};
BoxRetentionPolicyAssignment assignment = await client.RetentionPoliciesManager
.CreateRetentionPolicyAssignmentAsync(assignmentParams);client.retentionPolicies
.assign('11111', 'folder', '22222')
.then((assignment) => {
/* assignment -> {
type: 'retention_policy_assignment',
id: '12345',
retention_policy:
{ type: 'retention_policy',
id: '11111',
policy_name: 'Tax Documents' },
assigned_to: { type: 'folder', id: '22222' },
assigned_by:
{ type: 'user',
id: '33333',
name: 'Example User',
login: 'user@example.com' },
assigned_at: '2015-07-20T14:28:09-07:00' }
*/
});client.retentionPolicy.assign(policyId: "12345", assignedContentId: "1111", assignContentType: .folder) { result in
guard case let .success(retentionPolicyAssignment) = result else {
print("Error creating retention policy assignment")
return
}
print("Retention policy assignment: \(retentionPolicyAssignment.id) was created")
}Response Example
{
"id": "11446498",
"type": "retention_policy_assignment",
"assigned_at": "2012-12-12T10:53:43-08:00",
"assigned_by": {
"id": "11446498",
"type": "user",
"login": "ceo@example.com",
"name": "Aaron Levie"
},
"assigned_to": {
"id": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65",
"type": "metadata_template"
},
"filter_fields": [
{
"field": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4",
"value": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e"
}
],
"retention_policy": {
"id": "12345",
"type": "retention_policy",
"disposition_action": "permanently_delete",
"policy_name": "Some Policy Name",
"retention_length": "365"
},
"start_date_field": "upload_date"
}