Creating plug-ins to post-process staff query results

Staff resolution returns a list of the users that are assigned to a specific role, for example, potential owner of a task. You can create a plug-in to change the results of staff queries returned by staff resolution. For example, to improve workload balancing, you might have a plug-in that removes users from the query result who already have a high workload.

Why and when to perform this task

You can have only one post-processing plug-in; this means that the plug-in must handle the staff results from all tasks. Your plug-in can add or remove users, or change user or group information. It can also change the result type, for example, from a list of users to a group, or to everybody.

Because the plug-in runs after staff resolution completes, any rules that you have to preserve confidentiality or security have already been applied. The plug-in receives information about users that have been removed during staff resolution (in the HTM_REMOVED_USERS map key). You must ensure that your plug-in uses this context information to preserve any confidentiality or security rules you might have.

To implement post-processing of staff query results, you use the StaffQueryResultPostProcessorPlugin interface. The interface has methods for modifying the query results for tasks, escalations, task templates, and application components.

Complete the following steps to create a plug-in to post-process staff query results.

Steps for this task

  1. Write a class that implements the StaffQueryResultPostProcessorPlugin interface.

    You must implement all of the interface methods. This class can invoke methods of other classes.

    This class runs in the context of a Java 2 Enterprise Edition (J2EE) Enterprise JavaBeans (EJB) application. Ensure that this class and its helper classes follow the EJB specification.

    Tip: 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 results in a database deadlock.
    The following example shows how you might change the editor role of a task called SpecialTask.
    public StaffQueryResult processStaffQueryResult
                             (StaffQueryResult originalStaffQueryResult,
                                               Task task,
                                               int  role,
                                               Map  context) 
    {
      StaffQueryResult newStaffQueryResult = originalStaffQueryResult;
      StaffQueryResultFactory staffResultFactory = 
                              StaffQueryResultFactory.newInstance();
      if (role == com.ibm.task.api.WorkItem.REASON_EDITOR &&
          task.getName() != null && 
          task.getName().equals("SpecialTask")) 
      {
          UserData user = staffResultFactory.newUserData
                               ("SuperEditor",
                                 new Locale("en-US"), 
                                "SuperEditor@company.com");
          ArrayList userList = new ArrayList();
          userList.add(user);  
    
          newStaffQueryResult = staffResultFactory.newStaffQueryResult(userList);
       }  
       return(newStaffQueryResult);
    }  
  2. Assemble the plug-in class and its helper classes into a JAR file.

    If the helper classes are used by several J2EE applications, you can package these classes in a separate JAR file that you register as a shared library.

  3. Create a service provider configuration file for the plug-in in the META-INF/services/ directory of your JAR file.

    The configuration file provides the mechanism for identifying and loading the plug-in. This file conforms to the Java 2 service provider interface specification.

    1. Create a file with the name com.ibm.task.spi.plug-in_nameStaffQueryResultPostProcessorPlugin, where plug-in_name is the name of the plug-in.

      For example, if your plug-in is called MyHandler and it implements the com.ibm.task.spi.StaffQueryResultPostProcessorPlugin interface, the name of the configuration file is com.ibm.task.spi.MyHandlerStaffQueryResultPostProcessorPlugin.

    2. In the first line of the file that is neither a comment line nor a blank line, specify the fully qualified name of the plug-in class that you created in step 1.

      For example, if your plug-in class is called StaffPostProcessor and it is in the com.customer.plugins package, then the first line of the configuration file must contain the following entry: com.customer.plugins.StaffPostProcessor.

      You have an installable JAR file that contains a plug-in that post processes staff query results and a service provider configuration file that can be used to load the plug-in.
  4. Install the plug-in.

    You can have only one post-processing plug-in for staff query results. You must install the plug-in as a shared library.

  5. Register the plug-in.
    1. In the administrative console, go to the Custom Properties page of the human task container (Application servers > server_name > Human task container > Custom properties).
    2. Add a custom property with the name Staff.PostProcessorPlugin, and a value of the name that you gave to your plug-in, MyHandler in this example.

Copyright IBM Corporation 2005, 2006.
This information center is powered by Eclipse technology (http://www.eclipse.org)