Starting and Terminating Processes Using the GP API

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.

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

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.

publicvoid startProcess( java.lang.String processId )

  {

...

}

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

IWDClientUserwdUser = 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.

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

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

   Tip

   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.

importcom.sap.caf.eu.gp.process.api.GPProcessFactory;

importcom.sap.caf.eu.gp.process.api.IGPProcess;

...

publicvoid 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);

...

}

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

importcom.sap.caf.eu.gp.process.api.GPProcessFactory;

importcom.sap.caf.eu.gp.process.api.IGPProcess;

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

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

importcom.sap.security.api.IUser;

publicvoid 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

      IGPProcessRoleInstanceroleInstance = 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.

      // get role name

      String name = process.getAdminRole().getRoleName();

     // create a new role instance

      IGPProcessRoleInstanceroleInstance = roles. createProcessRoleInstance(name);

     // assign the user you want

      roleInstance.addUser(adminUser);

     //add the new role instance to the assignment list

      roles.addProcessRoleInstance(roleInstance); 

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

importcom.sap.caf.eu.gp.structure.api.GPStructureFactory;

importcom.sap.caf.eu.gp.structure.api.IGPStructure;

publicvoid 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);

   }

...

}

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

IGPRuntimeManagerrtm = 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);

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

importcom.sap.caf.eu.gp.process.api.GPProcessFactory;

importcom.sap.caf.eu.gp.process.api.IGPProcessInstance;

importcom.sap.caf.eu.gp.process.api.IGPProcessInstanceInfo;

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

importcom.sap.security.api.IUser;

...

publicvoid 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);

   }

...

}