IBM WebSphere Application ServerTM
Release 7

com.ibm.task.spi.ppp
Interface StaffQueryResultPostProcessorPlugin2


public interface StaffQueryResultPostProcessorPlugin2

This interface provides methods that allow to modify StaffQueryResult data computed by the people resolution subsystem of Human Task Manager. It is this modified result which is used as result of people assignment for a specific task or escalation role. The interface enables scenarios which require post processing with fine granularity, while optimizing the amount of data to be kept in the database. It is applicable in any of the following scenarios or combinations thereof: A. role specific post processing: specific post processing is to be applied depending on the task / escalation role considered. B. task and escalation template specific post processing: specific post processing is to be applied depending on the task / escalation template considered. C. task and escalation instance specific processing: specific post processing is to be applied depending on every task/escalation instance considered. In cases A. and B., ideally, only one staff query result will be kept in the database per task/escalation template and role. In case C., ideally, one staff query result will be kept in the database per task/escalation instance and role. The interface defines two methods: - processStaffQueryResult - isInstanceSpecific I. The processStaffQueryResult method This method method is used to invoke the custom post processing logic. To facilitate fine-grained post processing decisions, the invocation of this method includes contextual information about: a. the people query specification which corresponds to the modeled people assignment criteria (name, parameters and their values) for a specific role b. the specific role and application context in which the role is to be considered The following post processing contexts are distinguished: 1. Task template context: post processing is provided with information about - the task template concerned - the task template or task instance role concerned (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 concerned - the task instance role concerned (Administrators, Readers, Editors, Potential Starters, Potential Owners) 3. Ad-hoc task instance context: post processing is provided with information about - the task instance concerned and the application component associated with the task instance - the task instance role concerned (Administrators, Readers, Editors, Potential Starters, Potential Owners) 4. Escalation template context: post processing is provided with information about - the escalation and task template concerned - the escalation instance role concerned (Escalation Receivers) 5. Escalation template based (non ad-hoc) escalation instance context: post processing is provided with information about - the escalation instance and escalation and task template - the escalation role concerned (Escalation Receivers) 6. Ad-hoc escalation instance context: post processing is provided with information about - the escalation instance concerned - the application component associated with the escalation instance - the escalation role concerned (Escalation Receivers) 7. Application component context: post processing is provided with information about - the application component concerned - the application component role (Instance Creators) concerned II. The isInstanceSpecific method The custom plugin implementation can control whether or not the instance specific application contexts (2, 5) are employed or not. For this purpose, the interface method isInstanceSpecific is to be implemented accordingly: a. in case post processing shall make decisions on the granularity of (task or escalation) instances, the plugin implementation has to indicate this as result of the isInstanceSpecific method, i.e. return 'true' as value. b. in case post processing shall make decisions on the granularity of task templates only (i.e. the same decision is granted per role for all task / escalation instances associated with the same task template), the plugin implementation has to indicate this as result of the isInstanceSpecific method, i.e. return 'false' as value. Note that above decision can be taken per task template, i.e. 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 run-time to efficiently store results of post processing. If possible, only one post processing result will be stored per role and task template. Note that above decision 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 (3,5) the isInstanceSpecific method will not be invoked, as the result has to be 'true' anyway. III. PostProcessingContext object Both methods are invoked with a PostProcessingContext object. This object allows to retrieve contextual information via getter methods about the concerned assignmentReason, taskTemplate, taskInstance, escalationTemplate, escalationInstance, applicationComponent. See PostProcessingContext The available information in the context object depends on the specific case: The isInstanceSpecific method is always invoked with a context object containing assignmenReason and taskTemplate information. The postProcessStaffQueryResult method is always invoked with assignmentReason and additional information. For the latter see next subsection. IV. Establishing the post processing context in the custom plugin implementation Within a custom implementation of the postProcessStaffQueryResult method use the following algorithm to establish the context: a. assignmentReason is a task template or task role, taskTemplate!=null, task==null -> task template context applies Available information in the context object: assignmentReason, taskTemplate b. assignmentReason is a task template or task role, taskTemplate!=null, task!=null -> task template based (non ad-hoc) task instance context applies Available information in the context object: assignmentReason, taskTemplate, taskInstance c. assignmentReason is a task template or task role, taskTemplate==null, task!=null, applicationComponent!=null -> ad-hoc task instance context applies Available information in the context object: assignmentReason, taskInstance, applicationComponent d. assignmentReason is Instance Creator role, taskTemplate==null, task==null, applicationComponent!=null -> application component context applies (see below, subsection V) Available information in the context object: assignmentReason, applicationComponent e. assignmentReason is an escalation role, escalationTemplate!=null, escalation==null -> escalation template context applies Available information in the context object: assignmentReason, escalationTemplate, taskTemplate f. assignmentReason is an escalation role, escalationTemplate!=null, escalation!=null -> escalation template based (non ad-hoc) escalation instance context applies Available information in the context object: assignmentReason, escalationTemplate, taskTemplate, escalationInstance, taskInstance g. assignmentReason is an escalation role, escalationTemplate==null, escalation!=null, applicationComponent!=null -> ad-hoc escalation instance context applies Available information in the context object: assignmentReason, escalationInstance, taskInstance, applicationComponent V. ApplicationComponent context This context occurs in the following cases: a. Creation of ad-hoc task templates The application component associated with the task template defines authorization for this action via the application component Instance Creators role. b. Creation of ad-hoc task instances The application component associated with the task defines authorization for this action via the application component Instance Creators role. c. Creation of template based task instances In case no Instance Creators role is defined for a task template, a default specification is used. This default is defined for the Instance Creators role of the application component which is associated with the task template. VI. Plugin instantiation and use of static data The post processor plugin is initialized upon server start-up as a singleton. During the life-cycle of the plugin static information can be employed by the custom plugin implmentation. VII. Code sample The sample below sketches the code required 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 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, 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
static java.lang.String COPYRIGHT
           
 
Method Summary
 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.
 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

COPYRIGHT

static final java.lang.String COPYRIGHT
See Also:
Constant Field Values
Method Detail

isInstanceSpecific

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 post processed staff query result will be shared per role across all task / escalation instances which are associated with the same task template. This method is not invoked for ad-hoc task / escalation instances, as for these an instance specific processing is assumed in all cases.

Parameters:
pppContext - The post processing 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

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. It indicates contextual information concerning the people query and the application considered.

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/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".
peopleQueryVariable - 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:

IBM WebSphere Application ServerTM
Release 7