Skip to content

Latest commit

 

History

History
320 lines (252 loc) · 16.3 KB

retention_policies.md

File metadata and controls

320 lines (252 loc) · 16.3 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

Indefinite policies

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);

Finite policies

The static BoxRetentionPolicy.createFinitePolicy(com.box.sdk.BoxAPIConnection, java.lang.String, int, com.box.sdk.BoxRetentionPolicy.BoxRetentionPolicyAction) 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.

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

Optional parameters

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

String notifiedUserID = "12345";
String description = "Policy to retain all reports";
RetentionPolicyParams optionalParams = new RetentionPolicyParams();
optionalParams.setCanOwnerExtendRetention(true);
optionalParams.setAreOwnersNotified(true);
optionalParams.setDescription(description);
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, BoxRetentionPolicyAction.RemoveRetention, 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.setPolicyName("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, String startDateField, 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);
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);

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");

Delete Retention Policy Assignment

To delete Retention Policy Assignment call delete() method.

BoxRetentionPolicyAssignment assignment = new BoxRetentionPolicyAssignment(api, id);
assignment.delete();

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

Get Files Under Retention For Assignment

To get an iterable with all files under retention for assignment policy, call the getFilesUnderRetention(BoxAPIConnection api, int limit, String... fields) method. This will return an interable with BoxFile.Info objects containing information about the files.

BoxRetentionPolicyAssignment policyAssignment = new BoxRetentionPolicyAssignment(api, id);
Iterable<BoxFile.Info> filesUnderRetention = policyAssignment.getFilesUnderRetention();
for (BoxFile.Info item : filesUnderRetention){
    // Do something with the files under retention.
}

Get File Versions Under Retention For Assignment

To get an iterable with all file versions under retention for assignment policy, call the getFileVersionsUnderRetention(BoxAPIConnection api, int limit, String... fields) method. This will return an interable with BoxFile.Info objects containing information about the file. You can get version by calling BoxFile.Info#getVersion().

BoxRetentionPolicyAssignment policyAssignment = new BoxRetentionPolicyAssignment(api, id);
Iterable<BoxFile.Info> fileVersionsUnderRetention = policyAssignment.getFileVersionsUnderRetention();
for (BoxFile.Info file : fileVersionsUnderRetention){
    BoxFileVersion version = file.getVersion();
    // Do something with the file version under retention.
}

Extend retention for a file

Once you create retention policy and assign it to a folder all files and subfolders will have same policy applied. If you need to extend retention for some file you can change it's dispositionAt value:

BoxFile.Info info = someFile.getInfo();
// to read current disposition date coming from retention policy 
BoxFile.Info info = someFile.getInfo("disposition_at");
Date currentDispositionDate = info.getDispositionAt();

// calculate new disposition date
Date dispositionAt = Date.from(
    LocalDateTime.ofInstant(currentDispositionDate.toInstant(), ZoneId.of("Z"))
    .plusDays(30)
    .toInstant(UTC)
);

// to change disposition date on a file you need to updateInfo
info.setDispositionAt(dispositionAt);
uploadedFile.updateInfo(info);