001/* 002 * (C) Copyright 2012 Nuxeo SA (http://nuxeo.com/) and contributors. 003 * 004 * All rights reserved. This program and the accompanying materials 005 * are made available under the terms of the GNU Lesser General Public License 006 * (LGPL) version 2.1 which accompanies this distribution, and is available at 007 * http://www.gnu.org/licenses/lgpl.html 008 * 009 * This library is distributed in the hope that it will be useful, 010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 012 * Lesser General Public License for more details. 013 * 014 * Contributors: Laurent Doguin, Antoine Taillefer 015 */ 016package org.nuxeo.ecm.platform.task; 017 018import java.io.Serializable; 019import java.util.Date; 020import java.util.List; 021import java.util.Map; 022 023import org.nuxeo.ecm.core.api.CoreSession; 024import org.nuxeo.ecm.core.api.DocumentModel; 025import org.nuxeo.ecm.core.api.NuxeoPrincipal; 026 027/** 028 * The task service handle document based Tasks. You can create, search, accept, end or reject tasks. An event is 029 * launched when a task is ended, hence giving you the possibility to execute specific code. 030 * 031 * @author Laurent Doguin 032 * @since 5.5 033 */ 034public interface TaskService extends Serializable, TaskProvider { 035 036 /** 037 * Property used to pass task in the notified events properties 038 */ 039 String TASK_INSTANCE_EVENT_PROPERTIES_KEY = "taskInstance"; 040 041 /** 042 * The variable used as process instance variables. 043 */ 044 enum VariableName { 045 documentId, documentRepositoryName, endLifecycleTransition, initiator, document, principal, createdFromTaskService, directive, validated, right; 046 } 047 048 /** 049 * Creates a task and starts it. Notifies events with names {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED} and 050 * {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED}, passing the task in the event properties using key 051 * {@link #TASK_INSTANCE_EVENT_PROPERTIES_KEY} 052 * 053 * @param coreSession the session to use when notifying 054 * @param principal the principal marked as initiator of the task and used when notifying. 055 * @param document the document to attach to the task. 056 * @param taskName the task name. 057 * @param prefixedActorIds the list of actor ids, prefixed with 'user:' or 'group:'. 058 * @param createOneTaskPerActor if true, one task will be created per actor, else a single task will be assigned to 059 * all actors. 060 * @param directive the directive, put in the task variables. 061 * @param comment string added to the task comments and used as a notification comment 062 * @param dueDate the due date, set on the task instance 063 * @param taskVariables additional task variables 064 * @param parentPath /task-root if null 065 */ 066 List<Task> createTask(CoreSession coreSession, NuxeoPrincipal principal, DocumentModel document, String taskName, 067 List<String> prefixedActorIds, boolean createOneTaskPerActor, String directive, String comment, 068 Date dueDate, Map<String, String> taskVariables, String parentPath); 069 070 /** 071 * Creates a task and starts it. Notifies events with names {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED} and 072 * {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED}, passing the task in the event properties using key 073 * {@link #TASK_INSTANCE_EVENT_PROPERTIES_KEY} 074 * 075 * @param coreSession the session to use when notifying 076 * @param principal the principal marked as initiator of the task and used when notifying. 077 * @param document the document to attach to the task. 078 * @param taskName the task name. 079 * @param taskType the task type. 080 * @param processId the process ID linked to this task if any. 081 * @param prefixedActorIds the list of actor ids, prefixed with 'user:' or 'group:'. 082 * @param createOneTaskPerActor if true, one task will be created per actor, else a single task will be assigned to 083 * all actors. 084 * @param directive the directive, put in the task variables. 085 * @param comment string added to the task comments and used as a notification comment 086 * @param dueDate the due date, set on the task instance 087 * @param taskVariables additional task variables 088 * @param parentPath /task-root if null 089 * @since 5.6 090 */ 091 List<Task> createTask(CoreSession coreSession, NuxeoPrincipal principal, DocumentModel document, String taskName, 092 String taskType, String processId, List<String> prefixedActorIds, boolean createOneTaskPerActor, 093 String directive, String comment, Date dueDate, Map<String, String> taskVariables, String parentPath); 094 095 /** 096 * Creates a task of the given document type and starts it. Notifies events with names 097 * {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED} and {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED}, passing the task 098 * in the event properties using key {@link #TASK_INSTANCE_EVENT_PROPERTIES_KEY} Also the map eventInfo is passed in 099 * the event properties 100 * 101 * @param coreSession the session to use when notifying 102 * @param principal the principal marked as initiator of the task and used when notifying. 103 * @param document the document to attach to the task. 104 * @param the task document type 105 * @param taskName the task name. 106 * @param taskType the task type. 107 * @param processId the process ID linked to this task if any. 108 * @param prefixedActorIds the list of actor ids, prefixed with 'user:' or 'group:'. 109 * @param createOneTaskPerActor if true, one task will be created per actor, else a single task will be assigned to 110 * all actors. 111 * @param directive the directive, put in the task variables. 112 * @param comment string added to the task comments and used as a notification comment 113 * @param dueDate the due date, set on the task instance 114 * @param taskVariables additional task variables 115 * @param parentPath /task-root if null 116 * @param eventInfo 117 * @since 5.6 118 */ 119 List<Task> createTask(CoreSession coreSession, NuxeoPrincipal principal, DocumentModel document, 120 String taskDocumentType, String taskName, String taskType, String processId, List<String> prefixedActorIds, 121 boolean createOneTaskPerActor, String directive, String comment, Date dueDate, 122 Map<String, String> taskVariables, String parentPath, Map<String, Serializable> eventInfo); 123 124 /** 125 * Creates a task of the given documents type and starts it. Notifies events with names 126 * {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED} and {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED}, passing the task 127 * in the event properties using key {@link #TASK_INSTANCE_EVENT_PROPERTIES_KEY} Also the map eventInfo is passed in 128 * the event properties 129 * 130 * @param coreSession the session to use when notifying 131 * @param principal the principal marked as initiator of the task and used when notifying. 132 * @param documents the documents to attach to the task. 133 * @param the task document type 134 * @param taskName the task name. 135 * @param taskType the task type. 136 * @param processId the process ID linked to this task if any. 137 * @param prefixedActorIds the list of actor ids, prefixed with 'user:' or 'group:'. 138 * @param createOneTaskPerActor if true, one task will be created per actor, else a single task will be assigned to 139 * all actors. 140 * @param directive the directive, put in the task variables. 141 * @param comment string added to the task comments and used as a notification comment 142 * @param dueDate the due date, set on the task instance 143 * @param taskVariables additional task variables 144 * @param parentPath /task-root if null 145 * @param eventInfo 146 * @since 5.6 147 * 148 * @deprecated since 7.4 use 149 * {@link #org.nuxeo.ecm.platform.task.core.service.TaskServiceImpl.createTaskWithProcessName(CoreSession, 150 * NuxeoPrincipal, List<DocumentModel>, String, String, String, String, String, List<String>, boolean, 151 * String, String, Date, Map<String, String>, String, Map<String, Serializable>) 152 * createTaskWithProcessName} instead 153 */ 154 List<Task> createTask(CoreSession coreSession, NuxeoPrincipal principal, List<DocumentModel> documents, 155 String taskDocumentType, String taskName, String taskType, String processId, List<String> prefixedActorIds, 156 boolean createOneTaskPerActor, String directive, String comment, Date dueDate, 157 Map<String, String> taskVariables, String parentPath, Map<String, Serializable> eventInfo); 158 159 /** 160 * Creates a task of the given documents type and starts it. Notifies events with names 161 * {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED} and {@link TaskEventNames#WORKFLOW_TASK_ASSIGNED}, passing the task 162 * in the event properties using key {@link #TASK_INSTANCE_EVENT_PROPERTIES_KEY} Also the map eventInfo is passed in 163 * the event properties. The process name can also be specified if any. 164 * 165 * @param coreSession the session to use when notifying 166 * @param principal the principal marked as initiator of the task and used when notifying. 167 * @param documents the documents to attach to the task. 168 * @param the task document type 169 * @param taskName the task name. 170 * @param taskType the task type. 171 * @param processId the process ID linked to this task if any. 172 * @param processName the process Name linked to this task if any. 173 * @param prefixedActorIds the list of actor ids, prefixed with 'user:' or 'group:'. 174 * @param createOneTaskPerActor if true, one task will be created per actor, else a single task will be assigned to 175 * all actors. 176 * @param directive the directive, put in the task variables. 177 * @param comment string added to the task comments and used as a notification comment 178 * @param dueDate the due date, set on the task instance 179 * @param taskVariables additional task variables 180 * @param parentPath /task-root if null 181 * @param eventInfo 182 * @since 7.4 183 */ 184 List<Task> createTaskForProcess(CoreSession coreSession, NuxeoPrincipal principal, List<DocumentModel> documents, 185 String taskDocumentType, String taskName, String taskType, String processId, String processName, List<String> actorIds, 186 boolean createOneTaskPerActor, String directive, String comment, Date dueDate, 187 Map<String, String> taskVariables, String parentPath, Map<String, Serializable> eventInfo); 188 189 /** 190 * Returns true if user is an administrator, the initiator of the task, or an actor of the task. 191 * 192 */ 193 boolean canEndTask(NuxeoPrincipal principal, Task task); 194 195 /** 196 * Ends the task using event name {@link TaskEventNames#WORKFLOW_TASK_COMPLETED} and marking the task as validated. 197 * 198 * @see #endTask(CoreSession, NuxeoPrincipal, Task, String, String, boolean) 199 * @return the name of the Seam event to raise 200 */ 201 String acceptTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment); 202 203 /** 204 * Ends the task using event name {@link TaskEventNames#WORKFLOW_TASK_REJECTED} and marking the task as not 205 * validated. 206 * 207 * @see #endTask(CoreSession, NuxeoPrincipal, Task, String, String, boolean) 208 * @return the name of the Seam event to raise 209 */ 210 String rejectTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment); 211 212 /** 213 * Ends the task 214 * 215 * @param coreSession the session to use when notifying and resolving of referenced document for notification. 216 * @param principal principal used when notifying 217 * @param task the instance to end 218 * @param comment string added to the task comments and used as a notification comment 219 * @param eventName the core event name to use when notifying 220 * @param isValidated boolean marker to state if the task was validated or rejected 221 * @throws NuxeoException when trying to end a task without being granted the right to do so (see 222 * {@link #canEndTask(NuxeoPrincipal, Task)}), or when any other error occurs 223 * @return the name of the Seam event to raise 224 */ 225 @Override 226 String endTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment, String eventName, 227 boolean isValidated); 228 229 /** 230 * Remove the documentTask identified by the given taskId if coreSession's principal has the Remove permission. 231 * 232 * @param coreSession 233 * @param taskId 234 * @Since 5.5 235 */ 236 void deleteTask(CoreSession coreSession, String taskId); 237 238 /** 239 * @param ti the task. 240 * @param user the user. 241 * @return the task's target document. 242 */ 243 DocumentModel getTargetDocumentModel(Task ti, CoreSession coreSession); 244 245 /** 246 * @param coreSession 247 * @param taskId 248 * @return the taskDocument with the given taskId 249 */ 250 Task getTask(CoreSession coreSession, String taskId); 251 252 /** 253 * Default value is /task-root 254 * 255 * @return the path registered in the taskPersister extension point. 256 */ 257 String getTaskRootParentPath(CoreSession coreSession); 258 259 /** 260 * Reassign the given task to the list of actors. The ACLs set for current assignees and task initiator are removed 261 * and new actors are granted 'Manage everything' on the task document. The 'workflowTaskReassigned' event is 262 * triggered. 263 * 264 * @param session 265 * @param taskId 266 * @param actors 267 * @since 5.7.3 268 */ 269 void reassignTask(CoreSession session, String taskId, List<String> actors, String comment); 270 271 /** 272 * Delegates the given task to the list of actors. The new actors are granted 'Manage everything' on the task 273 * document. The 'workflowTaskDelegated' event is triggered. 274 * 275 * @param session 276 * @param taskId 277 * @param actors 278 * @since 5.8 279 */ 280 void delegateTask(CoreSession session, String taskId, List<String> actors, String comment); 281 282}