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}