1 /**
2 * Copyright 2005-2012 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.krad.workflow.service;
17
18 import java.util.List;
19
20 import org.kuali.rice.kew.api.WorkflowDocument;
21 import org.kuali.rice.kew.api.exception.WorkflowException;
22 import org.kuali.rice.kew.api.exception.ResourceUnavailableException;
23 import org.kuali.rice.kim.api.identity.Person;
24 import org.kuali.rice.krad.bo.AdHocRouteRecipient;
25
26 /**
27 * This interface defines the contract that must be implemented by the workflow engine.
28 *
29 *
30 */
31 public interface WorkflowDocumentService {
32 /**
33 * @param documentHeaderId
34 * @return true if a workflowDocument exists for the given documentHeaderId
35 */
36 public boolean workflowDocumentExists(String documentHeaderId);
37
38 /**
39 * Given a documentTypeName and workflowUser, returns a new workflowDocument from the workflow
40 * server.
41 *
42 * @param documentTypeName
43 * @param workflowUser
44 * @return newly-created workflowDocument instance
45 * @throws IllegalArgumentException if the given documentTypeName is blank
46 * @throws IllegalArgumentException if the given workflowUser is null or contains no id
47 * @throws ResourceUnavailableException
48 */
49 public WorkflowDocument createWorkflowDocument(String documentTypeName, Person workflowUser)
50 throws WorkflowException;
51
52 /**
53 * Given a documentHeaderId and workflowUser, retrieves the workflowDocument associated with
54 * that documentHeaderId from the workflow server.
55 *
56 * @param documentHeaderId
57 * @param workflowUser
58 * @return existing workflowDoc
59 * @throws IllegalArgumentException if the given documentHeaderId is null
60 * @throws IllegalArgumentException if the given workflowUser is null or contains no id
61 */
62 public WorkflowDocument loadWorkflowDocument(String documentHeaderId, Person workflowUser) throws WorkflowException;
63
64 /**
65 * This method will first determine if the {@link WorkflowDocument#saveDocument(String)} method
66 * is valid to be called. If so the method will save the document to workflows action list
67 * optionally providing an annotation which will show up in the route log for this document
68 * corresponding to this action taken. If the WorkflowDocument.saveDocument() method is not
69 * valid to be called the system will instead call the method
70 * {@link WorkflowDocumentService#saveRoutingData(WorkflowDocument)}
71 *
72 * @param workflowDocument
73 * @param annotation
74 * @throws WorkflowException
75 */
76 public void save(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
77
78 /**
79 * save the routing data of the document to workflow
80 *
81 * @param workflowDocument
82 * @throws WorkflowException
83 */
84 public void saveRoutingData(WorkflowDocument workflowDocument) throws WorkflowException;
85
86 /**
87 * route this workflowDocument optionally providing an annotation for this action taken which
88 * will show up in the route log for this document corresponding to this action taken, and
89 * additionally optionally providing a list of ad hoc recipients for the document
90 *
91 * @param workflowDocument
92 * @param annotation
93 * @param adHocRecipients
94 */
95 public void route(WorkflowDocument workflowDocument, String annotation, List<AdHocRouteRecipient> adHocRecipients)
96 throws WorkflowException;
97
98 /**
99 * 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 }