001    /**
002     * Copyright 2005-2013 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     */
016    package org.kuali.rice.krad.workflow.service;
017    
018    import java.util.List;
019    
020    import org.kuali.rice.kew.api.WorkflowDocument;
021    import org.kuali.rice.kew.api.exception.WorkflowException;
022    import org.kuali.rice.kew.api.exception.ResourceUnavailableException;
023    import org.kuali.rice.kim.api.identity.Person;
024    import 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     */
031    public 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    }