IBM WebSphere Application ServerTM
Release 6

Package  com.ibm.task.api

Interface Summary
AutoDeletionModeThis interface defines symbolic constants that state whether a task instance is automatically deleted once it reaches an end execution state or not.
ClaimResultReturns the result of a claim API call that processes multiple task instances, for example, claim(TKIID[]).
CustomPropertyDescribes a named custom property.
CustomPropertyInfoProvides information about a custom property.
EscalationActionIndexThis interface defines symbolic constants to be used as column index when accessing the array of available action flags - see .
EscalationActionsThis interface defines symbolic constants for all actions that can be performed on escalation instances.
EscalationResultReturns the result of an API call that processes multiple escalation instances, for example, the result of a bulkTransferWorkItem(ESIID[], ...), call.
EscalationTemplateActionIndexThis interface defines symbolic constants to be used as column index when accessing the array of available action flags.
EscalationTemplateActionsThis interface defines symbolic constants for all actions that can be performed on escalation templates.
ExecutableQueryInterface for customizable queries.
GroupDetailInterface for accessing group details.
HtmConfigurationThis interface returns Human Task Manager configuration settings.
HumanTaskManagerRemote EJB interface for Enterprise Bean: HumanTaskManager
HumanTaskManagerDelegateHumanTaskManagerDelegate wraps the functions of the Human Task Manager API and hides the details of setting up the communication.
HumanTaskManagerHomeThe remote home interface of the HumanTaskManager session bean.
HumanTaskManagerServiceHumanTaskManagerService defines the human task methods that can be called by a local or remote client.
LocalHumanTaskManagerLocal EJB interface for Enterprise Bean: HumanTaskManager
LocalHumanTaskManagerHomeThe local home interface of the HumanTaskManager session bean.
LocalHumanTaskManagerServiceLocalHumanTaskManagerService defines the human task methods that can be called by a local client.
ObjectTypeThis interface defines symbolic constants for object types.
QueryColumnTypeThis interface defines symbolic constants for all column types of a query result set.
QueryResultSetProvides the results of a query request.
ReplyHandlerThis interface supports an asynchronous mode of operation.
TaskActionIndexThis interface defines symbolic constants to be used as column index when accessing the array of available action flags - see .
TaskActionsThis interface defines symbolic constants for all actions that can be performed on task instances.
TaskModelWraps task instances and templates that are created spontaneously.
TaskResultReturns the result of an API call that processes multiple task instances, for example, the result of a complete(TKIID[]) call.
TaskTemplateActionIndexThis interface defines symbolic constants to be used as column index when accessing the array of available action flags.
TaskTemplateActionsThis interface defines symbolic constants for all actions that can be performed on Task Templates.
UserDetailInterface for accessing user details.
ClientSettingInterface that supports the definition of user specific client settings.
CustomClientSettingsInterface for all client and Web client settings.
JspLocationInterface to retrieve JSP locations of a Web client setting.
PortalClientSettingInterface for Portal client settings.
WebClientSettingInterface for Web client settings.
ACOIDInterface for an application component object identifier.
ESIIDInterface for an escalation instance object identifier.
ESTIDInterface for an escalation template object identifier.
StaffResultSetReturns the persons or groups that are members of a specific role.
TKIIDInterface for a task instance object identifier.
TKTIDInterface for a task template object identifier.
ValidationProblemDescribes validation problems of task instances or templates that have been created spontaneously (ad hoc).
ApplicationComponentAccesses the properties of an application component.
EscalationAccesses the properties of an escalation instance.
EscalationTemplateAccesses the properties of an escalation template.
StoredQueryAccesses the properties of a query stored persistently.
TaskAccesses the properties of a task instance.
TaskTemplateAccesses the properties of a task template.
WorkItemAccesses the properties of a work item.

Class Summary
BinaryCustomPropertyDescribes a custom property that has a binary value.
ClientObjectWrapperWraps messages passed between the caller and the Human Task Manager.
ClientTaskFactoryFactory to create a ClientTaskFactory object.
HumanTaskManagerDelegateFactoryFactory to create a HumanTaskManagerDelegate object.
ReplyHandlerWrapperWraps the reply handler passed to the Human Task Manager.
JspApplicableRoleEnumThis enumeration class defines symbolic constants for JSP applicable role patterns.
JspUsageEnumThis enumeration class defines symbolic constants for JSP usage patterns.
ErrorTypeEnumThis enumeration class defines symbolic constants for error types that are found during validation of objects created spontaneously (ad-hoc).
QueryHelperHelper class to support native SQL requests against the ProcessChoreographer database.
StoredQueryPropertyDescribes a property of a stored query.

Exception Summary
ApplicationVetoExceptionException class for error message Api.ApplicationVeto.
FaultReplyExceptionA FaultReplyException states that a modelled fault is returned.
TaskBusinessExceptionA TaskBusinessException wraps fault responses from tasks.
WorkItemManagerExceptionA general non-recoverable exception that occured with Work Item Management functions.
AdminActionExceptionException class for error message Api.AdminAction.
AdministeredObjectDoesNotExistExceptionException class for error message Api.AdministeredObjectDoesNotExist.
AdministratorCannotBeResolvedExceptionException class for error message Api.AdministratorCannotBeResolved.
ApplicationComponentDoesNotExistExceptionException class for error message Api.ApplicationComponentDoesNotExist.
CannotAccessVMMServiceExceptionException class for error message Api.CannotAccessVMMService.
CannotCreateWorkItemExceptionException class for error message Api.CannotCreateWorkItem.
ChildTaskInstanceActiveExceptionException class for error message Api.ChildTaskInstanceActive.
CommunicationExceptionException class for error message Api.Communication.
ConflictingTypesExceptionException class for error message Api.ConflictingTypes.
CoreOTaskServiceInvalidResultExceptionException class for error message Core.OTaskServiceInvalidResult.
CoreOTaskServiceResultHasInvalidFaultMessageQNameExceptionException class for error message Core.OTaskServiceResultHasInvalidFaultMessageQName.
CoreOTaskServiceResultHasInvalidFaultMessageTypeExceptionException class for error message Core.OTaskServiceResultHasInvalidFaultMessageType.
CoreOTaskServiceResultHasInvalidOutputMessageTypeExceptionException class for error message Core.OTaskServiceResultHasInvalidOutputMessageType.
CoreOTaskServiceRuntimeExceptionReceivedExceptionException class for error message Core.OTaskServiceRuntimeExceptionReceived.
DataHandlingExceptionException class for error message Api.DataHandling.
EscalationDoesNotExistExceptionException class for error message Api.EscalationDoesNotExist.
EscalationNotAuthorizedExceptionException class for error message Api.EscalationNotAuthorized.
EscalationTemplateDoesNotExistExceptionException class for error message Api.EscalationTemplateDoesNotExist.
EscalationTemplateNotAuthorizedExceptionException class for error message Api.EscalationTemplateNotAuthorized.
EverybodyWorkItemExceptionException class for error message Api.EverybodyWorkItem.
FaultMessageDefinitionDoesNotMatchExceptionException class for error message Api.FaultMessageDefinitionDoesNotMatch.
FollowOnTasksNotSupportedExceptionException class for error message Api.FollowOnTasksNotSupported.
GenericTaskExceptionException class for error message Api.GenericTask.
GroupWorkItemExceptionException class for error message Api.GroupWorkItem.
IdWrongFormatExceptionException class for error message Api.IdWrongFormat.
IdWrongTypeExceptionException class for error message Api.IdWrongType.
InheritedAccessRightExceptionException class for error message Api.InheritedAccessRight.
InvalidApplicationStateExceptionException class for error message Api.InvalidApplicationState.
InvalidAssignmentReasonExceptionException class for error message Api.InvalidAssignmentReason.
InvalidLengthExceptionException class for error message Api.InvalidLength.
InvalidParameterExceptionException class for error message Api.InvalidParameter.
InvalidProtocolExceptionException class for error message Api.InvalidProtocol.
InvalidQNameExceptionException class for error message Api.InvalidQName.
InvalidStoredQueryParametersExceptionException class for error message Api.InvalidStoredQueryParameters.
IsAdHocExceptionException class for error message Api.IsAdHoc.
IsChildExceptionException class for error message Api.IsChild.
IsInlineExceptionException class for error message Api.IsInline.
IsNotAdHocExceptionException class for error message Api.IsNotAdHoc.
IsNotInlineExceptionException class for error message Api.IsNotInline.
IsNotTopLevelTaskExceptionException class for error message Api.IsNotTopLevelTask.
KeepOutputForCancelClaimNotSupportedExceptionException class for error message Api.KeepOutputForCancelClaimNotSupported.
LastAdminWorkItemExceptionException class for error message Api.LastAdminWorkItem.
MessageDefinitionDoesNotMatchExceptionException class for error message Api.MessageDefinitionDoesNotMatch.
MethodNotApplicableExceptionException class for error message Api.MethodNotApplicable.
NotAuthorizedExceptionException class for error message Api.NotAuthorized.
ObjectDoesNotExistExceptionException class for error message Api.ObjectDoesNotExist.
OutputMessageDefinitionDoesNotMatchExceptionException class for error message Api.OutputMessageDefinitionDoesNotMatch.
ParameterNullExceptionException class for error message Api.ParameterNull.
ParentTaskIsSuspendedExceptionException class for error message Api.ParentTaskIsSuspended.
PropertyVetoExceptionException class for error message Api.PropertyVeto.
QueryCannotJoinExceptionException class for error message Api.QueryCannotJoin.
QueryExceptionException class for error message Api.Query.
QueryHintExceptionException class for error message Api.QueryHint.
QueryHintInvalidExceptionException class for error message Api.QueryHintInvalid.
QueryHintScopeInvalidExceptionException class for error message Api.QueryHintScopeInvalid.
QueryHintValueInvalidExceptionException class for error message Api.QueryHintValueInvalid.
QueryInvalidOperandExceptionException class for error message Api.QueryInvalidOperand.
QueryInvalidTimestampExceptionException class for error message Api.QueryInvalidTimestamp.
QueryUndefinedParameterExceptionException class for error message Api.QueryUndefinedParameter.
QueryUnknownColumnExceptionException class for error message Api.QueryUnknownColumn.
QueryUnknownOperatorExceptionException class for error message Api.QueryUnknownOperator.
QueryUnknownTableExceptionException class for error message Api.QueryUnknownTable.
RefreshTimeoutInvalidExceptionException class for error message Api.RefreshTimeoutInvalid.
RunningInstancesExceptionException class for error message Api.RunningInstances.
SCAServiceAccessFailureExceptionException class for error message Api.SCAServiceAccessFailure.
SCAServiceResultErrorExceptionException class for error message Api.SCAServiceResultError.
SenderAddressInvalidExceptionException class for error message Api.SenderAddressInvalid.
ServiceNotUniqueExceptionException class for error message Api.ServiceNotUnique.
StaffServiceCannotAccessVMMExceptionException class for error message Api.StaffServiceCannotAccessVMM.
StaffServiceNestedGroupResolutionIsNotSupportedExceptionException class for error message Api.StaffServiceNestedGroupResolutionIsNotSupported.
StaffServiceRuntimeExceptionException class for error message Api.StaffServiceRuntime.
StaffServiceSubstitutionNotEnabledExceptionException class for error message Api.StaffServiceSubstitutionNotEnabled.
StaffServiceVMMEntityAttributeNotAvailableExceptionException class for error message Api.StaffServiceVMMEntityAttributeNotAvailable.
StaffServiceVMMEntityNameIsInvalidExceptionException class for error message Api.StaffServiceVMMEntityNameIsInvalid.
StaffServiceVMMEntityPropertyIsNotInSchemaExceptionException class for error message Api.StaffServiceVMMEntityPropertyIsNotInSchema.
StateObserverErrorException class for error message Api.StateObserver.
StoredQueryNameNotUniqueExceptionException class for error message Api.StoredQueryNameNotUnique.
SubTasksNotSupportedExceptionException class for error message Api.SubTasksNotSupported.
SubstituteDoesNotExistExceptionException class for error message Api.SubstituteDoesNotExist.
SubstitutionNotAuthorizedExceptionException class for error message Api.SubstitutionNotAuthorized.
SystemFaultExceptionDefines an exception which is thrown when during the execution of a task the Human Task Manager itself runs into an error situation.
TaskDelegationNotSupportedExceptionException class for error message Api.TaskDelegationNotSupported.
TaskDoesNotExistExceptionException class for error message Api.TaskDoesNotExist.
TaskExpiredExceptionException class for error message Api.TaskExpired.
TaskHistoryNotEnabledExceptionException class for error message Api.TaskHistoryNotEnabled.
TaskInstanceActiveExceptionException class for error message Api.TaskInstanceActive.
TaskIsEscalatedExceptionException class for error message Api.TaskIsEscalated.
TaskIsSuspendedExceptionException class for error message Api.TaskIsSuspended.
TaskIsWaitingForSubTaskExceptionException class for error message Api.TaskIsWaitingForSubTask.
TaskModelNotAuthorizedExceptionException class for error message Api.TaskModelNotAuthorized.
TaskNotAuthorizedExceptionException class for error message Api.TaskNotAuthorized.
TaskNotSuspendedExceptionException class for error message Api.TaskNotSuspended.
TaskTemplateDoesNotExistExceptionException class for error message Api.TaskTemplateDoesNotExist.
TaskTemplateNotAuthorizedExceptionException class for error message Api.TaskTemplateNotAuthorized.
TaskTemplateNotStoppedExceptionException class for error message Api.TaskTemplateNotStopped.
TaskTerminatedExceptionException class for error message Api.TaskTerminated.
TaskTransferTargetNotAuthorizedExceptionException class for error message Api.TaskTransferTargetNotAuthorized.
TimeIntervalInvalidExceptionException class for error message Api.TimeIntervalInvalid.
URLInvalidExceptionException class for error message Api.URLInvalid.
UnexpectedFailureExceptionException class for error message Api.UnexpectedFailure.
UnknownAdminOperationExceptionException class for error message Api.UnknownAdminOperation.
UserDoesNotExistExceptionException class for error message Api.UserDoesNotExist.
UserRegistryExceptionException class for error message Api.UserRegistry.
VMMEntityAttributeNotAvailableExceptionException class for error message Api.VMMEntityAttributeNotAvailable.
WorkItemDoesNotExistExceptionException class for error message Api.WorkItemDoesNotExist.
WorkItemNotFoundExceptionException class for error message Api.WorkItemNotFound.
WrongEscalationStateExceptionException class for error message Api.WrongEscalationState.
WrongKindExceptionException class for error message Api.WrongKind.
WrongMessageTypeExceptionException class for error message Api.WrongMessageType.
WrongStateExceptionException class for error message Api.WrongState.
WrongTaskKindExceptionException class for error message Api.WrongTaskKind.
WrongTaskStateExceptionException class for error message Api.WrongTaskState.
WrongTaskTemplateKindExceptionException class for error message Api.WrongTaskTemplateKind.
WrongTaskTemplateStateExceptionException class for error message Api.WrongTaskTemplateState.
TaskErrorThis class is the base class for all Human Task Manager runtime exceptions.
TaskExceptionThis is the base class for all exceptions thrown by the Human Task Manager.



Package Description

Provides the application programming interface (API) for managing task-related objects in the ProcessChoreographer Human Task Manager. You can create application programs that use the API to manage information related to tasks. You can:

The API contains a stateless session bean HumanTaskManager for local and remote access. The HumanTaskManagerService interface describes the functions that can be called locally and remotely. It exposes the functions that can be called by an application program. The application program can be any Java program, including another EJB.

The application program accesses the HumanTaskManager session bean through the bean's home and remote or local interfaces. A reference must be added to your application deployment descriptor. For example, for client applications such as a J2EE client application add the reference to the application-client.xml, for a Web application to the web.xml, and for an EJB application to the ejb-jar.xml.

Add the reference to the remote interface as in the following example:

   <ejb-ref>
     <ejb-ref-name>ejb/HumanTaskManagerHome</ejb-ref-name>
     <ejb-ref-type>Session</ejb-ref-type>
     <home>com.ibm.task.api.HumanTaskManagerHome</home>
     <remote>com.ibm.task.api.HumanTaskManager</remote>
   </ejb-ref>

Add the reference to the local interface as in the following example:

   <ejb-local-ref>
     <ejb-ref-name>ejb/LocalHumanTaskManagerHome</ejb-ref-name>
     <ejb-ref-type>Session</ejb-ref-type>
     <local-home>com.ibm.task.api.LocalHumanTaskManagerHome</local-home>
     <local>com.ibm.task.api.LocalHumanTaskManager</local>
   </ejb-local-ref>

If you use WebSphere Integration Developer to add the EJB reference to the deployment descriptor, the binding for the EJB reference is automatically created when the application is deployed.

If you use the remote interface of the HumanTaskManager bean, complete the following actions:

The HumanTaskManager bean's local or remote home interface is then made available to the client through JNDI by the container where the HumanTaskManager session bean is deployed. To access the remote interface:

   // Obtain the default initial JNDI context
   Context initialContext= new InitialContext();
   // Lookup the remote home interface of the HumanTaskManager bean
   Object result= initialContext.lookup("java:comp/env/ejb/HumanTaskManagerHome");
   // Convert the lookup result to the proper type
   HumanTaskManagerHome home= (HumanTaskManagerHome)javax.rmi.PortableRemoteObject.narrow(result,HumanTaskManagerHome.class);
To access the local interface:
   // Obtain the default initial JNDI context
   Context initialContext= new InitialContext();
   // Lookup the local home interface of the HumanTaskManager bean
   LocalHumanTaskManagerHome home= (LocalHumanTaskManagerHome)initialContext.lookup("java:comp/env/ejb/LocalHumanTaskManagerHome");

The home interface contains a create method that returns the HumanTaskManager session bean's remote or local interface. For example, access the remote interface of the session bean:

   HumanTaskManager manager= home.create();
For example, access the local interface of the session bean:
   LocalHumanTaskManager manager= home.create();

When the HumanTaskManager session bean is accessed, the application program can call any of the business functions exposed by the API. For example:

   manager.claim(tkiid);

If the method called does not complete successfully, an exception is thrown that denotes the cause of the error. You can handle this exception specifically to provide guidance to the caller.

However, it is common practice to handle only a subset of the exceptions specifically and to provide general guidance for the other potential exceptions. All specific exceptions inherit from a generic TaskException. It is a best practice to catch the generic exception with a final catch(TaskException) statement. This statement helps to ensure the upward compatibility of your application program because it takes account of all of the other exceptions that can occur, now and in future releases.

When a method is called, null can be specified as a parameter value to indicate that a value is not passed. For example, the order-by clause of a query call can be null to indicate that the result of the query is not to be sorted.

Always qualify your null values to prevent potential upgrade problems to a newer level of WebSphere Process Server, for example, specify (String)null or (Integer)null instead of just null.

Also note that access to the HumanTaskManager session bean does not guarantee that all functions can be executed; the caller must also be authorized for these actions.

When an instance of the HumanTaskManager session bean is created, the container associates a context with the instance of the session bean. The context contains the caller's principal ID, a group membership list, and indicates whether the caller has one of the Human Task Manager J2EE roles, that is, whether the caller belongs to the group of Human Task Manager system administrators or monitors. The context is used by both the container and the Human Task Manager to check the caller's authorization for each call even when global security is not set. If global security is not set, the caller's principal ID has the value 'UNAUTHENTICATED'.

In other words, if global security is set, you need to login before the API can be accessed.

Calls from applications are run as transactions. A transaction is either established and ended explicitly by the application program, or established by the container when the application progam calls the task manager and ended by the container when the application program receives the result (the deployment descriptor specifies TX_REQUIRED). For example, the application program can establish and end a transaction as follows:

   // Obtain user transaction interface
   UserTransaction transaction= (UserTransaction)intialContext.lookup("jta/usertransaction");
   // Begin a transaction
   transaction.begin();
      // Human Task Manager calls ...
   // On successful return, commit the transaction
   transaction.commit();
Design your own transactions to prevent database deadlocks when multiple transaction instances are running concurrently. For example, avoid running statements similar to the following in parallel:
   UserTransaction transaction= (UserTransaction)intialContext.lookup("jta/usertransaction");
   transaction.begin();
     manager.getTask(tkiid); // read-locks the task
     manager.claim(tkiid);   // write-locks the task to update the state
   transaction.commit();

The following table shows how WebSphere Process Server terms map to WebSphere Integration Developer terms.
WebSphere Process Server WebSphere Integration Developer
participating task to-do task
originating task invocation task
human task collaboration task
administrative task administration task
staff plug-in people directory


IBM WebSphere Application ServerTM
Release 6