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