001/**
002 * Copyright 2005-2016 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    /**
065     * This method will first determine if the {@link WorkflowDocument#saveDocument(String)} method
066     * is valid to be called. If so the method will save the document to workflows action list
067     * optionally providing an annotation which will show up in the route log for this document
068     * corresponding to this action taken. If the WorkflowDocument.saveDocument() method is not
069     * valid to be called the system will instead call the method
070     * {@link WorkflowDocumentService#saveRoutingData(WorkflowDocument)}
071     * 
072     * @param workflowDocument
073     * @param annotation
074     * @throws WorkflowException
075     */
076    public void save(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
077
078    /**
079     * save the routing data of the document to workflow
080     * 
081     * @param workflowDocument
082     * @throws WorkflowException
083     */
084    public void saveRoutingData(WorkflowDocument workflowDocument) throws WorkflowException;
085
086    /**
087     * route this workflowDocument optionally providing an annotation for this action taken which
088     * will show up in the route log for this document corresponding to this action taken, and
089     * additionally optionally providing a list of ad hoc recipients for the document
090     * 
091     * @param workflowDocument
092     * @param annotation
093     * @param adHocRecipients
094     */
095    public void route(WorkflowDocument workflowDocument, String annotation, List<AdHocRouteRecipient> adHocRecipients)
096            throws WorkflowException;
097
098    /**
099     * approve this workflowDocument optionally providing an annotation for this action taken which
100     * will show up in the route log for this document corresponding to this action taken, and
101     * additionally optionally providing a list of ad hoc recipients for the document
102     * 
103     * @param workflowDocument
104     * @param annotation
105     * @param adHocRecipients
106     */
107    public void approve(WorkflowDocument workflowDocument, String annotation, List<AdHocRouteRecipient> adHocRecipients)
108            throws WorkflowException;
109
110    /**
111     * super user approve this workflowDocument optionally providing an annotation for this action
112     * taken which will show up in the route log for this document corresponding to this action
113     * taken
114     * 
115     * @param workflowDocument
116     * @param annotation
117     */
118    public void superUserApprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
119
120    /**
121     * super user cancel this workflowDocument optionally providing an annotation for this action
122     * taken which will show up in the route log for this document corresponding to this action
123     * taken
124     * 
125     * @param workflowDocument
126     * @param annotation
127     * @throws WorkflowException
128     */
129    public void superUserCancel(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
130
131    /**
132     * super user disapprove this workflowDocument optionally providing an annotation for this
133     * action taken which will show up in the route log for this document corresponding to this
134     * action taken
135     * 
136     * @param workflowDocument
137     * @param annotation
138     * @throws WorkflowException
139     */
140    public void superUserDisapprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
141
142    /**
143     * disapprove this workflowDocument optionally providing an annotation for this action taken
144     * which will show up in the route log for this document corresponding to this action taken
145     * 
146     * @param workflowDocument
147     * @param annotation
148     */
149    public void disapprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
150
151    /**
152     * cancel this workflowDocument optionally providing an annotation for this action taken which
153     * will show up in the route log for this document corresponding to this action taken
154     * 
155     * @param workflowDocument
156     * @param annotation
157     */
158    public void cancel(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
159
160    /**
161     * acknowledge this workflowDocument optionally providing an annotation for this action taken
162     * which will show up in the route log for this document corresponding to this action taken,
163     * additionally optionally providing a list of ad hoc recipients for this document which should
164     * be restricted to actions requested of acknowledge or fyi as all other action request types
165     * will be discarded
166     * 
167     * @param workflowDocument
168     * @param annotation
169     * @param adHocRecipients
170     */
171    public void acknowledge(WorkflowDocument workflowDocument, String annotation,
172            List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
173
174    /**
175     * blanket approve this document optionally providing an annotation for this action taken which
176     * will show up in the route log for this document corresponding to this action taken, and
177     * additionally optionally providing a list of ad hoc recipients for this document which should
178     * be restricted to actions requested of acknowledge or fyi as all other action request types
179     * will be discarded.
180     * 
181     * @param workflowDocument
182     * @param annotation
183     * @param adHocRecipients
184     */
185    public void blanketApprove(WorkflowDocument workflowDocument, String annotation,
186            List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
187
188    /**
189     * clear the fyi request for this document, optinoally providing a list of ad hoc recipients for
190     * this document which should be restricted to actions requested of fyi as all other action
191     * request types will be discarded
192     * 
193     * @param workflowDocument
194     * @param adHocRecipients
195     */
196    public void clearFyi(WorkflowDocument workflowDocument, List<AdHocRouteRecipient> adHocRecipients)
197            throws WorkflowException;
198
199    /**
200     * Gets the current route level name of the workflow document even if document has no active
201     * node names. Allows for getting the node name of a document already in a final status.
202     * 
203     * @param workflowDocument
204     * @return node name of the current node if only one or list of node names separated by string
205     *         ", " if more than one current node name
206     * @throws WorkflowException
207     */
208    public String getCurrentRouteLevelName(WorkflowDocument workflowDocument) throws WorkflowException;
209
210    /**
211     * Sends workflow notification to the list of ad hoc recipients. This method is usually used to
212     * notify users of a note that has been added to a document. The notificationLabel parameter is
213     * used to give the request a custom label in the user's Action List
214     * 
215     * @param workflowDocument
216     * @param annotation
217     * @param adHocRecipients
218     * @param notificationLabel
219     * @throws WorkflowException
220     */
221    public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation,
222            List<AdHocRouteRecipient> adHocRecipients, String notificationLabel) throws WorkflowException;
223
224    /**
225     * Sends workflow notification to the list of ad hoc recipients. This method is usually used to
226     * notify users of a note that has been added to a document
227     * 
228     * @param workflowDocument
229     * @param annotation
230     * @param adHocRecipients
231     * @throws WorkflowException
232     */
233    public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation,
234            List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
235
236    /**
237     * Returns the current node names of the document delimited by {@code ", "} if there is more
238     * than one.
239     */
240    public String getCurrentRouteNodeNames(WorkflowDocument workflowDocument);
241    
242    /**
243     * Completes document
244     * 
245     * @param workflowDocument
246     * @param annotation
247     * @param adHocRecipients
248     */
249    public void complete(WorkflowDocument workflowDocument, String annotation, List adHocRecipients) throws WorkflowException;
250
251    /**
252     * recall this workflowDocument optionally providing an annotation for this action taken which
253     * will show up in the route log for this document corresponding to this action taken
254     *
255     * @param workflowDocument
256     * @param annotation
257     */
258    public void recall(WorkflowDocument workflowDocument, String annotation, boolean cancel) throws WorkflowException;
259}