001 /*
002 * Copyright 2005-2007 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.exception.ResourceUnavailableException;
022 import org.kuali.rice.kew.exception.WorkflowException;
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 * @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 }