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}