Administration and Configuration Guide For Human Tasks

Writing Your Own PeopleQueryEvaluator

The default people query evaluator class in WSO2 BPS 3.1.0 is based on the Carbon User Manager API. But if you wish you use a different people query evaluator mechanism, it is possible to plug in a different class which implements an interface in the human task core package. In order to write your people query evaluator you'll need to write a Java class implementing org.wso2.carbon.humantask.core.engine.PeopleQueryEvaluator. You can find the relevant JARs having this interface in the BPS_HOME/repository/component/plugins folder.

An outline of the methods to be implemented is given below.

public interface PeopleQueryEvaluator {
    /**
     * Check whether if the given username exist in the user store.
     *
     * @param userName : The user name to be checked.
     * @return : true if the user exist.
     */
    boolean isExistingUser(String userName);

    /**
     * Check whether if the given roleName exists in the user store.
     *
     * @param roleName : The roleName to be checked.
     * @return : true if the roleName exists in the user store.
     */
    boolean isExistingRole(String roleName);

    /**
     * Checks whether the are users for the given roleName.
     *
     * @param roleName : The role name.
     * @return : True if there are users for the given roleName. false otherwise.
     */
    boolean hasUsersForRole(String roleName);

    /**
     * Returns the list of user names in the user store for the given role name.
     *
     * @param roleName : The role name.
     * @return : The list of user names for the given role name.
     */
    List<String> getUserNameListForRole(String roleName);

    /**
     * Returns the list of matching roles for a given user name.
     *
     * @param userName : The user name to get the list of roles.
     * @return : The list of matching role names.
     */
    List<String> getRoleNameListForUser(String userName);

    /**
     * Creates a new org entity object for the given roleName
     *
     * @param roleName : The name of the role.
     * @return : the created object.
     */
    OrganizationalEntityDAO createGroupOrgEntityForRole(String roleName);

    /**
     * Creates a new org entity object for the given user name
     *
     * @param userName : The name of the user.
     * @return : the created object.
     */
    OrganizationalEntityDAO createUserOrgEntityForName(String userName);

    /**
     * Creates the GenericHumanRoleDAO object for the given role and the role type.
     *
     * @param roleName : the name of the human role.
     * @param type     : The type of the human role.
     * @return : the created GenericHumanRoleDAO object.
     */
    GenericHumanRoleDAO createGHRForRoleName(String roleName,
                                             GenericHumanRoleDAO.GenericHumanRoleType type);

    /**
     * checks if the given list of orgEntities exists in the user store.
     *
     * @param orgEntities : The list of orgEntities to be checked.
     */
    void checkOrgEntitiesExist(List<OrganizationalEntityDAO> orgEntities);

    /**
     * checks if the given list orgEntity exists in the user store.
     *
     * @param orgEntity : The orgEntity to be checked.
     * @throws : @see: HumanTaskRuntimeException if the org entities does not exist.
     */
    void checkOrgEntityExists(OrganizationalEntityDAO orgEntity);

    
    boolean isOrgEntityInRole(OrganizationalEntityDAO entity,
                                     GenericHumanRoleDAO role);
    
    /**
     * Returns the currently logged in user's user name.
     *
     * @return : The user name of the logged in user.
     */
    String getLoggedInUser();
}
        

Once the custom people query evaluator class is bungled as a JAR file, it should be copied to BPS_HOME/repository/component/lib folder and restart the server for the new implementation to be used.You also need to give the fully qualified class name of the new implementation in the human task configuration file (BPS_HOME/repository/conf/humantask.xml)

    <PeopleQueryEvaluatorConfig>
        <PeopleQueryEvaluatorClass>org.wso2.carbon.humantask.core.integration.CarbonUserManagerBasedPeopleQueryEvaluator</PeopleQueryEvaluatorClass>
    </PeopleQueryEvaluatorConfig>

Task Instance Cleanup

With the amount of tasks growing in the database, the completed tasks could be removed using the task instance clean up configuration element in the BPS_HOME/repository/conf/humantask.xml file. A scheduled task will remove the tasks from the database for the given interval and the task statuses. The configuration element is as follows.

    <TaskCleanupConfig>
        <cronExpression>0 0 0/4 * * ?</cronExpression>
        <statuses>COMPLETED,OBSOLETE</statuses>
    </TaskCleanupConfig>
  • cronExpression : A valid cron expression as the scheduler interval.
  • statuses : A list of statuses to be removed. Only statuses at the end of task life cycle should be put here. (eg: COMPLETED or OBSOLETE)

Task Event Listeners

You can write custom task event listeners to be triggered on task events. For this you need to implement the interface org.wso2.carbon.humantask.core.api.event.HumanTaskEventListener. You can find the relevant JARs having this interface in the BPS_HOME/repository/component/plugins folder.

public interface HumanTaskEventListener {

    /**
     * This method will be called by the human task engine when a new event is generated.
     * The listener logic should be implemented in the method body.
     *
     * @param taskEventInfo : A final object containing the context information related to the
     * task event and the task itself.
     */
    public void onEvent(TaskEventInfo taskEventInfo);
}

The onEvent method will be called with org.wso2.carbon.humantask.core.api.event.TaskEventInfo object which holds the following information about the task.

  • Task Information of the related task
  • Event Initiator : The user who initiated this task event
  • The time stamp of the event
  • The event type : This would be the task action (org.wso2.carbon.humantask.core.dao.TaskEventType)
  • Event Details : The details of the task event in applicable
  • Old State : The task state before this event occurred
  • New State : The task state after this event occurred

The org.wso2.carbon.humantask.core.api.event.TaskInfo object would holde the following information regarding a task.

  • Task Id
  • Task Name
  • Task Description
  • Task Presentation Subject
  • Task Type
  • Task State
  • Task State Before Suspension
  • Task Owner
  • Task Created Date

Once the custom event listener implementation is packed as a JAR file it should be placed in $BPS_HOME/repository/components/lib folder. A fully qualified class name entry should be added for the task event listeners section in the humantask.xml configuration file (BPS_HOME/repository/conf/humantask.xml)

    <TaskEventListeners>
        <ClassName>org.foo.bar.EventListener1</ClassName>
        <ClassName>org.foo.bar.EventListener2</ClassName>
    </TaskEventListeners>