1 /**
2 * Copyright 2005-2011 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 * @param adHocRecipients
118 */
119 public void superUserApprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
120
121 /**
122 * super user cancel this workflowDocument optionally providing an annotation for this action
123 * taken which will show up in the route log for this document corresponding to this action
124 * taken
125 *
126 * @param workflowDocument
127 * @param annotation
128 * @throws WorkflowException
129 */
130 public void superUserCancel(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
131
132 /**
133 * super user disapprove this workflowDocument optionally providing an annotation for this
134 * action taken which will show up in the route log for this document corresponding to this
135 * action taken
136 *
137 * @param workflowDocument
138 * @param annotation
139 * @throws WorkflowException
140 */
141 public void superUserDisapprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
142
143 /**
144 * disapprove this workflowDocument optionally providing an annotation for this action taken
145 * which will show up in the route log for this document corresponding to this action taken
146 *
147 * @param workflowDocument
148 * @param annotation
149 */
150 public void disapprove(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
151
152 /**
153 * cancel this workflowDocument optionally providing an annotation for this action taken which
154 * will show up in the route log for this document corresponding to this action taken
155 *
156 * @param workflowDocument
157 * @param annotation
158 */
159 public void cancel(WorkflowDocument workflowDocument, String annotation) throws WorkflowException;
160
161 /**
162 * acknowledge this workflowDocument optionally providing an annotation for this action taken
163 * which will show up in the route log for this document corresponding to this action taken,
164 * additionally optionally providing a list of ad hoc recipients for this document which should
165 * be restricted to actions requested of acknowledge or fyi as all other action request types
166 * will be discarded
167 *
168 * @param workflowDocument
169 * @param annotation
170 * @param adHocRecipients
171 */
172 public void acknowledge(WorkflowDocument workflowDocument, String annotation,
173 List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
174
175 /**
176 * blanket approve this document optionally providing an annotation for this action taken which
177 * will show up in the route log for this document corresponding to this action taken, and
178 * additionally optionally providing a list of ad hoc recipients for this document which should
179 * be restricted to actions requested of acknowledge or fyi as all other action request types
180 * will be discarded.
181 *
182 * @param workflowDocument
183 * @param annotation
184 * @param adHocRecipients
185 */
186 public void blanketApprove(WorkflowDocument workflowDocument, String annotation,
187 List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
188
189 /**
190 * clear the fyi request for this document, optinoally providing a list of ad hoc recipients for
191 * this document which should be restricted to actions requested of fyi as all other action
192 * request types will be discarded
193 *
194 * @param workflowDocument
195 * @param adHocRecipients
196 */
197 public void clearFyi(WorkflowDocument workflowDocument, List<AdHocRouteRecipient> adHocRecipients)
198 throws WorkflowException;
199
200 /**
201 * Gets the current route level name of the workflow document even if document has no active
202 * node names. Allows for getting the node name of a document already in a final status.
203 *
204 * @param workflowDocument
205 * @return node name of the current node if only one or list of node names separated by string
206 * ", " if more than one current node name
207 * @throws WorkflowException
208 */
209 public String getCurrentRouteLevelName(WorkflowDocument workflowDocument) throws WorkflowException;
210
211 /**
212 * Sends workflow notification to the list of ad hoc recipients. This method is usually used to
213 * notify users of a note that has been added to a document. The notificationLabel parameter is
214 * used to give the request a custom label in the user's Action List
215 *
216 * @param workflowDocument
217 * @param annotation
218 * @param adHocRecipients
219 * @param notificationLabel
220 * @throws WorkflowException
221 */
222 public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation,
223 List<AdHocRouteRecipient> adHocRecipients, String notificationLabel) throws WorkflowException;
224
225 /**
226 * Sends workflow notification to the list of ad hoc recipients. This method is usually used to
227 * notify users of a note that has been added to a document
228 *
229 * @param workflowDocument
230 * @param annotation
231 * @param adHocRecipients
232 * @throws WorkflowException
233 */
234 public void sendWorkflowNotification(WorkflowDocument workflowDocument, String annotation,
235 List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
236
237 /**
238 * Returns the current node names of the document delimited by {@code ", "} if there is more
239 * than one.
240 */
241 public String getCurrentRouteNodeNames(WorkflowDocument workflowDocument);
242
243 }