Managing Runtime Activities Using the GP API

Once you instantiate a Guided Procedures (GP) process, you can access and modify it at runtime, adding flexibility and complexity to the workflow. Using the GP runtime API, you can:

• Retrieve the input and output context of process, block and action instances

  The context is the structure of all current attribute values assigned to the parameters defined for the activity instance. You can use context information for display purposes, troubleshooting or logic control.

• Dynamically assign or change task processors

  If you cannot determine the task processor at design time, or you have changed your decision at runtime, you can dynamically assign a different user to a specific process role or task.

To be able to manage and modify runtime activities, you must have access to a running process started previously.

More information: Starting and Terminating Processes Within a Composite

Retrieving Input and Output Activity Context

1. Instantiate the IGPRuntimeManager if you have not done so already.
   Note

   You can place the code for retrieving activity context in a separate method, so that you are able to reuse it easily. The example code fragments below reside in the processInstanceContext() method and illustrate one possible way to access the input and output context of a process instance.

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

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

...

publicvoidprocessInstanceContext(java.sql.Date startDate, java.sql.Date endDate) {

   IGPRuntimeManagerrtm = GPProcessFactory.getRuntimeManager();

...  

1. Retrieve one or more process instances using the methods available in the GP API.

   The example shows you how to access all process instances belonging to the current user. From all available running instances, you have to retrieve the ones for which the user is assigned to the Owner process role.

importcom.sap.security.api.IUser;

importcom.sap.tc.webdynpro.services.sal.um.api.IWDClientUser;

importcom.sap.tc.webdynpro.services.sal.um.api.WDClientUser;

importcom.sap.caf.eu.gp.context.api.IGPUserContext;

importcom.sap.caf.eu.gp.context.api.GPContextFactory;

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

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

try{

  // create a user and user context - current user

   IWDClientUser wdUser = WDClientUser.getCurrentUser();     

   IUser user = wdUser.getSAPUser();  

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

   // get all process instances belonging to the current user  

   IGPProcessInstanceInfo[] instances = rtm.getRunningInstances(GPSearchRole.SEARCH_ROLE_OWNER, startDate, endDate, userContext);

...

1. Retrieve the context of the process instance or the context of its blocks and actions.
   Note

   You can find the

   getInputContext()getOutputContext()

   and methods in the IGPActivityInstance interface. Both of them return the instance context in an IGPStructure . If a parameter in the context is NULL, the value of its attribute is empty.

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

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

...

   // for each process instance

   for(inti=0; i<instances.length; i++){

      // get information about the instance

      String instanceId = instances[i].getProcessInstanceID();

      IGPProcessInstance instance = rtm.getProcessInstance(instanceId, userContext);

      // retrieve process input and output context

      IGPStructure processInputInstance = instance.getInputContext();

      IGPStructure processOuputInstance = instance.getOutputContext();

      //do something

   }

}

catch(Exception e) {...}

Assigning and Changing Users Dynamically

If required, you can dynamically assign users for specific tasks at runtime.

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

// dynamically assign a user to a role (provide IUser, IGPUserContext)

rtm.addRuntimeDefinedUserToRole(prInstance, "Processor", user, userContext);

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

public voidonExecute(IExecutionContext context)throwsTechnicalCallableObjectException {

  IProcessRoleInstance roleInstance = context.getProcessRoleInstance();

  // add user to the role   roleInstance.addRuntimeDefinedUser(user);

}

To change task processors dynamically, use the following method:

// dynamically change the user assigned to a role for a particular task

StringprInstanceID= prInstance.getID();

rtm.changeTaskProcessor(

                 // process instance ID

                prInstanceID,

                 // activity instance ID

                activityInstanceID,

                 // current user (IGPUserContext)

                currentProcessorContext,

                 // new user (IGPUserContext)

                newProcessorContext);

You can provide a null value for the current user argument as long as only one processor has been assigned to this task previously. Otherwise, the method call results in a GPInvocationException.