Skip to content

Latest commit

 

History

History
238 lines (189 loc) · 12.4 KB

retention_policies.md

File metadata and controls

238 lines (189 loc) · 12.4 KB
Raw

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

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

BoxRetentionPolicy.createIndefinitePolicy(api, name);

The static createFinitePolicy(BoxAPIConnection api, String name, int retentionPeriod, String action) 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);

Both finite and indefinite policies allow you to specify optional parameters using the RetentionPolicyParams object.

String notifiedUserID = "12345";
RetentionPolicyParams optionalParams = new RetentionPolicyParams();
optionalParams.setCanOwnerExtendRetention(true);
optionalParams.setAreOwnersNotified(true);
optionalParams.addCustomNotificationRecipient(notifiedUserID);

// Create indefinite policy with optional parameters
BoxRetentionPolicy.createIndefinitePolicy(api, "Retain Stuff Forever", optionalParams);

// Create finite policy with optional parameters
BoxRetentionPolicy.createFinitePolicy(api, "Keep One Year", 365, BoxRetentionPolicy.ACTION_REMOVE_RETENTION, optionalParams);

Get Retention Policy

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

// Get the policy name and status for a given retention policy
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 fieldsToUpdate).

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 api, String... fields) 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 name, String type, String userID, int limit, BoxAPIConnection api, String... fields) 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... fields) 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 getAllAssignments(int limit, String... fields). If it is necessary to retrieve only assignments of certain type, you can call getFolderAssignments(int limit, String... fields) or getEnterpriseAssignments(int limit, String... fields).

BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id);
Iterable<BoxRetentionPolicyAssignment.Info> allAssignments = policy.getAllAssignments("assigned_by");
Iterable<BoxRetentionPolicyAssignment.Info> folderAssignments = policy.getFolderAssignments(50, "assigned_by");
Iterable<BoxRetentionPolicyAssignment.Info> enterpriseAssignments = policy.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 target) method to assign the policy to a specific folder, assignToEnterprise() to assign the retention policy to the entire enterprise, or assignToMetadataTemplate(String templateID, MetadataFieldFilter... filterFields) to assign the policy to items with a specific metadata template.

// Assign the policy to the entire enterprise
BoxRetentionPolicy policy = new BoxRetentionPolicy(api, policyID);
BoxRetentionPolicyAssignment.Info enterpriseAssignmentInfo = policy.assignToEnterprise();

// Assign the policy to a single folder
BoxFolder folder = new BoxFolder(api, folderID);
BoxRetentionPolicyAssignment.Info folderAssignmentInfo = policy.assignTo(folder);

// Assign the policy to all items with metadata template "f0dce190-8106-43ca-9d67-7dce9b10a55e"
BoxRetentionPolicyAssignment.Info metadataAssignmentInfo = policy.assignToMetadataTemplate("f0dce190-8106-43ca-9d67-7dce9b10a55e");

Get Retention Policy Assignment

Calling getInfo(String... fields) 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... fields) 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 the current retention policy, call the static getAll(BoxAPIConnection api, String... fields) method. It is possible to add filters to query passing a BoxFileVersionRetention.QueryFilter object as a parameter to getRetentions(BoxAPIConnection api, BoxFileVersionRetention.QueryFilter filter, String... fields).

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.
}