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 taskDocumentType 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 taskDocumentType 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     * @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     * @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,
186            List<String> actorIds, 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    boolean canEndTask(NuxeoPrincipal principal, Task task);
193
194    /**
195     * Ends the task using event name {@link TaskEventNames#WORKFLOW_TASK_COMPLETED} and marking the task as validated.
196     *
197     * @see #endTask(CoreSession, NuxeoPrincipal, Task, String, String, boolean)
198     * @return the name of the Seam event to raise
199     */
200    String acceptTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment);
201
202    /**
203     * Ends the task using event name {@link TaskEventNames#WORKFLOW_TASK_REJECTED} and marking the task as not
204     * validated.
205     *
206     * @see #endTask(CoreSession, NuxeoPrincipal, Task, String, String, boolean)
207     * @return the name of the Seam event to raise
208     */
209    String rejectTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment);
210
211    /**
212     * Ends the task
213     *
214     * @param coreSession the session to use when notifying and resolving of referenced document for notification.
215     * @param principal principal used when notifying
216     * @param task the instance to end
217     * @param comment string added to the task comments and used as a notification comment
218     * @param eventName the core event name to use when notifying
219     * @param isValidated boolean marker to state if the task was validated or rejected
220     * @throws NuxeoException when trying to end a task without being granted the right to do so (see
221     *             {@link #canEndTask(NuxeoPrincipal, Task)}), or when any other error occurs
222     * @return the name of the Seam event to raise
223     */
224    @Override
225    String endTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment, String eventName,
226            boolean isValidated);
227
228    /**
229     * Remove the documentTask identified by the given taskId if coreSession's principal has the Remove permission.
230     *
231     * @param coreSession
232     * @param taskId
233     * @Since 5.5
234     */
235    void deleteTask(CoreSession coreSession, String taskId);
236
237    /**
238     * @param ti the task
239     * @param coreSession
240     * @return the task's target document
241     */
242    DocumentModel getTargetDocumentModel(Task ti, CoreSession coreSession);
243
244    /**
245     * @param coreSession
246     * @param taskId
247     * @return the taskDocument with the given taskId
248     */
249    Task getTask(CoreSession coreSession, String taskId);
250
251    /**
252     * Default value is /task-root
253     *
254     * @return the path registered in the taskPersister extension point.
255     */
256    String getTaskRootParentPath(CoreSession coreSession);
257
258    /**
259     * Reassign the given task to the list of actors. The ACLs set for current assignees and task initiator are removed
260     * and new actors are granted 'Manage everything' on the task document. The 'workflowTaskReassigned' event is
261     * triggered.
262     *
263     * @param session
264     * @param taskId
265     * @param actors
266     * @since 5.7.3
267     */
268    void reassignTask(CoreSession session, String taskId, List<String> actors, String comment);
269
270    /**
271     * Delegates the given task to the list of actors. The new actors are granted 'Manage everything' on the task
272     * document. The 'workflowTaskDelegated' event is triggered.
273     *
274     * @param session
275     * @param taskId
276     * @param actors
277     * @since 5.8
278     */
279    void delegateTask(CoreSession session, String taskId, List<String> actors, String comment);
280
281}