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

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_Def_Queries Task Def Queries ** #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 *** #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-4-189... https://community.jboss.org/servlet/JiveServlet/downloadImage/102-18641-4... 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/TaskServi... https://community.jboss.org/servlet/JiveServlet/downloadImage/18935/TaskS... 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.         // 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... https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task... h3. Task Def Structure TBD h3. Task Def Queries TBD 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... https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task... h3. https://community.jboss.org/servlet/JiveServlet/showImage/18933/TaskServi... https://community.jboss.org/servlet/JiveServlet/downloadImage/18933/TaskS... 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... https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task... 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; h3. Transaction Strategies Depending on the Scenario is how the transactions strategies will need to be configured. Based on CDI qualifiers we will be able to provide different implementations that will be selected based on the environment. h3. Task Instance Structure The task instance structure will contain only the information required by 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... https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task... 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... https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task... 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);         taskCommentService.removeComment(commentId); 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. h2. -------------------------------------------------------------- Comment by going to Community [https://community.jboss.org/docs/DOC-18641] Create a new document in jBPM at Community [https://community.jboss.org/choose-container!input.jspa?contentType=102&a...]