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