Package com.appiancorp.suiteapi.process

Interface ExceptionHandlerService

All Superinterfaces:

com.appiancorp.services.ContextSensitiveService, Service

public interface ExceptionHandlerService
extends com.appiancorp.services.ContextSensitiveService

Provides methods relating to process exception handling.

Process exception handling is used for raising exceptions on processes or tasks when something goes wrong so that particular users (identified by their role for the process or task) can be notified of the problem and given a recommended course of action.

All exception types must first be registered using registerExceptionTypesWithNotes(com.appiancorp.suiteapi.process.ProcessExceptionType[], java.lang.String[]). See ProcessExceptionType for more information on how to configure a ProcessExceptionType before registering it.

Once an exception type has been registered it can be raised using raiseException(String, Long) or raiseExceptionMessage(String, Long, String) to raise an exception with a non-default message. After an exception has been raised on a process or a task (either by the process engine or by manually calling raiseException), the exception will be resolved as soon as the state of the process or task becomes anything other than ProcessSummary.STATE_PAUSED_BY_EXCEPTION or TaskSummary.TASK_STATUS_PAUSED_BY_EXCEPTION respectively.

Methods of service classes can all throw the unchecked exception ServiceException if any system-level error (for example, server failure) occurs, and will in general throw a checked exception (InvalidXXXException) when an entity to be retrieved is inaccessible, instead of returning null. Exceptions to this paradigm (including the use of ResultList as described below) are noted. All checked exceptions extend AppianException.

It may be necessary to retrieve a subset of results as opposed to an entire collection, and also to sort the subset by some property of the returned object. "Paging" methods which return a ResultPage are provided in certain instances for this purpose. The ResultPage will contain the sorted subset of results (via Result.getResults()), and the total number of items in the available result set (via ResultPage.getAvailableItems()).

It may also be necessary to retrieve some results, even if all results cannot be retrieved (for instance, some of the entities corresponding to a list of entity IDs may no longer exist). Methods which return a ResultList are provided for this purpose. The Result.getResults() method in this case will return all results which can be retrieved. In addition, there will be a list of result codes (ResultList.getResultCodes()) that represent the successful retrieval of an entity, or, if the entity could not be retrieved, the reason for the failure. See the CODE_XXX constants in ResultList for details.

See Also:

• NotesContentService
• ProcessAdministrationService
• ProcessAnalyticsService
• ProcessDesignService
• ProcessExecutionService

Field Summary

Fields

Modifier and Type	Field	Description
static final boolean	getAllExceptionTypes$UPDATES	Deprecated, for removal: This API element is subject to removal in a future version.
static final boolean	getExceptionType$UPDATES	Deprecated, for removal: This API element is subject to removal in a future version.
static final boolean	getExceptionTypes$UPDATES	Deprecated, for removal: This API element is subject to removal in a future version.
static final boolean	raiseException$UPDATES	Deprecated, for removal: This API element is subject to removal in a future version.
static final boolean	raiseExceptionMessage$UPDATES	Deprecated, for removal: This API element is subject to removal in a future version.
static final boolean	registerExceptionTypesWithNotes$UPDATES	Deprecated, for removal: This API element is subject to removal in a future version.

Fields inherited from interface com.appiancorp.services.ContextSensitiveService

SET_SERVICE_CONTEXT_METHOD_NAME

Method Summary

Modifier and Type	Method	Description
ResultPage	getAllExceptionTypes(int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_)	Get all the ProcessExceptionType objects, paging.
ProcessExceptionType	getExceptionType(String exceptionTypeLocalId_)	Get the ProcessExceptionType from its unique id.
ProcessExceptionType[]	getExceptionTypes(String[] exceptionTypeLocalIds_)	Get the ProcessExceptionType objects from their unique ids.
void	raiseException(String exceptionTypeLocalId_, Long id_)	Raise an exception on a task or process.
void	raiseExceptionMessage(String exceptionTypeLocalId_, Long id_, String message_)	Raise an exception on a task or process.
void	registerExceptionTypesWithNotes(ProcessExceptionType[] exceptionTypes_, String[] content_)	Register exception types, and the note content for those exception types.

Methods inherited from interface com.appiancorp.services.ContextSensitiveService

setServiceContext

Field Details

getExceptionType$UPDATES

@Deprecated(forRemoval=true)
static final boolean getExceptionType$UPDATES

Deprecated, for removal: This API element is subject to removal in a future version.

See Also:

• Constant Field Values

getExceptionTypes$UPDATES

@Deprecated(forRemoval=true)
static final boolean getExceptionTypes$UPDATES

Deprecated, for removal: This API element is subject to removal in a future version.

See Also:

• Constant Field Values

getAllExceptionTypes$UPDATES

@Deprecated(forRemoval=true)
static final boolean getAllExceptionTypes$UPDATES

Deprecated, for removal: This API element is subject to removal in a future version.

See Also:

• Constant Field Values

raiseException$UPDATES

@Deprecated(forRemoval=true)
static final boolean raiseException$UPDATES

Deprecated, for removal: This API element is subject to removal in a future version.

See Also:

• Constant Field Values

raiseExceptionMessage$UPDATES

@Deprecated(forRemoval=true)
static final boolean raiseExceptionMessage$UPDATES

Deprecated, for removal: This API element is subject to removal in a future version.

See Also:

• Constant Field Values

registerExceptionTypesWithNotes$UPDATES

@Deprecated(forRemoval=true)
static final boolean registerExceptionTypesWithNotes$UPDATES

Deprecated, for removal: This API element is subject to removal in a future version.

See Also:

• Constant Field Values

Method Details

getExceptionType

@Read(K_PROCESS_EXECUTION)
ProcessExceptionType getExceptionType(String exceptionTypeLocalId_)
                               throws InvalidExceptionTypeException

Get the ProcessExceptionType from its unique id.

Parameters:

exceptionTypeLocalId_ - The localId of the ProcessExceptionType to get.

Returns:

Returns the ProcessExceptionType associated with the passed id.

Throws:

InvalidExceptionTypeException - if no ProcessExceptionType with the passed id exists.

getExceptionTypes

@Read(K_PROCESS_EXECUTION)
ProcessExceptionType[] getExceptionTypes(String[] exceptionTypeLocalIds_)
                                  throws InvalidExceptionTypeException

Get the ProcessExceptionType objects from their unique ids.

Parameters:

exceptionTypeLocalIds_ - The localIds of the ProcessExceptionType objects to get.

Returns:

Returns an array of ProcessExceptionType objects associated with the passed ids.

Throws:

InvalidExceptionTypeException - Thrown if no exception type with the passed id exists.

getAllExceptionTypes

@Read(K_PROCESS_EXECUTION)
ResultPage getAllExceptionTypes(int startIndex_,
 int batchSize_,
 Integer sortProperty_,
 Integer sortOrder_)

Get all the ProcessExceptionType objects, paging.

Parameters:

startIndex_ - The index into the collection of total results at which to start. Negative numbers are treated as zeros.

batchSize_ - The number of results to return. use Constants.COUNT_ALL to return the entire collection, but this is STRONGLY discouraged.

sortProperty_ - The property by which the results will be sorted. This will be one of the SORT_BY_XXX constants in ProcessExceptionType

sortOrder_ - The order in which to sort the results. This is one of Constants.SORT_ORDER_ASCENDING or Constants.SORT_ORDER_DESCENDING

Returns:

Returns a ResultPage of ProcessExceptionType objects.

raiseException

@Write(K_PROCESS_EXECUTION)
void raiseException(String exceptionTypeLocalId_,
 Long id_)
             throws InvalidExceptionTypeException,
IllegalArgumentException,
InvalidProcessException,
InvalidActivityException,
PrivilegeException

Raise an exception on a task or process.

Parameters:

exceptionTypeLocalId_ - The localId of the exception type to raise.

id_ - The id of the process or task for which the exception should be raised.

Throws:

InvalidExceptionTypeException - if no exception type with the passed local id exists.

IllegalArgumentException - if the task or process specified by id_ does not exist

InvalidProcessException - if no process with the passed id exists.

InvalidActivityException - if no task with the passed id exists.

PrivilegeException - if the user does not have sufficient permissions to execute this method.

raiseExceptionMessage

@Write(K_PROCESS_EXECUTION)
void raiseExceptionMessage(String exceptionTypeLocalId_,
 Long id_,
 String message_)
                    throws InvalidExceptionTypeException,
IllegalArgumentException,
InvalidProcessException,
InvalidActivityException,
PrivilegeException

Raise an exception on a task or process.

Parameters:

exceptionTypeLocalId_ - The localId of the exception type to raise.

id_ - The id of the process or task for which the exception should be raised.

message_ - A custom message to show the user

Throws:

InvalidExceptionTypeException - if no exception type with the passed local id exists.

IllegalArgumentException - if the task or process specified by id_ does not exist

InvalidProcessException - if no process with the passed id exists.

InvalidActivityException - if no task with the passed id exists.

PrivilegeException - if the user does not have sufficient permissions to execute this method.

registerExceptionTypesWithNotes

@Write(K_PROCESS_EXECUTION)
void registerExceptionTypesWithNotes(ProcessExceptionType[] exceptionTypes_,
 String[] content_)
                              throws PrivilegeException,
AppianException

Register exception types, and the note content for those exception types. The minimum required fields on the exception type are: localId. The noteId field will be ignored. Note that there is NO need to separately write the note content to disk using NotesContentService.createNoteContent(java.lang.String, java.lang.String) - this will be handled automatically.

Parameters:

exceptionTypes_ - the exception types to be registered

content_ - the content of the notes associated with the respective exception types. The length of this array must be the same as the length of exceptionTypes_

Throws:

PrivilegeException - if the user does not have sufficient permissions to execute this method. A user can call this method successfully if com.appiancorp.suiteapi.process.security.ProcessPermissions#registerExceptionType returns true for the user.

AppianException