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}