[jboss-user] [jBPM] - Human Task API and Data Structures Proposal

Mauricio Salatino do-not-reply at jboss.com
Tue Jul 3 11:05:15 EDT 2012

Mauricio Salatino [https://community.jboss.org/people/salaboy21] modified the document:

"Human Task API and Data Structures Proposal"

To view the document, visit: https://community.jboss.org/docs/DOC-18641

h1. * 
 #Introduction Introduction

 #Generic_Service_Infrastructure Generic Service Infrastructure

 #Task_Def_Service Task Def Service

 #Task_Def_Structure Task Def Structure

 #Task_Presentation_Service Task Presentation Service

 #Task_Assignments_Service Task Assignments Service

 #Task_Delegation_Service Task Delegation Service

 #Task_Notification_Service_ Task Notification Service 

 #Task_Instance_Service Task Instance Service

 #Human_Task_LifeCycle_Manager Human Task LifeCycle Manager

 #Task_LifeCycle_Events Task LifeCycle Events

 #Transaction_Strategies Transaction Strategies

 #Task_Instance_Structure Task Instance Structure

 #Task_Query_Service Task Query Service

 #Task_Admin_Service Task Admin Service

 #Task_Attachment_and_Comment_Services_ Task Attachment and Comment Services 

 #_Task_Events_Callbacks_Listeners_Service  Task Events, Callbacks,  Listeners Service

h1. 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 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 https://github.com/Salaboy/human-task-poc-proposal

The following sections explain the scope of the proposed services:
 https://community.jboss.org/servlet/JiveServlet/showImage/102-18641-5-18930/TaskServices.png  https://community.jboss.org/servlet/JiveServlet/downloadImage/102-18641-5-18930/446-600/TaskServices.png 
h3. Generic Service Infrastructure
Each service architecture will vary depending on the implementation. 
For most of the services a simple implementation will do the work:
 https://community.jboss.org/servlet/JiveServlet/showImage/18935/TaskServicesArchitecture.png  https://community.jboss.org/servlet/JiveServlet/downloadImage/18935/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.

h1. 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.

        TaskDef taskDef = new TaskDef("myTaskDef");
        PeopleAssignments peopleAssignments = new PeopleAssignments();
        List<OrganizationalEntity> potentialOwners = new ArrayList<OrganizationalEntity>();
        //Deploy Definition 
        // list
        // getById
        // unregister

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 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

h3. Task Def Structure
h2. 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);

h2. 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.

h2. 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.

h2. 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.

h1. 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 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

 https://community.jboss.org/servlet/JiveServlet/showImage/18933/TaskServiceIntanceService.png  https://community.jboss.org/servlet/JiveServlet/downloadImage/18933/TaskServiceIntanceService.png 
As you can see the TaskInstanceService has a couple of important services that will be injected at runtime. 

h3. 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 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;

h4. 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.

h3. 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

h3. 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.  

h3. 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 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
h2. 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 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

h2. 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);

h2.  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.


Comment by going to Community

Create a new document in jBPM at Community
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-user/attachments/20120703/80b5c925/attachment-0001.html 

More information about the jboss-user mailing list