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.kew.api.action;
17
18 import java.util.List;
19 import java.util.Set;
20
21 import javax.jws.WebMethod;
22 import javax.jws.WebParam;
23 import javax.jws.WebResult;
24 import javax.jws.WebService;
25 import javax.jws.soap.SOAPBinding;
26 import javax.xml.bind.annotation.XmlElement;
27 import javax.xml.bind.annotation.XmlElementWrapper;
28
29 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
30 import org.kuali.rice.core.api.uif.RemotableAttributeError;
31 import org.kuali.rice.kew.api.KewApiConstants;
32 import org.kuali.rice.kew.api.WorkflowDocument;
33 import org.kuali.rice.kew.api.doctype.IllegalDocumentTypeException;
34 import org.kuali.rice.kew.api.document.Document;
35 import org.kuali.rice.kew.api.document.DocumentContentUpdate;
36 import org.kuali.rice.kew.api.document.DocumentDetail;
37 import org.kuali.rice.kew.api.document.DocumentStatus;
38 import org.kuali.rice.kew.api.document.DocumentUpdate;
39 import org.kuali.rice.kew.api.document.InvalidDocumentContentException;
40 import org.kuali.rice.kew.api.document.attribute.WorkflowAttributeDefinition;
41 import org.kuali.rice.kew.api.document.WorkflowDocumentService;
42
43 /**
44 * This service defines various operations which are used to perform actions against a workflow
45 * {@link Document}. These actions include creation, routing, approval, acknowledgment, saving,
46 * updating document data, etc.
47 *
48 * <p>
49 * It also includes operations that allow for loading of information about which actions a given
50 * principal is permitted to execute against a given document ({@link ValidActions}), as well as
51 * providing information about what actions a particular principal has been requested to execute
52 * against a given document ({@link RequestedActions}).
53 *
54 * <p>
55 * This service can be used in conjunction with the {@link WorkflowDocumentService} which provides
56 * additional operations that relate to documents (but not document actions).
57 *
58 * <p>
59 * Unless otherwise specified, all parameters to all methods must not be null. If the argument is a
60 * string value it must also not be "blank" (either the empty string or a string of only
61 * whitespace). In the cases where this is violated, a {@link RiceIllegalArgumentException} will be
62 * thrown. Additionally, unless otherwise specified, all methods will return non-null return values.
63 * In the case of collections, an empty collection will be returned in preference to a null
64 * collection value. All collections which are returned from methods on this service will be
65 * unmodifiable collections.
66 *
67 * <p>
68 * Many of the actions trigger processing by the workflow engine. Unless otherwise specified, any
69 * method on this service which performs an action against the document will also submit the
70 * document to the workflow engine after performing the action. This may trigger the workflow
71 * document to transition to the next node in the workflow process or activate additional action
72 * requests depending on what the current state of the active node instance(s) is on the document.
73 *
74 * <p>
75 * Workflow engine processing may happen either asynchronously or synchronously depending on
76 * configuration and capabilities of the back end workflow engine implementation. However,
77 * asynchronous operation is suggested for most use cases. This means that when operating in
78 * asynchronous mode, after an action is submitted against the document there may be a delay in
79 * state changes to the document. For example, if a principal submits an approve against a document
80 * that triggers transition to the next node in the workflow process (generating new action requests
81 * in the process) those new actions requests will not be represented in the information returned in
82 * the {@link DocumentActionResult} result object. Though future invocations of
83 * {@link #determineRequestedActions(String, String)} and similar methods may yield such
84 * information, though it may do so after an non-deterministic amount of time since the workflow
85 * engine makes no guarantees about how quickly it will complete processing. Additionally,
86 * asynchronous workflow processing is scheduled in a work queue and therefore it may not be picked
87 * up for processing immediately depending on system load and other factors.
88 *
89 * <p>
90 * If there is an error during asynchronous workflow processing then the document will be put into
91 * exception routing (which can be executed in various ways depending on how the document type
92 * defines it's exception policy). Regardless of the exact process that gets triggered during
93 * exception routing, the end result is a set of {@link ActionRequestType#COMPLETE} requests to
94 * those principals who are capable of resolving the exception scenario as well as the document's
95 * status being transitioned to {@link DocumentStatus#EXCEPTION}. Once they have resolved any
96 * barriers to successful processing of the document, they can take the
97 * {@link #complete(DocumentActionParameters)} action against the document in order to satisfy the
98 * outstanding exception request(s) and send the document back through the workflow engine.
99 *
100 * <p>
101 * In contrast, when operating the workflow engine in synchronous mode, processing will happen
102 * immediately and control will not be returned to the caller until all outstanding processing has
103 * completed. As a result, the information returned in the {@link DocumentActionResult} will always
104 * be in a consistent state after each action is performed. When operating in synchronous mode, the
105 * process of exception routing does not occur when failures are encountered during workflow engine
106 * processing, rather any exceptions that are raised during processing will instead be thrown back
107 * to the calling code.
108 *
109 * <p>
110 * Implementations of this service are required to be thread-safe and should be able to be invoked
111 * either locally or remotely.
112 *
113 * @see WorkflowDocumentService
114 * @see WorkflowDocument
115 *
116 * @author Kuali Rice Team (rice.collab@kuali.org)
117 *
118 */
119 @WebService(name = "workflowDocumentActionsService", targetNamespace = KewApiConstants.Namespaces.KEW_NAMESPACE_2_0)
120 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
121 public interface WorkflowDocumentActionsService {
122
123 /**
124 * Creates a new document instance from the given document type. The initiator of the resulting
125 * document will be the same as the initiator that is passed to this method. Optional
126 * {@link DocumentUpdate} and {@link DocumentContentUpdate} parameters can be supplied in order
127 * to create the document with these additional pieces of data already set.
128 *
129 * <p>
130 * By default, if neither the {@link DocumentUpdate} or {@link DocumentContentUpdate} is passed
131 * to this method, the document that is created and returned from this operation will have the
132 * following initial state:
133 *
134 * <ul>
135 * <ol>
136 * {@code status} set to {@link DocumentStatus#INITIATED}
137 * </ol>
138 * <ol>
139 * {@code createDate} and {@code dateLastModified} set to the current date and time
140 * </ol>
141 * <ol>
142 * {@code current} set to 'true'
143 * </ol>
144 * <ol>
145 * {@code documentContent} set to the default and empty content
146 * </ol>
147 * </ul>
148 *
149 * <p>
150 * Additionally, the initial {@link org.kuali.rice.kew.api.document.node.RouteNodeInstance} for the workflow process on the document
151 * will be created and linked to the document as it's initial node. Once the document is
152 * created, the {@link #route(DocumentActionParameters)} operation must be invoked in order to
153 * submit it to the workflow engine for initial processing.
154 *
155 * <p>
156 * In certain situations, the given principal may not be permitted to initiate documents of the
157 * given type. In these cases an {@link InvalidActionTakenException} will be thrown.
158 *
159 * @param documentTypeName the name of the document type from which to create this document
160 * @param initiatorPrincipalId the id of the principal who is initiating this document
161 * @param documentUpdate specifies additional document to set on the document upon creation,
162 * this is optional and if null is passed then the document will be created with the
163 * default document state
164 * @param documentContentUpdate defines what the initial document content for the document
165 * should be, this is optional if null is passed then the document will be created with
166 * the default empty document content
167 *
168 * @return the document that was created
169 *
170 * @throws RiceIllegalArgumentException if {@code principalId} is null or blank
171 * @throws RiceIllegalArgumentException if {@code principalId} does not identify a valid
172 * principal
173 * @throws RiceIllegalArgumentException if {@code documentTypeName} is null or blank
174 * @throws RiceIllegalArgumentException if {@code documentTypeName} does not identify an
175 * existing document type
176 * @throws IllegalDocumentTypeException if the specified document type is not active
177 * @throws IllegalDocumentTypeException if the specified document type does not support document
178 * creation (in other words, it's a document type that is only used as a parent)
179 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
180 * action
181 */
182 @WebMethod(operationName = "create")
183 @WebResult(name = "document")
184 @XmlElement(name = "document", required = true)
185 Document create(
186 @WebParam(name = "documentTypeName") String documentTypeName,
187 @WebParam(name = "initiatorPrincipalId") String initiatorPrincipalId,
188 @WebParam(name = "documentUpdate") DocumentUpdate documentUpdate,
189 @WebParam(name = "documentContentUpdate") DocumentContentUpdate documentContentUpdate)
190 throws RiceIllegalArgumentException, IllegalDocumentTypeException, InvalidActionTakenException;
191
192 /**
193 * Determines which actions against the document with the given id are valid for the principal
194 * with the given id.
195 *
196 * @param documentId the id of the document for which to determine valid actions
197 * @param principalId the id of the principal for which to determine valid actions against the
198 * given document
199 *
200 * @return a {@link ValidActions} object which contains the valid actions for the given
201 * principal against the given document
202 *
203 * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
204 * @throws RiceIllegalArgumentException if document with the given {@code documentId} does not
205 * exist
206 * @throws RiceIllegalArgumentException if {@code principalId} is null or blank
207 * @throws RiceIllegalArgumentException if principal with the given {@code principalId} does not
208 * exist
209 */
210 @WebMethod(operationName = "determineValidActions")
211 @WebResult(name = "validActions")
212 @XmlElement(name = "validActions", required = true)
213 ValidActions determineValidActions(
214 @WebParam(name = "documentId") String documentId,
215 @WebParam(name = "principalId") String principalId)
216 throws RiceIllegalArgumentException;
217
218 /**
219 * Determines which actions are requested against the document with the given id for the
220 * principal with the given id. These are generally derived based on action requests that are
221 * currently pending against the document.
222 *
223 * <p>
224 * This method is distinguished from {@link #determineValidActions(String, String)} in that fact
225 * that valid actions are the actions that the principal is permitted to take, while requested
226 * actions are those that the principal is specifically being asked to take. Note that the
227 * actions that are requested are used when assembling valid actions but are not necessarily the
228 * only authoritative source for determination of valid actions for the principal, as
229 * permissions and other configuration can also come into play.
230 *
231 * @param documentId the id of the document for which to determine requested actions
232 * @param principalId the id of the principal for which to determine requested actions against
233 * the given document
234 *
235 * @return a {@link RequestedActions} object which contains the actions that are being requested
236 * from the given principal against the given document
237 *
238 * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
239 * @throws RiceIllegalArgumentException if document with the given {@code documentId} does not
240 * exist
241 * @throws RiceIllegalArgumentException if {@code principalId} is null or blank
242 * @throws RiceIllegalArgumentException if principal with the given {@code principalId} does not
243 * exist
244 */
245 @WebMethod(operationName = "determineRequestedActions")
246 @WebResult(name = "requestedActions")
247 @XmlElement(name = "requestedActions", required = true)
248 RequestedActions determineRequestedActions(
249 @WebParam(name = "documentId") String documentId,
250 @WebParam(name = "principalId") String principalId)
251 throws RiceIllegalArgumentException;
252
253 /**
254 * Executes an {@link ActionType#ACKNOWLEDGE} action for the given principal and document
255 * specified in the supplied parameters. When a principal acknowledges a document, any of the
256 * principal's pending action requests at or below the acknowledge level (which includes fyi
257 * requests as well) will be satisfied by the principal's action. The principal's action should
258 * be recorded with the document as an {@link ActionTaken}.
259 *
260 * <p>
261 * Depending on document type policy, a pending action request at or below the acknowledge level
262 * may have to exist on the document in order for the principal to take this action. Otherwise
263 * an {@link InvalidActionTakenException} may be thrown. In order to determine if an acknowledge
264 * action is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
265 * checked.
266 *
267 * @param parameters the parameters which indicate which principal is executing the action
268 * against which document, as well as additional operations to take against the document,
269 * such as updating document data
270 *
271 * @return the result of executing the action, including a view on the updated state of the
272 * document and related actions
273 *
274 * @throws RiceIllegalArgumentException if {@code parameters} is null
275 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
276 * {@code parameters} exists
277 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
278 * in {@code parameters} exists
279 * @throws InvalidDocumentContentException if the document content on the
280 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
281 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
282 * action
283 */
284 @WebMethod(operationName = "acknowledge")
285 @WebResult(name = "documentActionResult")
286 @XmlElement(name = "documentActionResult", required = true)
287 DocumentActionResult acknowledge(@WebParam(name = "parameters") DocumentActionParameters parameters)
288 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
289
290 /**
291 * Executes an {@link ActionType#APPROVE} action for the given principal and document specified
292 * in the supplied parameters. When a principal approves a document, any of the principal's
293 * pending action requests at or below the approve level (which includes complete, acknowledge,
294 * and fyi requests as well) will be satisfied by the principal's action. The principal's action
295 * should be recorded with the document as an {@link ActionTaken}.
296 *
297 * <p>
298 * Depending on document type policy, a pending action request at or below the approve level may
299 * have to exist on the document in order for the principal to take this action. Otherwise an
300 * {@link InvalidActionTakenException} may be thrown. In order to determine if an approve action
301 * is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
302 * checked.
303 *
304 * @param parameters the parameters which indicate which principal is executing the action
305 * against which document, as well as additional operations to take against the document,
306 * such as updating document data
307 *
308 * @return the result of executing the action, including a view on the updated state of the
309 * document and related actions
310 *
311 * @throws RiceIllegalArgumentException if {@code parameters} is null
312 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
313 * {@code parameters} exists
314 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
315 * in {@code parameters} exists
316 * @throws InvalidDocumentContentException if the document content on the
317 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
318 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
319 * action
320 */
321 @WebMethod(operationName = "approve")
322 @WebResult(name = "documentActionResult")
323 @XmlElement(name = "documentActionResult", required = true)
324 DocumentActionResult approve(@WebParam(name = "parameters") DocumentActionParameters parameters)
325 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
326
327 /**
328 * Executes an {@link ActionType#ADHOC_REQUEST} action for the given principal and document
329 * specified in the supplied parameters to create an ad hoc action request to the target
330 * principal specified in the {@code AdHocToPrincipal}.
331 *
332 * <p>
333 * Operates as per {@link #adHocToGroup(DocumentActionParameters, AdHocToGroup)} with the
334 * exception that this method is used to send an adhoc request to principal instead of a group.
335 *
336 * <p>
337 * Besides this difference, the same rules that are in play for sending ad hoc requests to group
338 * apply for sending ad hoc requests to principals.
339 *
340 * @param parameters the parameters which indicate which principal is executing the action
341 * against which document, as well as additional operations to take against the document,
342 * such as updating document data
343 * @param adHocToPrincipal defines various pieces of information that informs what type of ad
344 * hoc request should be created
345 *
346 * @return the result of executing the action, including a view on the updated state of the
347 * document and related actions
348 *
349 * @throws RiceIllegalArgumentException if {@code parameters} is null
350 * @throws RiceIllegalArgumentException if {@code adHocToPrincipal} is null
351 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
352 * {@code parameters} exists
353 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
354 * in {@code parameters} exists
355 * @throws InvalidDocumentContentException if the document content on the
356 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
357 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
358 * action
359 * @throws InvalidActionTakenException if the target principal is not permitted to receive ad
360 * hoc requests on documents of this type
361 * @throws InvalidActionTakenException if the specified ad hoc request cannot be generated
362 * because the current state of the document would result in an illegal request being
363 * generated
364 *
365 * @see #adHocToGroup(DocumentActionParameters, AdHocToGroup)
366 */
367 @WebMethod(operationName = "adHocToPrincipal")
368 @WebResult(name = "documentActionResult")
369 @XmlElement(name = "documentActionResult", required = true)
370 DocumentActionResult adHocToPrincipal(
371 @WebParam(name = "parameters") DocumentActionParameters parameters,
372 @WebParam(name = "adHocToPrincipal") AdHocToPrincipal adHocToPrincipal)
373 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
374
375 /**
376 * Executes an {@link ActionType#ADHOC_REQUEST} action for the given group and document
377 * specified in the supplied parameters to create an ad hoc action request to the target group
378 * specified in the {@code AdHocToGroup}. The {@code AdHocToGroup} contains additional
379 * information on how the ad hoc action request should be created, including the type of request
380 * to generate, at which node it should generated, etc.
381 *
382 * <p>
383 * The policy for how ad hoc actions handle request generation and interact with the workflow
384 * engine is different depending on the state of the document when the request to generate the
385 * ad hoc is submitted. There are also different scenarios under which certain types of ad hoc
386 * actions are allowed to be executed (throwing {@link InvalidActionTakenException} in
387 * situations where the actions are not permitted). The rules are defined as follows:
388 *
389 * <ol>
390 * <li>If the status of the document is {@link DocumentStatus#INITIATED} then the action request
391 * will be generated with a status of {@link ActionRequestStatus#INITIALIZED} and no processing
392 * directives will be submitted to the workflow engine. When the document is routed, these ad
393 * hoc requests will get activated</li>
394 * <li>If the ad hoc request being created is an {@link ActionRequestType#COMPLETE} or
395 * {@link ActionRequestType#APPROVE} and the document is in a "terminal" state (either
396 * {@link DocumentStatus#CANCELED}, {@link DocumentStatus#DISAPPROVED},
397 * {@link DocumentStatus#PROCESSED}, {@link DocumentStatus#FINAL}) or is in
398 * {@link DocumentStatus#EXCEPTION} status, then an {@link InvalidActionTakenException} will be
399 * thrown. This is because submitting such an action with a document in that state would result
400 * in creation of an illegal action request.</li>
401 * <li>If the document is in a "terminal" state (see above for definition) then the request will
402 * be immediately (and synchronously) activated.</li>
403 * <li>Otherwise, after creating the ad hoc request it will be in the
404 * {@link ActionRequestStatus#INITIALIZED} status, and the document will be immediately
405 * forwarded to the workflow engine for processing at which point the ad hoc request will
406 * activated at the appropriate time.</li>
407 * </ol>
408 *
409 * <p>
410 * Unlink other actions, ad hoc actions don't result in the recording of an {@link ActionTaken}
411 * against the document. Instead, only the requested ad hoc {@link ActionRequest} is created.
412 *
413 * @param parameters the parameters which indicate which principal is executing the action
414 * against which document, as well as additional operations to take against the document,
415 * such as updating document data
416 * @param adHocToGroup defines various pieces of information that informs what type of ad hoc
417 * request should be created
418 *
419 * @return the result of executing the action, including a view on the updated state of the
420 * document and related actions
421 *
422 * @throws RiceIllegalArgumentException if {@code parameters} is null
423 * @throws RiceIllegalArgumentException if {@code adHocToGroup} is null
424 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
425 * {@code parameters} exists
426 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
427 * in {@code parameters} exists
428 * @throws InvalidDocumentContentException if the document content on the
429 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
430 * @throws InvalidActionTakenException if the supplied principals i is not allowed to execute
431 * this action
432 * @throws InvalidActionTakenException if any of the principals in the target group are not
433 * permitted to receive ad hoc requests on documents of this type
434 * @throws InvalidActionTakenException if the specified ad hoc request cannot be generated
435 * because the current state of the document would result in an illegal request being
436 * generated
437 */
438 @WebMethod(operationName = "adHocToGroup")
439 @WebResult(name = "documentActionResult")
440 @XmlElement(name = "documentActionResult", required = true)
441 DocumentActionResult adHocToGroup(
442 @WebParam(name = "parameters") DocumentActionParameters parameters,
443 @WebParam(name = "adHocToGroup") AdHocToGroup adHocToGroup)
444 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
445
446 /**
447 * Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action for the given principal and
448 * document specified in the supplied parameters against the action request with the given id.
449 * The process of revoking an ad hoc request simply deactivates the request associating the
450 * generated {@link ActionTaken} of the revoke action with the deactivated request (this allows
451 * for it to be determined what caused the ad hoc request to be deactivated). As with other
452 * actions, this action taken is then recorded with the document.
453 *
454 * @param parameters the parameters which indicate which principal is executing the action
455 * against which document, as well as additional operations to take against the document,
456 * such as updating document data
457 * @param actionRequestId the id of the action request to revoke
458 *
459 * @return the result of executing the action, including a view on the updated state of the
460 * document and related actions
461 *
462 * @throws RiceIllegalArgumentException if {@code parameters} is null
463 * @throws RiceIllegalArgumentException if {@code actionRequestId} is null or blank
464 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
465 * {@code parameters} exists
466 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
467 * in {@code parameters} exists
468 * @throws InvalidDocumentContentException if the document content on the
469 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
470 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
471 * action
472 * @throws InvalidActionTakenException if a pending ad hoc request with the given
473 * {@code actionRequestId} does not exist on the specified document, this could mean
474 * that the action request id is invalid, or that the action request has already been
475 * deactivated and is no longer pending
476 */
477 @WebMethod(operationName = "revokeAdHocRequestById")
478 @WebResult(name = "documentActionResult")
479 @XmlElement(name = "documentActionResult", required = true)
480 DocumentActionResult revokeAdHocRequestById(
481 @WebParam(name = "parameters") DocumentActionParameters parameters,
482 @WebParam(name = "actionRequestId") String actionRequestId)
483 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
484
485 /**
486 * Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action which revokes all pending ad hoc
487 * action requests that match the supplied {@link AdHocRevoke} criteria for the given principal
488 * and document specified in the supplied parameters. The process of revoking an ad hoc requests
489 * simply deactivates all ad hoc requests that match the given {@code AdHocRevoke} criteria,
490 * associating the generated {@link ActionTaken} of the revoke action with the deactivated
491 * requests (this allows for it to be determined what caused the ad hoc request to be
492 * deactivated). As with other actions, this action taken is then recorded with the document.
493 *
494 * <p>
495 * It's possible that the given ad hoc revoke command will match no action requests on the
496 * document, in which case this method will complete successfully but no requests will be
497 * deactivated.
498 *
499 * @param parameters the parameters which indicate which principal is executing the action
500 * against which document, as well as additional operations to take against the document,
501 * such as updating document data
502 * @param revoke the criteria for matching ad hoc action requests on the specified document that
503 * should be revoked
504 *
505 * @return the result of executing the action, including a view on the updated state of the
506 * document and related actions
507 *
508 * @throws RiceIllegalArgumentException if {@code parameters} is null
509 * @throws RiceIllegalArgumentException if {@code revoke} is null
510 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
511 * {@code parameters} exists
512 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
513 * in {@code parameters} exists
514 * @throws InvalidDocumentContentException if the document content on the
515 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
516 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
517 * action
518 */
519 @WebMethod(operationName = "revokeAdHocRequests")
520 @WebResult(name = "documentActionResult")
521 @XmlElement(name = "documentActionResult", required = true)
522 DocumentActionResult revokeAdHocRequests(
523 @WebParam(name = "parameters") DocumentActionParameters parameters,
524 @WebParam(name = "revoke") AdHocRevoke revoke)
525 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
526
527 /**
528 * Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action which revokes all pending ad hoc
529 * action requests for the given principal and document specified in the supplied parameters.
530 * This process of revoking all ad hoc requests will simply deactivate all ad hoc requests on
531 * the specified document, associating the generated {@link ActionTaken} of the revoke action
532 * with the deactivated requests (this allows for it to be determined what caused the ad hoc
533 * request to be deactivated). As with other actions, this action taken is then recorded with
534 * the document.
535 *
536 * <p>
537 * It's possible that the specified document will have no pending adhoc requests, in which case
538 * this method will complete successfully but no requests will be deactivated.
539 *
540 * @param parameters the parameters which indicate which principal is executing the action
541 * against which document, as well as additional operations to take against the document,
542 * such as updating document data
543 *
544 * @return the result of executing the action, including a view on the updated state of the
545 * document and related actions
546 *
547 * @throws RiceIllegalArgumentException if {@code parameters} is null
548 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
549 * {@code parameters} exists
550 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
551 * in {@code parameters} exists
552 * @throws InvalidDocumentContentException if the document content on the
553 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
554 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
555 * action
556 */
557 @WebMethod(operationName = "revokeAllAdHocRequests")
558 @WebResult(name = "documentActionResult")
559 @XmlElement(name = "documentActionResult", required = true)
560 DocumentActionResult revokeAllAdHocRequests(@WebParam(name = "parameters") DocumentActionParameters parameters)
561 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
562
563 /**
564 * Executes a {@link ActionType#CANCEL} action for the given principal and document specified in
565 * the supplied parameters. When a principal cancels a document, all pending action requests on
566 * the document are deactivated and the the principal's action will be recorded on the document
567 * as an {@link ActionTaken}. Additionally, the document will be (synchronously) transitioned to
568 * the {@link DocumentStatus#CANCELED} status.
569 *
570 * <p>
571 * In order to cancel a document, the principal must have permission to cancel documents of the
572 * appropriate type, and one of the following must hold true:
573 *
574 * <ol>
575 * <li>The document must have a status of {@link DocumentStatus#INITIATED} <strong>or</strong></li>
576 * <li>The document must have a status of {@link DocumentStatus#SAVED} <strong>or</strong></li>
577 * <li>The principal must have a pending "complete" or "approve" request on the document.
578 *
579 * @param parameters the parameters which indicate which principal is executing the action
580 * against which document, as well as additional operations to take against the document,
581 * such as updating document data
582 *
583 * @return the result of executing the action, including a view on the updated state of the
584 * document and related actions
585 *
586 * @throws RiceIllegalArgumentException if {@code parameters} is null
587 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
588 * {@code parameters} exists
589 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
590 * in {@code parameters} exists
591 * @throws InvalidDocumentContentException if the document content on the
592 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
593 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
594 * action
595 */
596 @WebMethod(operationName = "cancel")
597 @WebResult(name = "documentActionResult")
598 @XmlElement(name = "documentActionResult", required = true)
599 DocumentActionResult cancel(@WebParam(name = "parameters") DocumentActionParameters parameters)
600 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
601
602 /**
603 * Executes a {@link ActionType#RECALL} action for the given principal and document specified in
604 * the supplied parameters. When a principal cancels a document, all pending action requests on
605 * the document are deactivated and the the principal's action will be recorded on the document
606 * as an {@link ActionTaken}. Additionally, the document will be (synchronously) transitioned to
607 * the {@link DocumentStatus#RECALLED} status.
608 *
609 * TODO: FILL IN DOCS FOR RECALL ACTION
610 * <p>
611 * In order to cancel a document, the principal must have permission to cancel documents of the
612 * appropriate type, and one of the following must hold true:
613 *
614 * <ol>
615 * <li>The document must have a status of {@link DocumentStatus#INITIATED} <strong>or</strong></li>
616 * <li>The document must have a status of {@link DocumentStatus#SAVED} <strong>or</strong></li>
617 * <li>The principal must have a pending "complete" or "approve" request on the document.
618 *
619 * @since 2.1
620 * @param parameters the parameters which indicate which principal is executing the action
621 * against which document, as well as additional operations to take against the document,
622 * such as updating document data
623 * @param cancel whether to recall & cancel or recall & return to action list
624 *
625 * @return the result of executing the action, including a view on the updated state of the
626 * document and related actions
627 *
628 * @throws RiceIllegalArgumentException if {@code parameters} is null
629 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
630 * {@code parameters} exists
631 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
632 * in {@code parameters} exists
633 * @throws InvalidDocumentContentException if the document content on the
634 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
635 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
636 * action
637 */
638 @WebMethod(operationName = "recall")
639 @WebResult(name = "documentActionResult")
640 @XmlElement(name = "documentActionResult", required = true)
641 DocumentActionResult recall(@WebParam(name = "parameters") DocumentActionParameters parameters,
642 @WebParam(name = "cancel") boolean cancel)
643 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
644
645 /**
646 * Executes an {@link ActionType#FYI} action for the given principal and document specified in
647 * the supplied parameters. When a principal clears fyis on a document, any of the principal's
648 * pending fyis will be satisfied by the principal's action. The principal's action should be
649 * recorded with the document as an {@link ActionTaken}.
650 *
651 * <p>
652 * Depending on document type policy, a pending fyi request may have to exist on the document in
653 * order for the principal to take this action. Otherwise an {@link InvalidActionTakenException}
654 * may be thrown. In order to determine if an fyi action is valid, the {@link ValidActions} or
655 * {@link RequestedActions} for the document can be checked.
656 *
657 * @param parameters the parameters which indicate which principal is executing the action
658 * against which document, as well as additional operations to take against the document,
659 * such as updating document data
660 *
661 * @return the result of executing the action, including a view on the updated state of the
662 * document and related actions
663 *
664 * @throws RiceIllegalArgumentException if {@code parameters} is null
665 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
666 * {@code parameters} exists
667 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
668 * in {@code parameters} exists
669 * @throws InvalidDocumentContentException if the document content on the
670 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
671 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
672 * action
673 */
674 @WebMethod(operationName = "clearFyi")
675 @WebResult(name = "documentActionResult")
676 @XmlElement(name = "documentActionResult", required = true)
677 DocumentActionResult clearFyi(@WebParam(name = "parameters") DocumentActionParameters parameters)
678 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
679
680 /**
681 * Executes an {@link ActionType#COMPLETE} action for the given principal and document specified
682 * in the supplied parameters. When a principal completes a document, any of the principal's
683 * pending action requests at or below the complete level (which includes approve, acknowledge,
684 * and fyi requests as well) will be satisfied by the principal's action. The principal's action
685 * should be recorded with the document as an {@link ActionTaken}.
686 *
687 * <p>
688 * Depending on document type policy, a pending action request at or below the complete level
689 * may have to exist on the document in order for the principal to take this action. Otherwise
690 * an {@link InvalidActionTakenException} may be thrown. In order to determine if an complete
691 * action is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
692 * checked.
693 *
694 * @param parameters the parameters which indicate which principal is executing the action
695 * against which document, as well as additional operations to take against the document,
696 * such as updating document data
697 *
698 * @return the result of executing the action, including a view on the updated state of the
699 * document and related actions
700 *
701 * @throws RiceIllegalArgumentException if {@code parameters} is null
702 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
703 * {@code parameters} exists
704 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
705 * in {@code parameters} exists
706 * @throws InvalidDocumentContentException if the document content on the
707 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
708 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
709 * action
710 */
711 @WebMethod(operationName = "complete")
712 @WebResult(name = "documentActionResult")
713 @XmlElement(name = "documentActionResult", required = true)
714 DocumentActionResult complete(@WebParam(name = "parameters") DocumentActionParameters parameters)
715 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
716
717 /**
718 * Executes a {@link ActionType#DISAPPROVE} action for the given principal and document
719 * specified in the supplied parameters. When a principal disapproves a document, all pending
720 * action requests on the document are deactivated and the the principal's action will be
721 * recorded on the document as an {@link ActionTaken}. Additionally, the document will be
722 * (synchronously) transitioned to the {@link DocumentStatus#DISAPPROVED} status.
723 *
724 * <p>
725 * Depending on document type policy and configuration, notifications may be sent to past
726 * approvers of the document. By default, an "acknowledge" request will be sent to each
727 * principal who took an "approve" or "complete" action on the document previously.
728 *
729 * <p>
730 * In order to disapprove a document, the principal must have a pending approve or complete
731 * request on the document.
732 *
733 * @param parameters the parameters which indicate which principal is executing the action
734 * against which document, as well as additional operations to take against the document,
735 * such as updating document data
736 *
737 * @return the result of executing the action, including a view on the updated state of the
738 * document and related actions
739 *
740 * @throws RiceIllegalArgumentException if {@code parameters} is null
741 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
742 * {@code parameters} exists
743 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
744 * in {@code parameters} exists
745 * @throws InvalidDocumentContentException if the document content on the
746 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
747 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
748 * action
749 */
750 @WebMethod(operationName = "disapprove")
751 @WebResult(name = "documentActionResult")
752 @XmlElement(name = "documentActionResult", required = true)
753 DocumentActionResult disapprove(@WebParam(name = "parameters") DocumentActionParameters parameters)
754 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
755
756 /**
757 * Submits a document that is in either the "initiated" or "saved" state to the workflow engine
758 * for processing. The route action triggers the beginning of the routing process and
759 * (synchronously) switches the status of the document to {@link DocumentStatus#ENROUTE}. It
760 * then queues up a request to the workflow engine to process the document.
761 *
762 * <p>
763 * When the route action is executed, an {@link ActionType#COMPLETE} action is recorded on the
764 * document for the principal who executed the route action. At this point in time, any action
765 * requests that are currently on the document in an "initialized" state will be activated.
766 * Requests of this nature can commonly exist if ad hoc requests have been attached to the
767 * document prior to execution of the route action.
768 *
769 * <p>
770 * By default, the principal who initiated the document is the same principal who must submit
771 * the route command. However, a document type policy can be set which will relax this
772 * constraint.
773 *
774 * <p>
775 * The route action should ideally only ever be executed once for a given document. Depending on
776 * document type policy, attempting to execute a "route" action against a document which is
777 * already enroute or in a terminal state may result in an {@link InvalidActionTakenException}
778 * being thrown.
779 *
780 * @param parameters the parameters which indicate which principal is executing the action
781 * against which document, as well as additional operations to take against the document,
782 * such as updating document data
783 *
784 * @return the result of executing the action, including a view on the updated state of the
785 * document and related actions
786 *
787 * @throws RiceIllegalArgumentException if {@code parameters} is null
788 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
789 * {@code parameters} exists
790 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
791 * in {@code parameters} exists
792 * @throws InvalidDocumentContentException if the document content on the
793 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
794 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
795 * action
796 */
797 @WebMethod(operationName = "route")
798 @WebResult(name = "documentActionResult")
799 @XmlElement(name = "documentActionResult", required = true)
800 DocumentActionResult route(@WebParam(name = "parameters") DocumentActionParameters parameters)
801 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
802
803 /**
804 * Triggers the execution of a full {@link ActionType#BLANKET_APPROVE} action for the given
805 * principal and document specified in the supplied parameters. Blanket approval will
806 * orchestrate a document from it's current node all the way to the end of the document's
807 * workflow process. During this process, it will automatically act on all "approve" and
808 * "complete" requests, effectively bypassing them. When it does this, it will notify the
809 * original recipients of these requests by routing acknowledge requests to them.
810 *
811 * <p>
812 * Blanket approve processing is handled by a special mode of the workflow engine which runs the
813 * document through it's full processing lifecycle, ensuring that it makes it's way to the end
814 * of it's route path (by bypassing any steps that would cause the process to halt, such as
815 * approval requests). Because of this nature, blanket approve processing behavior is governed
816 * by the same configuration as the rest of the workflow engine. So depending on whether the
817 * engine is configured or synchronous or asynchronous operation, the blanket approve processing
818 * will behave in the same manner.
819 *
820 * <p>
821 * In order to execute a blanket approve operation, the principal must have permissions to do
822 * so.
823 *
824 * @param parameters the parameters which indicate which principal is executing the action
825 * against which document, as well as additional operations to take against the document,
826 * such as updating document data
827 *
828 * @return the result of executing the action, including a view on the updated state of the
829 * document and related actions
830 *
831 * @throws RiceIllegalArgumentException if {@code parameters} is null
832 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
833 * {@code parameters} exists
834 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
835 * in {@code parameters} exists
836 * @throws InvalidDocumentContentException if the document content on the
837 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
838 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
839 * action
840 */
841 @WebMethod(operationName = "blanketApprove")
842 @WebResult(name = "documentActionResult")
843 @XmlElement(name = "documentActionResult", required = true)
844 DocumentActionResult blanketApprove(@WebParam(name = "parameters") DocumentActionParameters parameters)
845 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
846
847 /**
848 * Triggers the execution of a {@link ActionType#BLANKET_APPROVE} action which orchestrates the
849 * document to the given set of node names for the given principal and document specified in the
850 * supplied parameters. This method functions the same as
851 * {@link #blanketApprove(DocumentActionParameters)} with the exception that the blanket approve
852 * process will be halted once all node names in the given set have been reached.
853 *
854 * <p>
855 * If null or an empty set is passed for {@code nodeNames} on this method, it's behavior will be
856 * equivalent to {@link #blanketApprove(DocumentActionParameters)}.
857 *
858 * @param parameters the parameters which indicate which principal is executing the action
859 * against which document, as well as additional operations to take against the document,
860 * such as updating document data
861 * @param nodeNames a set of node names to which to blanket approve the given document
862 *
863 * @return the result of executing the action, including a view on the updated state of the
864 * document and related actions
865 *
866 * @throws RiceIllegalArgumentException if {@code parameters} is null
867 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
868 * {@code parameters} exists
869 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
870 * in {@code parameters} exists
871 * @throws InvalidDocumentContentException if the document content on the
872 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
873 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
874 * action
875 */
876 @WebMethod(operationName = "blanketApproveToNodes")
877 @WebResult(name = "documentActionResult")
878 @XmlElement(name = "documentActionResult", required = true)
879 DocumentActionResult blanketApproveToNodes(
880 @WebParam(name = "parameters") DocumentActionParameters parameters,
881 @WebParam(name = "nodeName") Set<String> nodeNames)
882 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
883
884 /**
885 * Triggers the execution of a {@link ActionType#RETURN_TO_PREVIOUS} action for the given
886 * principal and document specified in the supplied parameters. Return a document to a previous
887 * node will allow for the document to be pushed back to an earlier node in the process based on
888 * the criteria present in the {@link ReturnPoint} that is passed to this method.
889 *
890 * <p>
891 * The document is synchronously returned to the suggested return point (assuming the desired
892 * return point can be identified for the given document), and then the document will be
893 * submitted to the engine for further processing (effectively, re-establishing the flow of the
894 * document from the target return point).
895 *
896 * <p>
897 * Return the document to the first node in the document is treated as a special case and,
898 * rather then transitioning the document back to the "initiated" status, will route a
899 * "complete" request to the initiator of the document. The effectively enacts a return to the
900 * document initiator in these cases.
901 *
902 * @param parameters the parameters which indicate which principal is executing the action
903 * against which document, as well as additional operations to take against the document,
904 * such as updating document data
905 *
906 * @return the result of executing the action, including a view on the updated state of the
907 * document and related actions
908 *
909 * @throws RiceIllegalArgumentException if {@code parameters} is null
910 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
911 * {@code parameters} exists
912 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
913 * in {@code parameters} exists
914 * @throws InvalidDocumentContentException if the document content on the
915 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
916 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
917 * action
918 */
919 @WebMethod(operationName = "returnToPreviousNode")
920 @WebResult(name = "documentActionResult")
921 @XmlElement(name = "documentActionResult", required = true)
922 DocumentActionResult returnToPreviousNode(
923 @WebParam(name = "parameters") DocumentActionParameters parameters,
924 @WebParam(name = "returnPoint") ReturnPoint returnPoint)
925 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
926
927
928 /**
929 * Triggers the execution of a {@link ActionType#MOVE} action for the given
930 * principal and document specified in the supplied parameters. Move a document to a
931 * node will allow for the document to be pushed to a different node in the process based on
932 * the criteria present in the {@link MovePoint} that is passed to this method.
933 *
934 * <p />
935 * The document is synchronously moved to the suggested move point (assuming the desired
936 * move point can be identified for the given document), and then the document will be
937 * submitted to the engine for further processing (effectively, re-establishing the flow of the
938 * document from the target return point).
939 *
940 *
941 * @param parameters the parameters which indicate which principal is executing the action
942 * against which document, as well as additional operations to take against the document,
943 * such as updating document data
944 * @param movePoint the point to move the document
945 *
946 * @return the result of executing the action, including a view on the updated state of the
947 * document and related actions
948 *
949 * @throws RiceIllegalArgumentException if {@code parameters} is null
950 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
951 * {@code parameters} exists
952 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
953 * in {@code parameters} exists
954 * @throws InvalidDocumentContentException if the document content on the
955 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
956 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
957 * action
958 */
959 @WebMethod(operationName = "move")
960 @WebResult(name = "documentActionResult")
961 @XmlElement(name = "documentActionResult", required = true)
962 DocumentActionResult move(
963 @WebParam(name = "parameters") DocumentActionParameters parameters,
964 @WebParam(name = "movePoint") MovePoint movePoint)
965 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
966
967 /**
968 * Triggers the execution of a {@link ActionType#TAKE_GROUP_AUTHORITY} action for the given
969 * principal and document specified in the supplied parameters. Takes authority of a group by a
970 * member of that group.
971 *
972 * @param parameters the parameters which indicate which principal is executing the action
973 * against which document, as well as additional operations to take against the document,
974 * such as updating document data
975 * @param groupId the group id to take authority of
976 *
977 * @return the result of executing the action, including a view on the updated state of the
978 * document and related actions
979 *
980 * @throws RiceIllegalArgumentException if {@code parameters} is null
981 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
982 * {@code parameters} exists
983 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
984 * in {@code parameters} exists
985 * @throws InvalidDocumentContentException if the document content on the
986 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
987 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
988 * action
989 */
990 @WebMethod(operationName = "takeGroupAuthority")
991 @WebResult(name = "documentActionResult")
992 @XmlElement(name = "documentActionResult", required = true)
993 DocumentActionResult takeGroupAuthority(
994 @WebParam(name = "parameters") DocumentActionParameters parameters,
995 @WebParam(name = "groupId") String groupId)
996 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
997
998 /**
999 * Triggers the execution of a {@link ActionType#RELEASE_GROUP_AUTHORITY} action for the given
1000 * principal and document specified in the supplied parameters. Releases authority of a group by a
1001 * member of that group.
1002 *
1003 * @param parameters the parameters which indicate which principal is executing the action
1004 * against which document, as well as additional operations to take against the document,
1005 * such as updating document data
1006 * @param groupId the group id to take authority of
1007 *
1008 * @return the result of executing the action, including a view on the updated state of the
1009 * document and related actions
1010 *
1011 * @throws RiceIllegalArgumentException if {@code parameters} is null
1012 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1013 * {@code parameters} exists
1014 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1015 * in {@code parameters} exists
1016 * @throws InvalidDocumentContentException if the document content on the
1017 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1018 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1019 * action
1020 */
1021 @WebMethod(operationName = "releaseGroupAuthority")
1022 @WebResult(name = "documentActionResult")
1023 @XmlElement(name = "documentActionResult", required = true)
1024 DocumentActionResult releaseGroupAuthority(
1025 @WebParam(name = "parameters") DocumentActionParameters parameters,
1026 @WebParam(name = "groupId") String groupId)
1027 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1028
1029 /**
1030 * Triggers the execution of a {@link ActionType#SAVE} action for the given
1031 * principal and document specified in the supplied parameters. Saves a document to a
1032 * at the current point.
1033 *
1034 * @param parameters the parameters which indicate which principal is executing the action
1035 * against which document, as well as additional operations to take against the document,
1036 * such as updating document data
1037 *
1038 * @return the result of executing the action, including a view on the updated state of the
1039 * document and related actions
1040 *
1041 * @throws RiceIllegalArgumentException if {@code parameters} is null
1042 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1043 * {@code parameters} exists
1044 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1045 * in {@code parameters} exists
1046 * @throws InvalidDocumentContentException if the document content on the
1047 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1048 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1049 * action
1050 */
1051 @WebMethod(operationName = "save")
1052 @WebResult(name = "documentActionResult")
1053 @XmlElement(name = "documentActionResult", required = true)
1054 DocumentActionResult save(@WebParam(name = "parameters") DocumentActionParameters parameters)
1055 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1056
1057 /**
1058 * Triggers the execution of a {@link ActionType#SAVE} action for the given
1059 * principal and document specified in the supplied parameters. Saves the current document data for
1060 * the document. Note that passing an annotation to this will have no effect because it is not
1061 * recorded in the route log
1062 *
1063 * @param parameters the parameters which indicate which principal is executing the action
1064 * against which document, as well as additional operations to take against the document,
1065 * such as updating document data
1066 *
1067 * @return the result of executing the action, including a view on the updated state of the
1068 * document and related actions
1069 *
1070 * @throws RiceIllegalArgumentException if {@code parameters} is null
1071 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1072 * {@code parameters} exists
1073 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1074 * in {@code parameters} exists
1075 * @throws InvalidDocumentContentException if the document content on the
1076 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1077 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1078 * action
1079 */
1080 @WebMethod(operationName = "saveDocumentData")
1081 @WebResult(name = "documentActionResult")
1082 @XmlElement(name = "documentActionResult", required = true)
1083 DocumentActionResult saveDocumentData(@WebParam(name = "parameters") DocumentActionParameters parameters)
1084 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1085
1086 /**
1087 * Deletes the document.
1088 *
1089 * @param documentId the unique id of the document to delete
1090 * @param principalId
1091 *
1092 * @return the document that was removed from the system
1093 *
1094 * @throws RiceIllegalArgumentException if {@code documentId} is null
1095 * @throws RiceIllegalArgumentException if {@code principalId} is null
1096 * @throws RiceIllegalArgumentException if no document with the {@code documentId} exists
1097 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1098 * action
1099 */
1100 @WebMethod(operationName = "delete")
1101 @WebResult(name = "document")
1102 @XmlElement(name = "document", required = true)
1103 Document delete(
1104 @WebParam(name = "documentId") String documentId,
1105 @WebParam(name = "principalId") String principalId)
1106 throws RiceIllegalArgumentException, InvalidActionTakenException;
1107
1108 /**
1109 * Records the non-routed document action. - Checks to make sure the document status
1110 * allows the action. Records the action.
1111 *
1112 * @param documentId the unique id of the document to delete
1113 * @param principalId
1114 *
1115 * @return the document that was removed from the system
1116 *
1117 * @throws RiceIllegalArgumentException if {@code documentId} is null
1118 * @throws RiceIllegalArgumentException if {@code principalId} is null
1119 * @throws RiceIllegalArgumentException if {@code annotation} is null
1120 * @throws RiceIllegalArgumentException if no document with the {@code documentId} exists
1121 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1122 * action
1123 */
1124 @WebMethod(operationName = "logAnnotation")
1125 void logAnnotation(
1126 @WebParam(name = "documentId") String documentId,
1127 @WebParam(name = "principalId") String principalId,
1128 @WebParam(name = "annotation") String annotation)
1129 throws RiceIllegalArgumentException, InvalidActionTakenException;
1130
1131 // TODO finish javadoc
1132 /**
1133 *
1134 *
1135 * @param documentId the unique id of the document to delete
1136 *
1137 * @throws RiceIllegalArgumentException if {@code documentId} is null
1138 */
1139 @WebMethod(operationName = "initiateIndexing")
1140 void initiateIndexing(@WebParam(name = "documentId") String documentId)
1141 throws RiceIllegalArgumentException;
1142
1143
1144 /**
1145 * Triggers the execution of a {@link ActionType#SU_BLANKET_APPROVE} action for the given
1146 * principal and document specified in the supplied parameters. Does a blanket approve for a super user
1147 * and runs post-processing depending on {@code executePostProcessor}
1148 *
1149 * @param parameters the parameters which indicate which principal is executing the action
1150 * against which document, as well as additional operations to take against the document,
1151 * such as updating document data
1152 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1153 *
1154 * @return the result of executing the action, including a view on the updated state of the
1155 * document and related actions
1156 *
1157 * @throws RiceIllegalArgumentException if {@code parameters} is null
1158 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1159 * {@code parameters} exists
1160 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1161 * in {@code parameters} exists
1162 * @throws InvalidDocumentContentException if the document content on the
1163 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1164 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1165 * action
1166 */
1167 @WebMethod(operationName = "superUserBlanketApprove")
1168 @WebResult(name = "documentActionResult")
1169 @XmlElement(name = "documentActionResult", required = true)
1170 DocumentActionResult superUserBlanketApprove(
1171 @WebParam(name = "parameters") DocumentActionParameters parameters,
1172 @WebParam(name = "executePostProcessor") boolean executePostProcessor)
1173 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1174
1175 /**
1176 * Triggers the execution of a {@link ActionType#SU_APPROVE} action for the given
1177 * principal and document specified in the supplied parameters. Does an approve for a super user
1178 * on a node and runs post-processing depending on {@code executePostProcessor}
1179 *
1180 * @param parameters the parameters which indicate which principal is executing the action
1181 * against which document, as well as additional operations to take against the document,
1182 * such as updating document data
1183 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1184 *
1185 * @return the result of executing the action, including a view on the updated state of the
1186 * document and related actions
1187 *
1188 * @throws RiceIllegalArgumentException if {@code parameters} is null
1189 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1190 * {@code parameters} exists
1191 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1192 * in {@code parameters} exists
1193 * @throws InvalidDocumentContentException if the document content on the
1194 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1195 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1196 * action
1197 */
1198 @WebMethod(operationName = "superUserNodeApprove")
1199 @WebResult(name = "documentActionResult")
1200 @XmlElement(name = "documentActionResult", required = true)
1201 DocumentActionResult superUserNodeApprove(
1202 @WebParam(name = "parameters") DocumentActionParameters parameters,
1203 @WebParam(name = "executePostProcessor") boolean executePostProcessor,
1204 @WebParam(name = "nodeName") String nodeName)
1205 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1206
1207 /**
1208 * Triggers the execution of a {@link ActionType#SU_APPROVE} action for the given
1209 * actionRequestId and principal and document specified in the supplied parameters. Does an approve for a super user
1210 * on a node and runs post-processing depending on {@code executePostProcessor}
1211 *
1212 * @param parameters the parameters which indicate which principal is executing the action
1213 * against which document, as well as additional operations to take against the document,
1214 * such as updating document data
1215 * @param actionRequestId unique Id of an action request to take action on
1216 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1217 *
1218 * @return the result of executing the action, including a view on the updated state of the
1219 * document and related actions
1220 *
1221 * @throws RiceIllegalArgumentException if {@code parameters} is null
1222 * @throws RiceIllegalArgumentException if (@code actionRequestId}
1223 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1224 * {@code parameters} exists
1225 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1226 * in {@code parameters} exists
1227 * @throws InvalidDocumentContentException if the document content on the
1228 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1229 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1230 * action
1231 */
1232 @WebMethod(operationName = "superUserTakeRequestedAction")
1233 @WebResult(name = "documentActionResult")
1234 @XmlElement(name = "documentActionResult", required = true)
1235 DocumentActionResult superUserTakeRequestedAction(
1236 @WebParam(name = "parameters") DocumentActionParameters parameters,
1237 @WebParam(name = "executePostProcessor") boolean executePostProcessor,
1238 @WebParam(name = "actionRequestId") String actionRequestId)
1239 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1240
1241 /**
1242 * Triggers the execution of a {@link ActionType#SU_DISAPPROVE} action for the given
1243 * principal and document specified in the supplied parameters. Does a disapprove for a super user
1244 * on a node and runs post-processing depending on {@code executePostProcessor}
1245 *
1246 * @param parameters the parameters which indicate which principal is executing the action
1247 * against which document, as well as additional operations to take against the document,
1248 * such as updating document data
1249 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1250 *
1251 * @return the result of executing the action, including a view on the updated state of the
1252 * document and related actions
1253 *
1254 * @throws RiceIllegalArgumentException if {@code parameters} is null
1255 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1256 * {@code parameters} exists
1257 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1258 * in {@code parameters} exists
1259 * @throws InvalidDocumentContentException if the document content on the
1260 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1261 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1262 * action
1263 */
1264 @WebMethod(operationName = "superUserDisapprove")
1265 @WebResult(name = "documentActionResult")
1266 @XmlElement(name = "documentActionResult", required = true)
1267 DocumentActionResult superUserDisapprove(
1268 @WebParam(name = "parameters") DocumentActionParameters parameters,
1269 @WebParam(name = "executePostProcessor") boolean executePostProcessor)
1270 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1271
1272 /**
1273 * Triggers the execution of a {@link ActionType#SU_CANCEL} action for the given
1274 * principal and document specified in the supplied parameters. Does an cancel for a super user
1275 * on a node and runs post-processing depending on {@code executePostProcessor}
1276 *
1277 * @param parameters the parameters which indicate which principal is executing the action
1278 * against which document, as well as additional operations to take against the document,
1279 * such as updating document data
1280 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1281 *
1282 * @return the result of executing the action, including a view on the updated state of the
1283 * document and related actions
1284 *
1285 * @throws RiceIllegalArgumentException if {@code parameters} is null
1286 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1287 * {@code parameters} exists
1288 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1289 * in {@code parameters} exists
1290 * @throws InvalidDocumentContentException if the document content on the
1291 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1292 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1293 * action
1294 */
1295 @WebMethod(operationName = "superUserCancel")
1296 @WebResult(name = "documentActionResult")
1297 @XmlElement(name = "documentActionResult", required = true)
1298 DocumentActionResult superUserCancel(
1299 @WebParam(name = "parameters") DocumentActionParameters parameters,
1300 @WebParam(name = "executePostProcessor") boolean executePostProcessor)
1301 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1302
1303 /**
1304 * Triggers the execution of a {@link ActionType#SU_RETURN_TO_PREVIOUS} action for the given
1305 * principal and document specified in the supplied parameters. Returns the document to the
1306 * previous node for a super user on a node and runs post-processing depending on {@code executePostProcessor}
1307 *
1308 * @param parameters the parameters which indicate which principal is executing the action
1309 * against which document, as well as additional operations to take against the document,
1310 * such as updating document data
1311 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1312 * @param returnPoint point to return to
1313 *
1314 * @return the result of executing the action, including a view on the updated state of the
1315 * document and related actions
1316 *
1317 * @throws RiceIllegalArgumentException if {@code parameters} is null
1318 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1319 * {@code parameters} exists
1320 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1321 * in {@code parameters} exists
1322 * @throws InvalidDocumentContentException if the document content on the
1323 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1324 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1325 * action
1326 */
1327 @WebMethod(operationName = "superUserReturnToPreviousNode")
1328 @WebResult(name = "documentActionResult")
1329 @XmlElement(name = "documentActionResult", required = true)
1330 DocumentActionResult superUserReturnToPreviousNode(
1331 @WebParam(name = "parameters") DocumentActionParameters parameters,
1332 @WebParam(name = "executePostProcessor") boolean executePostProcessor,
1333 @WebParam(name = "returnPoint") ReturnPoint returnPoint)
1334 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1335
1336 /**
1337 * Places a document in exception routing or the given principal and document specified in the supplied parameters.
1338 *
1339 * @param parameters the parameters which indicate which principal is executing the action
1340 * against which document, as well as additional operations to take against the document,
1341 * such as updating document data
1342 *
1343 * @return the result of executing the action, including a view on the updated state of the
1344 * document and related actions
1345 *
1346 * @throws RiceIllegalArgumentException if {@code parameters} is null
1347 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1348 * {@code parameters} exists
1349 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1350 * in {@code parameters} exists
1351 * @throws InvalidDocumentContentException if the document content on the
1352 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1353 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1354 * action
1355 */
1356 @WebMethod(operationName = "placeInExceptionRouting")
1357 @WebResult(name = "documentActionResult")
1358 @XmlElement(name = "documentActionResult", required = true)
1359 DocumentActionResult placeInExceptionRouting(@WebParam(name = "parameters") DocumentActionParameters parameters)
1360 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1361
1362 /**
1363 * Validates a workflow attribute definition and returns a list of validation errors
1364 *
1365 * @param definition WorkflowAttributeDefinition to validate
1366 *
1367 * @return a list of RemotableAttributeErrors caused by validation of the passed in {@code definition}
1368 *
1369 * @throws RiceIllegalArgumentException if {@code parameters} is null
1370 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1371 * {@code parameters} exists
1372 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1373 * in {@code parameters} exists
1374 * @throws InvalidDocumentContentException if the document content on the
1375 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1376 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1377 * action
1378 */
1379 @WebMethod(operationName = "validateWorkflowAttributeDefinition")
1380 @WebResult(name = "validationErrors")
1381 @XmlElementWrapper(name = "validationErrors", required = true)
1382 @XmlElement(name = "validationError", required = true)
1383 List<RemotableAttributeError> validateWorkflowAttributeDefinition(
1384 @WebParam(name = "definition") WorkflowAttributeDefinition definition)
1385 throws RiceIllegalArgumentException;
1386
1387 // TODO add, annotate, and javadoc the following methods to this service
1388 /**
1389 * Determines if a passed in user exists in a document's route log or future route depending on the passed in
1390 * {@code lookFuture} value
1391 *
1392 * @param documentId unique Id of document
1393 * @param principalId unique Id of Principal to look for in document's route log
1394 * @param lookFuture boolean value determines whether or not to look at the future route log
1395 *
1396 * @return boolean value representing if a principal exists in a Document's route log
1397 *
1398 * @throws RiceIllegalArgumentException if {@code documentId} is null
1399 * @throws RiceIllegalArgumentException if {@code principalId} is null
1400 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1401 * {@code parameters} exists
1402 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1403 * in {@code parameters} exists
1404 */
1405 @WebMethod(operationName = "isUserInRouteLog")
1406 @WebResult(name = "userInRouteLog")
1407 boolean isUserInRouteLog(
1408 @WebParam(name = "documentId") String documentId,
1409 @WebParam(name = "principalId") String principalId,
1410 @WebParam(name = "lookFuture") boolean lookFuture)
1411 throws RiceIllegalArgumentException;
1412
1413 /**
1414 * Determines if a passed in user exists in a document's route log or future route depending on the passed in
1415 * {@code lookFuture} value and {@code flattenNodes}
1416 *
1417 * @param documentId unique Id of document
1418 * @param principalId unique Id of Principal to look for in document's route log
1419 * @param lookFuture boolean value determines whether or not to look at the future route log
1420 *
1421 * @return boolean value representing if a principal exists in a Document's route log
1422 *
1423 * @throws RiceIllegalArgumentException if {@code documentId} is null
1424 * @throws RiceIllegalArgumentException if {@code principalId} is null
1425 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1426 * {@code parameters} exists
1427 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1428 * in {@code parameters} exists
1429 */
1430 @WebMethod(operationName = "isUserInRouteLogWithOptionalFlattening")
1431 @WebResult(name = "userInRouteLogWithOptionalFlattening")
1432 boolean isUserInRouteLogWithOptionalFlattening(
1433 @WebParam(name = "documentId") String documentId,
1434 @WebParam(name = "principalId") String principalId,
1435 @WebParam(name = "lookFuture") boolean lookFuture,
1436 @WebParam(name = "flattenNodes") boolean flattenNodes)
1437 throws RiceIllegalArgumentException;
1438
1439 /**
1440 * Re-resolves the given role for all documents for the given document type (including children).
1441 *
1442 * @param documentTypeName documentTypeName of DocuemntType for role
1443 * @param roleName name of Role to reresolve
1444 * @param qualifiedRoleNameLabel qualified role name label
1445 *
1446 * @throws RiceIllegalArgumentException if {@code documentTypeName} is null
1447 * @throws RiceIllegalArgumentException if {@code roleName} is null
1448 * @throws RiceIllegalArgumentException if {@code qualifiedRoleNameLable} is null
1449 */
1450 @WebMethod(operationName = "reResolveRoleByDocTypeName")
1451 void reResolveRoleByDocTypeName(
1452 @WebParam(name = "documentTypeName") String documentTypeName,
1453 @WebParam(name = "roleName") String roleName,
1454 @WebParam(name = "qualifiedRoleNameLabel") String qualifiedRoleNameLabel)
1455 throws RiceIllegalArgumentException;
1456
1457 /**
1458 * Re-resolves the given role for all documents for the given document id (including children).
1459 *
1460 * @param documentId documentId of Docuemnt for role
1461 * @param roleName name of Role to reresolve
1462 * @param qualifiedRoleNameLabel qualified role name label
1463 *
1464 * @throws RiceIllegalArgumentException if {@code documentTypeName} is null
1465 * @throws RiceIllegalArgumentException if {@code roleName} is null
1466 * @throws RiceIllegalArgumentException if {@code qualifiedRoleNameLable} is null
1467 */
1468 @WebMethod(operationName = "reResolveRoleByDocumentId")
1469 void reResolveRoleByDocumentId(
1470 @WebParam(name = "documentId") String documentId,
1471 @WebParam(name = "roleName") String roleName,
1472 @WebParam(name = "qualifiedRoleNameLabel") String qualifiedRoleNameLabel)
1473 throws RiceIllegalArgumentException;
1474
1475 /**
1476 * Executes a simulation of a document to get all previous and future route information
1477 *
1478 * @param reportCriteria criteria for the simulation to follow
1479 *
1480 * @return DocumentDetail object representing the results of the simulation
1481 *
1482 * @throws RiceIllegalArgumentException if {@code reportCriteria} is null
1483 */
1484 @WebMethod(operationName = "executeSimulation")
1485 @WebResult(name = "documentDetail")
1486 DocumentDetail executeSimulation(
1487 @WebParam(name = "reportCriteria") RoutingReportCriteria reportCriteria)
1488 throws RiceIllegalArgumentException;
1489
1490 /**
1491 * Determines if a passed in user is the final approver for a document
1492 *
1493 * @param documentId unique Id of the document
1494 * @param principalId unique Id of Principal to look for in document's route log
1495 *
1496 * @return boolean value representing if a principal is the final approver for a document
1497 *
1498 * @throws RiceIllegalArgumentException if {@code documentId} is null
1499 * @throws RiceIllegalArgumentException if {@code principalId} is null
1500 */
1501 @WebMethod(operationName = "isFinalApprover")
1502 @WebResult(name = "finalApprover")
1503 boolean isFinalApprover(
1504 @WebParam(name = "documentId") String documentId,
1505 @WebParam(name = "principalId") String principalId)
1506 throws RiceIllegalArgumentException;
1507
1508 /**
1509 * Determines if a passed in user is the last approver at a specified route node
1510 *
1511 * @param documentId unique Id of the document
1512 * @param principalId unique Id of Principal to look for in document's route log
1513 * @param nodeName name of route node to determine last approver for
1514 *
1515 * @return boolean value representing if a principal is the last approver at the specified route node
1516 *
1517 * @throws RiceIllegalArgumentException if {@code documentId} is null
1518 * @throws RiceIllegalArgumentException if {@code principalId} is null
1519 * @throws RiceIllegalArgumentException if {@code nodeName} is null
1520 */
1521 @WebMethod(operationName = "isLastApproverAtNode")
1522 @WebResult(name = "lastApproverAtNode")
1523 boolean isLastApproverAtNode(
1524 @WebParam(name = "documentId") String documentId,
1525 @WebParam(name = "principalId") String principalId,
1526 @WebParam(name = "nodeName") String nodeName)
1527 throws RiceIllegalArgumentException;
1528
1529 /**
1530 * Determines if a route node has an 'approve action' request
1531 *
1532 * @param docType document type of document
1533 * @param docContent string representing content of document
1534 * @param nodeName name of route node to determine if approve action request exists
1535 *
1536 * @return boolean value representing if a route node has an 'approve action' request
1537 *
1538 * @throws RiceIllegalArgumentException if {@code docType} is null
1539 * @throws RiceIllegalArgumentException if {@code docContent} is null
1540 * @throws RiceIllegalArgumentException if {@code nodeName} is null
1541 */
1542 @WebMethod(operationName = "routeNodeHasApproverActionRequest")
1543 @WebResult(name = "routeNodeHasApproverActionRequest")
1544 boolean routeNodeHasApproverActionRequest(
1545 @WebParam(name = "docType") String docType,
1546 @WebParam(name = "docContent") String docContent,
1547 @WebParam(name = "nodeName") String nodeName)
1548 throws RiceIllegalArgumentException;
1549
1550 /**
1551 * Determines if a document has at least one action request
1552 *
1553 * @param reportCriteria criteria for routing report
1554 * @param actionRequestedCodes list of action request codes to see if they exist for the document
1555 * @param ignoreCurrentActionRequests boolean value to determine if current action requests should be ignored
1556 *
1557 * @return boolean value representing if a document will have at least one action request
1558 *
1559 * @throws RiceIllegalArgumentException if {@code docType} is null
1560 * @throws RiceIllegalArgumentException if {@code docContent} is null
1561 * @throws RiceIllegalArgumentException if {@code nodeName} is null
1562 */
1563 @WebMethod(operationName = "documentWillHaveAtLeastOneActionRequest")
1564 @WebResult(name = "documentWillHaveAtLeastOneActionRequest")
1565 boolean documentWillHaveAtLeastOneActionRequest(
1566 @WebParam(name = "reportCriteria") RoutingReportCriteria reportCriteria,
1567 @WebParam(name = "actionRequestedCodes") List<String> actionRequestedCodes,
1568 @WebParam(name = "ignoreCurrentActionRequests") boolean ignoreCurrentActionRequests)
1569 throws RiceIllegalArgumentException;
1570
1571 /**
1572 * Returns a list of principal Ids that exist in a route log
1573 *
1574 * @param documentId unique id of the document to get the route log for
1575 * @param lookFuture boolean value that determines if the method should look at future action requests
1576 *
1577 * @return list of principal ids that exist in a route log
1578 *
1579 * @throws RiceIllegalArgumentException if {@code documentId} is null
1580 */
1581 @WebMethod(operationName = "getPrincipalIdsInRouteLog")
1582 @WebResult(name = "principalIds")
1583 @XmlElementWrapper(name = "principalIds", required = true)
1584 @XmlElement(name = "principalId", required = true)
1585 List<String> getPrincipalIdsInRouteLog(
1586 @WebParam(name = "documentId") String documentId,
1587 @WebParam(name = "lookFuture") boolean lookFuture)
1588 throws RiceIllegalArgumentException;
1589
1590 }