001/**
002 * Copyright 2005-2018 The Kuali Foundation
003 *
004 * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.php
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 */
016package org.kuali.rice.krad.workflow.service;
017
018import java.util.List;
019
020import org.kuali.rice.kew.api.WorkflowDocument;
021import org.kuali.rice.kew.api.exception.WorkflowException;
022import org.kuali.rice.kew.api.exception.ResourceUnavailableException;
023import org.kuali.rice.kim.api.identity.Person;
024import org.kuali.rice.krad.bo.AdHocRouteRecipient;
025
026/**
027 * This interface defines the contract that must be implemented by the workflow engine.
028 *
029 *
030 */
031public interface WorkflowDocumentService {
032    /**
033     * @param documentHeaderId
034     * @return true if a workflowDocument exists for the given documentHeaderId
035     */
036    public boolean workflowDocumentExists(String documentHeaderId);
037
038    /**
039     * Given a documentTypeName and workflowUser, returns a new workflowDocument from the workflow
040     * server.
041     *
042     * @param documentTypeName
043     * @param workflowUser
044     * @return newly-created workflowDocument instance
045     * @throws IllegalArgumentException if the given documentTypeName is blank
046     * @throws IllegalArgumentException if the given workflowUser is null or contains no id
047     * @throws ResourceUnavailableException
048     */
049    public WorkflowDocument createWorkflowDocument(String documentTypeName, Person workflowUser)
050            throws WorkflowException;
051
052    /**
053     * Given a documentHeaderId and workflowUser, retrieves the workflowDocument associated with
054     * that documentHeaderId from the workflow server.
055     *
056     * @param documentHeaderId
057     * @param workflowUser
058     * @return existing workflowDoc
059     * @throws IllegalArgumentException if the given documentHeaderId is null
060     * @throws IllegalArgumentException if the given workflowUser is null or contains no id
061     */
062    public WorkflowDocument loadWorkflowDocument(String documentHeaderId, Person workflowUser) throws WorkflowException;
063
064    void route(WorkflowDocument workflowDocument, String annotation, String nodeName, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
065
066    /**
067     * This method will first determine if the {@link WorkflowDocument#saveDocument(String)} method
068     * is valid to be called. If so the method will save the document to workflows action list
069     * optionally providing an annotation which will show up in the route log for this document
070     * corresponding to this action taken. If the WorkflowDocument.saveDocument() method is not
071     * valid to be called the system will instead call the method
072     * {@link WorkflowDocumentService#saveRoutingData(WorkflowDocument)}
073     *
074     * @param workflowDocument
075     * @param annotation
076     * @throws WorkflowException
077     */
078    public void save(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
079
080    /**
081     * save the routing data of the document to workflow
082     *
083     * @param workflowDocument
084     * @throws WorkflowException
085     */
086    public void saveRoutingData(WorkflowDocument workflowDocument) throws WorkflowException;
087
088    /**
089     * route this workflowDocument optionally providing an annotation for this action taken which
090     * will show up in the route log for this document corresponding to this action taken, and
091     * additionally optionally providing a list of ad hoc recipients for the document
092     *
093     * @param workflowDocument
094     * @param annotation
095     * @param adHocRecipients
096     */
097    public void route(WorkflowDocument workflowDocument, String annotation, List<AdHocRouteRecipient> adHocRecipients)
098            throws WorkflowException;
099
100    void acknowledge(WorkflowDocument workflowDocument, String annotation, String nodeName, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
101
102    /**
103     * approve this workflowDocument optionally providing an annotation for this action taken which
104     * will show up in the route log for this document corresponding to this action taken, and
105     * additionally optionally providing a list of ad hoc recipients for the document
106     *
107     * @param workflowDocument
108     * @param annotation
109     * @param adHocRecipients
110     */
111    public void approve(WorkflowDocument workflowDocument, String annotation, List<AdHocRouteRecipient> adHocRecipients)
112            throws WorkflowException;
113
114    void approve(WorkflowDocument workflowDocument, String annotation, String nodeName, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
115
116    /**
117     * super user approve this workflowDocument optionally providing an annotation for this action
118     * taken which will show up in the route log for this document corresponding to this action
119     * taken
120     *
121     * @param workflowDocument
122     * @param annotation
123     */
124    public void superUserApprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
125
126    /**
127     * super user cancel this workflowDocument optionally providing an annotation for this action
128     * taken which will show up in the route log for this document corresponding to this action
129     * taken
130     *
131     * @param workflowDocument
132     * @param annotation
133     * @throws WorkflowException
134     */
135    public void superUserCancel(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
136
137    /**
138     * super user disapprove this workflowDocument optionally providing an annotation for this
139     * action taken which will show up in the route log for this document corresponding to this
140     * action taken
141     *
142     * @param workflowDocument
143     * @param annotation
144     * @throws WorkflowException
145     */
146    public void superUserDisapprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
147
148    /**
149     * disapprove this workflowDocument optionally providing an annotation for this action taken
150     * which will show up in the route log for this document corresponding to this action taken
151     *
152     * @param workflowDocument
153     * @param annotation
154     */
155    public void disapprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
156
157    void blanketApprove(WorkflowDocument workflowDocument, String annotation, String nodeName, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
158
159    /**
160     * cancel this workflowDocument optionally providing an annotation for this action taken which
161     * will show up in the route log for this document corresponding to this action taken
162     *
163     * @param workflowDocument
164     * @param annotation
165     */
166    public void cancel(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
167
168    /**
169     * acknowledge this workflowDocument optionally providing an annotation for this action taken
170     * which will show up in the route log for this document corresponding to this action taken,
171     * additionally optionally providing a list of ad hoc recipients for this document which should
172     * be restricted to actions requested of acknowledge or fyi as all other action request types
173     * will be discarded
174     *
175     * @param workflowDocument
176     * @param annotation
177     * @param adHocRecipients
178     */
179    public void acknowledge(WorkflowDocument workflowDocument, String annotation,
180            List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
181
182    /**
183     * blanket approve this document optionally providing an annotation for this action taken which
184     * will show up in the route log for this document corresponding to this action taken, and
185     * additionally optionally providing a list of ad hoc recipients for this document which should
186     * be restricted to actions requested of acknowledge or fyi as all other action request types
187     * will be discarded.
188     *
189     * @param workflowDocument
190     * @param annotation
191     * @param adHocRecipients
192     */
193    public void blanketApprove(WorkflowDocument workflowDocument, String annotation,
194            List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
195
196    /**
197     * clear the fyi request for this document, optinoally providing a list of ad hoc recipients for
198     * this document which should be restricted to actions requested of fyi as all other action
199     * request types will be discarded
200     *
201     * @param workflowDocument
202     * @param adHocRecipients
203     */
204    public void clearFyi(WorkflowDocument workflowDocument, List<AdHocRouteRecipient> adHocRecipients)
205            throws WorkflowException;
206
207    /**
208     * Gets the current route level name of the workflow document even if document has no active
209     * node names. Allows for getting the node name of a document already in a final status.
210     *
211     * @param workflowDocument
212     * @return node name of the current node if only one or list of node names separated by string
213     *         ", " if more than one current node name
214     * @throws WorkflowException
215     */
216    public String getCurrentRouteLevelName(WorkflowDocument workflowDocument) throws WorkflowException;
217
218    /**
219     * Sends workflow notification to the list of ad hoc recipients. This method is usually used to
220     * notify users of a note that has been added to a document. The notificationLabel parameter is
221     * used to give the request a custom label in the user's Action List
222     *
223     * @param workflowDocument
224     * @param annotation
225     * @param adHocRecipients
226     * @param notificationLabel
227     * @throws WorkflowException
228     */
229    public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation,
230            List<AdHocRouteRecipient> adHocRecipients, String notificationLabel) throws WorkflowException;
231
232    /**
233     * Sends workflow notification at the specified node to the list of ad hoc recipients. This method is usually used
234     * to notify users of a note that has been added to a document. The notificationLabel parameter is
235     * used to give the request a custom label in the user's Action List
236     *
237     * @param workflowDocument
238     * @param annotation
239     * @param nodeName
240     * @param adHocRecipients
241     * @param notificationLabel
242     * @throws WorkflowException
243     */
244    public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation, String nodeName,
245                                         List<AdHocRouteRecipient> adHocRecipients, String notificationLabel) throws WorkflowException;
246
247    void clearFyi(WorkflowDocument workflowDocument, String nodeName, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
248
249    /**
250     * Sends workflow notification to the list of ad hoc recipients. This method is usually used to
251     * notify users of a note that has been added to a document
252     *
253     * @param workflowDocument
254     * @param annotation
255     * @param adHocRecipients
256     * @throws WorkflowException
257     */
258    public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation,
259            List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
260
261    /**
262     * Sends workflow notification at the specified node to the list of ad hoc recipients. This method is usually used to
263     * notify users of a note that has been added to a document
264     *
265     * @param workflowDocument
266     * @param annotation
267     * @param nodeName
268     * @param adHocRecipients
269     * @throws WorkflowException
270     */
271    public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation, String nodeName,
272                                         List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
273
274
275    /**
276     * Returns the current node names of the document delimited by {@code ", "} if there is more
277     * than one.
278     */
279    public String getCurrentRouteNodeNames(WorkflowDocument workflowDocument);
280
281    /**
282     * Completes document
283     *
284     * @param workflowDocument
285     * @param annotation
286     * @param adHocRecipients
287     */
288    public void complete(WorkflowDocument workflowDocument, String annotation, List adHocRecipients) throws WorkflowException;
289
290    /**
291     * recall this workflowDocument optionally providing an annotation for this action taken which
292     * will show up in the route log for this document corresponding to this action taken
293     *
294     * @param workflowDocument
295     * @param annotation
296     */
297    public void recall(WorkflowDocument workflowDocument, String annotation, boolean cancel) throws WorkflowException;
298
299    void complete(WorkflowDocument workflowDocument, String annotation, String nodeName, List adHocRecipients) throws WorkflowException;
300}