A legal hold policy blocks permanent deletion of content during ongoing litigation. Admins can create legal hold policies and then later assign them to specific folders, files, or users.
Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates. It is important to note that the legal hold object contains no information about what this policy applies to.
If an order of discovery is received or the customer is part of an ongoing litigation, a legal hold policy can be created to keep track of everything that needs to be held. The actual holding is done via Legal Hold Assignments.
- Get Information About a Legal Hold Policy
- List Legal Hold Policies
- Create New Legal Hold Policy
- Update Legal Hold Policy
- Delete Legal Hold Policy
- Assign Legal Hold Policy
- List Legal Hold Policy Assignments
- Get Information About a Legal Hold Assignment
- Delete Legal Hold Assignment
- List File Version Legal Holds
- Get Information about a File Version Legal Hold
To retrieve information about a legal hold policy, first call client.legal_hold_policy(policy_id)
to initialize the LegalHoldPolicy and then call legal_hold_policy.get(*, fields=None, headers=None, **kwargs) to
retrieve data from the API. This method returns a new LegalHoldPolicy object with fields populated by
data form the API, leaving the original object unmodified.
legal_hold_policy = client.legal_hold_policy(policy_id='12345').get()
print(f'The "{legal_hold_policy.policy_name}" policy is {legal_hold_policy.status}')To get the legal hold policies available in the enterprise, call
client.get_legal_hold_policies(policy_name=None, limit=None, marker=None, fields=None).
You can optionally pass a policy_name value to filter the results to include only policies that are a case-insensitive
prefix match by name. This method returns a BoxObjectCollection that allows you to iterate over the
LegalHoldPolicy objects in the collection.
policies = client.get_legal_hold_policies()
for policy in policies:
print(f'Legal Hold Policy "{policy.name}" has ID {policy.id}')To create a new legal hold policy, call
client.create_legal_hold_policy(policy_name, description=None, filter_starting_at=None, filter_ending_at=None, is_ongoing=None) with the name for the policy. You can optionally include a human-readable description, as
well as parameters describing which time period the policy applies to. You must specify either filter_starting_at
and filter_ending_at dates, or is_ongoing=True. This method returns a new LegalHoldPolicy object
representing the created policy.
new_policy = client.create_legal_hold_policy('New Policy', is_ongoing=True)
print(f'Created legal hold policy with ID {new_policy.id}')To update an existing legal hold policy, call legal_hold_policy.update_info(data=policy_update) with
a dict of properties to update on the policy. This method returns a new LegalHoldPolicy object
with the updates applied, leaving the original object unmodified.
policy_update = {'description': 'New Description', 'release_notes': 'Example Notes'}
updated_policy = client.legal_hold_policy(policy_id='12345').update_info(data=policy_update)To delete a legal hold policy, call legal_hold_policy.delete(). This method returns True to indicate that
the deletion request was successful.
Note: This is an asynchronous process - the policy assignment may not be fully deleted yet when the response comes back.
client.legal_hold_policy(policy_id='12345').delete()
print('Legal hold policy was deleted!')To assign a legal hold policy, call legal_hold_policy.assign(assignee). You can assign a legal hold policy
to a Folder, File, FileVersion, or User.
This will cause the associated items to be held and unable to be deleted.
folder_to_assign = client.folder(folder_id='22222')
assignment = client.legal_hold_policy(policy_id'12345').assign(folder_to_assign)
print(f'Applied policy "{assignment.legal_hold_policy.policy_name}" to {assignment.assigned_to.type} {assignment.assigned_to.id}')To get the assignments for a specific legal hold policy, call
legal_hold_policy.get_assignments(assign_to_type=None, assign_to_id=None, limit=None, marker=None, fields=None).
This method returns a BoxObjectCollection that allows you to iterate over the
LegalHoldPolicyAssignment objects in the collection.
assignments = client.legal_hold_policy(policy_id='12345').get_assignments()
for assignment in assignments:
print(f'Found policy assignment with ID {assignment.id}')To filter by the assignee type and/or id you can use pass in the assign_to_type and assign_to_id filter.
folder_id = '1111'
assignments = client.legal_hold_policy('1234').get_assignments('folder', folder_id)
for assignment in assignments:
print(f'Found policy assignment with ID {assignment.id}')To retrieve information about a legal hold policy assignment, first call
client.legal_hold_policy_assignment(policy_assignment_id) to initialize the
LegalHoldPolicyAssignment and then call legal_hold_policy_assignment.get(*, fields=None, headers=None, **kwargs) to
retrieve data about the assignment from the API. This method returns a new
LegalHoldPolicyAssignment with fields populated by data from the API, leaving the original object
unmodified.
assignment_id = '98765'
assignment = client.legal_hold_policy_assignment(assignment_id).get()
print(f'Policy {assignment.legal_hold_policy.id} is assigned to {assignment.assigned_to.type} {assignment.assigned_to.id}')To delete an existing legal hold policy assignment, call legal_hold_policy_assignment.delete(). This method
returns True to indicate that the deletion request was successful.
Note: This is an asynchronous process - the policy assignment may not be fully deleted yet when the response comes back.
assignment_id = '1111'
client.legal_hold_policy_assignment(assignment_id).delete()To get the actual hold records associated with a policy, call
legal_hold_policy.get_file_version_legal_holds(). This method returns a
BoxObjectCollection that allows you to iterate over the LegalHold objects in the
collection.
legal_holds = client.legal_hold_policy(policy_id='12345').get_file_version_legal_holds()
for legal_hold in legal_holds:
print(f'Got file version legal hold with ID {legal_hold.id}')To retrieve information about a file version legal hold, call legal_hold.get(*, fields=None, headers=None, **kwargs). This method
returns a new LegalHold with fields populated by data from the API, leaving the original object
unmodified.
file_version_legal_hold_id = '55555'
legal_hold = client.legal_hold(file_version_legal_hold_id).get()
print(f'Version {legal_hold.file_version.id} of file {legal_hold.file.id} is held by {len(legal_hold.legal_hold_policy_assignments)} assignment(s)')