com.ibm.task.spi.ppp

Interface StaffQueryResultPostProcessorPlugin2


  1. public interface StaffQueryResultPostProcessorPlugin2
This interface allows for the modification of StaffQueryResult data that is computed by the people resolution subsystem of the Human Task Manager. The modified StaffQueryResult data is then used as people assignment for a specific task or escalation role.

Using this functionality enables scenarios which require post processing with fine granularity, while optimizing the amount of data kept in the database. It is applicable in any of the following scenarios or combinations thereof:

  1. Role specific post processing: specific post processing is to be applied depending on the task or escalation role considered.
  2. Task and escalation template specific post processing: specific post processing is to be applied depending on the task or escalation template considered.
  3. Task and escalation instance specific processing: specific post processing is to be applied depending on every task or escalation instance considered.

For role specific or task and escalation template specific post processing, ideally, one staff query result is stored in the database per task or escalation template and role.

For task and escalation instance specific post processing, ideally, one staff query result is stored in the database per task or escalation instance and role.

This interface exposes two methods:

The processStaffQueryResult method

This method method invokes the custom post processing logic. To facilitate fine-grained post processing decisions, the invocation of this method includes contextual information about:

Following post processing contexts are distinguished:

  1. Task template context: post processing is provided with information about
    • The task template
    • The task template or task instance role (instance creators, administrators, readers, editors, potential starters, potential owners)
  2. Task template based (non ad-hoc) task instance context: post processing is provided with information about
    • The task instance and task template
    • The task instance role (administrators, readers, editors, potential starters, potential owners)
  3. Ad-hoc task instance context: post processing is provided with information about
    • The task instance and the application component associated with the task instance
    • The task instance role (administrators, readers, editors, potential starters, potential owners)
  4. Escalation template context: post processing is provided with information about
    • The escalation and task template
    • The escalation instance role (escalation receivers)
  5. Escalation template based (non ad-hoc) escalation instance context: post processing is provided with information about
    • The escalation instance and the escalation and task templates
    • The escalation role (escalation receivers)
  6. Ad-hoc escalation instance context: post processing is provided with information about
    • The escalation instance
    • The application component associated with the escalation instance
    • The escalation role (escalation receivers)
  7. Application component context: post processing is provided with information about
    • The application component
    • The application component role (instance creators)

The isInstanceSpecific method

The custom plugin implementation can control whether the instance specific application contexts (task template based (non ad-hoc) task instance based context, escalation template based (non ad-hoc) escalation instance context) are applied or not. For this purpose, the isInstanceSpecific method is to be implemented accordingly:

Note that these decisions can be taken per task template, that is, the plugin implementation can be instance specific in the context of one task template and instance agnostic in the context of another task template.

The result of the isInstanceSpecific method is exploited by the Human Task Manager runtime to efficiently store results of post processing. If possible, only one post processing result will be stored per role and task template.

Also note that these decisions can be taken only if a task template exists as a common context. In case of ad-hoc task or escalation instances this is not the case. Therefore, for ad-hoc contexts (ad-hoc task instance context, ad-hoc escalation instance context), the isInstanceSpecific method is not invoked since the result has to be 'true' anyway.

The PostProcessingContext object

Both methods are invoked passing a PostProcessingContext object. This object allows to retrieve contextual information about the assignment reason, the task template, task instance, escalation template, escalation instance, and the application component. See PostProcessingContext for more information.

The information available in the post processing context object depends on the method call.

Establishing the Post Processing Context in the Custom Plugin Implementation

Establish the PostProcessingContext in the implementation of the postProcessStaffQueryResult method as follows:

The ApplicationComponent context

This context is applicable in the following cases:

Plugin instantiation and use of static data

The post processor plugin is initialized upon server startup as a singleton. During the life cycle of the plugin, static information can be employed by the custom plugin implementation.

Code example

The following example illustrates the code for a role specific and instance and template agnostic custom plugin implementation:

 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 peopleQueryVariables,
           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, e.g. in a DB, 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;
   }
 }
 
Since:
7.0.0.2
Version:
7.0.0.2

Field Summary

Modifier and Type Field and Description
  1. static
  2. java.lang.String
COPYRIGHT

Method Summary

Modifier and Type Method and Description
  1. boolean
isInstanceSpecific(PostProcessingContext pppContext)
This method is called to determine whether or not post processing is to be applied on a per task or escalation instance basis.
  1. StaffQueryResult
processStaffQueryResult(StaffQueryResult originalStaffQueryResult,java.util.Map peopleQuerySpec,java.util.Map peopleQueryVariables,java.lang.String[] usersRemovedByPeopleQuery,PostProcessingContext pppContext)
This method is called for post processing the staff query result computed by the built-in people resolution of Human Task Manager.

Field Detail

  1. static final java.lang.String COPYRIGHT
See Also:

Method Detail

isInstanceSpecific

  1. boolean isInstanceSpecific(PostProcessingContext pppContext)
This method is called to determine whether or not post processing is to be applied on a per task or escalation instance basis. In case processing is not instance specific, the modified staff query result is shared per role across all task and escalation instances which are associated with the same task template.

This method is not invoked for ad-hoc task or escalation instances because for these instances an instance specific processing is assumed in all cases.

Parameters:
pppContext - The post processing context object to be used. The context contains a task template object. See PostProcessingContext.
Returns:
true, if post processing is instance specific for the indicated context, otherwise, false is returned.

processStaffQueryResult

  1. StaffQueryResult processStaffQueryResult( StaffQueryResult originalStaffQueryResult,
  2. java.util.Map peopleQuerySpec,
  3. java.util.Map peopleQueryVariables,
  4. java.lang.String[] usersRemovedByPeopleQuery,
  5. PostProcessingContext pppContext)
This method is called for post processing the staff query result computed by the built-in people resolution of Human Task Manager.
Parameters:
originalStaffQueryResult - The staff query result computed by the built-in people resolution.
peopleQuerySpec - The people assignment criteria (PAC) description considered for the current people assignment including name, parameter names and values (all of String type) as specified for a task or escalation role. To access the PAC name, use in the map the key HTM_VERB_NAME. To access the value of a parameter use in the map the parameter name as key, e.g. "groupName".
peopleQueryVariables - The map of replacement variables and their resolved values. The resolved value(s) can be of type String or String[]. Contained are the replacement variables specified in the people assignment criteria considered. To access the values resolved for a replacement variable, use in the map the name of the variable as key, e.g. "htm:task.originator" .
usersRemovedByPeopleQuery - The array of user IDs excluded by the specified people assignment criteria. The exclusions may be imperative and therefore to be considered explicitly, in order to avoid accidental re-inclusion via post processing.
pppContext - The postProcessingContext object to determine the assignment reason and application context being considered. The context can contain information about the task template, task instance, escalation template, escalation instance, application component considered. For access details, see PostProcessingContext.
Returns:
StaffQueryResult The modified staff query result.