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