Class: RetentionPolicies

RetentionPolicies(client) → {void}

Simple manager for interacting with all Retention Policies endpoints and actions.

Constructor

new RetentionPolicies(client) → {void}

Parameters:
Name Type Description
client BoxClient The Box API Client that is responsible for making calls to the API
Source:
Returns:
Type
void

Members

(readonly) assignmentTypes :RetentionPolicyAssignmentType

Enum of valid policy assignment types, which specify what object the policy applies to
Type:
Source:

(readonly) dispositionActions :RetentionPolicyDispositionAction

Enum of valid retention policy disposition actions, which specify what should be done when the retention period is over
Type:
Source:

(readonly) policyTypes :RetentionPolicyType

Enum of valid retention policy types, which specify how long the policy should remain in effect.
Type:
Source:

(readonly) retentionTypes :RetentionType

Enum of valid retention types. Could be either modifiable or non-modifiable.
Type:
Source:

Methods

assign(policyID, assignType, assignID, optionsopt, callbackopt) → {Promise.<Object>}

Assign a retention policy to a folder or the entire enterprise. API Endpoint: '/retention_policy_assignments Method: POST
Parameters:
Name Type Attributes Description
policyID string The ID of the policy to assign
assignType RetentionPolicyAssignmentType The type of object the policy will be assigned to
assignID string The Box ID of the object to assign the retention policy to
options Object <optional>
 Optional parameters for the request
Properties
Name Type Attributes Description
filter_fields Array.<MetadataFilterField> <optional>
 Metadata fields to filter against, if assigning to a metadata template
start_date_field string <optional>
 Id of Metadata field which will be used to specify the start date for the retention policy, or set this to "upload_date" as value to use the date when the file was uploaded to Box
callback function <optional>
 Passed the new assignment object if successful, error otherwise
Source:
Returns:
A promise resolving to the created assignment object
Type
Promise.<Object>

assign(policyID, assignType, assignID, optionsopt, callbackopt) → {Promise.<Object>}

Assign a retention policy to a folder or the entire enterprise. API Endpoint: '/retention_policy_assignments Method: POST
Parameters:
Name Type Attributes Description
policyID string The ID of the policy to assign
assignType RetentionPolicyAssignmentType The type of object the policy will be assigned to
assignID string The Box ID of the object to assign the retention policy to
options Object <optional>
 Optional parameters for the request
Properties
Name Type Attributes Description
filter_fields Array.<MetadataFilterField> <optional>
 Metadata fields to filter against, if assigning to a metadata template
start_date_field string <optional>
 Id of Metadata field which will be used to specify the start date for the retention policy, or set this to "upload_date" as value to use the date when the file was uploaded to Box
callback function <optional>
 Passed the new assignment object if successful, error otherwise
Source:
Returns:
A promise resolving to the created assignment object
Type
Promise.<Object>

create(name, type, action, optionsopt, callbackopt) → {Promise.<Object>}

Used to create a single retention policy for an enterprise API Endpoint: '/retention_policies' Method: POST
Parameters:
Name Type Attributes Description
name string The name of the retention policy to be created
type RetentionPolicyType The type of policy to create
action RetentionPolicyDispositionAction The disposition action for the new policy
options Object <optional>
 Additional parameters
Properties
Name Type Attributes Description
are_owners_notified boolean <optional>
 Whether or not owner and co-owners of a file are notified when the policy nears expiration
can_owner_extend_retention boolean <optional>
 Whether or not the owner of a file will be allowed to extend the retention
custom_notification_recipients Array.<UserMini> <optional>
 A list of users notified when the retention policy duration is about to end
description string <optional>
 The additional text description of the retention policy
retention_length int <optional>
 For finite policies, the number of days to retain the content
retention_type RetentionType <optional>
 The type of retention for the new policy
callback function <optional>
 Passed the new policy information if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the new policy object
Type
Promise.<Object>

create(name, type, action, optionsopt, callbackopt) → {Promise.<Object>}

Used to create a single retention policy for an enterprise API Endpoint: '/retention_policies' Method: POST
Parameters:
Name Type Attributes Description
name string The name of the retention policy to be created
type RetentionPolicyType The type of policy to create
action RetentionPolicyDispositionAction The disposition action for the new policy
options Object <optional>
 Additional parameters
Properties
Name Type Attributes Description
are_owners_notified boolean <optional>
 Whether or not owner and co-owners of a file are notified when the policy nears expiration
can_owner_extend_retention boolean <optional>
 Whether or not the owner of a file will be allowed to extend the retention
custom_notification_recipients Array.<UserMini> <optional>
 A list of users notified when the retention policy duration is about to end
description string <optional>
 The additional text description of the retention policy
retention_length int <optional>
 For finite policies, the number of days to retain the content
retention_type RetentionType <optional>
 The type of retention for the new policy
callback function <optional>
 Passed the new policy information if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the new policy object
Type
Promise.<Object>

deleteAssignment(assignmentID, callbackopt) → {Promise.<void>}

Delete a specific policy assignment. API Endpoint: '/retention_policy_assignments/:assignmentID' Method: DELETE
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to delete
callback function <optional>
 Empty response body passed if successful.
Source:
Returns:
A promise resolving to nothing
Type
Promise.<void>

deleteAssignment(assignmentID, callbackopt) → {Promise.<void>}

Delete a specific policy assignment. API Endpoint: '/retention_policy_assignments/:assignmentID' Method: DELETE
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to delete
callback function <optional>
 Empty response body passed if successful.
Source:
Returns:
A promise resolving to nothing
Type
Promise.<void>

get(policyID, optionsopt, callbackopt) → {Promise.<Object>}

Fetches details about a specific retention policy API Endpoint: '/retention_policies/:policyID' Method: GET
Parameters:
Name Type Attributes Description
policyID string The Box ID of the retention policy being requested
options Object <optional>
 Additional options for the request. Can be left null in most cases.
callback function <optional>
 Passed the policy information if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the policy object
Type
Promise.<Object>

get(policyID, optionsopt, callbackopt) → {Promise.<Object>}

Fetches details about a specific retention policy API Endpoint: '/retention_policies/:policyID' Method: GET
Parameters:
Name Type Attributes Description
policyID string The Box ID of the retention policy being requested
options Object <optional>
 Additional options for the request. Can be left null in most cases.
callback function <optional>
 Passed the policy information if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the policy object
Type
Promise.<Object>

getAll(optionsopt, callbackopt) → {Promise.<Object>}

Fetches a list of retention policies for the enterprise API Endpoint: '/retention_policies Method: GET
Parameters:
Name Type Attributes Description
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
policy_name string <optional>
 A full or partial name to filter the retention policies by
policy_type RetentionPolicyType <optional>
 A policy type to filter the retention policies by
created_by_user_id string <optional>
 A user id to filter the retention policies by
callback function <optional>
 Passed the policy objects if they were acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the collection of policies
Type
Promise.<Object>

getAll(optionsopt, callbackopt) → {Promise.<Object>}

Fetches a list of retention policies for the enterprise API Endpoint: '/retention_policies Method: GET
Parameters:
Name Type Attributes Description
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
policy_name string <optional>
 A full or partial name to filter the retention policies by
policy_type RetentionPolicyType <optional>
 A policy type to filter the retention policies by
created_by_user_id string <optional>
 A user id to filter the retention policies by
callback function <optional>
 Passed the policy objects if they were acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the collection of policies
Type
Promise.<Object>

getAllFileVersionRetentions(optionsopt, callbackopt) → {Promise.<Object>}

Get a list of retention records for a retained file versions in an enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/file_version_retentions' Method: GET
Parameters:
Name Type Attributes Description
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
file_id string <optional>
 A file id to filter the file version retentions by
file_version_id string <optional>
 A file version id to filter the file version retentions by
policy_id string <optional>
 A policy id to filter the file version retentions by
disposition_action RetentionPolicyDispositionAction <optional>
 The disposition action of the retention policy to filter by
disposition_before string <optional>
 Filter by retention policies which will complete before a certain time
disposition_after string <optional>
 Filter by retention policies which will complete after a certain time
limit int <optional>
 The maximum number of items to return in a page
marker string <optional>
 Paging marker, left blank to begin paging from the beginning
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the collection of retention records
Type
Promise.<Object>

getAllFileVersionRetentions(optionsopt, callbackopt) → {Promise.<Object>}

Get a list of retention records for a retained file versions in an enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/file_version_retentions' Method: GET
Parameters:
Name Type Attributes Description
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
file_id string <optional>
 A file id to filter the file version retentions by
file_version_id string <optional>
 A file version id to filter the file version retentions by
policy_id string <optional>
 A policy id to filter the file version retentions by
disposition_action RetentionPolicyDispositionAction <optional>
 The disposition action of the retention policy to filter by
disposition_before string <optional>
 Filter by retention policies which will complete before a certain time
disposition_after string <optional>
 Filter by retention policies which will complete after a certain time
limit int <optional>
 The maximum number of items to return in a page
marker string <optional>
 Paging marker, left blank to begin paging from the beginning
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the collection of retention records
Type
Promise.<Object>

getAssignment(assignmentID, optionsopt, callbackopt) → {Promise.<Object>}

Fetch a specific policy assignment API Endpoint: '/retention_policy_assignments/:assignmentID' Method: GET
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to fetch
options Object <optional>
 Additional options for the request. Can be left null in most cases.
callback function <optional>
 Passed the assignment object if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the assignment object
Type
Promise.<Object>

getAssignment(assignmentID, optionsopt, callbackopt) → {Promise.<Object>}

Fetch a specific policy assignment API Endpoint: '/retention_policy_assignments/:assignmentID' Method: GET
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to fetch
options Object <optional>
 Additional options for the request. Can be left null in most cases.
callback function <optional>
 Passed the assignment object if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the assignment object
Type
Promise.<Object>

getAssignments(policyID, optionsopt, callbackopt) → {Promise.<Object>}

Fetch a list of assignments for a given retention policy API Endpoint: '/retention_policies/:policyID/assignments' Method: GET
Parameters:
Name Type Attributes Description
policyID string The Box ID of the retention policy to get assignments for
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
type RetentionPolicyAssignmentType <optional>
 The type of the retention policy assignment to retrieve
callback function <optional>
 Passed the assignment objects if they were acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the collection of policy assignments
Type
Promise.<Object>

getAssignments(policyID, optionsopt, callbackopt) → {Promise.<Object>}

Fetch a list of assignments for a given retention policy API Endpoint: '/retention_policies/:policyID/assignments' Method: GET
Parameters:
Name Type Attributes Description
policyID string The Box ID of the retention policy to get assignments for
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
type RetentionPolicyAssignmentType <optional>
 The type of the retention policy assignment to retrieve
callback function <optional>
 Passed the assignment objects if they were acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the collection of policy assignments
Type
Promise.<Object>

getFilesUnderRetentionForAssignment(assignmentID, optionsopt, callbackopt) → {Promise.<Object>}

Get files under retention by each assignment To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/retention_policy_assignments/:assignmentID/files_under_retention' Method: GET
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to fetch
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
limit int <optional>
 The maximum number of items to return in a page
marker string <optional>
 Paging marker, left blank to begin paging from the beginning
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the collection of retention records
Type
Promise.<Object>

getFilesUnderRetentionForAssignment(assignmentID, optionsopt, callbackopt) → {Promise.<Object>}

Get files under retention by each assignment To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/retention_policy_assignments/:assignmentID/files_under_retention' Method: GET
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to fetch
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
limit int <optional>
 The maximum number of items to return in a page
marker string <optional>
 Paging marker, left blank to begin paging from the beginning
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the collection of retention records
Type
Promise.<Object>

getFileVersionRetention(retentionID, optionsopt, callbackopt) → {Promise.<Object>}

Get the specific retention record for a retained file version. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/file_version_retentions/:retentionID' Method: GET
Parameters:
Name Type Attributes Description
retentionID string The ID for the file retention record to retrieve
options Object <optional>
 Additional options for the request. Can be left null in most cases.
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the retention record
Type
Promise.<Object>

getFileVersionRetention(retentionID, optionsopt, callbackopt) → {Promise.<Object>}

Get the specific retention record for a retained file version. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/file_version_retentions/:retentionID' Method: GET
Parameters:
Name Type Attributes Description
retentionID string The ID for the file retention record to retrieve
options Object <optional>
 Additional options for the request. Can be left null in most cases.
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the retention record
Type
Promise.<Object>

getFileVersionsUnderRetentionForAssignment(assignmentID, optionsopt, callbackopt) → {Promise.<Object>}

Get file versions under retention by each assignment To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/retention_policy_assignments/:assignmentID/file_versions_under_retention' Method: GET
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to fetch
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
limit int <optional>
 The maximum number of items to return in a page
marker string <optional>
 Paging marker, left blank to begin paging from the beginning
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the collection of retention records
Type
Promise.<Object>

getFileVersionsUnderRetentionForAssignment(assignmentID, optionsopt, callbackopt) → {Promise.<Object>}

Get file versions under retention by each assignment To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. API Endpoint: '/retention_policy_assignments/:assignmentID/file_versions_under_retention' Method: GET
Parameters:
Name Type Attributes Description
assignmentID string The Box ID of the policy assignment object to fetch
options Object <optional>
 Additional options for the request. Can be left null in most cases.
Properties
Name Type Attributes Description
limit int <optional>
 The maximum number of items to return in a page
marker string <optional>
 Paging marker, left blank to begin paging from the beginning
callback function <optional>
 Pass the file version retention record if successful, error otherwise
Source:
Returns:
A promise resolving to the collection of retention records
Type
Promise.<Object>

update(policyID, updates, callbackopt) → {Promise.<Object>}

Update or modify a retention policy. API Endpoint: '/retention_policies/:policyID' Method: PUT
Parameters:
Name Type Attributes Description
policyID string The Box ID of the retention policy to update
updates Object The information to be updated
Properties
Name Type Attributes Description
policy_name string <optional>
 The name of the retention policy
disposition_action RetentionPolicyDispositionAction <optional>
 The disposition action for the updated policy
are_owners_notified boolean <optional>
 Whether or not owner and co-owners of a file are notified when the policy nears expiration
can_owner_extend_retention boolean <optional>
 Whether or not the owner of a file will be allowed to extend the retention
custom_notification_recipients Array.<UserMini> <optional>
 A list of users notified when the retention policy duration is about to end
description string <optional>
 The additional text description of the retention policy
retention_length int <optional>
 For finite policies, the number of days to retain the content
retention_type RetentionType <optional>
 The type of retention. The only possible value here is non_modifiable. You can convert a modifiable policy to non_modifiable, but not the other way around.
status string <optional>
 Used to retire a retention policy if status is set to retired
callback function <optional>
 Passed the updated policy information if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the updated policy object
Type
Promise.<Object>

update(policyID, updates, callbackopt) → {Promise.<Object>}

Update or modify a retention policy. API Endpoint: '/retention_policies/:policyID' Method: PUT
Parameters:
Name Type Attributes Description
policyID string The Box ID of the retention policy to update
updates Object The information to be updated
Properties
Name Type Attributes Description
policy_name string <optional>
 The name of the retention policy
disposition_action RetentionPolicyDispositionAction <optional>
 The disposition action for the updated policy
are_owners_notified boolean <optional>
 Whether or not owner and co-owners of a file are notified when the policy nears expiration
can_owner_extend_retention boolean <optional>
 Whether or not the owner of a file will be allowed to extend the retention
custom_notification_recipients Array.<UserMini> <optional>
 A list of users notified when the retention policy duration is about to end
description string <optional>
 The additional text description of the retention policy
retention_length int <optional>
 For finite policies, the number of days to retain the content
retention_type RetentionType <optional>
 The type of retention. The only possible value here is non_modifiable. You can convert a modifiable policy to non_modifiable, but not the other way around.
status string <optional>
 Used to retire a retention policy if status is set to retired
callback function <optional>
 Passed the updated policy information if it was acquired successfully, error otherwise
Source:
Returns:
A promise resolving to the updated policy object
Type
Promise.<Object>