IBM BPM, V8.0.1, All platforms > Programming IBM BPM > Developing client applications for BPEL processes and tasks > Create plug-ins to customize human task functionality > Use a plug-in to post-process people query results

Developing a plug-in using the StaffQueryResultPostProcessorPlugin2 interface

The StaffQueryResultPostProcessorPlugin2 interface provides optimized performance for cases where the post-processing will yield the same result for a specific task role or escalation role across all task instances or escalation instances that are based on the same task template.

When implementing the StaffQueryResultPostProcessorPlugin2 interface, an important performance consideration is the boolean method isInstanceSpecific, which controls how the people query result post-processing for each task template and escalation template is handled.

Template-specific

For each role, the same list of people is returned for all instances, so the post-processing results can be calculated once for the template and used by all instances. Role-based substitution is an example where all task instances can share the same people query post-processing result. This option provides better performance than instance-specific post-processing.

Instance-specific

For each role, different instances require different lists of people to be returned. Workload balancing is an example that requires different people query result post-processing for each task instance. For performance reasons, do not use instance-specific post-processing for templates that could be handled as template-specific.

If you want to call the HumanTaskManagerService interface from this class, do not call a method that updates the task that produced the event. This action might result in inconsistent task data in the database.

Parameters

The StaffQueryResultPostProcessorPlugin2 interface provides the following input parameters to the plug-in:

originalStaffQueryResult

You can use this Map object to get information about the users computed by the built-in staff resolution and substitution.

peopleQuerySpec

This is a Map object, contains the people assignment criteria (PAC) description being considered for the current people assignment. It includes the name, parameter names, and values (all of String type) as specified for a task or escalation role. To access the people assignment criteria name, use the key HTM_VERB_NAME. To access the value of a parameter, use the parameter name as the key, for example groupName.

peopleQueryVariables

This Map object contains the replacement variables that were specified in the people assignment criteria, and their resolved values. To access the values resolved for a replacement variable, use the name of the variable as the key, for example, htm:task.originator. The result is either of type String or String[].

usersRemovedByPeopleQuery

This string array identifies which user IDs were excluded by the people assignment criteria. If these exclusions are imperative, your plug-in can use this list to avoid adding any user IDs that were already excluded.

pppContext

You can use this postProcessingContext object to access information about the application context being considered. Use the corresponding getter methods defined and explained in the class Javadoc.

For example, the assignment reason and the identity of the appropriate template or instance for the current task or escalation. Depending on whether the post-processing is template-specific or instance-specific, this object provides different information to the post-processor for each possible context:

Template-specific contexts:

Each of these contexts provide different information.

Task template

• The task template.

• One of the following work item assignment reasons: Instance creator, administrator, reader, editor, potential starter, or potential owner.

Escalation template

• The escalation template.

• The work item assignment reason: Escalation receiver.

Instance-specific contexts:

Each of these contexts provide different information.

Non ad hoc task instance

• The task template.

• The task instance.

• One of the following work item assignment reasons: Administrator, reader, editor, potential starter, or potential owner.

Ad hoc task instance

• The task instance.

• The application component associated with the task instance.

• One of the following work item assignment reasons: Administrator, reader, editor, potential starter, or potential owner.

Non ad hoc escalation instance

• The task template.

• The task instance.

• The escalation template.

• The escalation instance.

• The work item assignment reason: Escalation receiver.

Ad hoc escalation instance

• The escalation instance.

• The task instance that is associated with the escalation.

• The application component associated with the escalation instance.

• The work item assignment reason: Escalation receiver.

Special case context:

When an ad hoc task template or instance is created and when a task template is created with no instance creator people assignment criteria, then the authorization is based on the instance creator role for the associated application component.

Application component

• The application component.

• The work item assignment reason: Instance creator.

The assignment reasons are indicated by the corresponding roles.

Example: StaffQueryResultPostProcessorPlugin2 implementation

The following example illustrates an implementation of the StaffQueryResultPostProcessorPlugin2 interface with a user substitution that depends on the task role.

package com.ibm.task.spi.ppp;

import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;

import com.ibm.task.api.WorkItem;
import com.ibm.task.spi.StaffQueryResult;
import com.ibm.task.spi.StaffQueryResultFactory;
import com.ibm.task.spi.UserData;

public class MyStaffResultProcessor implements
        StaffQueryResultPostProcessorPlugin2
{
    public boolean isInstanceSpecific(PostProcessingContext pppContext)    {
        // post processing logic is not depending on task/escalation
        // instance specifics
        return false;
    } 
    // post processing method providing for user substitution that are     // in the Potential Owner role
    public StaffQueryResult processStaffQueryResult(
            StaffQueryResult originalStaffQueryResult,             Map peopleQuerySpec,             Map peopleQueryVariable,             String[] usersRemovedByPeopleQuery,             PostProcessingContext pppContext)    {

        StaffQueryResult newStaffQueryResult = null;
        int assignmentReason = pppContext.getAssignmentReason();

        // apply people substitution for potential owners
        switch (assignmentReason)
        {
        case WorkItem.REASON_POTENTIAL_OWNER:
            newStaffQueryResult = substitutePotentialOwners(originalStaffQueryResult);
            break;
        default:
            newStaffQueryResult = originalStaffQueryResult;
        } 
        return newStaffQueryResult;
    } 
    // method providing for substitution logic for users in the Potential Owner
    // role
    private StaffQueryResult substitutePotentialOwners(
            StaffQueryResult originalStaffQueryResult)    {
        StaffQueryResult newStaffQueryResult = originalStaffQueryResult;
        StaffQueryResultFactory staffResultFactory = StaffQueryResultFactory
                .newInstance();

        Map userDataMap = originalStaffQueryResult.getUserDataMap();
        Map newUserDataMap = new HashMap();
        Iterator iterator = userDataMap.keySet().iterator();

        while (iterator.hasNext())
        {
            String originalUserId = (String) iterator.next();

            // a real substitution logic would contain a lookup, for example in a database,             // an LDAP directory             String substituteUserId = null;
            if (originalUserId.equals("Edward"))
            {
                substituteUserId = "Bob";
            }             else if (originalUserId.equals("Jack"))
            {
                substituteUserId = "John";
            } 
            UserData substituteUserData = staffResultFactory.newUserData(
                    substituteUserId,                     null,                     null);

            // include the substitute
            newUserDataMap.put(substituteUserId, substituteUserData);
        } 
        if (newUserDataMap.size() > 0)
        {
            // create a new StaffQueryResult including the map
            newStaffQueryResult = StaffQueryResultFactory.newInstance()
                    .newStaffQueryResult(newUserDataMap);
        } 
        return newStaffQueryResult;
    } }

For more information about this interface, see the Javadoc.

Use a plug-in to post-process people query results

Related concepts:
People query result post-processing plug-in
Developing a plug-in using the StaffQueryResultPostProcessorPlugin interface
Replacement variables in human tasks

Related information:

Sample: People assignment customization using the Post Processor Plugin