Bug 845992 - Human task service configuration irregularities
Human task service configuration irregularities
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise BRMS Platform 5
Classification: JBoss
Component: doc-BRMS_Business_Process_Management_Guide (Show other bugs)
BRMS 5.3.0.GA
Unspecified Unspecified
unspecified Severity high
: ---
: ---
Assigned To: lcarlon
Jiri Svitak
: Documentation
: 848945 (view as bug list)
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-08-06 08:29 EDT by Jiri Svitak
Modified: 2015-06-01 21:34 EDT (History)
9 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-01-20 22:42:14 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Jiri Svitak 2012-08-06 08:29:20 EDT
This bug involves both configuration settings and documentation of the human task service.

I have discovered several problems and irregularities while studying documentation of the product:


1.) Section 10.2.2 [1] of the documentation states, that the default implementation for client server communication is HornetQ. Section
10.2.6 [2] says, that the default listening port for HornetQ is 5445. However this is not true, because when I deploy the BRMS (on EAP 6.0), there is no open 5445 port. Just 5446:

[jsvitak@jsvitak-nb deployments]$ sudo lsof -i -P | grep java
...
java      3024  jsvitak  551u  IPv4  41053      0t0  TCP localhost:5446 (LISTEN)
...

Suggested solution is to either correct the docs or change the default HornetQ port in jbpm-human-task.war.


2.) As already has been said, the default implementation for the human task client-server communication is HornetQ. However all the examples describe setting up a Mina connection (with listening port (9123). So HornetQ code examples should be added too. For example registering human task work item handler takes into account only Mina task client, which connects to default Mina port 9123.


3.) The same as before applies here for the business central configuration [3]:

"jbpm.console.task.service.port: port where Task Server is deployed (default 9123) applies to all transports"
and
"jbpm.console.task.service.strategy (default HornetQ)"

These two statements are in contradiction. Default is HornetQ task client (which should have a different port - 5445 or 5446?), but default 9123 port is used by Mina task client.


Solution:
I think that the documentation, together with the configuration of the product components should be more consistent.

I apologize if I included someone in CC by a mistake, but I don't know who decides the configuration settings for the product.


[1] http://docs.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Business_Process_Management_Guide/ch10s02s02.html
[2] http://docs.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Business_Process_Management_Guide/ch10s02s06.html
[3] http://docs.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Business_Process_Management_Guide/chapter_console.html
Comment 1 lcarlon 2012-08-07 02:39:17 EDT
Hi Jiri,

1) I've updated the default to 5446, at [1] and [2]. I've also updated the text to state that HornetQ is the default and removed references JMS and Mina, but have left them in the supported config section, with the note that HornetQ is the default, but Mina and JMS are also accepted.

2) My inclination is to change the examples to use HornetQ.

My question though - is it simply a case of swapping the code in the example at [3], from: 

TaskClient client = new TaskClient(new MinaTaskClientConnector("client 1",
    new MinaTaskClientHandler(SystemEventListenerFactory.getSystemEventListener())));
client.connect("127.0.0.1", 9123);

to:

TaskClient client = new TaskClient(new HornetQTaskClientConnector("client 1",
    new HornetQTaskClientHandler(SystemEventListenerFactory.getSystemEventListener())));
client.connect("127.0.0.1", 5446);

and again at [4] from:

EntityManagerFactory emf = Persistence.createEntityManagerFactory("org.jbpm.task");
TaskService taskService = new TaskService(emf, SystemEventListenerFactory.getSystemEventListener());
MinaTaskServer server = new MinaTaskServer( taskService );
Thread thread = new Thread( server );
thread.start();

to:

EntityManagerFactory emf = Persistence.createEntityManagerFactory("org.jbpm.task");
TaskService taskService = new TaskService(emf, SystemEventListenerFactory.getSystemEventListener());
HornetQTaskServer server = new HornetQTaskServer( taskService );
Thread thread = new Thread( server );
thread.start();

or is there more to it?

3) I've change it to read: 

jbpm.console.task.service.port: The port where the task server is deployed (5446 when using HornetQ) 


[1] http://docs.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Business_Process_Management_Guide/ch10s02s02.html

[2] http://docs.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Business_Process_Management_Guide/ch10s02s06.html

[3] http://docs.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Business_Process_Management_Guide/ch10s02s03.html

[4] http://docs.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html-single/BRMS_Business_Process_Management_Guide/index.html#id3248662
Comment 2 lcarlon 2012-08-16 18:19:45 EDT
*** Bug 848945 has been marked as a duplicate of this bug. ***
Comment 3 lcarlon 2012-08-16 18:21:49 EDT
Comments from 848945 which provide some of the requested information:

The default port for HornetQ is not 5445, it is 5446:
https://access.redhat.com/knowledge/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html-single/BRMS_Business_Process_Management_Guide/index.html#id3289108

As HornetQ is the default protocol, the section below should be fixed. WSHumanTaskHandler and CommandBasedWSHumanTaskHandler don't work with HornetQTaskClientConnector, so, must be used CommandBasedHornetQWSHumanTaskHandler.
https://access.redhat.com/knowledge/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html-single/BRMS_Business_Process_Management_Guide/index.html#id3119294

In the same topic above, the example using Mina should be changed to use HornetQ (the documentation does not have any example about it).
So, instead of:

TaskClient client = new TaskClient(new MinaTaskClientConnector("client 1",
    new MinaTaskClientHandler(SystemEventListenerFactory.getSystemEventListener())));
client.connect("127.0.0.1", 9123);

Might be used:

1. TaskClient client = new TaskClient(new HornetQTaskClientConnector("HornetQConnector" + UUID.randomUUID(),
2.     new HornetQTaskClientHandler(SystemEventListenerFactory.getSystemEventListener())));		
3. client.connect("127.0.0.1", 5446);	
4. CommandBasedHornetQWSHumanTaskHandler handler = new CommandBasedHornetQWSHumanTaskHandler(ksession);
5. handler.setClient(client);
6. handler.connect();
7. ksession.getWorkItemManager().registerWorkItemHandler("Human Task", handler);

Some things in the example above is important to mention (according with several jBPM community foruns and customers):
1) (line 1) The HornetQ Client Connector "must" use an unique name, so the UUID.randomUUID() should be used to compose its name.
2) (line 4) CommandBasedHornetQWSHumanTaskHandler should be used instead of WSHumanTaskHandler or CommandBasedWSHumanTaskHandler as already mentioned.
3) (line 5,6 and 7)The ksession, taskclient and the handler must be linked to each other. It is a important piece where several example are missing. Including this on the topic "10.2.3. Interacting with the Human Task Service" is very important.
Comment 4 Mauricio Salatino 2012-08-24 04:13:55 EDT
Hi, did you add this information into the documentation?
Comment 5 lcarlon 2012-08-24 05:34:34 EDT
Hi Mauricio,

Comment 1 lists the only changes I have made so far. I've been on other issues this week, will try to get to this next week.

Thanks
Lee
Comment 6 Mauricio Salatino 2012-08-24 11:00:24 EDT
Thanks for the update Lee, can you please keep me posted?
Cheers
Comment 7 lcarlon 2012-08-29 00:15:25 EDT
(In reply to comment #3)

The example in 10.2.3 has been updated to read:

TaskClient client = new TaskClient(new HornetQTaskClientConnector("HornetQConnector" + UUID.randomUUID(), new HornetQTaskClientHandler(SystemEventListenerFactory.getSystemEventListener())));
	client.connect("127.0.0.1", 5446);
	CommandBasedHornetQWSHumanTaskHandler handler = new CommandBasedHornetQWSHumanTaskHandler(ksession);
	handler.setClient(client);
	handler.connect();
	ksession.getWorkItemManager().registerWorkItemHandler("Human Task", handler);

(I'll post links as soon as the document hits the internal doc stage)
Comment 8 lcarlon 2012-08-29 00:28:25 EDT
I've updated section 10.2.2 Integrate a Human Task service to read:

StatefulKnowledgeSession ksession = ...;
ksession.getWorkItemManager().registerWorkItemHandler("Human Task", new CommandBasedHornetQWSHumanTaskHandler());

However does CommandBasedHornetQWSHumanTaskHandler() have a method to change the address and port, the way WSHumanTaskHandler has setConnection(ipAddress, port)?

Links to updates to follow as soon as they are live on the stage.
Comment 9 lcarlon 2012-08-29 00:29:37 EDT
I still have one more question.

In Section 10.2.5[1] Starting the Human Task Service, the Mina Task Server is started with the following:

MinaTaskServer server = new MinaTaskServer( taskService );

How should this be changed for HornetQ? Is it as simple as HornetQTaskServer Server = new HornetQTaskServer( taskService );

Thanks
Lee

[1] https://access.redhat.com/knowledge/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Business_Process_Management_Guide/ch10s02s05.html
Comment 11 lcarlon 2012-08-29 18:38:44 EDT
Hi Alessandro,

Are you able to comment on the questions I have in comments 8 & 9?

Thanks
Lee
Comment 12 Alessandro Lazarotti 2012-08-30 16:22:28 EDT
Hi Lee, 
Yes, you can also use setConnection on CommandBasedHornetQWSHumanTaskHandler:
https://github.com/droolsjbpm/jbpm/blob/5.2.x/jbpm-human-task/src/main/java/org/jbpm/task/service/hornetq/CommandBasedHornetQWSHumanTaskHandler.java

About the question in comment #9 I am not sure. It does not have a constructor only with TaskService as param, but it you can use another one using port and a host name: https://github.com/droolsjbpm/jbpm/blob/5.2.x/jbpm-human-task/src/main/java/org/jbpm/task/service/hornetq/HornetQTaskServer.java - however I am not sure if just that is enough, I've never used HornetQTaskServer in this way.

Usually, if you will not use jbpm-human-ask.war as a taskservice provider, you will use a LocalTaskService instead of create a new Thread with Mina or HornetQ. I've talked with many customer interested in LocalTaskService and Sync handlers and they are not mentioned in BRMS documentation. Maybe will be a good replacement to change the sample starting a standalone TaskService as Mina or HornetQ to a LocalTask. What do you think?
Comment 13 lcarlon 2012-09-03 01:20:00 EDT
Hi Alessandro,

Thanks for the info, I've updated the information in the staged docs regarding setConnnection and CommandBasedHornetQWSHumanTaskHandler.

I think replacing the sample starting a standalone TaskService as Mina or HornetQ with a LocalTask, is a good idea. Is this something you are able to provide a sample for?

Thanks
Lee
Comment 14 Alessandro Lazarotti 2012-09-03 23:22:58 EDT
Lee, the code bellow should be enough as snippet

-----------------------------------------------------
org.jbpm.task.service.TaskService taskService = new org.jbpm.task.service.TaskService(
  emf, SystemEventListenerFactory.getSystemEventListener());

TaskServiceSession taskServiceSession = taskService.createSession();

//adding users to TaskServiceSession
taskServiceSession.addUser(new User("Administrator"));
taskServiceSession.addUser(new User("krisv"));
	    	    
LocalTaskService localTaskService = new LocalTaskService( taskService );
humanTaskHandler = new SyncWSHumanTaskHandler( localTaskService, ksession );
humanTaskHandler.setLocal( true );
humanTaskHandler.connect();
ksession.getWorkItemManager().registerWorkItemHandler( "Human Task", humanTaskHandler );	

//using HT API ...
List<TaskSummary> tasks = localTaskService.getTasksAssignedAsPotentialOwner("krisv", "en-UK");
Comment 15 lcarlon 2012-09-11 16:11:32 EDT
Changing status back to modified as I haven't included Alessandro's snippet yet or staged the doc, as soon as that is done I will change the status back to on QA and list the changes that need to be reviewed.

If other changes have been made that mean this should be moved to ON QA now, please leave details in a comment.

Thanks 
Lee
Comment 16 lcarlon 2012-09-16 18:55:46 EDT
Thanks Alessandro, 

I've added the snippet to the guide. 

QE:
The guide is currently being moved to the CCMS we're now using, but as soon as the info is available on the internal doc stage I will update the bug with a link and a list of changes that have been made.

Lee
Comment 19 lcarlon 2012-09-24 18:59:23 EDT
Hi Jiri, 

Thanks for reviewing the changes and reporting against the issues you found.

I've made the following changes:

Section 10.3.5. The text has been changed to read:

   The human tasks service does not maintain the relationships between users and groups. A user group callback class must be created and listed in the jbpm-human-task.war/WEB-INF/web.xml file. The default implementation, org.jbpm.task.service.DefaultUserGroupCallbackImpl, assigns all users to all groups and is provided for testing purposes only.
   To add the user group callback class, open jbpm-human-task.war/WEB-INF/web.xml and add the class as in the following example:
<!-- use org.jbpm.task.service.DefaultUserGroupCallbackImpl to configure sample user group callback for demo purpose-->
<init-param>
<param-name>user.group.callback.class</param-name>
<param-value>org.jbpm.task.service.DefaultUserGroupCallbackImpl</param-value>
</init-param>

Section 10.3.7. I've updated the listing for user.group.callback.class to read:

user.group.callback.class: The implementation of UserGroupCallback interface to be used to resolve users and groups (default DefaultUserGroupCallbackImpl which is provided for testing purposes).

As soon as the changes are on the internal doc stage I'll update the status and provide a link.

Thanks
Lee
Comment 21 Jiri Svitak 2012-09-25 04:25:32 EDT
Verified.

Note You need to log in before you can comment on or make changes to this bug.