1 /**
2 * Copyright 2005-2015 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(@WebParam(name = "documentTypeName") String documentTypeName,
186 @WebParam(name = "initiatorPrincipalId") String initiatorPrincipalId,
187 @WebParam(name = "documentUpdate") DocumentUpdate documentUpdate, @WebParam(
188 name = "documentContentUpdate") DocumentContentUpdate documentContentUpdate) throws RiceIllegalArgumentException, IllegalDocumentTypeException, InvalidActionTakenException;
189
190 /**
191 * Determines which actions against the document with the given id are valid for the principal
192 * with the given id.
193 *
194 * @param documentId the id of the document for which to determine valid actions
195 * @param principalId the id of the principal for which to determine valid actions against the
196 * given document
197 *
198 * @return a {@link ValidActions} object which contains the valid actions for the given
199 * principal against the given document
200 *
201 * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
202 * @throws RiceIllegalArgumentException if document with the given {@code documentId} does not
203 * exist
204 * @throws RiceIllegalArgumentException if {@code principalId} is null or blank
205 * @throws RiceIllegalArgumentException if principal with the given {@code principalId} does not
206 * exist
207 */
208 @WebMethod(operationName = "determineValidActions")
209 @WebResult(name = "validActions")
210 @XmlElement(name = "validActions", required = true)
211 ValidActions determineValidActions(
212 @WebParam(name = "documentId") String documentId,
213 @WebParam(name = "principalId") String principalId)
214 throws RiceIllegalArgumentException;
215
216 /**
217 * Determines whether the given action is valid for the document and principal id.
218 *
219 * @param actionTypeCode type code for the action to check
220 * @param documentId the id of the document to check action for
221 * @param principalId the id of the principal to check permission for
222 *
223 * @return boolean true if the action is valid, false if not
224 *
225 * @throws RiceIllegalArgumentException if {@code actionTypeCode} is null or blank
226 * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
227 * @throws RiceIllegalArgumentException if document with the given {@code documentId} does not
228 * exist
229 * @throws RiceIllegalArgumentException if {@code principalId} is null or blank
230 * @throws RiceIllegalArgumentException if principal with the given {@code principalId} does not
231 * exist
232 */
233 @WebMethod(operationName = "isValidAction")
234 @WebResult(name = "isValidAction")
235 boolean isValidAction(
236 @WebParam(name = "actionTypeCode") String actionTypeCode,
237 @WebParam(name = "documentId") String documentId,
238 @WebParam(name = "principalId") String principalId)
239 throws RiceIllegalArgumentException;
240
241 /**
242 * Determines which actions are requested against the document with the given id for the
243 * principal with the given id. These are generally derived based on action requests that are
244 * currently pending against the document.
245 *
246 * <p>
247 * This method is distinguished from {@link #determineValidActions(String, String)} in that fact
248 * that valid actions are the actions that the principal is permitted to take, while requested
249 * actions are those that the principal is specifically being asked to take. Note that the
250 * actions that are requested are used when assembling valid actions but are not necessarily the
251 * only authoritative source for determination of valid actions for the principal, as
252 * permissions and other configuration can also come into play.
253 *
254 * @param documentId the id of the document for which to determine requested actions
255 * @param principalId the id of the principal for which to determine requested actions against
256 * the given document
257 *
258 * @return a {@link RequestedActions} object which contains the actions that are being requested
259 * from the given principal against the given document
260 *
261 * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
262 * @throws RiceIllegalArgumentException if document with the given {@code documentId} does not
263 * exist
264 * @throws RiceIllegalArgumentException if {@code principalId} is null or blank
265 * @throws RiceIllegalArgumentException if principal with the given {@code principalId} does not
266 * exist
267 */
268 @WebMethod(operationName = "determineRequestedActions")
269 @WebResult(name = "requestedActions")
270 @XmlElement(name = "requestedActions", required = true)
271 RequestedActions determineRequestedActions(
272 @WebParam(name = "documentId") String documentId,
273 @WebParam(name = "principalId") String principalId)
274 throws RiceIllegalArgumentException;
275
276 /**
277 * Executes an {@link ActionType#ACKNOWLEDGE} action for the given principal and document
278 * specified in the supplied parameters. When a principal acknowledges a document, any of the
279 * principal's pending action requests at or below the acknowledge level (which includes fyi
280 * requests as well) will be satisfied by the principal's action. The principal's action should
281 * be recorded with the document as an {@link ActionTaken}.
282 *
283 * <p>
284 * Depending on document type policy, a pending action request at or below the acknowledge level
285 * may have to exist on the document in order for the principal to take this action. Otherwise
286 * an {@link InvalidActionTakenException} may be thrown. In order to determine if an acknowledge
287 * action is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
288 * checked.
289 *
290 * @param parameters the parameters which indicate which principal is executing the action
291 * against which document, as well as additional operations to take against the document,
292 * such as updating document data
293 *
294 * @return the result of executing the action, including a view on the updated state of the
295 * document and related actions
296 *
297 * @throws RiceIllegalArgumentException if {@code parameters} is null
298 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
299 * {@code parameters} exists
300 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
301 * in {@code parameters} exists
302 * @throws InvalidDocumentContentException if the document content on the
303 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
304 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
305 * action
306 */
307 @WebMethod(operationName = "acknowledge")
308 @WebResult(name = "documentActionResult")
309 @XmlElement(name = "documentActionResult", required = true)
310 DocumentActionResult acknowledge(@WebParam(name = "parameters") DocumentActionParameters parameters)
311 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
312
313 /**
314 * Executes an {@link ActionType#APPROVE} action for the given principal and document specified
315 * in the supplied parameters. When a principal approves a document, any of the principal's
316 * pending action requests at or below the approve level (which includes complete, acknowledge,
317 * and fyi requests as well) will be satisfied by the principal's action. The principal's action
318 * should be recorded with the document as an {@link ActionTaken}.
319 *
320 * <p>
321 * Depending on document type policy, a pending action request at or below the approve level may
322 * have to exist on the document in order for the principal to take this action. Otherwise an
323 * {@link InvalidActionTakenException} may be thrown. In order to determine if an approve action
324 * is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
325 * checked.
326 *
327 * @param parameters the parameters which indicate which principal is executing the action
328 * against which document, as well as additional operations to take against the document,
329 * such as updating document data
330 *
331 * @return the result of executing the action, including a view on the updated state of the
332 * document and related actions
333 *
334 * @throws RiceIllegalArgumentException if {@code parameters} is null
335 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
336 * {@code parameters} exists
337 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
338 * in {@code parameters} exists
339 * @throws InvalidDocumentContentException if the document content on the
340 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
341 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
342 * action
343 */
344 @WebMethod(operationName = "approve")
345 @WebResult(name = "documentActionResult")
346 @XmlElement(name = "documentActionResult", required = true)
347 DocumentActionResult approve(@WebParam(name = "parameters") DocumentActionParameters parameters)
348 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
349
350 /**
351 * Executes an {@link ActionType#ADHOC_REQUEST} action for the given principal and document
352 * specified in the supplied parameters to create an ad hoc action request to the target
353 * principal specified in the {@code AdHocToPrincipal}.
354 *
355 * <p>
356 * Operates as per {@link #adHocToGroup(DocumentActionParameters, AdHocToGroup)} with the
357 * exception that this method is used to send an adhoc request to principal instead of a group.
358 *
359 * <p>
360 * Besides this difference, the same rules that are in play for sending ad hoc requests to group
361 * apply for sending ad hoc requests to principals.
362 *
363 * @param parameters the parameters which indicate which principal is executing the action
364 * against which document, as well as additional operations to take against the document,
365 * such as updating document data
366 * @param adHocToPrincipal defines various pieces of information that informs what type of ad
367 * hoc request should be created
368 *
369 * @return the result of executing the action, including a view on the updated state of the
370 * document and related actions
371 *
372 * @throws RiceIllegalArgumentException if {@code parameters} is null
373 * @throws RiceIllegalArgumentException if {@code adHocToPrincipal} is null
374 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
375 * {@code parameters} exists
376 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
377 * in {@code parameters} exists
378 * @throws InvalidDocumentContentException if the document content on the
379 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
380 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
381 * action
382 * @throws InvalidActionTakenException if the target principal is not permitted to receive ad
383 * hoc requests on documents of this type
384 * @throws InvalidActionTakenException if the specified ad hoc request cannot be generated
385 * because the current state of the document would result in an illegal request being
386 * generated
387 *
388 * @see #adHocToGroup(DocumentActionParameters, AdHocToGroup)
389 */
390 @WebMethod(operationName = "adHocToPrincipal_v2_1_3")
391 @WebResult(name = "documentActionResult")
392 @XmlElement(name = "documentActionResult", required = true)
393 DocumentActionResult adHocToPrincipal(
394 @WebParam(name = "parameters") DocumentActionParameters parameters,
395 @WebParam(name = "adHocToPrincipal") AdHocToPrincipal adHocToPrincipal)
396 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
397
398
399 /**
400 * Executes an {@link ActionType#ADHOC_REQUEST} action for the given principal and document
401 * specified in the supplied parameters to create an ad hoc action request to the target
402 * principal specified in the {@code AdHocToPrincipal}.
403 *
404 * <p>
405 * Operates as per {@link #adHocToGroup(DocumentActionParameters, AdHocToGroup)} with the
406 * exception that this method is used to send an adhoc request to principal instead of a group.
407 *
408 * <p>
409 * Besides this difference, the same rules that are in play for sending ad hoc requests to group
410 * apply for sending ad hoc requests to principals.
411 *
412 * @param parameters the parameters which indicate which principal is executing the action
413 * against which document, as well as additional operations to take against the document,
414 * such as updating document data
415 * @param adHocToPrincipal defines various pieces of information that informs what type of ad
416 * hoc request should be created
417 *
418 * @return the result of executing the action, including a view on the updated state of the
419 * document and related actions
420 *
421 * @throws RiceIllegalArgumentException if {@code parameters} is null
422 * @throws RiceIllegalArgumentException if {@code adHocToPrincipal} is null
423 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
424 * {@code parameters} exists
425 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
426 * in {@code parameters} exists
427 * @throws InvalidDocumentContentException if the document content on the
428 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
429 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
430 * action
431 * @throws InvalidActionTakenException if the target principal is not permitted to receive ad
432 * hoc requests on documents of this type
433 * @throws InvalidActionTakenException if the specified ad hoc request cannot be generated
434 * because the current state of the document would result in an illegal request being
435 * generated
436 *
437 * @see #adHocToGroup(DocumentActionParameters, AdHocToGroup)
438 * @since 2.1.3
439 */
440 @Deprecated
441 @WebMethod(operationName = "adHocToPrincipal")
442 @WebResult(name = "documentActionResult")
443 @XmlElement(name = "documentActionResult", required = true)
444 DocumentActionResult adHocToPrincipal(
445 @WebParam(name = "parameters") DocumentActionParameters parameters,
446 @WebParam(name = "adHocToPrincipal") AdHocToPrincipal_v2_1_2 adHocToPrincipal)
447 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
448
449 /**
450 * Executes an {@link ActionType#ADHOC_REQUEST} action for the given group and document
451 * specified in the supplied parameters to create an ad hoc action request to the target group
452 * specified in the {@code AdHocToGroup}. The {@code AdHocToGroup} contains additional
453 * information on how the ad hoc action request should be created, including the type of request
454 * to generate, at which node it should generated, etc.
455 *
456 * <p>
457 * The policy for how ad hoc actions handle request generation and interact with the workflow
458 * engine is different depending on the state of the document when the request to generate the
459 * ad hoc is submitted. There are also different scenarios under which certain types of ad hoc
460 * actions are allowed to be executed (throwing {@link InvalidActionTakenException} in
461 * situations where the actions are not permitted). The rules are defined as follows:
462 *
463 * <ol>
464 * <li>If the status of the document is {@link DocumentStatus#INITIATED} then the action request
465 * will be generated with a status of {@link ActionRequestStatus#INITIALIZED} and no processing
466 * directives will be submitted to the workflow engine. When the document is routed, these ad
467 * hoc requests will get activated</li>
468 * <li>If the ad hoc request being created is an {@link ActionRequestType#COMPLETE} or
469 * {@link ActionRequestType#APPROVE} and the document is in a "terminal" state (either
470 * {@link DocumentStatus#CANCELED}, {@link DocumentStatus#DISAPPROVED},
471 * {@link DocumentStatus#PROCESSED}, {@link DocumentStatus#FINAL}) or is in
472 * {@link DocumentStatus#EXCEPTION} status, then an {@link InvalidActionTakenException} will be
473 * thrown. This is because submitting such an action with a document in that state would result
474 * in creation of an illegal action request.</li>
475 * <li>If the document is in a "terminal" state (see above for definition) then the request will
476 * be immediately (and synchronously) activated.</li>
477 * <li>Otherwise, after creating the ad hoc request it will be in the
478 * {@link ActionRequestStatus#INITIALIZED} status, and the document will be immediately
479 * forwarded to the workflow engine for processing at which point the ad hoc request will
480 * activated at the appropriate time.</li>
481 * </ol>
482 *
483 * <p>
484 * Unlink other actions, ad hoc actions don't result in the recording of an {@link ActionTaken}
485 * against the document. Instead, only the requested ad hoc {@link ActionRequest} is created.
486 *
487 * @param parameters the parameters which indicate which principal is executing the action
488 * against which document, as well as additional operations to take against the document,
489 * such as updating document data
490 * @param adHocToGroup defines various pieces of information that informs what type of ad hoc
491 * request should be created
492 *
493 * @return the result of executing the action, including a view on the updated state of the
494 * document and related actions
495 *
496 * @throws RiceIllegalArgumentException if {@code parameters} is null
497 * @throws RiceIllegalArgumentException if {@code adHocToGroup} is null
498 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
499 * {@code parameters} exists
500 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
501 * in {@code parameters} exists
502 * @throws InvalidDocumentContentException if the document content on the
503 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
504 * @throws InvalidActionTakenException if the supplied principals i is not allowed to execute
505 * this action
506 * @throws InvalidActionTakenException if any of the principals in the target group are not
507 * permitted to receive ad hoc requests on documents of this type
508 * @throws InvalidActionTakenException if the specified ad hoc request cannot be generated
509 * because the current state of the document would result in an illegal request being
510 * generated
511 */
512 @WebMethod(operationName = "adHocToGroup_v2_1_3")
513 @WebResult(name = "documentActionResult")
514 @XmlElement(name = "documentActionResult", required = true)
515 DocumentActionResult adHocToGroup(
516 @WebParam(name = "parameters") DocumentActionParameters parameters,
517 @WebParam(name = "adHocToGroup") AdHocToGroup adHocToGroup)
518 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
519
520 /**
521 * Executes an {@link ActionType#ADHOC_REQUEST} action for the given group and document
522 * specified in the supplied parameters to create an ad hoc action request to the target group
523 * specified in the {@code AdHocToGroup}. The {@code AdHocToGroup} contains additional
524 * information on how the ad hoc action request should be created, including the type of request
525 * to generate, at which node it should generated, etc.
526 *
527 * <p>
528 * The policy for how ad hoc actions handle request generation and interact with the workflow
529 * engine is different depending on the state of the document when the request to generate the
530 * ad hoc is submitted. There are also different scenarios under which certain types of ad hoc
531 * actions are allowed to be executed (throwing {@link InvalidActionTakenException} in
532 * situations where the actions are not permitted). The rules are defined as follows:
533 *
534 * <ol>
535 * <li>If the status of the document is {@link DocumentStatus#INITIATED} then the action request
536 * will be generated with a status of {@link ActionRequestStatus#INITIALIZED} and no processing
537 * directives will be submitted to the workflow engine. When the document is routed, these ad
538 * hoc requests will get activated</li>
539 * <li>If the ad hoc request being created is an {@link ActionRequestType#COMPLETE} or
540 * {@link ActionRequestType#APPROVE} and the document is in a "terminal" state (either
541 * {@link DocumentStatus#CANCELED}, {@link DocumentStatus#DISAPPROVED},
542 * {@link DocumentStatus#PROCESSED}, {@link DocumentStatus#FINAL}) or is in
543 * {@link DocumentStatus#EXCEPTION} status, then an {@link InvalidActionTakenException} will be
544 * thrown. This is because submitting such an action with a document in that state would result
545 * in creation of an illegal action request.</li>
546 * <li>If the document is in a "terminal" state (see above for definition) then the request will
547 * be immediately (and synchronously) activated.</li>
548 * <li>Otherwise, after creating the ad hoc request it will be in the
549 * {@link ActionRequestStatus#INITIALIZED} status, and the document will be immediately
550 * forwarded to the workflow engine for processing at which point the ad hoc request will
551 * activated at the appropriate time.</li>
552 * </ol>
553 *
554 * <p>
555 * Unlink other actions, ad hoc actions don't result in the recording of an {@link ActionTaken}
556 * against the document. Instead, only the requested ad hoc {@link ActionRequest} is created.
557 *
558 * @param parameters the parameters which indicate which principal is executing the action
559 * against which document, as well as additional operations to take against the document,
560 * such as updating document data
561 * @param adHocToGroup defines various pieces of information that informs what type of ad hoc
562 * request should be created
563 *
564 * @return the result of executing the action, including a view on the updated state of the
565 * document and related actions
566 *
567 * @throws RiceIllegalArgumentException if {@code parameters} is null
568 * @throws RiceIllegalArgumentException if {@code adHocToGroup} is null
569 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
570 * {@code parameters} exists
571 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
572 * in {@code parameters} exists
573 * @throws InvalidDocumentContentException if the document content on the
574 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
575 * @throws InvalidActionTakenException if the supplied principals i is not allowed to execute
576 * this action
577 * @throws InvalidActionTakenException if any of the principals in the target group are not
578 * permitted to receive ad hoc requests on documents of this type
579 * @throws InvalidActionTakenException if the specified ad hoc request cannot be generated
580 * because the current state of the document would result in an illegal request being
581 * generated
582 * @since 2.1.3
583 */
584 @Deprecated
585 @WebMethod(operationName = "adHocToGroup")
586 @WebResult(name = "documentActionResult")
587 @XmlElement(name = "documentActionResult", required = true)
588 DocumentActionResult adHocToGroup(@WebParam(name = "parameters") DocumentActionParameters parameters,
589 @WebParam(name = "adHocToGroup") AdHocToGroup_v2_1_2 adHocToGroup)
590 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
591
592 /**
593 * Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action for the given principal and
594 * document specified in the supplied parameters against the action request with the given id.
595 * The process of revoking an ad hoc request simply deactivates the request associating the
596 * generated {@link ActionTaken} of the revoke action with the deactivated request (this allows
597 * for it to be determined what caused the ad hoc request to be deactivated). As with other
598 * actions, this action taken is then recorded with the document.
599 *
600 * @param parameters the parameters which indicate which principal is executing the action
601 * against which document, as well as additional operations to take against the document,
602 * such as updating document data
603 * @param actionRequestId the id of the action request to revoke
604 *
605 * @return the result of executing the action, including a view on the updated state of the
606 * document and related actions
607 *
608 * @throws RiceIllegalArgumentException if {@code parameters} is null
609 * @throws RiceIllegalArgumentException if {@code actionRequestId} is null or blank
610 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
611 * {@code parameters} exists
612 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
613 * in {@code parameters} exists
614 * @throws InvalidDocumentContentException if the document content on the
615 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
616 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
617 * action
618 * @throws InvalidActionTakenException if a pending ad hoc request with the given
619 * {@code actionRequestId} does not exist on the specified document, this could mean
620 * that the action request id is invalid, or that the action request has already been
621 * deactivated and is no longer pending
622 */
623 @WebMethod(operationName = "revokeAdHocRequestById")
624 @WebResult(name = "documentActionResult")
625 @XmlElement(name = "documentActionResult", required = true)
626 DocumentActionResult revokeAdHocRequestById(
627 @WebParam(name = "parameters") DocumentActionParameters parameters,
628 @WebParam(name = "actionRequestId") String actionRequestId)
629 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
630
631 /**
632 * Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action which revokes all pending ad hoc
633 * action requests that match the supplied {@link AdHocRevoke} criteria for the given principal
634 * and document specified in the supplied parameters. The process of revoking an ad hoc requests
635 * simply deactivates all ad hoc requests that match the given {@code AdHocRevoke} criteria,
636 * associating the generated {@link ActionTaken} of the revoke action with the deactivated
637 * requests (this allows for it to be determined what caused the ad hoc request to be
638 * deactivated). As with other actions, this action taken is then recorded with the document.
639 *
640 * <p>
641 * It's possible that the given ad hoc revoke command will match no action requests on the
642 * document, in which case this method will complete successfully but no requests will be
643 * deactivated.
644 *
645 * @param parameters the parameters which indicate which principal is executing the action
646 * against which document, as well as additional operations to take against the document,
647 * such as updating document data
648 * @param revoke the criteria for matching ad hoc action requests on the specified document that
649 * should be revoked
650 *
651 * @return the result of executing the action, including a view on the updated state of the
652 * document and related actions
653 *
654 * @throws RiceIllegalArgumentException if {@code parameters} is null
655 * @throws RiceIllegalArgumentException if {@code revoke} is null
656 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
657 * {@code parameters} exists
658 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
659 * in {@code parameters} exists
660 * @throws InvalidDocumentContentException if the document content on the
661 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
662 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
663 * action
664 */
665 @WebMethod(operationName = "revokeAdHocRequests")
666 @WebResult(name = "documentActionResult")
667 @XmlElement(name = "documentActionResult", required = true)
668 DocumentActionResult revokeAdHocRequests(
669 @WebParam(name = "parameters") DocumentActionParameters parameters,
670 @WebParam(name = "revoke") AdHocRevoke revoke)
671 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
672
673 /**
674 * Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action which revokes all pending ad hoc
675 * action requests for the given principal and document specified in the supplied parameters.
676 * This process of revoking all ad hoc requests will simply deactivate all ad hoc requests on
677 * the specified document, associating the generated {@link ActionTaken} of the revoke action
678 * with the deactivated requests (this allows for it to be determined what caused the ad hoc
679 * request to be deactivated). As with other actions, this action taken is then recorded with
680 * the document.
681 *
682 * <p>
683 * It's possible that the specified document will have no pending adhoc requests, in which case
684 * this method will complete successfully but no requests will be deactivated.
685 *
686 * @param parameters the parameters which indicate which principal is executing the action
687 * against which document, as well as additional operations to take against the document,
688 * such as updating document data
689 *
690 * @return the result of executing the action, including a view on the updated state of the
691 * document and related actions
692 *
693 * @throws RiceIllegalArgumentException if {@code parameters} is null
694 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
695 * {@code parameters} exists
696 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
697 * in {@code parameters} exists
698 * @throws InvalidDocumentContentException if the document content on the
699 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
700 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
701 * action
702 */
703 @WebMethod(operationName = "revokeAllAdHocRequests")
704 @WebResult(name = "documentActionResult")
705 @XmlElement(name = "documentActionResult", required = true)
706 DocumentActionResult revokeAllAdHocRequests(@WebParam(name = "parameters") DocumentActionParameters parameters)
707 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
708
709 /**
710 * Executes a {@link ActionType#CANCEL} action for the given principal and document specified in
711 * the supplied parameters. When a principal cancels a document, all pending action requests on
712 * the document are deactivated and the the principal's action will be recorded on the document
713 * as an {@link ActionTaken}. Additionally, the document will be (synchronously) transitioned to
714 * the {@link DocumentStatus#CANCELED} status.
715 *
716 * <p>
717 * In order to cancel a document, the principal must have permission to cancel documents of the
718 * appropriate type, and one of the following must hold true:
719 *
720 * <ol>
721 * <li>The document must have a status of {@link DocumentStatus#INITIATED} <strong>or</strong></li>
722 * <li>The document must have a status of {@link DocumentStatus#SAVED} <strong>or</strong></li>
723 * <li>The principal must have a pending "complete" or "approve" request on the document.
724 *
725 * @param parameters the parameters which indicate which principal is executing the action
726 * against which document, as well as additional operations to take against the document,
727 * such as updating document data
728 *
729 * @return the result of executing the action, including a view on the updated state of the
730 * document and related actions
731 *
732 * @throws RiceIllegalArgumentException if {@code parameters} is null
733 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
734 * {@code parameters} exists
735 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
736 * in {@code parameters} exists
737 * @throws InvalidDocumentContentException if the document content on the
738 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
739 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
740 * action
741 */
742 @WebMethod(operationName = "cancel")
743 @WebResult(name = "documentActionResult")
744 @XmlElement(name = "documentActionResult", required = true)
745 DocumentActionResult cancel(@WebParam(name = "parameters") DocumentActionParameters parameters)
746 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
747
748 /**
749 * Executes a {@link ActionType#RECALL} action for the given principal and document specified in
750 * the supplied parameters. When a principal cancels a document, all pending action requests on
751 * the document are deactivated and the the principal's action will be recorded on the document
752 * as an {@link ActionTaken}. Additionally, the document will be (synchronously) transitioned to
753 * the {@link DocumentStatus#RECALLED} status.
754 *
755 * TODO: FILL IN DOCS FOR RECALL ACTION
756 * <p>
757 * In order to cancel a document, the principal must have permission to cancel documents of the
758 * appropriate type, and one of the following must hold true:
759 *
760 * <ol>
761 * <li>The document must have a status of {@link DocumentStatus#INITIATED} <strong>or</strong></li>
762 * <li>The document must have a status of {@link DocumentStatus#SAVED} <strong>or</strong></li>
763 * <li>The principal must have a pending "complete" or "approve" request on the document.
764 *
765 * @since 2.1
766 * @param parameters the parameters which indicate which principal is executing the action
767 * against which document, as well as additional operations to take against the document,
768 * such as updating document data
769 * @param cancel whether to recall & cancel or recall & return to action list
770 *
771 * @return the result of executing the action, including a view on the updated state of the
772 * document and related actions
773 *
774 * @throws RiceIllegalArgumentException if {@code parameters} is null
775 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
776 * {@code parameters} exists
777 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
778 * in {@code parameters} exists
779 * @throws InvalidDocumentContentException if the document content on the
780 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
781 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
782 * action
783 */
784 @WebMethod(operationName = "recall")
785 @WebResult(name = "documentActionResult")
786 @XmlElement(name = "documentActionResult", required = true)
787 DocumentActionResult recall(@WebParam(name = "parameters") DocumentActionParameters parameters,
788 @WebParam(name = "cancel") boolean cancel)
789 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
790
791 /**
792 * Executes an {@link ActionType#FYI} action for the given principal and document specified in
793 * the supplied parameters. When a principal clears fyis on a document, any of the principal's
794 * pending fyis will be satisfied by the principal's action. The principal's action should be
795 * recorded with the document as an {@link ActionTaken}.
796 *
797 * <p>
798 * Depending on document type policy, a pending fyi request may have to exist on the document in
799 * order for the principal to take this action. Otherwise an {@link InvalidActionTakenException}
800 * may be thrown. In order to determine if an fyi action is valid, the {@link ValidActions} or
801 * {@link RequestedActions} for the document can be checked.
802 *
803 * @param parameters the parameters which indicate which principal is executing the action
804 * against which document, as well as additional operations to take against the document,
805 * such as updating document data
806 *
807 * @return the result of executing the action, including a view on the updated state of the
808 * document and related actions
809 *
810 * @throws RiceIllegalArgumentException if {@code parameters} is null
811 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
812 * {@code parameters} exists
813 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
814 * in {@code parameters} exists
815 * @throws InvalidDocumentContentException if the document content on the
816 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
817 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
818 * action
819 */
820 @WebMethod(operationName = "clearFyi")
821 @WebResult(name = "documentActionResult")
822 @XmlElement(name = "documentActionResult", required = true)
823 DocumentActionResult clearFyi(@WebParam(name = "parameters") DocumentActionParameters parameters)
824 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
825
826 /**
827 * Executes an {@link ActionType#COMPLETE} action for the given principal and document specified
828 * in the supplied parameters. When a principal completes a document, any of the principal's
829 * pending action requests at or below the complete level (which includes approve, acknowledge,
830 * and fyi requests as well) will be satisfied by the principal's action. The principal's action
831 * should be recorded with the document as an {@link ActionTaken}.
832 *
833 * <p>
834 * Depending on document type policy, a pending action request at or below the complete level
835 * may have to exist on the document in order for the principal to take this action. Otherwise
836 * an {@link InvalidActionTakenException} may be thrown. In order to determine if an complete
837 * action is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
838 * checked.
839 *
840 * @param parameters the parameters which indicate which principal is executing the action
841 * against which document, as well as additional operations to take against the document,
842 * such as updating document data
843 *
844 * @return the result of executing the action, including a view on the updated state of the
845 * document and related actions
846 *
847 * @throws RiceIllegalArgumentException if {@code parameters} is null
848 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
849 * {@code parameters} exists
850 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
851 * in {@code parameters} exists
852 * @throws InvalidDocumentContentException if the document content on the
853 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
854 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
855 * action
856 */
857 @WebMethod(operationName = "complete")
858 @WebResult(name = "documentActionResult")
859 @XmlElement(name = "documentActionResult", required = true)
860 DocumentActionResult complete(@WebParam(name = "parameters") DocumentActionParameters parameters)
861 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
862
863 /**
864 * Executes a {@link ActionType#DISAPPROVE} action for the given principal and document
865 * specified in the supplied parameters. When a principal disapproves a document, all pending
866 * action requests on the document are deactivated and the the principal's action will be
867 * recorded on the document as an {@link ActionTaken}. Additionally, the document will be
868 * (synchronously) transitioned to the {@link DocumentStatus#DISAPPROVED} status.
869 *
870 * <p>
871 * Depending on document type policy and configuration, notifications may be sent to past
872 * approvers of the document. By default, an "acknowledge" request will be sent to each
873 * principal who took an "approve" or "complete" action on the document previously.
874 *
875 * <p>
876 * In order to disapprove a document, the principal must have a pending approve or complete
877 * request on the document.
878 *
879 * @param parameters the parameters which indicate which principal is executing the action
880 * against which document, as well as additional operations to take against the document,
881 * such as updating document data
882 *
883 * @return the result of executing the action, including a view on the updated state of the
884 * document and related actions
885 *
886 * @throws RiceIllegalArgumentException if {@code parameters} is null
887 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
888 * {@code parameters} exists
889 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
890 * in {@code parameters} exists
891 * @throws InvalidDocumentContentException if the document content on the
892 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
893 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
894 * action
895 */
896 @WebMethod(operationName = "disapprove")
897 @WebResult(name = "documentActionResult")
898 @XmlElement(name = "documentActionResult", required = true)
899 DocumentActionResult disapprove(@WebParam(name = "parameters") DocumentActionParameters parameters)
900 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
901
902 /**
903 * Submits a document that is in either the "initiated" or "saved" state to the workflow engine
904 * for processing. The route action triggers the beginning of the routing process and
905 * (synchronously) switches the status of the document to {@link DocumentStatus#ENROUTE}. It
906 * then queues up a request to the workflow engine to process the document.
907 *
908 * <p>
909 * When the route action is executed, an {@link ActionType#COMPLETE} action is recorded on the
910 * document for the principal who executed the route action. At this point in time, any action
911 * requests that are currently on the document in an "initialized" state will be activated.
912 * Requests of this nature can commonly exist if ad hoc requests have been attached to the
913 * document prior to execution of the route action.
914 *
915 * <p>
916 * By default, the principal who initiated the document is the same principal who must submit
917 * the route command. However, a document type policy can be set which will relax this
918 * constraint.
919 *
920 * <p>
921 * The route action should ideally only ever be executed once for a given document. Depending on
922 * document type policy, attempting to execute a "route" action against a document which is
923 * already enroute or in a terminal state may result in an {@link InvalidActionTakenException}
924 * being thrown.
925 *
926 * @param parameters the parameters which indicate which principal is executing the action
927 * against which document, as well as additional operations to take against the document,
928 * such as updating document data
929 *
930 * @return the result of executing the action, including a view on the updated state of the
931 * document and related actions
932 *
933 * @throws RiceIllegalArgumentException if {@code parameters} is null
934 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
935 * {@code parameters} exists
936 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
937 * in {@code parameters} exists
938 * @throws InvalidDocumentContentException if the document content on the
939 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
940 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
941 * action
942 */
943 @WebMethod(operationName = "route")
944 @WebResult(name = "documentActionResult")
945 @XmlElement(name = "documentActionResult", required = true)
946 DocumentActionResult route(@WebParam(name = "parameters") DocumentActionParameters parameters)
947 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
948
949 /**
950 * Triggers the execution of a full {@link ActionType#BLANKET_APPROVE} action for the given
951 * principal and document specified in the supplied parameters. Blanket approval will
952 * orchestrate a document from it's current node all the way to the end of the document's
953 * workflow process. During this process, it will automatically act on all "approve" and
954 * "complete" requests, effectively bypassing them. When it does this, it will notify the
955 * original recipients of these requests by routing acknowledge requests to them.
956 *
957 * <p>
958 * Blanket approve processing is handled by a special mode of the workflow engine which runs the
959 * document through it's full processing lifecycle, ensuring that it makes it's way to the end
960 * of it's route path (by bypassing any steps that would cause the process to halt, such as
961 * approval requests). Because of this nature, blanket approve processing behavior is governed
962 * by the same configuration as the rest of the workflow engine. So depending on whether the
963 * engine is configured or synchronous or asynchronous operation, the blanket approve processing
964 * will behave in the same manner.
965 *
966 * <p>
967 * In order to execute a blanket approve operation, the principal must have permissions to do
968 * so.
969 *
970 * @param parameters the parameters which indicate which principal is executing the action
971 * against which document, as well as additional operations to take against the document,
972 * such as updating document data
973 *
974 * @return the result of executing the action, including a view on the updated state of the
975 * document and related actions
976 *
977 * @throws RiceIllegalArgumentException if {@code parameters} is null
978 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
979 * {@code parameters} exists
980 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
981 * in {@code parameters} exists
982 * @throws InvalidDocumentContentException if the document content on the
983 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
984 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
985 * action
986 */
987 @WebMethod(operationName = "blanketApprove")
988 @WebResult(name = "documentActionResult")
989 @XmlElement(name = "documentActionResult", required = true)
990 DocumentActionResult blanketApprove(@WebParam(name = "parameters") DocumentActionParameters parameters)
991 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
992
993 /**
994 * Triggers the execution of a {@link ActionType#BLANKET_APPROVE} action which orchestrates the
995 * document to the given set of node names for the given principal and document specified in the
996 * supplied parameters. This method functions the same as
997 * {@link #blanketApprove(DocumentActionParameters)} with the exception that the blanket approve
998 * process will be halted once all node names in the given set have been reached.
999 *
1000 * <p>
1001 * If null or an empty set is passed for {@code nodeNames} on this method, it's behavior will be
1002 * equivalent to {@link #blanketApprove(DocumentActionParameters)}.
1003 *
1004 * @param parameters the parameters which indicate which principal is executing the action
1005 * against which document, as well as additional operations to take against the document,
1006 * such as updating document data
1007 * @param nodeNames a set of node names to which to blanket approve the given document
1008 *
1009 * @return the result of executing the action, including a view on the updated state of the
1010 * document and related actions
1011 *
1012 * @throws RiceIllegalArgumentException if {@code parameters} is null
1013 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1014 * {@code parameters} exists
1015 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1016 * in {@code parameters} exists
1017 * @throws InvalidDocumentContentException if the document content on the
1018 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1019 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1020 * action
1021 */
1022 @WebMethod(operationName = "blanketApproveToNodes")
1023 @WebResult(name = "documentActionResult")
1024 @XmlElement(name = "documentActionResult", required = true)
1025 DocumentActionResult blanketApproveToNodes(
1026 @WebParam(name = "parameters") DocumentActionParameters parameters,
1027 @WebParam(name = "nodeName") Set<String> nodeNames)
1028 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1029
1030 /**
1031 * Triggers the execution of a {@link ActionType#RETURN_TO_PREVIOUS} action for the given
1032 * principal and document specified in the supplied parameters. Return a document to a previous
1033 * node will allow for the document to be pushed back to an earlier node in the process based on
1034 * the criteria present in the {@link ReturnPoint} that is passed to this method.
1035 *
1036 * <p>
1037 * The document is synchronously returned to the suggested return point (assuming the desired
1038 * return point can be identified for the given document), and then the document will be
1039 * submitted to the engine for further processing (effectively, re-establishing the flow of the
1040 * document from the target return point).
1041 *
1042 * <p>
1043 * Return the document to the first node in the document is treated as a special case and,
1044 * rather then transitioning the document back to the "initiated" status, will route a
1045 * "complete" request to the initiator of the document. The effectively enacts a return to the
1046 * document initiator in these cases.
1047 *
1048 * @param parameters the parameters which indicate which principal is executing the action
1049 * against which document, as well as additional operations to take against the document,
1050 * such as updating document data
1051 *
1052 * @return the result of executing the action, including a view on the updated state of the
1053 * document and related actions
1054 *
1055 * @throws RiceIllegalArgumentException if {@code parameters} is null
1056 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1057 * {@code parameters} exists
1058 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1059 * in {@code parameters} exists
1060 * @throws InvalidDocumentContentException if the document content on the
1061 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1062 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1063 * action
1064 */
1065 @WebMethod(operationName = "returnToPreviousNode")
1066 @WebResult(name = "documentActionResult")
1067 @XmlElement(name = "documentActionResult", required = true)
1068 DocumentActionResult returnToPreviousNode(
1069 @WebParam(name = "parameters") DocumentActionParameters parameters,
1070 @WebParam(name = "returnPoint") ReturnPoint returnPoint)
1071 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1072
1073
1074 /**
1075 * Triggers the execution of a {@link ActionType#MOVE} action for the given
1076 * principal and document specified in the supplied parameters. Move a document to a
1077 * node will allow for the document to be pushed to a different node in the process based on
1078 * the criteria present in the {@link MovePoint} that is passed to this method.
1079 *
1080 * <p />
1081 * The document is synchronously moved to the suggested move point (assuming the desired
1082 * move point can be identified for the given document), and then the document will be
1083 * submitted to the engine for further processing (effectively, re-establishing the flow of the
1084 * document from the target return point).
1085 *
1086 *
1087 * @param parameters the parameters which indicate which principal is executing the action
1088 * against which document, as well as additional operations to take against the document,
1089 * such as updating document data
1090 * @param movePoint the point to move the document
1091 *
1092 * @return the result of executing the action, including a view on the updated state of the
1093 * document and related actions
1094 *
1095 * @throws RiceIllegalArgumentException if {@code parameters} is null
1096 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1097 * {@code parameters} exists
1098 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1099 * in {@code parameters} exists
1100 * @throws InvalidDocumentContentException if the document content on the
1101 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1102 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1103 * action
1104 */
1105 @WebMethod(operationName = "move")
1106 @WebResult(name = "documentActionResult")
1107 @XmlElement(name = "documentActionResult", required = true)
1108 DocumentActionResult move(
1109 @WebParam(name = "parameters") DocumentActionParameters parameters,
1110 @WebParam(name = "movePoint") MovePoint movePoint)
1111 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1112
1113 /**
1114 * Triggers the execution of a {@link ActionType#TAKE_GROUP_AUTHORITY} action for the given
1115 * principal and document specified in the supplied parameters. Takes authority of a group by a
1116 * member of that group.
1117 *
1118 * @param parameters the parameters which indicate which principal is executing the action
1119 * against which document, as well as additional operations to take against the document,
1120 * such as updating document data
1121 * @param groupId the group id to take authority of
1122 *
1123 * @return the result of executing the action, including a view on the updated state of the
1124 * document and related actions
1125 *
1126 * @throws RiceIllegalArgumentException if {@code parameters} is null
1127 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1128 * {@code parameters} exists
1129 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1130 * in {@code parameters} exists
1131 * @throws InvalidDocumentContentException if the document content on the
1132 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1133 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1134 * action
1135 */
1136 @WebMethod(operationName = "takeGroupAuthority")
1137 @WebResult(name = "documentActionResult")
1138 @XmlElement(name = "documentActionResult", required = true)
1139 DocumentActionResult takeGroupAuthority(
1140 @WebParam(name = "parameters") DocumentActionParameters parameters,
1141 @WebParam(name = "groupId") String groupId)
1142 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1143
1144 /**
1145 * Triggers the execution of a {@link ActionType#RELEASE_GROUP_AUTHORITY} action for the given
1146 * principal and document specified in the supplied parameters. Releases authority of a group by a
1147 * member of that group.
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 groupId the group id to take authority of
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 = "releaseGroupAuthority")
1168 @WebResult(name = "documentActionResult")
1169 @XmlElement(name = "documentActionResult", required = true)
1170 DocumentActionResult releaseGroupAuthority(
1171 @WebParam(name = "parameters") DocumentActionParameters parameters,
1172 @WebParam(name = "groupId") String groupId)
1173 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1174
1175 /**
1176 * Triggers the execution of a {@link ActionType#SAVE} action for the given
1177 * principal and document specified in the supplied parameters. Saves a document to a
1178 * at the current point.
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 *
1184 * @return the result of executing the action, including a view on the updated state of the
1185 * document and related actions
1186 *
1187 * @throws RiceIllegalArgumentException if {@code parameters} is null
1188 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1189 * {@code parameters} exists
1190 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1191 * in {@code parameters} exists
1192 * @throws InvalidDocumentContentException if the document content on the
1193 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1194 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1195 * action
1196 */
1197 @WebMethod(operationName = "save")
1198 @WebResult(name = "documentActionResult")
1199 @XmlElement(name = "documentActionResult", required = true)
1200 DocumentActionResult save(@WebParam(name = "parameters") DocumentActionParameters parameters)
1201 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1202
1203 /**
1204 * Triggers the execution of a {@link ActionType#SAVE} action for the given
1205 * principal and document specified in the supplied parameters. Saves the current document data for
1206 * the document. Note that passing an annotation to this will have no effect because it is not
1207 * recorded in the route log
1208 *
1209 * @param parameters the parameters which indicate which principal is executing the action
1210 * against which document, as well as additional operations to take against the document,
1211 * such as updating document data
1212 *
1213 * @return the result of executing the action, including a view on the updated state of the
1214 * document and related actions
1215 *
1216 * @throws RiceIllegalArgumentException if {@code parameters} is null
1217 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1218 * {@code parameters} exists
1219 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1220 * in {@code parameters} exists
1221 * @throws InvalidDocumentContentException if the document content on the
1222 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1223 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1224 * action
1225 */
1226 @WebMethod(operationName = "saveDocumentData")
1227 @WebResult(name = "documentActionResult")
1228 @XmlElement(name = "documentActionResult", required = true)
1229 DocumentActionResult saveDocumentData(@WebParam(name = "parameters") DocumentActionParameters parameters)
1230 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1231
1232 /**
1233 * Deletes the document.
1234 *
1235 * @param documentId the unique id of the document to delete
1236 * @param principalId
1237 *
1238 * @return the document that was removed from the system
1239 *
1240 * @throws RiceIllegalArgumentException if {@code documentId} is null
1241 * @throws RiceIllegalArgumentException if {@code principalId} is null
1242 * @throws RiceIllegalArgumentException if no document with the {@code documentId} exists
1243 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1244 * action
1245 */
1246 @WebMethod(operationName = "delete")
1247 @WebResult(name = "document")
1248 @XmlElement(name = "document", required = true)
1249 Document delete(
1250 @WebParam(name = "documentId") String documentId,
1251 @WebParam(name = "principalId") String principalId)
1252 throws RiceIllegalArgumentException, InvalidActionTakenException;
1253
1254 /**
1255 * Records the non-routed document action. - Checks to make sure the document status
1256 * allows the action. Records the action.
1257 *
1258 * @param documentId the unique id of the document to delete
1259 * @param principalId
1260 *
1261 * @return the document that was removed from the system
1262 *
1263 * @throws RiceIllegalArgumentException if {@code documentId} is null
1264 * @throws RiceIllegalArgumentException if {@code principalId} is null
1265 * @throws RiceIllegalArgumentException if {@code annotation} is null
1266 * @throws RiceIllegalArgumentException if no document with the {@code documentId} exists
1267 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1268 * action
1269 */
1270 @WebMethod(operationName = "logAnnotation")
1271 void logAnnotation(
1272 @WebParam(name = "documentId") String documentId,
1273 @WebParam(name = "principalId") String principalId,
1274 @WebParam(name = "annotation") String annotation)
1275 throws RiceIllegalArgumentException, InvalidActionTakenException;
1276
1277 /**
1278 * Initiates the process of document attribute indexing for the document with the given id.
1279 * Calling this method does not trigger processing of the workflow engine, though it may occur
1280 * asynchronously or synchronously depending on configuration of the implementation.
1281 *
1282 * @param documentId the unique id of the document for which to initiate indexing
1283 *
1284 * @throws RiceIllegalArgumentException if {@code documentId} is null
1285 */
1286 @WebMethod(operationName = "initiateIndexing")
1287 void initiateIndexing(@WebParam(name = "documentId") String documentId)
1288 throws RiceIllegalArgumentException;
1289
1290
1291 /**
1292 * Triggers the execution of a {@link ActionType#SU_BLANKET_APPROVE} action for the given
1293 * principal and document specified in the supplied parameters. Does a blanket approve for a super user
1294 * and runs post-processing depending on {@code executePostProcessor}
1295 *
1296 * @param parameters the parameters which indicate which principal is executing the action
1297 * against which document, as well as additional operations to take against the document,
1298 * such as updating document data
1299 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1300 *
1301 * @return the result of executing the action, including a view on the updated state of the
1302 * document and related actions
1303 *
1304 * @throws RiceIllegalArgumentException if {@code parameters} is null
1305 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1306 * {@code parameters} exists
1307 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1308 * in {@code parameters} exists
1309 * @throws InvalidDocumentContentException if the document content on the
1310 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1311 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1312 * action
1313 */
1314 @WebMethod(operationName = "superUserBlanketApprove")
1315 @WebResult(name = "documentActionResult")
1316 @XmlElement(name = "documentActionResult", required = true)
1317 DocumentActionResult superUserBlanketApprove(
1318 @WebParam(name = "parameters") DocumentActionParameters parameters,
1319 @WebParam(name = "executePostProcessor") boolean executePostProcessor)
1320 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1321
1322 /**
1323 * Triggers the execution of a {@link ActionType#SU_APPROVE} action for the given
1324 * principal and document specified in the supplied parameters. Does an approve for a super user
1325 * on a node and runs post-processing depending on {@code executePostProcessor}
1326 *
1327 * @param parameters the parameters which indicate which principal is executing the action
1328 * against which document, as well as additional operations to take against the document,
1329 * such as updating document data
1330 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1331 *
1332 * @return the result of executing the action, including a view on the updated state of the
1333 * document and related actions
1334 *
1335 * @throws RiceIllegalArgumentException if {@code parameters} is null
1336 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1337 * {@code parameters} exists
1338 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1339 * in {@code parameters} exists
1340 * @throws InvalidDocumentContentException if the document content on the
1341 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1342 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1343 * action
1344 */
1345 @WebMethod(operationName = "superUserNodeApprove")
1346 @WebResult(name = "documentActionResult")
1347 @XmlElement(name = "documentActionResult", required = true)
1348 DocumentActionResult superUserNodeApprove(
1349 @WebParam(name = "parameters") DocumentActionParameters parameters,
1350 @WebParam(name = "executePostProcessor") boolean executePostProcessor,
1351 @WebParam(name = "nodeName") String nodeName)
1352 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1353
1354 /**
1355 * Triggers the execution of a {@link ActionType#SU_APPROVE} action for the given
1356 * actionRequestId and principal and document specified in the supplied parameters. Does an approve for a super user
1357 * on a node and runs post-processing depending on {@code executePostProcessor}
1358 *
1359 * @param parameters the parameters which indicate which principal is executing the action
1360 * against which document, as well as additional operations to take against the document,
1361 * such as updating document data
1362 * @param actionRequestId unique Id of an action request to take action on
1363 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1364 *
1365 * @return the result of executing the action, including a view on the updated state of the
1366 * document and related actions
1367 *
1368 * @throws RiceIllegalArgumentException if {@code parameters} is null
1369 * @throws RiceIllegalArgumentException if (@code actionRequestId}
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 = "superUserTakeRequestedAction")
1380 @WebResult(name = "documentActionResult")
1381 @XmlElement(name = "documentActionResult", required = true)
1382 DocumentActionResult superUserTakeRequestedAction(
1383 @WebParam(name = "parameters") DocumentActionParameters parameters,
1384 @WebParam(name = "executePostProcessor") boolean executePostProcessor,
1385 @WebParam(name = "actionRequestId") String actionRequestId)
1386 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1387
1388 /**
1389 * Triggers the execution of a {@link ActionType#SU_DISAPPROVE} action for the given
1390 * principal and document specified in the supplied parameters. Does a disapprove for a super user
1391 * on a node and runs post-processing depending on {@code executePostProcessor}
1392 *
1393 * @param parameters the parameters which indicate which principal is executing the action
1394 * against which document, as well as additional operations to take against the document,
1395 * such as updating document data
1396 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1397 *
1398 * @return the result of executing the action, including a view on the updated state of the
1399 * document and related actions
1400 *
1401 * @throws RiceIllegalArgumentException if {@code parameters} is null
1402 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1403 * {@code parameters} exists
1404 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1405 * in {@code parameters} exists
1406 * @throws InvalidDocumentContentException if the document content on the
1407 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1408 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1409 * action
1410 */
1411 @WebMethod(operationName = "superUserDisapprove")
1412 @WebResult(name = "documentActionResult")
1413 @XmlElement(name = "documentActionResult", required = true)
1414 DocumentActionResult superUserDisapprove(
1415 @WebParam(name = "parameters") DocumentActionParameters parameters,
1416 @WebParam(name = "executePostProcessor") boolean executePostProcessor)
1417 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1418
1419 /**
1420 * Triggers the execution of a {@link ActionType#SU_CANCEL} action for the given
1421 * principal and document specified in the supplied parameters. Does an cancel for a super user
1422 * on a node and runs post-processing depending on {@code executePostProcessor}
1423 *
1424 * @param parameters the parameters which indicate which principal is executing the action
1425 * against which document, as well as additional operations to take against the document,
1426 * such as updating document data
1427 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1428 *
1429 * @return the result of executing the action, including a view on the updated state of the
1430 * document and related actions
1431 *
1432 * @throws RiceIllegalArgumentException if {@code parameters} is null
1433 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1434 * {@code parameters} exists
1435 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1436 * in {@code parameters} exists
1437 * @throws InvalidDocumentContentException if the document content on the
1438 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1439 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1440 * action
1441 */
1442 @WebMethod(operationName = "superUserCancel")
1443 @WebResult(name = "documentActionResult")
1444 @XmlElement(name = "documentActionResult", required = true)
1445 DocumentActionResult superUserCancel(
1446 @WebParam(name = "parameters") DocumentActionParameters parameters,
1447 @WebParam(name = "executePostProcessor") boolean executePostProcessor)
1448 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1449
1450 /**
1451 * Triggers the execution of a {@link ActionType#SU_RETURN_TO_PREVIOUS} action for the given
1452 * principal and document specified in the supplied parameters. Returns the document to the
1453 * previous node for a super user on a node and runs post-processing depending on {@code executePostProcessor}
1454 *
1455 * @param parameters the parameters which indicate which principal is executing the action
1456 * against which document, as well as additional operations to take against the document,
1457 * such as updating document data
1458 * @param executePostProcessor boolean value determining if the post-processor should be run or not
1459 * @param returnPoint point to return to
1460 *
1461 * @return the result of executing the action, including a view on the updated state of the
1462 * document and related actions
1463 *
1464 * @throws RiceIllegalArgumentException if {@code parameters} is null
1465 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1466 * {@code parameters} exists
1467 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1468 * in {@code parameters} exists
1469 * @throws InvalidDocumentContentException if the document content on the
1470 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1471 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1472 * action
1473 */
1474 @WebMethod(operationName = "superUserReturnToPreviousNode")
1475 @WebResult(name = "documentActionResult")
1476 @XmlElement(name = "documentActionResult", required = true)
1477 DocumentActionResult superUserReturnToPreviousNode(
1478 @WebParam(name = "parameters") DocumentActionParameters parameters,
1479 @WebParam(name = "executePostProcessor") boolean executePostProcessor,
1480 @WebParam(name = "returnPoint") ReturnPoint returnPoint)
1481 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1482
1483 /**
1484 * Places a document in exception routing or the given principal and document specified in the supplied parameters.
1485 *
1486 * @param parameters the parameters which indicate which principal is executing the action
1487 * against which document, as well as additional operations to take against the document,
1488 * such as updating document data
1489 *
1490 * @return the result of executing the action, including a view on the updated state of the
1491 * document and related actions
1492 *
1493 * @throws RiceIllegalArgumentException if {@code parameters} is null
1494 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1495 * {@code parameters} exists
1496 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1497 * in {@code parameters} exists
1498 * @throws InvalidDocumentContentException if the document content on the
1499 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1500 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1501 * action
1502 */
1503 @WebMethod(operationName = "placeInExceptionRouting")
1504 @WebResult(name = "documentActionResult")
1505 @XmlElement(name = "documentActionResult", required = true)
1506 DocumentActionResult placeInExceptionRouting(@WebParam(name = "parameters") DocumentActionParameters parameters)
1507 throws RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException;
1508
1509 /**
1510 * Validates a workflow attribute definition and returns a list of validation errors
1511 *
1512 * @param definition WorkflowAttributeDefinition to validate
1513 *
1514 * @return a list of RemotableAttributeErrors caused by validation of the passed in {@code definition}
1515 *
1516 * @throws RiceIllegalArgumentException if {@code parameters} is null
1517 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1518 * {@code parameters} exists
1519 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1520 * in {@code parameters} exists
1521 * @throws InvalidDocumentContentException if the document content on the
1522 * {@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
1523 * @throws InvalidActionTakenException if the supplied principal is not allowed to execute this
1524 * action
1525 */
1526 @WebMethod(operationName = "validateWorkflowAttributeDefinition")
1527 @WebResult(name = "validationErrors")
1528 @XmlElementWrapper(name = "validationErrors", required = true)
1529 @XmlElement(name = "validationError", required = true)
1530 List<RemotableAttributeError> validateWorkflowAttributeDefinition(
1531 @WebParam(name = "definition") WorkflowAttributeDefinition definition)
1532 throws RiceIllegalArgumentException;
1533
1534 // TODO add, annotate, and javadoc the following methods to this service
1535 /**
1536 * Determines if a passed in user exists in a document's route log or future route depending on the passed in
1537 * {@code lookFuture} value
1538 *
1539 * @param documentId unique Id of document
1540 * @param principalId unique Id of Principal to look for in document's route log
1541 * @param lookFuture boolean value determines whether or not to look at the future route log
1542 *
1543 * @return boolean value representing if a principal exists in a Document's route log
1544 *
1545 * @throws RiceIllegalArgumentException if {@code documentId} is null
1546 * @throws RiceIllegalArgumentException if {@code principalId} is null
1547 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1548 * {@code parameters} exists
1549 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1550 * in {@code parameters} exists
1551 */
1552 @WebMethod(operationName = "isUserInRouteLog")
1553 @WebResult(name = "userInRouteLog")
1554 boolean isUserInRouteLog(
1555 @WebParam(name = "documentId") String documentId,
1556 @WebParam(name = "principalId") String principalId,
1557 @WebParam(name = "lookFuture") boolean lookFuture)
1558 throws RiceIllegalArgumentException;
1559
1560 /**
1561 * Determines if a passed in user exists in a document's route log or future route depending on the passed in
1562 * {@code lookFuture} value and {@code flattenNodes}
1563 *
1564 * @param documentId unique Id of document
1565 * @param principalId unique Id of Principal to look for in document's route log
1566 * @param lookFuture boolean value determines whether or not to look at the future route log
1567 *
1568 * @return boolean value representing if a principal exists in a Document's route log
1569 *
1570 * @throws RiceIllegalArgumentException if {@code documentId} is null
1571 * @throws RiceIllegalArgumentException if {@code principalId} is null
1572 * @throws RiceIllegalArgumentException if no document with the {@code documentId} specified in
1573 * {@code parameters} exists
1574 * @throws RiceIllegalArgumentException if no principal with the {@code principalId} specified
1575 * in {@code parameters} exists
1576 */
1577 @WebMethod(operationName = "isUserInRouteLogWithOptionalFlattening")
1578 @WebResult(name = "userInRouteLogWithOptionalFlattening")
1579 boolean isUserInRouteLogWithOptionalFlattening(
1580 @WebParam(name = "documentId") String documentId,
1581 @WebParam(name = "principalId") String principalId,
1582 @WebParam(name = "lookFuture") boolean lookFuture,
1583 @WebParam(name = "flattenNodes") boolean flattenNodes)
1584 throws RiceIllegalArgumentException;
1585
1586 /**
1587 * Re-resolves the given role for all documents for the given document type (including children).
1588 *
1589 * @param documentTypeName documentTypeName of DocuemntType for role
1590 * @param roleName name of Role to reresolve
1591 * @param qualifiedRoleNameLabel qualified role name label
1592 *
1593 * @throws RiceIllegalArgumentException if {@code documentTypeName} is null
1594 * @throws RiceIllegalArgumentException if {@code roleName} is null
1595 * @throws RiceIllegalArgumentException if {@code qualifiedRoleNameLable} is null
1596 */
1597 @WebMethod(operationName = "reResolveRoleByDocTypeName")
1598 void reResolveRoleByDocTypeName(
1599 @WebParam(name = "documentTypeName") String documentTypeName,
1600 @WebParam(name = "roleName") String roleName,
1601 @WebParam(name = "qualifiedRoleNameLabel") String qualifiedRoleNameLabel)
1602 throws RiceIllegalArgumentException;
1603
1604 /**
1605 * Re-resolves the given role for all documents for the given document id (including children).
1606 *
1607 * @param documentId documentId of Docuemnt for role
1608 * @param roleName name of Role to reresolve
1609 * @param qualifiedRoleNameLabel qualified role name label
1610 *
1611 * @throws RiceIllegalArgumentException if {@code documentTypeName} is null
1612 * @throws RiceIllegalArgumentException if {@code roleName} is null
1613 * @throws RiceIllegalArgumentException if {@code qualifiedRoleNameLable} is null
1614 */
1615 @WebMethod(operationName = "reResolveRoleByDocumentId")
1616 void reResolveRoleByDocumentId(
1617 @WebParam(name = "documentId") String documentId,
1618 @WebParam(name = "roleName") String roleName,
1619 @WebParam(name = "qualifiedRoleNameLabel") String qualifiedRoleNameLabel)
1620 throws RiceIllegalArgumentException;
1621
1622 /**
1623 * Executes a simulation of a document to get all previous and future route information
1624 *
1625 * @param reportCriteria criteria for the simulation to follow
1626 *
1627 * @return DocumentDetail object representing the results of the simulation
1628 *
1629 * @throws RiceIllegalArgumentException if {@code reportCriteria} is null
1630 */
1631 @WebMethod(operationName = "executeSimulation")
1632 @WebResult(name = "documentDetail")
1633 DocumentDetail executeSimulation(
1634 @WebParam(name = "reportCriteria") RoutingReportCriteria reportCriteria)
1635 throws RiceIllegalArgumentException;
1636
1637 /**
1638 * Determines if a passed in user is the final approver for a document
1639 *
1640 * @param documentId unique Id of the document
1641 * @param principalId unique Id of Principal to look for in document's route log
1642 *
1643 * @return boolean value representing if a principal is the final approver for a document
1644 *
1645 * @throws RiceIllegalArgumentException if {@code documentId} is null
1646 * @throws RiceIllegalArgumentException if {@code principalId} is null
1647 */
1648 @WebMethod(operationName = "isFinalApprover")
1649 @WebResult(name = "finalApprover")
1650 boolean isFinalApprover(
1651 @WebParam(name = "documentId") String documentId,
1652 @WebParam(name = "principalId") String principalId)
1653 throws RiceIllegalArgumentException;
1654
1655 /**
1656 * Determines if a passed in user is the last approver at a specified route node
1657 *
1658 * @param documentId unique Id of the document
1659 * @param principalId unique Id of Principal to look for in document's route log
1660 * @param nodeName name of route node to determine last approver for
1661 *
1662 * @return boolean value representing if a principal is the last approver at the specified route node
1663 *
1664 * @throws RiceIllegalArgumentException if {@code documentId} is null
1665 * @throws RiceIllegalArgumentException if {@code principalId} is null
1666 * @throws RiceIllegalArgumentException if {@code nodeName} is null
1667 */
1668 @WebMethod(operationName = "isLastApproverAtNode")
1669 @WebResult(name = "lastApproverAtNode")
1670 boolean isLastApproverAtNode(
1671 @WebParam(name = "documentId") String documentId,
1672 @WebParam(name = "principalId") String principalId,
1673 @WebParam(name = "nodeName") String nodeName)
1674 throws RiceIllegalArgumentException;
1675
1676 /**
1677 * Determines if a route node has an 'approve action' request
1678 *
1679 * @param docType document type of document
1680 * @param docContent string representing content of document
1681 * @param nodeName name of route node to determine if approve action request exists
1682 *
1683 * @return boolean value representing if a route node has an 'approve action' request
1684 *
1685 * @throws RiceIllegalArgumentException if {@code docType} is null
1686 * @throws RiceIllegalArgumentException if {@code docContent} is null
1687 * @throws RiceIllegalArgumentException if {@code nodeName} is null
1688 */
1689 @WebMethod(operationName = "routeNodeHasApproverActionRequest")
1690 @WebResult(name = "routeNodeHasApproverActionRequest")
1691 boolean routeNodeHasApproverActionRequest(
1692 @WebParam(name = "docType") String docType,
1693 @WebParam(name = "docContent") String docContent,
1694 @WebParam(name = "nodeName") String nodeName)
1695 throws RiceIllegalArgumentException;
1696
1697 /**
1698 * Determines if a document has at least one action request
1699 *
1700 * @param reportCriteria criteria for routing report
1701 * @param actionRequestedCodes list of action request codes to see if they exist for the document
1702 * @param ignoreCurrentActionRequests boolean value to determine if current action requests should be ignored
1703 *
1704 * @return boolean value representing if a document will have at least one action request
1705 *
1706 * @throws RiceIllegalArgumentException if {@code docType} is null
1707 * @throws RiceIllegalArgumentException if {@code docContent} is null
1708 * @throws RiceIllegalArgumentException if {@code nodeName} is null
1709 */
1710 @WebMethod(operationName = "documentWillHaveAtLeastOneActionRequest")
1711 @WebResult(name = "documentWillHaveAtLeastOneActionRequest")
1712 boolean documentWillHaveAtLeastOneActionRequest(
1713 @WebParam(name = "reportCriteria") RoutingReportCriteria reportCriteria,
1714 @WebParam(name = "actionRequestedCodes") List<String> actionRequestedCodes,
1715 @WebParam(name = "ignoreCurrentActionRequests") boolean ignoreCurrentActionRequests)
1716 throws RiceIllegalArgumentException;
1717
1718 /**
1719 * Returns a list of principal Ids that exist in a route log
1720 *
1721 * @param documentId unique id of the document to get the route log for
1722 * @param lookFuture boolean value that determines if the method should look at future action requests
1723 *
1724 * @return list of principal ids that exist in a route log
1725 *
1726 * @throws RiceIllegalArgumentException if {@code documentId} is null
1727 */
1728 @WebMethod(operationName = "getPrincipalIdsInRouteLog")
1729 @WebResult(name = "principalIds")
1730 @XmlElementWrapper(name = "principalIds", required = true)
1731 @XmlElement(name = "principalId", required = true)
1732 List<String> getPrincipalIdsInRouteLog(
1733 @WebParam(name = "documentId") String documentId,
1734 @WebParam(name = "lookFuture") boolean lookFuture)
1735 throws RiceIllegalArgumentException;
1736
1737 }