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

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.

  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.

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.

  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.

  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.

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.

  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.

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

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.