com.ibm.workflow.api
Interface WorkItem

All Superinterfaces:
Item

public interface WorkItem
extends Item


Method Summary
 ActivityInstance activityInstance()
          This API call retrieves the activity instance the work item is associated to from the MQ Workflow execution server (action call).
 Type activityKind()
          Returns the kind of the associated activity instance, whether it is a program or process and so on.
 void cancelCheckOut()
          This API call cancels the checkout of the work item (action call).
 void checkIn(ReadWriteContainer outContainer, int returnCode)
          This API call allows for the check in of a work item that was previously checked out for user processing (action call).
 ReadOnlyContainer checkOut()
          This API call checks out a ready work item for user processing (action call).
 ProgramData checkOut2(ProgramRetrieval requestedData, Basis platform)
          See checkOut; additionally allows for specifying which program definitions to retrieve.
 FmcError errorReason()
          Returns an error object describing the reason why the associated activity instance is in state InError.
 java.lang.String exitCondition()
          Returns the exit condition of the work item.
 java.util.Calendar expirationTime()
          Returns the expiration time of the work item.
 void finish()
          This API call ends the execution of a manual-exit work item (action call).
 java.util.Calendar firstNotificationTime()
          Returns the time the first notification for the work item is to occur or has occurred.
 void forceFinish()
          This API call ends the execution of a work item which is known to have completed (action call).
 void forceFinish2(Container outputContainer)
          See forceFinish(); allows for the specification of an output container.
 void forceRestart()
          This API call forces MQ Workflow to enable the restart of a work item (action call).
 void forceRestart2(Container inputContainer)
          See forceRestart(); allows for the specification of an input container.
 java.lang.String implementation()
          Returns the name of the implementing program of the associated activity instance.
 ReadOnlyContainer inContainer()
          This API call retrieves the input container associated with the work item from the MQ Workflow execution server (action call).
 boolean manualExitMode()
          Returns whether the exit mode
 boolean manualStartMode()
          Returns whether the start mode of the work item is manual.
 ReadWriteContainer outContainer()
          This API call retrieves the output container associated with the work item from the MQ Workflow execution server (action call).
 java.lang.String persistentOidOfActivityInstance()
          Returns the object ID of the associated activity instance.
 int priority()
          Returns the priority of the work item.
 void restart()
          This API call asks MQ Workflow to enable the restart of a work item (action call).
 java.util.Calendar secondNotificationTime()
          Returns the time the second notification for the work item is to occur or has occurred.
 java.lang.String[] staff()
          Returns all persons owning a work item
 void start()
          This API call starts a ready work item (action call).
 java.lang.String startCondition()
          Returns the start condition of the work item.
 void startTool(java.lang.String toolName)
          This API call starts the specified support tool (action call).
 ExecutionState state()
          Returns the state of the work item.
 Escalation stateOfNotification()
          Returns the notification state of the work item.
 java.lang.String[] supportTools()
          Returns the support tools associated with the work item.
 void terminate()
          This API call terminates a work item implemented by a program or process (action call).
 
Methods inherited from interface com.ibm.workflow.api.Item
category, creationTime, delete, description, documentation, endTime, icon, inContainerName, isComplete, isEmpty, kind, lastModificationTime, name, obtainProcessMonitor, outContainerName, owner, persistentOid, persistentOidOfProcessInstance, processAdmin, processInstance, processInstanceName, processInstanceState, processInstanceSystemGroupName, processInstanceSystemName, receivedAs, receivedTime, refresh, setDescription, setName, startTime, transfer
 

Method Detail

activityKind

public Type activityKind()
                  throws FmcException
Returns the kind of the associated activity instance, whether it is a program or process and so on.

Throws:
FmcException - thrown if an API error or a communication error occurred.

errorReason

public FmcError errorReason()
                     throws FmcException
Returns an error object describing the reason why the associated activity instance is in state InError.

Throws:
FmcException - thrown if an API error or a communication error occurred.

exitCondition

public java.lang.String exitCondition()
                               throws FmcException
Returns the exit condition of the work item.

Throws:
FmcException - thrown if an API error or a communication error occurred.

expirationTime

public java.util.Calendar expirationTime()
                                  throws FmcException
Returns the expiration time of the work item.

Throws:
FmcException - thrown if an API error or a communication error occurred.

firstNotificationTime

public java.util.Calendar firstNotificationTime()
                                         throws FmcException
Returns the time the first notification for the work item is to occur or has occurred.

Throws:
FmcException - thrown if an API error or a communication error occurred.

implementation

public java.lang.String implementation()
                                throws FmcException
Returns the name of the implementing program of the associated activity instance.

Throws:
FmcException - thrown if an API error or a communication error occurred.

manualExitMode

public boolean manualExitMode()
                       throws FmcException
Returns whether the exit mode

of the work item is manual.

Throws:
FmcException - thrown if an API error or a communication error occurred.

manualStartMode

public boolean manualStartMode()
                        throws FmcException
Returns whether the start mode of the work item is manual.

Throws:
FmcException - thrown if an API error or a communication error occurred.

persistentOidOfActivityInstance

public java.lang.String persistentOidOfActivityInstance()
                                                 throws FmcException
Returns the object ID of the associated activity instance.

Throws:
FmcException - thrown if an API error or a communication error occurred.

priority

public int priority()
             throws FmcException
Returns the priority of the work item.

Throws:
FmcException - thrown if an API error or a communication error occurred.

secondNotificationTime

public java.util.Calendar secondNotificationTime()
                                          throws FmcException
Returns the time the second notification for the work item is to occur or has occurred.

Throws:
FmcException - thrown if an API error or a communication error occurred.

staff

public java.lang.String[] staff()
                         throws FmcException
Returns all persons owning a work item

for the associated activity instance.

Throws:
FmcException - thrown if an API error or a communication error occurred.

startCondition

public java.lang.String startCondition()
                                throws FmcException
Returns the start condition of the work item.

Throws:
FmcException - thrown if an API error or a communication error occurred.

state

public ExecutionState state()
                     throws FmcException
Returns the state of the work item.

Throws:
FmcException - thrown if an API error or a communication error occurred.

stateOfNotification

public Escalation stateOfNotification()
                               throws FmcException
Returns the notification state of the work item.

Throws:
FmcException - thrown if an API error or a communication error occurred.

supportTools

public java.lang.String[] supportTools()
                                throws FmcException
Returns the support tools associated with the work item.

Throws:
FmcException - thrown if an API error or a communication error occurred.

activityInstance

public ActivityInstance activityInstance()
                                  throws FmcException

This API call retrieves the activity instance the work item is associated to from the MQ Workflow execution server (action call).

All information about the activity instance, primary and secondary, is retrieved.

Throws:
FmcException - thrown if an API error or a communication error occurred.

cancelCheckOut

public void cancelCheckOut()
                    throws FmcException

This API call cancels the checkout of the work item (action call).

The work item must have been checked out and is put into the Ready state. The associated process instance must be in the Running, Suspending, Suspended, or Terminating state.

Note that all sibling work items set into the Disabled state by the previous Checkout() request are also reset into the Ready state.

Throws:
FmcException - thrown if an API error or a communication error occurred.

checkIn

public void checkIn(ReadWriteContainer outContainer,
                    int returnCode)
             throws FmcException

This API call allows for the check in of a work item that was previously checked out for user processing (action call).

The work item must be in the CheckedOut state and the associated process instance must be in the Running or Suspending state.

Checking in a work item tells MQ Workflow that user processing has finished and workflow processing under the control of MQ Workflow can continue. The return code of the user processing and, optionally, the output container values are passed back to MQ Workflow. As usual, these container values and the return code can be used in exit conditions to let navigation continue depending on the success of the processing and in transition conditions to indicate how to proceed. The return code is automatically set into the _RC data member of the output container if this field has not been set explicitly.

When an output container is specified, then that container must be a valid container for the work item, that is, it must contain the correct schema and version definitions. In other words, it must be the (updated) output container retrieved with the CheckOut() request or the output container retrieved for the work item, and so on.

Throws:
FmcException - thrown if an API error or a communication error occurred.

checkOut

public ReadOnlyContainer checkOut()
                           throws FmcException

This API call checks out a ready work item for user processing (action call).

The work item must be implemented as a program and be in the Ready state. The associated process instance must be in the Running state.

Checkout then means that processing is not done by MQ Workflow's inherent program-invocation mechanism. MQ Workflow assumes that processing is done by user-specific means and changes the state of the work item to CheckedOut.

The caller can request program definitions for specific operating system platforms. The following class can be used to specify the requested program data: ProgramRetrieval

The following class can be used to specify the platform for which program definitions are to be retrieved: Basis

Throws:
FmcException - thrown if an API error or a communication error occurred.

checkOut2

public ProgramData checkOut2(ProgramRetrieval requestedData,
                             Basis platform)
                      throws FmcException
See checkOut; additionally allows for specifying which program definitions to retrieve.

Throws:
FmcException - thrown if an API error or a communication error occurred.

finish

public void finish()
            throws FmcException

This API call ends the execution of a manual-exit work item (action call).

The work item must be in state Executed, that is, must have run at least once. The work item is then put into the Finished state. Depending on the "delete finished items" option, it is deleted.

Throws:
FmcException - thrown if an API error or a communication error occurred.

forceFinish

public void forceFinish()
                 throws FmcException

This API call ends the execution of a work item which is known to have completed (action call).

A work item implemented by a program must be in the states Ready, Running, Executed, CheckedOut, InError, Terminating, or Terminated. A work item implemented by a process must be in the states Ready, Executed, InError, or Terminated. The associated process instance must be in the states Running, Suspending, Suspended, or Terminating.

Optionally, an output container can be specified to denote the result of processing. If none is specified, the output container available at the execution server is taken. For example, the output container defined with initial values.

The work item is then put into the ForceFinished state. The exit condition is considered to be true and navigation proceeds.

Depending on the "delete finished items" option, the work item is deleted.

Throws:
FmcException - thrown if an API error or a communication error occurred.

forceFinish2

public void forceFinish2(Container outputContainer)
                  throws FmcException
See forceFinish(); allows for the specification of an output container.

Throws:
FmcException -  

forceRestart

public void forceRestart()
                  throws FmcException

This API call forces MQ Workflow to enable the restart of a work item (action call).

A work item implemented by a program must be in states Ready, Running, Executed, CheckedOut, InError, Terminating, or Terminated. A work item implemented by a process must be in states Ready, Executed, InError, or Terminated. The associated process instance must be in states Running, Suspending, or Suspended.

Optionally, an input container can be specified to denote the input to be used for restarting the work item. If none is specified, the input container available at the execution server is taken.

The work item is then reset into the Ready state. Note that automatic activity instances must now be started manually.

Throws:
FmcException - thrown if an API error or a communication error occurred.

forceRestart2

public void forceRestart2(Container inputContainer)
                   throws FmcException
See forceRestart(); allows for the specification of an input container.

Throws:
FmcException - thrown if an API error or a communication error occurred.

inContainer

public ReadOnlyContainer inContainer()
                              throws FmcException

This API call retrieves the input container associated with the work item from the MQ Workflow execution server (action call).

Throws:
FmcException - thrown if an API error or a communication error occurred.

outContainer

public ReadWriteContainer outContainer()
                                throws FmcException

This API call retrieves the output container associated with the work item from the MQ Workflow execution server (action call).

Throws:
FmcException - thrown if an API error or a communication error occurred.

restart

public void restart()
             throws FmcException

This API call asks MQ Workflow to enable the restart of a work item (action call).

The work item must be in state Executed. It is then reset into the Ready state.

Throws:
FmcException - thrown if an API error or a communication error occurred.

start

public void start()
           throws FmcException

This API call starts a ready work item (action call).

The associated process instance must be in the Running state.

If the associated activity instance is implemented by a program, the program is started on the program execution agent associated to the logged-on user.

The work item is put into the Running state. If the activity implementation or an associated process activity cannot be started, the work item is put into the InError state.

Throws:
FmcException - thrown if an API error or a communication error occurred.

startTool

public void startTool(java.lang.String toolName)
               throws FmcException

This API call starts the specified support tool (action call).

The support tool must be one of the tools associated to the activity instance the work item is derived from. It is then started on the program execution agent associated to the logged-on user.

Throws:
FmcException - thrown if an API error or a communication error occurred.

terminate

public void terminate()
               throws FmcException

This API call terminates a work item implemented by a program or process (action call).

If the work item is implemented by a program, it must be in the states CheckedOut or Running and the process instance must be in the states Running, Suspending, or Suspended. If the work item is implemented by a process, it must be in the states Running, Suspending, or Suspended and the process instance must be in the states Running, Suspending, Suspended, or Terminating.

When the work item is implemented by a program and processed under the control of a program execution agent or user-defined program execution server, a message is sent to inform about the termination request. The program execution agent tries to kill fenced activity implementations.

A work item implemented by a process is terminated together with all its non-autonomous subprocesses with respect to control autonomy.

The work item is then put into the Terminating or Terminated state.

When the Terminated state has been reached, the exit condition is considered to be false, the output container and especially the return code (_RC) are not set, and navigation ends. Navigation can be explicitly continued by a user with process administration rights, that is, ForceFinish() or ForceRestart() repair actions can be called.

Throws:
FmcException - thrown if an API error or a communication error occurred.


© Copyright IBM Corporation 1999, 2008. All Rights Reserved.