Starting and Terminating Processes Using the GP API 

Use

Guided Procedures (GP) offers convenient and easy-to-use tools for starting a process in its runtime workset.

Using the GP APIs however, you can also enhance your composite application to enable it to start or terminate another composite built with GP automatically or from a custom user interface.

Prerequisites

·        You have created and activated the process that you want to start.

·        You have set up your project. For more information, see Setting Up Your Project.

Procedure

1. Declare and Implement a Method that Starts a Process

To start a process, you need to call the startProcess() method of the com.sap.caf.eu.gp.process.rt.api.IGPRuntimeManager. It requires the following parameters:

●      An active process template

●      A process instance name

●      A process instance description

●      A process initiator

●      An input parameters structure

●      A user that executes the method (not necessarily the same user as the initiator)

The following steps describe how to instantiate each of the above parameters.

       1.      Declare a method that starts a process.

You must define the process template identifier as a string method parameter.

If you are implementing a Web Dynpro component, you can do it in the component controller, for example.

Declaring the startProcess Method

public void startProcess( java.lang.String processId )   { ... }

       2.      Create an instance of the com.sap.caf.eu.gp.context.api.IGPUserContext interface to identify the process initiator and the user accessing the process template and executing the action.

When using Web Dynpro, you can also retrieve the user that is currently logged on to the application.

Instantiating an IGPUserContext for the Logged-In User

IWDClientUser wdUser = WDClientUser.getCurrentUser(); IUser user = wdUser.getSAPUser(); IGPUserContext userContext = GPContextFactory.getContextManager().createUserContext(user);

To implement a more general approach or to enable users to start processes on behalf of other users, you can retrieve an IUser instance by a logon ID specified dynamically at runtime.

Instantiating an IUser by User ID

IUser user2 = UMFactory.getUserFactory().getUserByLogonID(wdContext.currentContextElement().getLogonId());

       3.      Retrieve the last active version of the process template that you want to instantiate.

You use the process template identifier to search for the template. To be able to start it, you need its active version; therefore as a prerequisite, the template must have been activated at least once. For example, if the process template is currently being edited and its inactive version is 0.2, you retrieve and use the last active version 0.1.

To retrieve the template, you use com.sap.caf.eu.gp.process.dt.api.IGPDesigntimeManager.

The process template identifier is available in the process design time. To check it, launch the GP design time, select the process template in the gallery, open it, and go to the Instantiation tab page.

Retrieving the Last Active Process Template Version

import com.sap.caf.eu.gp.process.api.GPProcessFactory; import com.sap.caf.eu.gp.process.api.IGPProcess; ... public void startProcess( java.lang.String processId )   { ...       // obtain the process template       IGPProcess process =             GPProcessFactory.getDesigntimeManager().getActiveTemplate(             // by specifying its ID             processId,             // and the user accessing it             userContext); ... }

       4.      Create a process role assignments list.

To be able to start the process, you must make sure that a user is assigned to each of the process roles. If at process design time, the role type has been set to Initiator, the framework assigns the initiator to the roles automatically, and you can provide an empty roles list. However, if the role type is set to Initiation Defined, and there are no defaults set, or if you want to change the assignments at instantiation, you must explicitly set the user for each role.

For more information about default assignments and restrictions, see Creating Processes.

You can retrieve the process role number, as well as information about each individual role from the IGPProcess instance that you retrieved in the previous step.

The following code snippet is a simple example that demonstrate how you assign the same user to each process role.

Creating the Role Assignment List

import com.sap.caf.eu.gp.process.api.GPProcessFactory; import com.sap.caf.eu.gp.process.api.IGPProcess; import com.sap.caf.eu.gp.process.rt.api.IGPProcessRoleInstanceList; import com.sap.caf.eu.gp.process.rt.api.IGPRuntimeManager; import com.sap.security.api.IUser;   public void startProcess( java.lang.String processId )   { ...    // retrieve the Runtime Manager    IGPRuntimeManager rtm = GPProcessFactory.getRuntimeManager();    // create an empty role assignment list    IGPProcessRoleInstanceList roles = rtm.createProcessRoleInstanceList();    // get the process role number    int rolenum = process.getRoleInfoCount();    // iterate over the required roles    for (int i = 0; i < rolenum; i++) {       // create a new role instance by specifying the role's unique name       IGPProcessRoleInstance roleInstance = roles. createProcessRoleInstance(process.getRoleInfo(i).getRoleName());       // add a user to the role instance       roleInstance.addUser(roleUser);       // add the new role to the assignment list       roles.addProcessRoleInstance(roleInstance);        } ... }

You can also assign different users to the different process roles. You do this by retrieving and verifying the role name.

For the standard process roles (Administrator, Owner, Overseer), you can use the getAdminRole(), getOwnerRole() and getOverseerRole() methods of the IGPProcess interface.

Assigning Users to the Administrator Role

// get role name       String name = process.getAdminRole().getRoleName();       // create a new role instance       IGPProcessRoleInstance roleInstance = roles. createProcessRoleInstance(name);       // assign the user you want       roleInstance.addUser(adminUser);       //add the new role instance to the assignment list       roles.addProcessRoleInstance(roleInstance);

       5.      Construct the input parameters structure for the process.

If the process that you are instantiating requires certain input parameters, you must construct the input structure and populate it with values. This is not necessary if the process does not expose required input parameters.

You retrieve the information about the input structure from the IGPProcess instance that you already have, and use this information to construct the structure and add attributes to it.

The following example shows how to pre-fill some of the Time-Off Process input parameters with values.

Constructing the Input Structure

import com.sap.caf.eu.gp.structure.api.GPStructureFactory; import com.sap.caf.eu.gp.structure.api.IGPStructure;   public void startProcess( java.lang.String processId )   { ...   params= GPStructureFactory.getStructure(process.getInputParameters());               if (process.getTitle().equals("Time-Off Process")){       IGPStructure struc = params.addStructure("Time_off_data.1");       struc.setAttributeValue("AbsenceTypeText", "Vacation");       struc.setAttributeValue("SimulationCode",0);       struc.setAttributeValue("CompletionCode",0);       struc.setAttributeValue("PaidFlag", true);    } ... }

...

       6.      Once you have instantiated all required parameters, you can call the IGPRuntimeManager’s startProcess() method.

Starting the Process

IGPRuntimeManager rtm = GPProcessFactory.getRuntimeManager();   // initiate the process template by passing the process template IGPProcessInstance prInstance = rtm.startProcess(process, // a name, "My First Process", // a description, "This process has been started using the GP public API", // initiator user, // the role assignments, roles, // the input parameters params, // and the user actually executing this action user);

       7.      Optionally, you can dynamically assign or change users for specific tasks at runtime.

○       You can do this with the methods of the IGPRuntimeManager.

Assigning Users Dynamically

// dynamically assign a user to a role (provide IUser, IGPUserContext) rtm.addRuntimeDefinedUserToRole(prInstance, "Processor", user, userContext); // dynamically change the user assigned to a role for a particular task String prInstanceID = prInstance.getID(); rtm.changeTaskProcessor(                  // process instance ID                  prInstanceID,                  // activity instance ID                  activityInstanceID,                  // current user (IGPUserContext)                  currentProcessorContext,                  // new user (IGPUserContext)                  newProcessorContext);

○       You can also construct a callable object for background execution and overwrite its onExecute() method. In the implementation, you can retrieve the current process role instance from the GP context and assign a user to it.

Assigning Users with a Callable Object for Background Execution

public void onExecute(IExecutionContext context) throws TechnicalCallableObjectException {   IProcessRoleInstance roleInstance = context.getProcessRoleInstance();   // add user to the role   roleInstance.addRuntimeDefinedUser(user); }

2. Implement a Method for Terminating Process Instances

To terminate a process instance, you use the stopProcess() method of the com.sap.caf.eu.gp.process.rt.api.IGPRuntimeManager. It requires the following parameters:

●      A running process instance

●      A user that executes the method

...

       1.      Instantiate the IUser interface as described in the previous section.

       2.      Retrieve the process instance that you want to terminate.

To do that, you need its identifier. You can check the process instance ID in the GP monitoring tool which is integrated in the SAP NetWeaver Administrator, for example. For more information, see Process Instances.

The following example shows how to retrieve and terminate all running process instances that have been started by a specified user (in this case the logged-in user) in a timeframe defined by a start and end date.

Terminating Process Instances

import com.sap.caf.eu.gp.process.api.GPProcessFactory; import com.sap.caf.eu.gp.process.api.IGPProcessInstance; import com.sap.caf.eu.gp.process.api.IGPProcessInstanceInfo; import com.sap.caf.eu.gp.process.rt.api.IGPRuntimeManager; import com.sap.security.api.IUser;   ... public void stopProcess( java.sql.Date startDate, java.sql.Date endDate )   {    //@@begin stopProcess()    IGPRuntimeManager rtm = GPProcessFactory.getRuntimeManager();    try{    IWDClientUser wdUser = WDClientUser.getCurrentUser();    user = wdUser.getSAPUser();    IGPUserContext userContext = GPContextFactory.getContextManager().createUserContext(user);    IGPProcessInstanceInfo[] array = rtm.getRunningInstances(GPSearchRole.SEARCH_ROLE_OWNER, startDate, endDate, userContext);      for (int i=0; i<array.length; i++){       String instanceId = array[i].getProcessInstanceID();       IGPProcessInstance instance = rtm.getProcessInstance(instanceId, userContext);       rtm.stopProcess(instance, userContext);    } ... }