Skip to content

Latest commit

 

History

History
387 lines (349 loc) · 9.63 KB

tasks.md

File metadata and controls

387 lines (349 loc) · 9.63 KB
Raw

Tasks

Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box.

Create a Task

To create a task call the tasks.create(fileID, options, callback) method.

var options = {
	message: 'Please review for publication!',
	due_at: '2014-04-03T11:09:43-07:00'
};
client.tasks.create('22222', options)
	.then(task => {
		/* task -> {
			type: 'task',
			id: '11111',
			item: 
			{ type: 'file',
				id: '22222',
				sequence_id: '0',
				etag: '0',
				sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
				name: 'box-logo.png' },
			due_at: '2014-04-03T11:09:43-07:00',
			action: 'review',
			message: 'Please review for publication!',
			task_assignment_collection: { total_count: 0, entries: [] },
			is_completed: false,
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2013-04-03T11:12:54-07:00' }
		*/
	});

Get a Task's Information

To get a task information call the tasks.get(taskID, options, callback) method.

client.tasks.get('11111')
	.then(task => {
		/* task -> {
			type: 'task',
			id: '11111',
			item: 
			{ type: 'file',
				id: '22222',
				sequence_id: '0',
				etag: '0',
				sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
				name: 'box-logo.png' },
			due_at: '2014-04-03T11:09:43-07:00',
			action: 'review',
			message: 'Please review for publication!',
			task_assignment_collection: { total_count: 0, entries: [] },
			is_completed: false,
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2013-04-03T11:12:54-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.tasks.get('11111', {fields: 'message,is_completed'})
	.then(task => {
		/* task -> {
			type: 'task',
			id: '11111',
			message: 'Please review for publication!',
			is_completed: false }
		*/
	});

Update a Task

To update a task call the tasks.update(taskID, updates, callback) method with the set of fields to update and their new values.

client.tasks.update('11111', { message: 'Could you please review?' })
	.then(task => {
		/* task -> {
			type: 'task',
			id: '11111',
			item: 
			{ type: 'file',
				id: '22222',
				sequence_id: '0',
				etag: '0',
				sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
				name: 'box-logo.png' },
			due_at: '2014-04-03T11:09:43-07:00',
			action: 'review',
			message: 'Could you please review?',
			task_assignment_collection: { total_count: 0, entries: [] },
			is_completed: false,
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2013-04-03T11:12:54-07:00' }
		*/
	});

Delete a Task

To delete a task, call the tasks.delete(taskID, callback) method with the ID of the task to be deleted.

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

Get Assignments for a Task

To get a list of assignments for a task, which associate the task to users who must complete it, call the tasks.getAssignments(taskID, options, callback) method.

client.tasks.getAssignments('11111')
	.then(assignments => {
		/* assignments -> {
			total_count: 1,
			entries: 
			[ { type: 'task_assignment',
				id: '22222',
				item: 
					{ type: 'file',
					id: '44444',
					sequence_id: '0',
					etag: '0',
					sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
					name: 'box-logo.png' },
				assigned_to: 
					{ type: 'user',
					id: '33333',
					name: 'Example User',
					login: '[email protected]' } } ] }
		*/
	});

Get Task Assignment

To retrieve information about a specific task assignment, call the tasks.getAssignment(assignmentID, options, callback) method with the ID of the assignment to get.

client.tasks.getAssignment('12345')
	.then(assignment => {
		/* assignment -> {
			type: 'task_assignment',
			id: '12345',
			item: 
			{ type: 'file',
				id: '33333',
				sequence_id: '0',
				etag: '0',
				sha1: '7840095ee096ee8297676a138d4e316eabb3ec96',
				name: 'script.js' },
			assigned_to: 
			{ type: 'user',
				id: '22222',
				name: 'Sample Assignee',
				login: '[email protected]' },
			message: null,
			completed_at: null,
			assigned_at: '2013-05-10T11:43:41-07:00',
			reminded_at: null,
			resolution_state: 'incomplete',
			assigned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' } }
		*/
	});

Assign Task

To assign a task to a user, call tasks.assignByUserID(taskID, userID, callback) or tasks.assignByEmail(taskID, email, callback) with the ID of the task to assign and either the ID or login email address of the user to whom the task should be assigned.

// Assign task 11111 to user 22222
var taskID = '11111';
var userID = '22222';
client.tasks.assignByUserID(taskID, userID)
	.then(assignment => {
		/* assignment -> {
			type: 'task_assignment',
			id: '12345',
			item: 
			{ type: 'file',
				id: '33333',
				sequence_id: '0',
				etag: '0',
				sha1: '7840095ee096ee8297676a138d4e316eabb3ec96',
				name: 'script.js' },
			assigned_to: 
			{ type: 'user',
				id: '22222',
				name: 'Sample Assignee',
				login: '[email protected]' },
			message: null,
			completed_at: null,
			assigned_at: '2013-05-10T11:43:41-07:00',
			reminded_at: null,
			resolution_state: 'incomplete',
			assigned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' } }
		*/
	});
// Assign task 11111 to the user with email address [email protected]
client.tasks.assignByEmail('11111', '[email protected]')
	.then(assignment => {
		// ...
	});

Update Task Assignment

To update a task assignment, call the tasks.updateAssignment(assignmentID, options, callback) method. This can be used to resolve or complete a task.

// Complete a task
client.tasks.updateAssignment(
	'12345',
	{
		message: 'Done!',
		resolution_state: client.tasks.resolutionStates.COMPLETE
	})
	.then(assignment => {
		/* assignment -> {
			type: 'task_assignment',
			id: '12345',
			item: 
			{ type: 'file',
				id: '33333',
				sequence_id: '0',
				etag: '0',
				sha1: '7840095ee096ee8297676a138d4e316eabb3ec96',
				name: 'script.js' },
			assigned_to: 
			{ type: 'user',
				id: '22222',
				name: 'Sample Assignee',
				login: '[email protected]' },
			message: 'Done!',
			completed_at: null,
			assigned_at: '2013-05-10T11:43:41-07:00',
			reminded_at: null,
			resolution_state: 'complete',
			assigned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' } }
		*/
	});
// Update the task assignment message
client.tasks.updateAssignment(
	'12345',
	{
		message: 'This needs some more changes'
	})
	.then(assignment => {
		// ...
	});

Remove Task Assignment

To delete a task assignment, effectively unassigning a user from the task, call the tasks.deleteAssignment(assignmentID, callback) method with the ID of the assignment to remove.

client.tasks.deleteAssignment('12345')
	.then(() => {
		// deletion succeeded — no value returned
	});

Get Tasks on a File

Calling the files.getTasks(fileID, options, callback) method will retrieve all of the tasks for given file.

client.files.getTasks('11111')
	.then(tasks => {
		/* tasks -> {
			total_count: 1,
			entries: 
			[ { type: 'task',
				id: '22222',
				item: 
					{ type: 'file',
					id: '11111',
					sequence_id: '6',
					etag: '6',
					sha1: '81cc829fb8366fcfc108aa6c5a9bde01a6a10c16',
					name: 'box-logo.png' },
				due_at: null } ] }
		*/
	});