Completing Actions Using the GP API

Use

The Guided Procedures (GP) framework completes actions when the underlying callable objects indicate that their processing is finished. Using the GP API, you can implement your own logic for triggering action completion outside the GP framework. For example, you can use such functionality if an error prevents the action from completing normally and the process from advancing as it should.

Prerequisites

You must have configured your project. For more information, see Setting Up Your Project .

Procedure

Instantiate a
```
com.sap.caf.eu.gp.context.api.
```
IGPUserContext object.
You need the IGPUserContext instance to authenticate the user who is trying to complete the action. In Web Dynpro you can create the object for the logged-in user. Another option is to use the security API and retrieve the user by his or her logon ID.

Example

Instantiating IGPUserContext for the Logged-In User in Web Dynpro
IUserloggedUser = WDClientUser.getCurrentUser().getSAPUser(); IGPUserContext userContext = GPContextFactory.getContextManager().createUserContext(loggedUser);

Create an action completion data object.
It is a com.sap.caf.eu.gp.process.rt.api.IGPActionCompletionData interface instance. The completion data object is used as a placeholder for all data that needs to be passed to the process context after the action has been completed - output parameters and result states, for example.

The completion data object constructor requires the process and the task IDs, as well as a user context as parameters.

Note

The process and task identifiers are strings, which you can check in the process URL if you start the GP runtime outside the portal. You start the runtime using the following URL: http:// <host> : <port> /webdynpro/dispatcher/sap.com/caf~eu~gp~ui~rtwc/WorkCenterRunTime

Example

Creating an IGPActionCompletionData Instance

importcom.sap.caf.eu.gp.process.rt.api.IGPActionCompletionData;

importcom.sap.caf.eu.gp.process.rt.api.IGPRuntimeManager;

...

publicvoid onActionStopAction(com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent )

...

StringprocessID = wdContext.currentContextElement().getProcessID();

StringactionID = wdContext.currentContextElement().getActionID();

IGPActionCompletionDatacompletionData = rtManager.createActionCompletionData(processID, actionID, userContext);

...

If the action that you are completing exposes output parameters, you must fill the output structure with values, so that the output can be used in the next process steps if required.
To retrieve the root output structure, use the completion data object's getOutputParameters() method. Then you can set the individual attribute values.

Example

Populating the Output Structure with Values

IGPStructurestruct = completionData.getOutputStructure();

         struct.setAttributeValue("name", wdContext.currentContextElement().getName());

         struct.setAttributeValue("address", wdContext.currentContextElement().getAddress());

Example

Retrieving Information about Action's Parameters, Result States, or Process Exceptions

IGPActionInstanceinstance =

         rtManager.getActionInstance(processID, actionID, userContext);

if(instance.getTemplate().isAction()){

//the action template

IGPActionaction = (IGPAction) instance.getTemplate();

//a collection of IGPAttributeInfo objects

Collectionoutput = action.getOutputParameters().getAttributes();

Iteratoritr = output.iterator();

while(itr.hasNext()){

      IGPAttributeInfo attr = (IGPAttributeInfo)itr.next();

      String name = attr.getTechName();

      int type = attr.getType();

...

//an array of IGPResultStateInfo objects

IGPResultStateInfo[]states = action.getResultStates();

for(int i=0; i<states.length; i++){

   String resultState = states[i].getName();

...

Set the action completion status.
You can end an action using one of the following statuses:
- RESULT_STATE_COMPLETED_DONE_ONLY - indicates that the action has been completed; a result state is not set
- RESULT_STATE_COMPLETED_RESULTSTATE - indicates that the action has been completed with a particular result state; if you use this status, you must explicitly set one of the result states available for the action
- RESULT_STATE_COMPLETED_PROCESS_EXCEPTION - indicates that the action has been completed with a process exception; you can set this status to manage the process flow using the configured exception handler at block level. For more information, see Configuring Exception Handling in the Power User's Guide.
- RESULT_STATE_COMPLETED_TECHNICAL_EXCEPTION - indicates that the action has been completed with an error that requires the process execution to be terminated; when completing the action with a technical exception, the output parameters are not stored in the process context.
  
  Note
  
  You can retrieve the exact result state and process exception names as described for the attributes' names and types in the previous step.

Example

Setting the Completion Status
completionData.setState( IGPActionCompletionData.RESULT_STATE_COMPLETED_DONE_ONLY);

Set the action type.
An action is either executed in the background, or exposes a user interface. For example, actions encapsulating composite forms are handled in the background, while those created for Web Dynpro callable objects are visual.

The GP framework handles the two action types differently so you must set the type explicitly.

Example

Setting the Action Type
completionData.setType(IGPActionCompletionData.ACTIVITY_TYPE_USER);

Finally, to complete the action, you call the GP runtime manager's completeAction() method, passing the action completion data as a parameter.

Example

Completing the Action
rtManager.completeAction(completionData);

Result

The action is completed, and the process execution either continues, or the process state is set to erroneous if you have completed the action with a technical exception.