retention_policies.md

Retention Policies

A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise.

• Create Retention Policy
• Get Retention Policy
• Update Retention Policy
• Get Retention Policies
• Get Retention Policy Assignments
• Create Retention Policy Assignment
• Get Retention Policy Assignment
• Get File Version Retention
• Get File Version Retentions

Create Retention Policy

The static createIndefinitePolicy(BoxAPIConnection, String) method will let you create a new indefinite retention policy with a specified name.

BoxRetentionPolicy.createIndefinitePolicy(api, name);

The static createFinitePolicy(BoxAPIConnection, String, int, String) method will let you create a new finite retention policy with a specified name, amount of time to apply the retention policy (in days) and a disposition action. the disposition action can be "permanently_delete" or "remove_retention".

BoxRetentionPolicy.createFinitePolicy(api, name, length, action);

Get Retention Policy

Calling getInfo(String...) will return a BoxRetentionPolicy.Info object containing information about the retention policy. If necessary to retrieve limited set of fields, it is possible to specify them using param.

BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id);
policy.getInfo("policy_name", "status");

Update Retention Policy

Updating a retention policy's information is done by calling updateInfo(BoxRetentionPolicy.Info).

BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id);
BoxRetentionPolicy.Info policyInfo = policy.new Info();
policyInfo.addPendingChange("policy_name", "new policy name");
policy.updateInfo(policyInfo);

Get Retention Policies

Calling the static getAll(BoxAPIConnection, String...) will return an iterable that will page through all of the retention policies. It is possible to specify filter for the name of retention policy, filter for the type of the policy, filter for the id of user, limit of items per single response and fields to retrieve by calling the static getAll(String, String, String, int, BoxAPIConnection, String...) method.

Iterable<BoxRetentionPolicy.Info> policies = BoxRetentionPolicy.getAll(api);
for (BoxRetentionPolicy.Info policyInfo : policies) {
	// Do something with the retention policy.
}

Get Retention Policy Assignments

Calling getAllAssignments(String...) will return an iterable that will page through all of the assignments of the retention policy. It is possible to specify maximum number of items per single response and fields to retrieve by calling getFolderAssignments(int, String...). If it is necessary to retrieve only assignments of certain type, you can call getFolderAssignments(int, String...) or getEnterpriseAssignments(int, String...).

BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id);
Iterable<BoxRetentionPolicyAssignment.Info> allAssignments = BoxRetentionPolicy.getAllAssignments("assigned_by");
Iterable<BoxRetentionPolicyAssignment.Info> folderAssignments = BoxRetentionPolicy.getFolderAssignments(50, "assigned_by");
Iterable<BoxRetentionPolicyAssignment.Info> enterpriseAssignments = BoxRetentionPolicy.getEnterpriseAssignments();
for (BoxRetentionPolicyAssignments.Info assignmentInfo : allAssignments) {
	// Do something with the assignment.
}
for (BoxRetentionPolicyAssignments.Info assignmentInfo : folderAssignments) {
	// Do something with the assignment.
}
for (BoxRetentionPolicyAssignments.Info assignmentInfo : enterpriseAssignments) {
	// Do something with the assignment.
}

Create Retention Policy Assignment

To create new retention policy assignment call assignTo(BoxFolder) method, or assignToEnterprise() to assign retention policy to enterprise.

BoxRetentionPolicy policy = new BoxRetentionPolicy(api, policyID);
BoxRetentionPolicyAssignment.Info enterpriseAssignmentInfo = policy.assignToEnterprise();
BoxFolder folder = new BoxFolder(api, folderID);
BoxRetentionPolicyAssignment.Info folderAssignmentInfo = policy.assignTo(folder);

Get Retention Policy Assignment

Calling getInfo(String...) will return a BoxRetentionPolicyAssignment.Info object containing information about the retention policy assignment.

BoxRetentionPolicyAssignment assignment = new BoxRetentionPolicyAssignment(api, id);
BoxRetentionPolicyAssignment.Info assignmentInfo = assignment.getInfo("assigned_to");

Get File Version Retention

Calling getInfo(String...) will return a BoxFileVersionRetention.Info object containing information about the file version retention policy.

BoxFileVersionRetention policy = new BoxFileVersionRetention(api, id);
BoxFileVersionRetention.Info policyInfo = policy.getInfo();

Get File Version Retentions

To get an iterable with all file version retentions for current retention policy, call the static getAll(BoxAPIConnection, String...). It is possible to add filters to query using QueryFilter object as a parameter: getAll(BoxAPIConnection, QueryFilter, String...).

BoxFileVersionRetention.QueryFilter filter = new BoxFileVersionRetention.QueryFilter()
                .addFileID("0")
                .addFileVersionID("1")
                .addPolicyID("2")
                .addDispositionAction(BoxRetentionPolicy.ACTION_PERMANENTLY_DELETE)
                .addDispositionBefore(BoxDateFormat.parse("2016-09-15T13:15:35+0000"))
                .addDispositionAfter(BoxDateFormat.parse("2014-09-15T13:15:35+0000"));
Iterable<BoxFileVersionRetention.Info> retentions
                = BoxFileVersionRetention.getRetentions(api, filter, "file", "applied_at");
for (BoxFileVersionRetention.Info retentionInfo : retentions) {
	// Do something with the file version retention.
}