Package pro.taskana.task.api

Interface TaskService

All Known Implementing Classes:

TaskServiceImpl

public interface TaskService

The TaskService manages all operations on Tasks.

Method Summary

Modifier and Type	Method	Description
Task	cancelClaim(String taskId)	Cancel the claim of an existing Task if it was claimed by the current user before.
Task	cancelClaim(String taskId, boolean keepOwner)	Cancel the claim of an existing Task if it was claimed by the current user before.
Task	cancelTask(String taskId)	Cancels the Task with the given id.
Task	claim(String taskId)	Claim an existing Task for the current user.
Task	completeTask(String taskId)	Complete a claimed Task as owner or TaskanaRole.ADMIN and update state and timestamps.
BulkOperationResults<String,TaskanaException>	completeTasks(List<String> taskIds)	Completes a List of Tasks.
Task	createTask(Task taskToCreate)	Inserts a Task that doesn't exist in the database yet.
TaskComment	createTaskComment(TaskComment taskComment)	Inserts the specified TaskComment into the database.
TaskCommentQuery	createTaskCommentQuery()	Creates an empty TaskCommentQuery.
TaskQuery	createTaskQuery()	Creates an empty TaskQuery.
void	deleteTask(String taskId)	Deletes the Task with the given id.
void	deleteTaskComment(String taskCommentId)	Deletes the TaskComment with the given id.
BulkOperationResults<String,TaskanaException>	deleteTasks(List<String> tasks)	Deletes a List of Tasks.
Task	forceCancelClaim(String taskId)	Cancel the claim of an existing Task even if it was claimed by another user.
Task	forceCancelClaim(String taskId, boolean keepOwner)	Cancel the claim of an existing Task even if it was claimed by another user.
Task	forceClaim(String taskId)	Claim an existing Task for the current user even if it is already claimed by someone else.
Task	forceCompleteTask(String taskId)	Completes a Task and updates state and timestamps in every case if the Task exists.
BulkOperationResults<String,TaskanaException>	forceCompleteTasks(List<String> taskIds)	Completes each existing Task in the given List in every case, independent of the owner or state of the Task.
void	forceDeleteTask(String taskId)	Deletes the Task with the given id even if it isn't completed.
Task	forceRequestChanges(String taskId)	Request changes for an existing Task even if the current user is not the owner or the Task is not in TaskState.IN_REVIEW yet.
Task	forceRequestReview(String taskId)	Request review for an existing Task even if the current user is not the owner or the Task is not in TaskState.CLAIMED yet.
Task	getTask(String taskId)	Fetches a Task from the database by the specified id.
TaskComment	getTaskComment(String taskCommentId)	Retrieves the TaskComment with the given id.
List<TaskComment>	getTaskComments(String taskId)	Retrieves the List of TaskComments for the Task with given id.
Attachment	newAttachment()	Instantiates a non-persistent/non-inserted Attachment.
ObjectReference	newObjectReference()	Instantiates a non-persistent/non-inserted ObjectReference.
ObjectReference	newObjectReference(String company, String system, String systemInstance, String type, String value)	Instantiates a non-persistent/non-inserted ObjectReference.
Task	newTask()	Instantiates a non-persistent/non-inserted Task.
Task	newTask(String workbasketId)	Instantiates a non-persistent/non-inserted Task.
Task	newTask(String workbasketKey, String domain)	Instantiates a non-persistent/non-inserted Task.
TaskComment	newTaskComment(String taskId)	Instantiates a non-persistent/non-inserted TaskComment.
Task	requestChanges(String taskId)	Request changes for an existing Task that is in TaskState.IN_REVIEW.
Task	requestReview(String taskId)	Request review for an existing Task that is in TaskState.CLAIMED.
Optional<Task>	selectAndClaim(TaskQuery taskQuery)	Selects and claims the first Task which is returned by the TaskQuery.
BulkOperationResults<String,TaskanaException>	setCallbackStateForTasks(List<String> externalIds, CallbackState state)	Sets the specified CallbackState on a List of Tasks.
BulkOperationResults<String,TaskanaException>	setOwnerOfTasks(String owner, List<String> taskIds)	Sets the owner on a List of Tasks.
BulkOperationResults<String,TaskanaException>	setPlannedPropertyOfTasks(Instant planned, List<String> taskIds)	Sets the planned Instant on a List of Tasks.
Task	setTaskRead(String taskId, boolean isRead)	Sets the value of isRead of the specified Task.
Task	terminateTask(String taskId)	Terminates a Task.
default Task	transfer(String taskId, String destinationWorkbasketId)	Transfers a Task to another Workbasket while always setting isTransferred to true.
Task	transfer(String taskId, String destinationWorkbasketId, boolean setTransferFlag)	Transfers a Task to another Workbasket.
default Task	transfer(String taskId, String workbasketKey, String domain)	Transfers a Task to another Workbasket while always setting isTransferred .
Task	transfer(String taskId, String workbasketKey, String domain, boolean setTransferFlag)	Transfers a Task to another Workbasket.
default BulkOperationResults<String,TaskanaException>	transferTasks(String destinationWorkbasketKey, String destinationWorkbasketDomain, List<String> taskIds)	Transfers a List of Tasks to another Workbasket while always setting isTransferred to true.
BulkOperationResults<String,TaskanaException>	transferTasks(String destinationWorkbasketKey, String destinationWorkbasketDomain, List<String> taskIds, boolean setTransferFlag)	Transfers a List of Tasks to another Workbasket.
default BulkOperationResults<String,TaskanaException>	transferTasks(String destinationWorkbasketId, List<String> taskIds)	Transfers a List of Tasks to another Workbasket while always setting isTransferred to true.
BulkOperationResults<String,TaskanaException>	transferTasks(String destinationWorkbasketId, List<String> taskIds, boolean setTransferFlag)	Transfers a List of Tasks to another Workbasket.
default BulkOperationResults<String,TaskanaException>	transferTasksWithOwner(String destinationWorkbasketKey, String destinationWorkbasketDomain, List<String> taskIds, String owner)	Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks while always setting isTransferred to true.
BulkOperationResults<String,TaskanaException>	transferTasksWithOwner(String destinationWorkbasketKey, String destinationWorkbasketDomain, List<String> taskIds, String owner, boolean setTransferFlag)	Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks.
default BulkOperationResults<String,TaskanaException>	transferTasksWithOwner(String destinationWorkbasketId, List<String> taskIds, String owner)	Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks to owner while always setting isTransferred to true.
BulkOperationResults<String,TaskanaException>	transferTasksWithOwner(String destinationWorkbasketId, List<String> taskIds, String owner, boolean setTransferFlag)	Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks.
default Task	transferWithOwner(String taskId, String destinationWorkbasketId, String owner)	Transfers a Task to another Workbasket and sets the owner of the Task in the new Workbasket to owner while always setting isTransferred to true.
Task	transferWithOwner(String taskId, String destinationWorkbasketId, String owner, boolean setTransferFlag)	Transfers a Task to another Workbasket and sets the owner of the Task.
default Task	transferWithOwner(String taskId, String workbasketKey, String domain, String owner)	Transfers a Task to another Workbasket and sets the owner of the Task in new Workbasket to owner while always setting isTransferred .
Task	transferWithOwner(String taskId, String workbasketKey, String domain, String owner, boolean setTransferFlag)	Transfers a Task to another Workbasket and sets the owner of the Task.
Task	updateTask(Task task)	Update a Task.
TaskComment	updateTaskComment(TaskComment taskComment)	Updates the specified TaskComment.
List<String>	updateTasks(List<String> taskIds, Map<TaskCustomField,String> customFieldsToUpdate)	Updates specified TaskCustomFields for all given Tasks.
List<String>	updateTasks(ObjectReference selectionCriteria, Map<TaskCustomField,String> customFieldsToUpdate)	Updates specified TaskCustomFields of Tasks associated with the given primaryObjRef.

Method Details

newTask

Task newTask()

Instantiates a non-persistent/non-inserted Task.

Since a Task doesn't allow setting a workbasketSummary, please either provide an implementation of the TaskRoutingProvider or use the referenced methods to create a Task within a specific Workbasket.

Returns:

the instantiated Task

See Also:

• newTask(String)
• newTask(String, String)

newTask

Task newTask(String workbasketId)

Instantiates a non-persistent/non-inserted Task.

Parameters:

workbasketId - the id of the Workbasket to which the Task belongs

Returns:

the instantiated Task

See Also:

• newTask()
• newTask(String, String)

newTask

Task newTask(String workbasketKey,
 String domain)

Instantiates a non-persistent/non-inserted Task.

Parameters:

workbasketKey - the key of the Workbasket to which the Task belongs

domain - the domain of the Workbasket to which the Task belongs

Returns:

the instantiated Task

See Also:

• newTask()
• newTask(String)

createTask

Task createTask(Task taskToCreate)
         throws WorkbasketNotFoundException,
ClassificationNotFoundException,
TaskAlreadyExistException,
InvalidArgumentException,
AttachmentPersistenceException,
ObjectReferencePersistenceException,
NotAuthorizedOnWorkbasketException

Inserts a Task that doesn't exist in the database yet.

If the workbasketSummary of the given Task is NULL, TaskService will call the TaskRoutingProvider to determine a Workbasket for the Task. If the TaskRoutingProvider is not active, e.g. because no TaskRoutingProvider is registered, or the TaskRoutingProvider doesn't find a Workbasket, the Task will not be inserted.

The default values of the created Task are:

• id - generated automatically
• externalId - if NULL, then generated automatically, else unchanged
• businessProcessId - generated automatically
• name - if NULL then the name of its Classification, else unchanged
• description - if NULL then description of its Classification, else unchanged
• creator - id of current user
• state - TaskState.READY
• isRead - false
• isTransferred - false

Parameters:

taskToCreate - the transient Task to be inserted

Returns:

the created and inserted Task

Throws:

TaskAlreadyExistException - if the Task already exists

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.APPEND for the Workbasket the Task is in

WorkbasketNotFoundException - if the Workbasket referenced by the workbasketSummary of the Task isn't found

ClassificationNotFoundException - if the Classification referenced by classificationSummary of the Task isn't found

InvalidArgumentException - if the primaryObjRef is invalid

AttachmentPersistenceException - if an Attachment with the same id was added to the Task multiple times without using Task.addAttachment(Attachment)

ObjectReferencePersistenceException - if an ObjectReference with the same id was added to the Task multiple times without using TaskSummary.addSecondaryObjectReference(ObjectReference)

getTask

Task getTask(String taskId)
      throws TaskNotFoundException,
NotAuthorizedOnWorkbasketException

Fetches a Task from the database by the specified id.

Parameters:

taskId - the id of the Task

Returns:

the Task with the specified taskId

Throws:

TaskNotFoundException - if the Task with taskId wasn't found

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

claim

Task claim(String taskId)
    throws TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Claim an existing Task for the current user.

Parameters:

taskId - the id of the Task to be claimed

Returns:

the claimed Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

InvalidTaskStateException - if the state of the Task with taskId isn't TaskState.READY

InvalidOwnerException - if the Task with taskId is claimed by some else

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

forceClaim

Task forceClaim(String taskId)
         throws TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Claim an existing Task for the current user even if it is already claimed by someone else.

Parameters:

taskId - the id of the Task to be claimed

Returns:

the claimed Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

InvalidTaskStateException - if the state of Task with taskId is in TaskState.END_STATES

InvalidOwnerException - cannot be thrown

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

selectAndClaim

Optional<Task> selectAndClaim(TaskQuery taskQuery)
                       throws InvalidOwnerException,
NotAuthorizedOnWorkbasketException

Selects and claims the first Task which is returned by the TaskQuery.

Parameters:

taskQuery - the TaskQuery

Returns:

the Task that got selected and claimed

Throws:

InvalidOwnerException - if the Task is claimed by someone else

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

cancelClaim

Task cancelClaim(String taskId)
          throws TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Cancel the claim of an existing Task if it was claimed by the current user before.

Parameters:

taskId - the id of the Task which should be unclaimed

Returns:

the unclaimed Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

InvalidTaskStateException - if the Task is already in one of the TaskState.END_STATES

InvalidOwnerException - if the Task is claimed by another user

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

cancelClaim

Task cancelClaim(String taskId,
 boolean keepOwner)
          throws TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Cancel the claim of an existing Task if it was claimed by the current user before.

Parameters:

taskId - the id of the Task which should be unclaimed

keepOwner - If set to true, will keep the TaskSummary.getOwner() and TaskSummary.getOwnerLongName()

Returns:

the unclaimed Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

InvalidTaskStateException - if the Task is already in one of the TaskState.END_STATES

InvalidOwnerException - if the Task is claimed by another user

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

forceCancelClaim

Task forceCancelClaim(String taskId,
 boolean keepOwner)
               throws TaskNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Cancel the claim of an existing Task even if it was claimed by another user.

Parameters:

taskId - the id of the Task which should be unclaimed

keepOwner - If set to true, will keep the TaskSummary.getOwner() and TaskSummary.getOwnerLongName()

Returns:

the unclaimed Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

InvalidTaskStateException - if the Task is already in one of the TaskState.END_STATES

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

forceCancelClaim

Task forceCancelClaim(String taskId)
               throws TaskNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Cancel the claim of an existing Task even if it was claimed by another user.

Parameters:

taskId - the id of the Task which should be unclaimed

Returns:

the unclaimed Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

InvalidTaskStateException - if the Task is already in one of the TaskState.END_STATES

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

requestReview

Task requestReview(String taskId)
            throws InvalidTaskStateException,
TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException

Request review for an existing Task that is in TaskState.CLAIMED.

Parameters:

taskId - the id of the specified Task

Returns:

the Task after a review has been requested

Throws:

InvalidTaskStateException - if the state of the Task with taskId is not in TaskState.CLAIMED

TaskNotFoundException - if the Task with taskId wasn't found

InvalidOwnerException - if the Task is claimed by another user

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

forceRequestReview

Task forceRequestReview(String taskId)
                 throws InvalidTaskStateException,
TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException

Request review for an existing Task even if the current user is not the owner or the Task is not in TaskState.CLAIMED yet.

Parameters:

taskId - the id of the specified Task

Returns:

the Task after a review has been requested

Throws:

InvalidTaskStateException - if the state of the Task with taskId is one of the TaskState.END_STATES

TaskNotFoundException - if the Task with taskId wasn't found

InvalidOwnerException - cannot be thrown

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

requestChanges

Task requestChanges(String taskId)
             throws InvalidTaskStateException,
TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException

Request changes for an existing Task that is in TaskState.IN_REVIEW. The TaskState is changed to TaskState.READY after changes have been requested.

Parameters:

taskId - the id of the specified Task

Returns:

the Task after changes have been requested

Throws:

InvalidTaskStateException - if the state of the Task with taskId is not in TaskState.IN_REVIEW

TaskNotFoundException - if the Task with taskId wasn't found

InvalidOwnerException - if the Task is claimed by another user

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

forceRequestChanges

Task forceRequestChanges(String taskId)
                  throws InvalidTaskStateException,
TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException

Request changes for an existing Task even if the current user is not the owner or the Task is not in TaskState.IN_REVIEW yet. The TaskState is changed to TaskState.READY after changes have been requested.

Parameters:

taskId - the id of the specified Task

Returns:

the Task after changes have been requested

Throws:

InvalidTaskStateException - if the state of the Task with taskId is one of the TaskState.END_STATES

TaskNotFoundException - if the Task with taskId wasn't found

InvalidOwnerException - cannot be thrown

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

completeTask

Task completeTask(String taskId)
           throws TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Complete a claimed Task as owner or TaskanaRole.ADMIN and update state and timestamps.

If the Task is already completed, the Task is returned unchanged.

Parameters:

taskId - the id of the Task which should be completed

Returns:

the completed Task

Throws:

InvalidTaskStateException - if the state of the Task with taskId is neither TaskState.CLAIMED nor TaskState.COMPLETED

TaskNotFoundException - if the Task with taskId wasn't found

InvalidOwnerException - if current user isn't the owner of the Task or TaskanaRole.ADMIN

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

forceCompleteTask

Task forceCompleteTask(String taskId)
                throws TaskNotFoundException,
InvalidOwnerException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Completes a Task and updates state and timestamps in every case if the Task exists.

If the Task is already completed, the Task is returned unchanged.

Parameters:

taskId - the id of the Task which should be completed

Returns:

the updated Task after completion

Throws:

InvalidTaskStateException - if the state of the Task with taskId is with taskId is TaskState.TERMINATED or TaskState.CANCELLED

TaskNotFoundException - if the Task with taskId wasn't found

InvalidOwnerException - if current user isn't the owner of the Task or TaskanaRole.ADMIN

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

completeTasks

BulkOperationResults<String,TaskanaException> completeTasks(List<String> taskIds)
                                                     throws InvalidArgumentException

Completes a List of Tasks.

Parameters:

taskIds - ids of the Tasks which should be completed

Returns:

the result of the operations with each id and Exception for each failed completion

Throws:

InvalidArgumentException - If the taskIds parameter is NULL

forceCompleteTasks

BulkOperationResults<String,TaskanaException> forceCompleteTasks(List<String> taskIds)
                                                          throws InvalidArgumentException

Completes each existing Task in the given List in every case, independent of the owner or state of the Task.

If the Task is already completed, the Task stays unchanged.

Parameters:

taskIds - id of the Tasks which should be completed

Returns:

the result of the operations with ids and Exception for each failed completion

Throws:

InvalidArgumentException - If the taskIds parameter is NULL

cancelTask

Task cancelTask(String taskId)
         throws TaskNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Cancels the Task with the given id.

Cancellation means a Task is obsolete from a business perspective and doesn't need to be completed anymore.

Parameters:

taskId - the id of the Task to cancel

Returns:

the updated Task

Throws:

TaskNotFoundException - if the Task with taskId wasn't found

InvalidTaskStateException - if the Task isn't in TaskState.READY or TaskState.CLAIMED

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

terminateTask

Task terminateTask(String taskId)
            throws TaskNotFoundException,
NotAuthorizedException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Terminates a Task. Termination is an administrative action to complete a Task.

This is typically done by administration to correct any technical issue.

Parameters:

taskId - the id of the Task to terminate

Returns:

the updated Task

Throws:

TaskNotFoundException - if the Task with taskId wasn't found

InvalidTaskStateException - if the Task isn't in TaskState.READY or TaskState.CLAIMED

NotAuthorizedException - if the current user isn't member of TaskanaRole.ADMIN or TaskanaRole.TASK_ADMIN

NotAuthorizedOnWorkbasketException - If the current user doesn't have the correct permission

transfer

default Task transfer(String taskId,
 String destinationWorkbasketId)
               throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket while always setting isTransferred to true.

Parameters:

taskId - the id of the Task which should be transferred

destinationWorkbasketId - the id of the target Workbasket

Returns:

the transferred Task

Throws:

TaskNotFoundException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

InvalidTaskStateException

See Also:

• transfer(String, String, boolean)

transfer

Task transfer(String taskId,
 String destinationWorkbasketId,
 boolean setTransferFlag)
       throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket.

The transfer resets isRead and sets isTransferred if setTransferFlag is true.

Parameters:

taskId - the id of the Task which should be transferred

destinationWorkbasketId - the id of the target Workbasket

setTransferFlag - controls whether to set isTransferred to true or not

Returns:

the transferred Task

Throws:

TaskNotFoundException - if the Task with taskId wasn't found

WorkbasketNotFoundException - if the target Workbasket was not found

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidTaskStateException - if the Task is in one of the TaskState.END_STATES

transfer

default Task transfer(String taskId,
 String workbasketKey,
 String domain)
               throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket while always setting isTransferred .

Parameters:

taskId - the id of the Task which should be transferred

workbasketKey - the key of the target Workbasket

domain - the domain of the target Workbasket

Returns:

the transferred Task

Throws:

TaskNotFoundException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

InvalidTaskStateException

See Also:

• transfer(String, String, String, boolean)

transfer

Task transfer(String taskId,
 String workbasketKey,
 String domain,
 boolean setTransferFlag)
       throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket.

The transfer resets isRead and sets isTransferred if setTransferFlag is true.

Parameters:

taskId - the id of the Task which should be transferred

workbasketKey - the key of the target Workbasket

domain - the domain of the target Workbasket

setTransferFlag - controls whether to set isTransferred or not

Returns:

the transferred Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

WorkbasketNotFoundException - if the target Workbasket was not found

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidTaskStateException - if the Task is in one of the TaskState.END_STATES

transferWithOwner

default Task transferWithOwner(String taskId,
 String destinationWorkbasketId,
 String owner)
                        throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket and sets the owner of the Task in the new Workbasket to owner while always setting isTransferred to true.

Parameters:

taskId - the id of the Task which should be transferred

destinationWorkbasketId - the id of the target Workbasket

owner - the owner of the Task after it has been transferred

Returns:

the transferred Task

Throws:

TaskNotFoundException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

InvalidTaskStateException

See Also:

• transferWithOwner(String, String, String, boolean)

transferWithOwner

Task transferWithOwner(String taskId,
 String destinationWorkbasketId,
 String owner,
 boolean setTransferFlag)
                throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket and sets the owner of the Task.

The transfer resets isRead and sets isTransferred if setTransferFlag is true.

Parameters:

taskId - the id of the Task which should be transferred

destinationWorkbasketId - the id of the target Workbasket

owner - the owner of the Task after it has been transferred

setTransferFlag - controls whether to set isTransferred to true or not

Returns:

the transferred Task

Throws:

TaskNotFoundException - if the Task with taskId wasn't found

WorkbasketNotFoundException - if the target Workbasket was not found

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidTaskStateException - if the Task is in one of the TaskState.END_STATES

transferWithOwner

default Task transferWithOwner(String taskId,
 String workbasketKey,
 String domain,
 String owner)
                        throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket and sets the owner of the Task in new Workbasket to owner while always setting isTransferred .

Parameters:

taskId - the id of the Task which should be transferred

workbasketKey - the key of the target Workbasket

domain - the domain of the target Workbasket

owner - the owner of the Task after it has been transferred

Returns:

the transferred Task

Throws:

TaskNotFoundException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

InvalidTaskStateException

See Also:

• transferWithOwner(String, String, String, String, boolean)

transferWithOwner

Task transferWithOwner(String taskId,
 String workbasketKey,
 String domain,
 String owner,
 boolean setTransferFlag)
                throws TaskNotFoundException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Transfers a Task to another Workbasket and sets the owner of the Task.

The transfer resets isRead and sets isTransferred if setTransferFlag is true.

Parameters:

taskId - the id of the Task which should be transferred

workbasketKey - the key of the target Workbasket

domain - the domain of the target Workbasket

owner - the owner of the Task after it has been transferred

setTransferFlag - controls whether to set isTransferred or not

Returns:

the transferred Task

Throws:

TaskNotFoundException - if the Task with taskId was not found

WorkbasketNotFoundException - if the target Workbasket was not found

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidTaskStateException - if the Task is in one of the TaskState.END_STATES

transferTasks

default BulkOperationResults<String,TaskanaException> transferTasks(String destinationWorkbasketId,
 List<String> taskIds)
                                                             throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket while always setting isTransferred to true.

Parameters:

destinationWorkbasketId - id of the target Workbasket

taskIds - List of source Tasks which will be moved

Returns:

Bulkresult with ids and Error for each failed transactions

Throws:

InvalidArgumentException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

See Also:

• transferTasks(String, List, boolean)

transferTasks

BulkOperationResults<String,TaskanaException> transferTasks(String destinationWorkbasketId,
 List<String> taskIds,
 boolean setTransferFlag)
                                                     throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket.

The transfer resets isRead and sets isTransferred if setTransferFlag is true. Exceptions will be thrown if the caller got no WorkbasketPermission on the target or if the target Workbasket doesn't exist. Other Exceptions will be stored and returned in the end.

Parameters:

destinationWorkbasketId - id of the target Workbasket

taskIds - List of source Tasks which will be moved

setTransferFlag - controls whether to set isTransferred or not

Returns:

Bulkresult with ids and Error for each failed transactions

Throws:

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidArgumentException - if the method parameters are empty or NULL

WorkbasketNotFoundException - if the target Workbasket can't be found

transferTasks

default BulkOperationResults<String,TaskanaException> transferTasks(String destinationWorkbasketKey,
 String destinationWorkbasketDomain,
 List<String> taskIds)
                                                             throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket while always setting isTransferred to true.

Parameters:

destinationWorkbasketKey - target key

destinationWorkbasketDomain - target domain

taskIds - List of source Tasks which will be moved

Returns:

Bulkresult with ids and Error for each failed transactions

Throws:

InvalidArgumentException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

See Also:

• transferTasks(String, String, List, boolean)

transferTasks

BulkOperationResults<String,TaskanaException> transferTasks(String destinationWorkbasketKey,
 String destinationWorkbasketDomain,
 List<String> taskIds,
 boolean setTransferFlag)
                                                     throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket.

The transfer resets isRead and sets isTransferred if setTransferFlag is true. Exceptions will be thrown if the caller got no WorkbasketPermission on the target Workbasket or if it doesn't exist. Other Exceptions will be stored and returned in the end.

Parameters:

destinationWorkbasketKey - target key

destinationWorkbasketDomain - target domain

taskIds - List of ids of source Tasks which will be moved

setTransferFlag - controls whether to set isTransferred or not

Returns:

BulkResult with ids and Error for each failed transactions

Throws:

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidArgumentException - if the method parameters are empty or NULL

WorkbasketNotFoundException - if the target Workbasket can't be found

transferTasksWithOwner

default BulkOperationResults<String,TaskanaException> transferTasksWithOwner(String destinationWorkbasketId,
 List<String> taskIds,
 String owner)
                                                                      throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks to owner while always setting isTransferred to true.

Parameters:

destinationWorkbasketId - id of the target Workbasket

taskIds - List of source Tasks which will be moved

owner - the owner of the Tasks after they have been transferred

Throws:

InvalidArgumentException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

See Also:

• transferTasksWithOwner(String, List, String, boolean)

transferTasksWithOwner

BulkOperationResults<String,TaskanaException> transferTasksWithOwner(String destinationWorkbasketId,
 List<String> taskIds,
 String owner,
 boolean setTransferFlag)
                                                              throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks.

The transfer resets isRead and sets isTransferred if setTransferFlag is true. Exceptions will be thrown if the caller got no WorkbasketPermission on the target or if the target Workbasket doesn't exist. Other Exceptions will be stored and returned in the end.

Parameters:

destinationWorkbasketId - id of the target Workbasket

taskIds - List of source Tasks which will be moved

owner - the owner of the Tasks after they have been transferred

setTransferFlag - controls whether to set isTransferred or not

Returns:

Bulkresult with ids and Error for each failed transactions

Throws:

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidArgumentException - if the method parameters are empty or NULL

WorkbasketNotFoundException - if the target Workbasket can't be found

transferTasksWithOwner

default BulkOperationResults<String,TaskanaException> transferTasksWithOwner(String destinationWorkbasketKey,
 String destinationWorkbasketDomain,
 List<String> taskIds,
 String owner)
                                                                      throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks while always setting isTransferred to true.

Parameters:

destinationWorkbasketKey - target key

destinationWorkbasketDomain - target domain

taskIds - List of source Tasks which will be moved

owner - the new owner of the transferred tasks

Returns:

Bulkresult with ids and Error for each failed transactions

Throws:

InvalidArgumentException

WorkbasketNotFoundException

NotAuthorizedOnWorkbasketException

See Also:

• transferTasksWithOwner(String, String, List, String, boolean)

transferTasksWithOwner

BulkOperationResults<String,TaskanaException> transferTasksWithOwner(String destinationWorkbasketKey,
 String destinationWorkbasketDomain,
 List<String> taskIds,
 String owner,
 boolean setTransferFlag)
                                                              throws InvalidArgumentException,
WorkbasketNotFoundException,
NotAuthorizedOnWorkbasketException

Transfers a List of Tasks to another Workbasket and sets the owner of the Tasks.

The transfer resets isRead and sets isTransferred if setTransferFlag is true. Exceptions will be thrown if the caller got no WorkbasketPermission on the target Workbasket or if it doesn't exist. Other Exceptions will be stored and returned in the end.

Parameters:

destinationWorkbasketKey - target key

destinationWorkbasketDomain - target domain

taskIds - List of ids of source Tasks which will be moved

owner - the new owner of the transferred tasks

setTransferFlag - controls whether to set isTransferred or not

Returns:

BulkResult with ids and Error for each failed transactions

Throws:

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the source Workbasket or no WorkbasketPermission.TRANSFER for the target Workbasket

InvalidArgumentException - if the method parameters are empty or NULL

WorkbasketNotFoundException - if the target Workbasket can't be found

updateTask

Task updateTask(Task task)
         throws InvalidArgumentException,
TaskNotFoundException,
ConcurrencyException,
ClassificationNotFoundException,
AttachmentPersistenceException,
ObjectReferencePersistenceException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException

Update a Task.

Parameters:

task - the Task to be updated

Returns:

the updated Task

Throws:

InvalidArgumentException - if the Task to be updated contains invalid properties like e.g. invalid secondaryObjectReferences

TaskNotFoundException - if the Task isn't found in the database by its id

ConcurrencyException - if the Task has been updated by another user in the meantime; that's the case if the given modified timestamp differs from the one in the database

ClassificationNotFoundException - if the classificationSummary of the updated Task refers to a Classification that can't be found

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

AttachmentPersistenceException - if an Attachment with the same id was added to the Task multiple times without using Task.addAttachment(Attachment)

ObjectReferencePersistenceException - if an ObjectReference with the same id was added to the Task multiple times without using TaskSummary.addSecondaryObjectReference(ObjectReference)

InvalidTaskStateException - if an attempt is made to change the owner of the Task that state isn't TaskState.READY

updateTasks

List<String> updateTasks(ObjectReference selectionCriteria,
 Map<TaskCustomField,String> customFieldsToUpdate)
                  throws InvalidArgumentException

Updates specified TaskCustomFields of Tasks associated with the given primaryObjRef. Tasks in Workbaskets without EDITTASKS permission will be ignored and not updated.

Parameters:

selectionCriteria - the primaryObjRef of the searched-for Tasks.

customFieldsToUpdate - a Map that contains as key the identification of the TaskCustomField and as value the corresponding new value of that TaskCustomField

Returns:

a List of the ids of all modified Tasks

Throws:

InvalidArgumentException - if the given selectionCriteria is invalid or the given customFieldsToUpdate are NULL or empty

See Also:

• updateTasks(List, Map)

updateTasks

List<String> updateTasks(List<String> taskIds,
 Map<TaskCustomField,String> customFieldsToUpdate)
                  throws InvalidArgumentException

Updates specified TaskCustomFields for all given Tasks.

Parameters:

taskIds - the taskIds that are used to select the Tasks

customFieldsToUpdate - a Map that contains as key the identification of the TaskCustomField and as value the corresponding new value of that TaskCustomField

Returns:

a list of the ids of all modified Tasks

Throws:

InvalidArgumentException - if the given customFieldsToUpdate are NULL or empty

See Also:

• updateTasks(ObjectReference, Map)

setTaskRead

Task setTaskRead(String taskId,
 boolean isRead)
          throws TaskNotFoundException,
NotAuthorizedOnWorkbasketException

Sets the value of isRead of the specified Task.

Parameters:

taskId - the id of the Task to be updated

isRead - the new status of isRead

Returns:

the updated Task

Throws:

TaskNotFoundException - if the Task with taskId wasn't found

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the Task is in

setCallbackStateForTasks

BulkOperationResults<String,TaskanaException> setCallbackStateForTasks(List<String> externalIds,
 CallbackState state)

Sets the specified CallbackState on a List of Tasks.

Note: this method is primarily intended to be used by the TaskanaAdapter

Parameters:

externalIds - the externalIds of the Tasks on which the CallbackState is set

state - the CallbackState that is to be set on the Tasks

Returns:

the result of the operations with ids and Exception for each failed operation

setOwnerOfTasks

BulkOperationResults<String,TaskanaException> setOwnerOfTasks(String owner,
 List<String> taskIds)

Sets the owner on a List of Tasks.

The owner will only be set on Tasks that are in TaskState.READY.

Parameters:

owner - the new owner of the Tasks

taskIds - the ids of the Tasks on which the owner is to be set

Returns:

the result of the operations with ids and Exception for each failed Task-update

setPlannedPropertyOfTasks

BulkOperationResults<String,TaskanaException> setPlannedPropertyOfTasks(Instant planned,
 List<String> taskIds)

Sets the planned Instant on a List of Tasks.

Only Tasks in state TaskState.READY and TaskState.CLAIMED will be affected by this method. On each Task, the corresponding due Instant is set according to the shortest serviceLevel in the Classification of the Task and its Attachments.

Parameters:

planned - the new planned Instant of the Tasks

taskIds - the ids of the Tasks on which the new planned Instant is to be set

Returns:

the result of the operations with ids and Exception for each failed Task update

deleteTask

void deleteTask(String taskId)
         throws TaskNotFoundException,
NotAuthorizedException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException,
InvalidCallbackStateException

Deletes the Task with the given id.

Parameters:

taskId - The id of the Task to delete

Throws:

NotAuthorizedOnWorkbasketException - If the current user doesn't have correct permission

TaskNotFoundException - If the given id doesn't refer to an existing Task

InvalidTaskStateException - If the state of the referenced Task isn't one of the TaskState.END_STATES

NotAuthorizedException - if the current user isn't member of TaskanaRole.ADMIN

InvalidCallbackStateException - the Callback State of the Task is CallbackState.CALLBACK_PROCESSING_REQUIRED

forceDeleteTask

void forceDeleteTask(String taskId)
              throws TaskNotFoundException,
NotAuthorizedException,
NotAuthorizedOnWorkbasketException,
InvalidTaskStateException,
InvalidCallbackStateException

Deletes the Task with the given id even if it isn't completed.

Parameters:

taskId - The id of the Task to delete

Throws:

TaskNotFoundException - if the given id doesn't refer to an existing Task

InvalidTaskStateException - if the state of the referenced Task isn't TaskState.TERMINATED or TaskState.CANCELLED

NotAuthorizedOnWorkbasketException - If the current user doesn't have correct permissions

NotAuthorizedException - if the current user isn't member of TaskanaRole.ADMIN

InvalidCallbackStateException - the Callback State of the Task is CallbackState.CALLBACK_PROCESSING_REQUIRED

deleteTasks

BulkOperationResults<String,TaskanaException> deleteTasks(List<String> tasks)
                                                   throws InvalidArgumentException,
NotAuthorizedException

Deletes a List of Tasks.

Parameters:

tasks - the ids of the Tasks to delete

Returns:

the result of the operations with each id and Exception for each failed deletion

Throws:

InvalidArgumentException - if the tasks parameter contains NULL values

NotAuthorizedException - if the current user isn't member of TaskanaRole.ADMIN

newTaskComment

TaskComment newTaskComment(String taskId)

Instantiates a non-persistent/non-inserted TaskComment.

Parameters:

taskId - the id of the Task to which the TaskComment belongs

Returns:

the instantiated TaskComment

createTaskComment

TaskComment createTaskComment(TaskComment taskComment)
                       throws TaskNotFoundException,
InvalidArgumentException,
NotAuthorizedOnWorkbasketException

Inserts the specified TaskComment into the database.

Parameters:

taskComment - the TaskComment to be created

Returns:

the created TaskComment

Throws:

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket of the commented Task.

TaskNotFoundException - if the given taskId doesn't refer to an existing Task

InvalidArgumentException - if the id of the provided TaskComment is neither NULL nor empty

getTaskComment

TaskComment getTaskComment(String taskCommentId)
                    throws TaskCommentNotFoundException,
TaskNotFoundException,
InvalidArgumentException,
NotAuthorizedOnWorkbasketException

Retrieves the TaskComment with the given id.

Parameters:

taskCommentId - the id of the TaskComment which should be retrieved

Returns:

the TaskComment identified by taskCommentId

Throws:

TaskCommentNotFoundException - if the given taskCommentId doesn't refer to an existing TaskComment

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket of the commented Task

TaskNotFoundException - if the taskId of the TaskComment doesn't refer to an existing Task

InvalidArgumentException - if the given taskCommentId is NULL or empty

getTaskComments

List<TaskComment> getTaskComments(String taskId)
                           throws TaskNotFoundException,
NotAuthorizedOnWorkbasketException

Retrieves the List of TaskComments for the Task with given id.

Parameters:

taskId - the id of the Task for which all TaskComments should be retrieved

Returns:

the List of TaskComments attached to the specified Task

Throws:

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket of the commented Task

TaskNotFoundException - if the given taskId doesn't refer to an existing Task

updateTaskComment

TaskComment updateTaskComment(TaskComment taskComment)
                       throws ConcurrencyException,
TaskCommentNotFoundException,
TaskNotFoundException,
InvalidArgumentException,
NotAuthorizedOnTaskCommentException,
NotAuthorizedOnWorkbasketException

Updates the specified TaskComment.

Parameters:

taskComment - the TaskComment to be updated in the database

Returns:

the updated TaskComment

Throws:

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket of the commented Task.

ConcurrencyException - if an attempt is made to update the TaskComment and another user updated it already; that's the case if the given modified timestamp differs from the one in the database

TaskCommentNotFoundException - if the id of the specified TaskComment doesn't refer to an existing TaskComment

TaskNotFoundException - if the taskId doesn't refer to an existing Task

InvalidArgumentException - if the id of the specified TaskComment is NULL or empty

NotAuthorizedOnTaskCommentException - If the current user doesn't have correct permissions

deleteTaskComment

void deleteTaskComment(String taskCommentId)
                throws TaskCommentNotFoundException,
TaskNotFoundException,
InvalidArgumentException,
NotAuthorizedOnTaskCommentException,
NotAuthorizedOnWorkbasketException

Deletes the TaskComment with the given id.

Parameters:

taskCommentId - the id of the TaskComment to delete

Throws:

InvalidArgumentException - if the taskCommentId is NULL or empty

TaskCommentNotFoundException - if the given taskCommentId doesn't refer to an existing TaskComment

TaskNotFoundException - if the taskId of the TaskComment doesn't refer to an existing Task

InvalidArgumentException - if the given taskCommentId is NULL or empty

NotAuthorizedOnWorkbasketException - if the current user has no WorkbasketPermission.READ for the Workbasket the commented Task is in

NotAuthorizedOnTaskCommentException - if the current user is not the creator of the TaskComment.

newAttachment

Attachment newAttachment()

Instantiates a non-persistent/non-inserted Attachment.

Returns:

the instantiated Attachment

newObjectReference

ObjectReference newObjectReference()

Instantiates a non-persistent/non-inserted ObjectReference.

Returns:

the instantiated ObjectReference

See Also:

• newObjectReference(String, String, String, String, String)

newObjectReference

ObjectReference newObjectReference(String company,
 String system,
 String systemInstance,
 String type,
 String value)

Instantiates a non-persistent/non-inserted ObjectReference.

Parameters:

company - the company of the new ObjectReference

system - the system of the new ObjectReference

systemInstance - the systemInstance of the new ObjectReference

type - the type of the new ObjectReference

value - the value of the new ObjectReference

Returns:

the instantiated ObjectReference

See Also:

• newObjectReference()

createTaskQuery

TaskQuery createTaskQuery()

Creates an empty TaskQuery.

Returns:

a TaskQuery

createTaskCommentQuery

TaskCommentQuery createTaskCommentQuery()

Creates an empty TaskCommentQuery.

Returns:

a TaskCommentQuery