Bug 778826 (SOA-1274)

project_key: SOA

We do not support utilizing the jBPM Java API from ESB actions, but I don't think our documentation is clear enough on this.

1.)  We list the jBPM reference guide (that has many examples of use the Java API) in the SOA-P documentation:  http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/

2.)  In the SOA-P programmer's guide, the section that talks about BPM basically only says, "JBossESB can make calls into jBPM using the BpmProcessor action. Please also read the jBPIntegrationGuide to learn how to call JBossESB from jBPM. The BpmProcessor action uses the jBPM command API to make calls into jBPM. The following jBPM commands have been implemented: ..." (http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/html-single/Programmers_Guide/index.html#d0e5151).  Seems we could say something a little more clear here like, "The only supported way JBossESB can make calls into jBPM is by using the BpmProcessor action" or something.

3.)  The "jBPIntegrationGuide" referred to in #2 doesn't seem to exist as a separate guide, but I'm guessing it is this section of the "Services Guide":  http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/html-single/Programmers_Guide/index.html#d0e5151  This does talk about ESB to jBPM and jBPM to ESB, but although it says things like "not recommended to deploy classes in PAR, etc.", it does not explicitly say anything or warn about using the jBPM API directly.  One might say that the neglate of advice to use it serves that purpose, but since this guide also references the jBPM reference guide, it's again pointing ESB developers at the jBPM Java API at least indirectly.

4.)  The last statement in the "Services Guide" about jBPM says, "We have demonstrated how jBPM can be used to orchestrate Services as well as do Human Task Management. Note that you are free to use any jBPM feature. For instance look at the QuickStart |bpm_orchestration2| how to use the jBPM fork and join concepts."  (http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/html-single/Services_Guide/index.html#sect-conclusion)  I think that is trying to say use any feature of jBPM "in the process you create that get's invoked by the ESB", but I can see where folks would assume that using the Java API that they read about in the the jBPM Reference Guide qualifies as "any jBPM feature" that they could use.

If we really don't want folks using the jBPM Java API from the ESB, I think we should probably explicitly say that and give some justification as to why that is not allowed.