Skip to content

Latest commit

 

History

History
346 lines (301 loc) · 10.7 KB

legal-hold-policies.md

File metadata and controls

346 lines (301 loc) · 10.7 KB
Raw

Legal Hold Policies

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.

Create Legal Hold Policy

To create a new legal hold policy, call the legalHoldPolicies.create(name, options, callback) method.

client.legalHoldPolicies.create('IRS Audit')
	.then(policy => {
		/* policy -> {
			type: 'legal_hold_policy',
			id: '11111',
			policy_name: 'IRS Audit',
			description: '',
			status: 'active',
			assignment_counts: { user: 0, folder: 0, file: 0, file_version: 0 },
			is_ongoing: true,
			created_by: 
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2017-01-24T16:57:22-08:00',
			modified_at: '2017-01-24T16:57:22-08:00',
			deleted_at: null,
			filter_started_at: null,
			filter_ended_at: null }
		*/
	});

Get Legal Hold Policy

To retrieve information about a specific legal hold policy, call the legalHoldPolicies.get(policyID, options, callback) method.

client.legalHoldPolicies.get('11111')
	.then(policy => {
		/* policy -> {
			type: 'legal_hold_policy',
			id: '11111',
			policy_name: 'IRS Audit',
			description: '',
			status: 'active',
			assignment_counts: { user: 1, folder: 0, file: 0, file_version: 0 },
			created_by: 
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2016-05-18T10:28:45-07:00',
			modified_at: '2016-05-18T11:25:59-07:00',
			deleted_at: null,
			filter_started_at: '2016-05-17T01:00:00-07:00',
			filter_ended_at: '2016-05-21T01:00:00-07:00' }
		*/
	});

Requesting information for only the fields you need with the fields option can improve performance and reduce the size of the network request.

client.legalHoldPolicies.get('12345', {fields: 'policy_name,created_at,created_by'}, callback);

Update Legal Hold Policy

To update or modify an existing legal hold policy, call the legalHoldPolicies.update(policyID, updates, callback) method where updates is the set of key-value pairs to be updated on the policy object.

client.legalHoldPolicies.update('11111', {description: 'Documents related to IRS audit'})
	.then(policy => {
		/* policy -> {
			type: 'legal_hold_policy',
			id: '11111',
			policy_name: 'IRS Audit',
			description: 'Documents related to IRS audit',
			status: 'active',
			assignment_counts: { user: 1, folder: 0, file: 0, file_version: 0 },
			created_by: 
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2016-05-18T10:28:45-07:00',
			modified_at: '2016-05-18T11:25:59-07:00',
			deleted_at: null,
			filter_started_at: '2016-05-17T01:00:00-07:00',
			filter_ended_at: '2016-05-21T01:00:00-07:00' }
		*/
	});

Delete Legal Hold Policy

To delete a legal hold policy, call the legalHoldPolicies.delete(policyID, callback) method. Note that this is an asynchronous process - the policy will not be fully deleted yet when the response comes back.

client.legalHoldPolicies.delete('11111')
	.then(() => {
		// deletion started — no value returned	
	});

Get Enterprise Legal Hold Policies

To retrieve all of the legal hold policies for the given enterprise, call the legalHoldPolicies.getAll(options, callback) method.

client.legalHoldPolicies.getAll({policy_name: 'Important'})
	.then(policies => {
		/* policies -> {
			entries: 
			[ { type: 'legal_hold_policy',
				id: '11111',
				policy_name: 'Important Policy 1' },
				{ type: 'legal_hold_policy',
				id: '22222',
				policy_name: 'Important Policy 2' } ],
			limit: 100,
			order: [ { by: 'policy_name', direction: 'ASC' } ] }
		*/
	});

Get Legal Hold Policy Assignments

To get a list of all legal hold policy assignments associated with a specified legal hold policy, call the legalHoldPolicies.getAssignments(policyID, options, callback) method.

client.legalHoldPolicies.getAssignments('8763245', {assign_to_type: 'folder'})
	.then(assignments => {
		/* assignments -> {
			entries: [ { type: 'legal_hold_policy_assignment', id: '22222' } ],
			limit: 100,
			next_marker: 'someMarkerString' }
		*/
	});

Assign Legal Hold Policy

To assign a legal hold policy, call the legalHoldPolicies.assign(policyID, assignType, assignID, callback) method.

client.legalHoldPolicies.assign('11111', 'folder', '12345')
	.then(assignment => {
		/* assignment -> {
			type: 'legal_hold_policy_assignment',
			id: '22222',
			legal_hold_policy: 
			{ type: 'legal_hold_policy',
				id: '11111',
				policy_name: 'IRS Audit' },
			assigned_to: { type: 'folder', id: '12345' },
			assigned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			assigned_at: '2016-05-18T17:38:03-07:00',
			deleted_at: null }
		*/
	});

Delete Legal Hold Policy Assignment

To delete a legal hold assignment and remove a legal hold policy from an item, call the legalHoldPolicies.deleteAssignment(assignmentID, callback) method. Note that this is an asynchronous process - the assignment will not be fully deleted yet when the response comes back.

client.legalHoldPolicies.deleteAssignment('22222')
	.then(() => {
		// deletion started — no value returned
	});

Get Legal Hold Policy Assignment

To retrieve information about a legal hold policy assignment, call the legalHoldPolicies.getAssignment(assignmentID, options, callback) method.

client.legalHoldPolicies.getAssignment('22222')
	.then(assignment => {
		/* assignment -> {
			type: 'legal_hold_policy_assignment',
			id: '22222',
			legal_hold_policy: 
			{ type: 'legal_hold_policy',
				id: '11111',
				policy_name: 'IRS Audit' },
			assigned_to: { type: 'user', id: '33333' },
			assigned_by: 
			{ type: 'user',
				id: '11111',
				name: 'Example User',
				login: '[email protected]' },
			assigned_at: '2016-05-18T10:32:19-07:00',
			deleted_at: null }
		*/
	});

Requesting information for only the fields you need with the fields option can improve performance and reduce the size of the network request.

client.legalHoldPolicies.getAssignment('22222', {fields: 'id,assigned_by,assigned_at'})
	.then(assignment => {
		/* assignment -> {
			type: 'legal_hold_policy_assignment',
			id: '22222',
			assigned_by: 
			{ type: 'user',
				id: '11111',
				name: 'Example User',
				login: '[email protected]' },
			assigned_at: '2016-05-18T10:32:19-07:00' }
		*/
	});

Get File Version Legal Hold

A file version legal hold is a record for a held file version. To get information for a specific file version legal hold record, call the legalHoldPolicies.getFileVersionLegalHold(legalHoldID, options, callback) method.

client.legalHoldPolicies.getFileVersionLegalHold('55555')
	.then(fileVersionHold => {
		/* fileVersionHold -> {
			type: 'legal_hold',
			id: '55555',
			file_version: { type: 'file_version', id: '123456789' },
			file: { type: 'file', id: '66666', etag: '1' },
			legal_hold_policy_assignments: 
			[ { type: 'legal_hold_policy_assignment', id: '22222' },
				{ type: 'legal_hold_policy_assignment', id: '33333' } ],
			deleted_at: null }
		*/
	});

Requesting information for only the fields you need with the fields option can improve performance and reduce the size of the network request.

client.legalHoldPolicies.getFileVersionLegalHold('8762345', {fields: 'id,file'})
	.then(fileVersionHold => {
		/* fileVersionHold -> {
			type: 'legal_hold',
			id: '55555',
			file: { type: 'file', id: '66666', etag: '1' } }
		*/
	});

Get File Version Legal Holds

To retrieve a list of all file version legal holds for a given policy, call the legalHoldPolicies.getAllFileVersionLegalHolds(policyID, options, callback) method.

client.legalHoldPolicies.getAllFileVersionLegalHolds('11111')
	.then(holds => {
		/* holds -> {
			entries: 
			[ { type: 'legal_hold', id: '22222' },
				{ type: 'legal_hold', id: '33333' },
				{ type: 'legal_hold', id: '44444' } ],
			limit: 100,
			order: 
			[ { by: 'retention_policy_set_id, file_version_id',
				direction: 'ASC' } ] }
		*/
	});