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