001 /**
002 * Copyright 2005-2014 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 }