Completing Actions Using the GP API (SAP Library - SAP NetWeaver Composition Environment Library)

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

1. Instantiate a com.sap.caf.eu.gp.context.api.IGPUserContext object.

You need the IGPUserContextinstance 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

IUser loggedUser = WDClientUser.getCurrentUser().getSAPUser();

IGPUserContext userContext = GPContextFactory.getContextManager().createUserContext(loggedUser);

2. 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

import com.sap.caf.eu.gp.process.rt.api.IGPActionCompletionData;

import com.sap.caf.eu.gp.process.rt.api.IGPRuntimeManager;

...

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

{

...

String processID = wdContext.currentContextElement().getProcessID();

String actionID = wdContext.currentContextElement().getActionID();

IGPActionCompletionData completionData = rtManager.createActionCompletionData(processID, actionID, userContext);

...

}

3. 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

IGPStructure struct = completionData.getOutputStructure();

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

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

Note

The attributes’ technical names and types must match exactly the ones that have been defined for the action at design time. You can also retrieve this information using the GP interfaces. Using the process and action identifiers, you can retrieve the action instance from the GP runtime manager and then get the action template. It contains the object’s metadata and enables you to retrieve information about the action’s output parameters, result states, and process exceptions.

Example

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

IGPActionInstance instance =

rtManager.getActionInstance(processID, actionID, userContext);

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

//the action template

IGPAction action = (IGPAction) instance.getTemplate();

//a collection of IGPAttributeInfo objects

Collection output = action.getOutputParameters().getAttributes();

Iterator itr = 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();

...

}

4. 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);

5. 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);

6. 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.