Human Task API and Data Structures Proposal

Version 7

    Introduction

     

    Based on the previous document for reviewing the architecture and APIs exposed by the Human Task module I've came up with this first schetck of proposal for changes.

    I've decided for this stage to show a more modular approach that the one provided by the current implementation.

    This modular approach will let us scale if more functionality is required without the need of chainging the interfaces of the already existing services. It will also allow us to

    provide different implementations for each of the modules which will give us a lot of flexibility to integrate with different technologies. For example provide an Attachments Service

    which uses a Content Repository and keep the comments in a database. We will be able to mix and match based on the scenario requirement.

     

    The main focus of this proposal is to decouple all the logical services provided by the Human Task module and enable different implementations to cohexist under the same set of APIs.

    This document describe also the Data Structures and Interfaces that will be exposed to the end User. All the other internal mechanisms and classes will be hidden.

     

     

    The figure shows the logical organization of the proposed services. The services are logically grouped Task Definition Services and Task Instances Services.

     

    All the services will be created using CDI beans, which will allow us to expose them via Switchyard / Camel  (https://docs.jboss.org/author/display/SWITCHYARD/Bean+Services)etc. In other words, these services will be completely agnostic of the

    transports that different applications under different scenarios can use to interact with them. Using CDI will enable us to define different profiles and configurations for the module

    depending on the scenario that we want to use it. Meaning that if you don't need a service, you just don't use it and you don't need to suffer the footprint of that unused service.

     

    The following repository contains some experiments towards the direction described in this wiki page:

    https://github.com/Salaboy/human-task-poc-proposal

     

    The following sections explain the scope of the proposed services:

    TaskServices.png

    Generic Service Infrastructure

    Each service architecture will vary depending on the implementation.

    For most of the services a simple implementation will do the work:

    TaskServicesArchitecture.png

    No matter the services implementation, they should be as stateless as possible. Storing all the information in a Database or Repository.

    There are some cases where Services implementation can provide a stateful context, but those implementations should specify why and how

    they will keep the correlation between different requests. This should be stated using qualifiers as well as a different CDI scope.

     

    Task Def Service

    A Task Definition is a structure that contains a reusable structure to define a Human Interaction. By reusable I mean, a Task that can be executed multiple times and

    that shares static information, such as Assignments, Delegation options, Deadlines, Notifications, etc. If all this information can be shared we can reduce the definition time

    just providing the users to select on of the provided definitions, instead of defining all this information every time that a task is required.

     

    The task service def service will deal with static Human Task Definitions. These definitions can be generated by the userTasks from a business processes or via the

    provided APIs by third parties applications. We will be able to deploy new task definitions to the service, list all the available definitions based on different criterias, etc.

    A set of more specific services will be provided to store and manage additional information about Task Definitions.

     

     

            // DEFINE ONCE, REUSE EVERYWHERE
            TaskDef taskDef = new TaskDef("myTaskDef");
            PeopleAssignments peopleAssignments = new PeopleAssignments();
            List<OrganizationalEntity> potentialOwners = new ArrayList<OrganizationalEntity>();
            potentialOwners.add(salaboy);
            peopleAssignments.setPotentialOwners(potentialOwners);
            taskDef.setPeopleAssignments(peopleAssignments);
    
            //Deploy Definition 
            taskDefService.deployTaskDef(taskDef);
            // list
            taskDefService.getAllTaskDef("*");
            // getById
            taskDefService.getTaskDefById("myTaskDef");
            // unregister
            //taskDefService.undeployTaskDef("myTaskDef");
    
    

     

    Service Interface:

     

    https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/api/TaskDefService.java

     

     

    Task Def Structure

    TBD

    Task Presentation Service

    The task presentation service will allow us to provide more information about how a task will be presented to the users. This will include the I18N options for all the texts

    related to a task such as Subject, Description, Goals, etc. Decoupling this logic and structures in a different service will allow us to only query this information when it's needed and

    not everytime that we want to interact with a task. Because this is not a core service, we can choose to not use it and disable it if our implementation doesn't require such presentation information.

    This service will allow us to define common presentation elements that can be shared among different task definitions.

     

      TaskPresentationService taskPresentationService = container.instance().select(TaskPresentationService.class).get();
    
            //Internally it will use taskDef.getTaskDef(id).getPresentationElements()
            List<PresentationElement> presentationElements = taskPresentationService.getPresentationElements(taskId);
    

     

    Task Assignments Service

    The task Assignment service will be in charge of hosting information about task assignments. This information will describe the potentialOwners, excludedOwners, StakeHolders, BusinessAdmins, etc.

    All this information will be related with a task definition and not with a task instance. In other words this is about static definitions (doing on modeling time) of the task and not about the

    assignments that will be defined at runtime when a Task Instance is created. Having this information decoupled will allow us to define different strategies for validating, querying and interacting with

    an external identity service. When a Task instance is created, using this information plus the runtime context and the defined strategies the concrete assigments will be applied to the Task instance.

    Instead of store and duplicate assignment information per task , we can reuse the assignments from previously defined tasks.

     

    Task Delegation Service

    This service will host different delegation schemas that can be used by the task definitions. Depending on the business scenario were the human interactions will be defined, this service will host common patterns that can be reused by Task Definitions. Instead of store and duplicate delegation/escalation information per task , we can reuse the delegationescalation information from previously defined tasks.

     

    Task Notification Service

    The service expose an interface that allows us to define templates for notifications that can be used on Task Deadlines, Lifecycle Events, Callbacks.

     

    Task Instance Service

    Once we have a Task Definiton deployed we can start creating instances of a specific Task Definition Type. The instance will use the static information provided

    by the task definition to create the new Task Instance. The information about assignments, deadlines and escalations/delegations will be defined inside the Task Definition (which support

    expressions) . When a new instance is created all the expressions are resolved and the task will only contain the relevant data for execution. If at runtime more information about the Task Definition is required, the Task Instance Service can use the Task Definition Service internally to get generic information.

     

    The Task Instance Service will expose the life cycle methods to interact with a Task Instance, such as: start, complete, forward, claim, release, etc (WS-HT defined methods).

    Internally, the Task Instance Service will contain the core logic to represent the task life cycle.

     

    Having this Service decoupled from the rest will allow us to improve that logic and have a well defined boundary of the module capabilties and responsabilities. Because we are working

    to provide a pluggable life cycle mechanism, different Task Instances Services implementation can be provided. Using CDI decorators and qualifiers the API usage will be extremely improved

    and it will easily allow us to run the component in any environment (From standalone to EE with major changes).

     

    Sync and Async Services should be modeled using CDI qualifiers instead of different interfaces.

     

           // Lifecycle methods for task instances only!!!! 
           TaskInstanceService taskInstanceService = taskServiceEntryPoint.getTaskInstanceService();
    
            Map<String, Object> params = new HashMap<String, Object>();
    
            // Instantiate 
            long taskId = taskInstanceService.newTask("myTaskDef", params);
            // Interact
            taskInstanceService.start(taskId, "salaboy");
    
    

     

    Service Interface:

    https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/api/TaskInstanceService.java


    TaskServiceIntanceService.png

    As you can see the TaskInstanceService has a couple of important services that will be injected at runtime.

     

    Human Task LifeCycle Manager

    The lifeCycleManager will be in charge of defining the lifecycle of each Task Instance. This Manager will be pluggable to allow us to provide different implementations for different needs.

    The MVEL Lifecycle Manager reuse the logic that is now contained inside the jbpm-human-task-core module, which loads an MVEL file which contains all the possible states for a TaskInstance.

     

    MVELLifecycleManager simple implementation:

     

    https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/internals/lifecycle/MVELLifecycleManager.java

     

    Different LifecycleManagers can be provided and the implementation can be decided at configuration time using one simple CDI Qualifier.

    For Example:

     

    @Inject @Mvel
    private LifecycleManager lifeCycleManager;
    

     

    Task LifeCycle Events

    No matter the LifecycleManager implementation, all of them will require to inform the outside world about the lifecycle events, allowing us to caputure those events for different usages.

    We will be able to Log those events, use those events as callbacks mechanisms, make inferences about them, etc.

     

    SEAM3 provides a CDI extension that allows us to get a PersistenceContext and define transactions in SE environments:

     

    http://docs.jboss.org/seam/3/persistence/latest/reference/en-US/html_single/

     

    This is what we are doing today manually, they provide a declarative way of defining our transaction policies and the persistence context propagation.

     

    It also provides an unification with Spring: http://www.javaworld.com/javaworld/jw-05-2008/jw-05-spring-seam3.html

    Which

    Transaction Strategies

    Depending on the Scenario is how the transactions strategies will need to be configured.

    Based on CDI qualifiers and interceptors we will be able to provide different implementations that will be selected based on the environment.

    Transactions are usually handled as Aspects, which in CDI can be defined using Interceptors. We will be able to select different Interceptors

    depending on the environment that we want to run our application. These interceptors will be selected based on quilifiers and they will  be injected into the relevant

    classes.

     

    Task Instance Structure

    The task instance structure will contain only the information required by a Task to run. All the information that belongs to the task definition will not be copied to the

    Task Instance structure. 

     

    Task Query Service

    The task query service provides a set of methods to query Task Instances. Because each task contains a lot of information, a separate service was created to provide a flexible mechanism

    to retrive task instance information. Internally it can use multiple service to retrieve the information.

     

    Service Interface:

    https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/api/TaskQueryService.java

    Task Admin Service

    The task admin service provides some Administration APIs to do clean ups and keep the storage as free as possible of unneeded data.

    Service Interface:

     

    Service Interface:
    https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/api/TaskAdminService.java

     

     

    Task Attachment and Comment Services

    Both services are decoupled to allow fine grained control on how the attachments are handled and stored. Depending on the context on the task and the architecture we the Human Interactions will happen is how we will want to handle attachments. Providing a decoupled interface for these services will allow us to gradually support different ways to store this information that is related with a specific task instance.

     

     

           TaskAttachmentService taskAttachmentService = container.instance().select(TaskAttachmentService.class).get();
    
            taskAttachmentService.addAttachment(taskId, attachment);
            List<Attachment> attachs = taskAttachmentService.getAttachments(taskId);
    
            TaskCommentService taskCommentService = container.instance().select(TaskCommentService.class).get();
    
            taskCommentService.addComment(taskId, comment);
            List<Comment> comments = taskCommentService.getComments(taskId);
            taskCommentService.removeComment(commentId);
    

     

     

    Task Events, Callbacks,  Listeners Service

    This service will expose a set of APIs that will allow external applications to register interest and callback functions to a Task Instance or a group of Task Instances (could be also by Task Definition).

    When a third party application creates a task inside the human task module, it will automatically becomes the owner of the task. If the application is interested in being notified about the Task Lifecycle or just a small set of events, the application will need to register a callback function or identifier which enables the component to contact back the application. This callbacks and listeners information should be (once again) agnostic to the transport. This information will represent a logic description about how to contact a third party application if it is needed, but several implementations can be plugged to achieve the desired behavior on runtime. We can leverage the Events features of CDI for listeners and callbacks.

     

    Having this service as a decoupled module will allow us to:

    • Provide different strategies for different environments
    • Allow external components to be notified (pull) or to poll the task events notifications and execute the callbacks for us. Meaning that we expose the information
      about what needs to happen but not how it will happen. Reducing the complexity of the component and leveraging already implemented features from frameworks like Switchard / Camel.