2017/04/28

Control business rules execution from your processes

Business processes benefit a lot from business rules, actually they are like must to have in today's constantly changing world. jBPM comes with excellent integration with Drools so that already has a lot of advantages to provide multiple levels of business rules integration:

  • BPMN2 Business Rule task
  • Conditional events (start, intermediate and boundary)
  • Sequence flow conditions

Default integration with rules is that process engine shares the same working memory with rules engine. That in many cases is desired but the main limitations is life cycle of rules and processes are tightly coupled - they are part of the same project (aka kjar) or in other words knowledge base. 

This in turn makes it harder to decouple it and manage life cycle of business rules independently. There are domains out there that have much higher frequency of change in the rules rather than in processes so this tight integration makes it hard to easily upgrade rules without affecting processes - keep in mind that processes are usually long running and can't be easily migrated to next version just because of rule changes.

To resolve this, alternative way of dealing with business rules from within process has been introduced. It does support only business rule tasks and not conditional events or sequence flow conditions. 

What's in the toolbox?

This new feature introduces two new components that serve different use cases:
  • Business Rule Task based on work item handler
  • Remote Business Rule Task based on work item handler and Kie Server Client
Both of them support two types of rule evaluation:
  • DRL
  • DMN 
Let's look at them in details, starting first with Business Rule Task handler.

Business Rule Task handler

Main use case for this alternative business rule task is to decouple process knowledge base from rule knowledge base. That means we will have two projects - kjars to be responsible for handling these two business assets. Rule project is solely responsible for defining business rules which can then be updated at any time without affecting processes. 



Next process project (kjar) does focus only on business processes and hand rule evaluation to the rule project. The only common place is that Business Rule Task handler that defines what kjar (rule project) should be used within process project. 

Since the alternative business rule task is based on work item node, it requires work item handler to be registered in process project. As usual work item is registered in deployment descriptor (accessible via project editor)


Business Rule Task handler is implemented by org.jbpm.process.workitem.bpmn2.BusinessRuleTaskHandler and it expects following arguments:
  • groupId - mandatory argument referring to rule's project groupId
  • artefactId - mandatory argument referring to rule's project artefactId
  • version - mandatory argument referring to rule's project version 
  • scanner interval - optional used to schedule periodic scans for rules updates - in milliseconds
Business Rule Task handler supports two types of rule evaluation:
  • DRL - that allows to specify following data input on task level to control its execution
    • Language - set to DRL
    • KieSessionName - name of the kie session as defined in kmodule.xml of rule project - can be left empty which means default kie session is used
    • KieSessionType - stateless or stateful - stateless is default if not given
    • all other data inputs will be inserted into working memory as facts thus will be available for rule evaluation. Note that data input and output should be matched by name to properly retrieve updated facts and put back into process variables
  • DMN - that allows to specify following as data input on task level:
    • Language - set to DMN
    • Namespace - DMN namespace to be used
    • Model - model to be used
    • Decision - optional decision name to be used
    • all other data inputs are added to DMN context for evaluation. All results from DMNResult are available as data outputs referred by name as defined in DMN
NOTE: Since projects are decoupled they need to have common data model that both will operate on. Currently that model must be on parent class loader instead of kjar level due to classes being loaded by different class loaders and thus making rules not match them properly. In case of execution server (KIE Server) model jar must be added to WEB-INF/lib of the KIE Server app and added to both projects as dependency in provided scope.


    Remote Business Rule Task handler

    Remote flavour of the handler comes with KIE Server Client and aims at providing even more decoupling as it will communicate with external decision service (KIE Server) to evaluate rules. This provide more flexibility and removes the limitation of common data model to be present on the application level. With remote business rule task users can simply define model project as project dependency (with default scope) for both projects - rules and processes. Since there is marshalling involved there is no problem with class loaders and thus working as expected.

    From project authoring point of view there is only one difference - Business Rule Task requires additional data input - ContainerId that defines which container on execution server it should target. Obviously this can be container alias as well for more flexibility.



    Similar as Business Rule Task, this handler supports both DRL and DMN. Depending on which type is needed it supports different data inputs:
    • DRL
      • Language - DRL
      • ContainerId - container id or alias of the container to be used to evaluate rules
      • KieSessionName - name of the kie session on execution server for given container
    • DMN
      • Language - DMN
      • ContainerId - container id or alias of the container to be used to evaluate rules
      • Namespace - DMN namespace to be used
      • Model - model to be used
      • Decision - optional decision name to be used
    Any other data input will be send as data to the execution server. Results handling is exactly the same as with Business Rule Task handler.


    Remote Business Task Handler is implemented by org.kie.server.client.integration.RemoteBusinessRuleTaskHandler. Handler expects following arguments:
    • serverUrl - location of the execution server that this handler should use, it can be comma separated list of URLs that will be used by load balancer
    • username - user to be used to authenticate calls to execution server
    • password - password to be used to authenticate calls to execution server
    • classLoader - projects class loader to gain access to custom types 

    Registration of the handler is done exactly the same, via deployment descriptor. 


    That would conclude the description of new capabilities. If you'd like to try it yourself simply clone this repository to your workbench, build and run it!

    Here you can see this being done...



    That's all for now, though stay tuned as more will come :)




    2017/04/13

    Email configuration for jBPM

    Quite frequent question from users is how to send emails from within process instance. This is rather simple activity but requires bit of configuration upfront.

    So lets start with application server configuration to provide JavaMail Sessions via JNDI directly to jBPM so process engine does not need to be concerned too much with infrastructure details.

    In this article, WildFly 10 is used as application server and the configuration is done via jboss cli. As mail server Gmail is used as it makes it quite common choice.

    Configure WildFly mail session

    This is quite simple as it requires to configure socket binding and then the actual JNDI resource of mail session type:

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=jbpm-mail-smtp/:add(host=smtp.gmail.com, port=465)

    /subsystem=mail/mail-session=jbpm/:add(jndi-name=java:/jbpmMailSession, from=username@gmail.com)
    /subsystem=mail/mail-session=jbpm/server=smtp/:add(outbound-socket-binding-ref=jbpm-mail-smtp, ssl=true, username=username@gmail.com, password=password)

    Items in bold are external references:
    • host - smtp server host name
    • port - smtp server port number
    • JNDI name the mail session will be bound to
    Items in red must be replaced with actual Gmail account details that shall be used when sending emails:
    • from - address that should be valid email account
    • username - account to be used when login to SMTP server
    • password - account's password to be used when login to SMTP server

    When starting WildFly server, you have to provide the JNDI name to be used by jBPM to find the mail session, this is given as system property:

    ./standalone.sh .... -Dorg.kie.mail.session=java:/jbpmMailSession

    this is all that is needed from application server point of view.

    Configure jBPM for sending emails

    There are two email components that can be used by jBPM to send emails:
    • Email service task (backed by work item handler)
    • User task notifications
    Both of them can rely on application server mail sessions, so configuration of the application server applies to both email capabilities.

    Work item handler configuration

    Email activity is based on work item mechanism so that requires work item handler to be registered for it. Work item handlers can be registered via deployment descriptor that can be done on kjar level or server level. Below screen shot illustrates the configuration of the deployment descriptor on kjar level done in workbench


    what this does - it's registering org.jbpm.process.workitem.email.EmailWorkItemHandler for Email work item/service task and since it should use mail session from JNDI we need to reset the handler property so they won't get in the way (argument of the EmailWorkItemHandler constructor):
    • host set to null
    • port set to -1
    • username set to null
    • password set to null
    • useTLS set to true
    this is done to make sure all these values are taken from JNDI mail session of the application server.

    As it was mentioned, this email registration can also be done on server level, global deployment descriptor that all kjars will inherit from. See more about deployment descriptor in the docs.

    That's all from jBPM configuration point of view. 

    Process with Email task

    Last thing is to actually take advantage of the configured Email infrastructure so let's model most basic process that the only thing it does is sending email and completing.


    Email task can be found in the left hand side panel - palette - under Service Tasks category.

    Once placed on the process flow you need to provide four data input to instruct email work item handler how to compose the email message:
    • From - valid email address
    • To - valid email address of the recipients (to specify multiple addresses separate them with semicolon ';')
    • Subject - email subject
    • Body - email body (can include html)

    That's all, just build and deploy it and enjoy receiving emails from your processes.

    2017/04/06

    Case management application in workbench

    As part of coming jBPM version 7 I'd like to present a new component that will allow an easy and comprehensive look into case management. As described in the article case management should be business focused and domain specific to bring in the most value to the end users who in many cases are not technical. But there is also the other side of the coin - administrators or technical business users. They are as important as end users because in many cases these are the people that keep the apps running and available for end users.

    With jBPM 7 they are certainly not left behind. A new component is available for that audience to allow them to have quick and rather complete view at the cases (both definitions and instances). To make it possible to deal with various type of cases that component was made generic to:

    • bring in visibility to the technical users
    • provide insight in where the case instance is
    • allow to perform certain operations on a case instance which might not be visible to end users through the case app
    The good thing is that the application can be used standalone or can be automatically provisioned by workbench and accessible from within the workbench UI.

    By launching the Case Management Showcase application you will be transferred to a new window to allow you to operate on cases:
    • start new instance of case definition
    • view and administrate on already active case instances
    • use workbench runtime views (Process Instances and Tasks) to interact with case instance activities

    As can be seen, the example show the Order IT hardware case instance, one that is shown in the case app article. I'd like to show that exact same capability exposed to end users through the case app can be performed by technical/admin users by using the Case Management app and workbench.




    That's as simple as that, those who are familiar with workbench as an environment will find themselves in there and navigate through the screen easily. Again, its target is technical users as that does not bring the business context thus might lead end users (non technical ones) to be confused and lost a bit. 

    Running workbench with case management app

    So that illustrates how it actually works but how to set this up?

    First of all, let's configure the runtime environment for workbench, there is not much of new  things compared to standard installation of the workbench:
    • user and roles setup
      • make sure there is an application user that has at least following roles:
        • kie-server
        • user
      • make sure there is a management user - this will be used by the provisioning service of the workbench to deploy automatically case management application
    • security domain setup 
      • make sure that the security domain used by workbench (by default it's other) has additional login module defined (org.kie.security.jaas.KieLoginModule)
    • system properties set for JVM running server
      • org.jbpm.casemgmt.showcase.deploy=true
      • instruct workbench to deploy case management showcase apps when starting
      • org.kie.server.location=http://localhost:8230/kie-server/services/rest/server
      • location of the kie server that the case management app is going to talk to
      • org.jbpm.casemgmt.showcase.wildfly.username
      • optional user name (of the management user) in case it's different than admin
      • org.jbpm.casemgmt.showcase.wildfly.password
      • optional user password (of the management user) in case it's different than admin
      • org.jbpm.casemgmt.showcase.wildfly.port
      • optional wildfly port that server is running on - default 8080
      • org.jbpm.casemgmt.showcase.wildfly.management-port 
      • optional wildfly management port - default 9990 
      • org.jbpm.casemgmt.showcase.wildfly.management-host 
      • optional wildfly management host name - default localhost
      • org.jbpm.casemgmt.showcase.path
      • local file path that points to war file to be deployed, can be used instead of relying on maven to download it
    That should be enough to start the workbench and provision Case Management application to be automatically deployed. 

    Assuming there are most of the defaults in use, following command is enough to start the server where workbench is deployed:
    ./standalone.sh 
    --server-config=standalone-full.xml 
    -Dorg.jbpm.casemgmt.showcase.deploy=true 
    -Dorg.kie.server.location=http://localhost:8230/kie-server/services/rest/server

    As part of the startup you should see Case management app being provisioned:
     [org.jbpm.workbench.wi.backend.server.casemgmt.service.CaseProvisioningExecutor] (EJB default - 1) Executing jBPM Case Management Showcase app provisioning...
    ....
    [org.jbpm.workbench.wi.backend.server.casemgmt.service.CaseProvisioningExecutor] (EJB default - 1) jBPM Case Management Showcase app provisioning completed.

    NOTE: the provisioning is based on maven resolution of the jbpm-case-mgmt-showcase so depending on the download time it can timeout from time to time. To overcome this you can download that artefact manually via maven to speed it up.

    Next, is to clone the Order IT hardware case project into workbench and build and deploy it to KIE Server for execution. Once it's built and deployed it's ready for execution. 



    That concludes how to get started with brand new stuff coming with version 7 ... which is really around the corner so start preparing for it!

    Special credits go to Cristiano and Neus for excellent work that resulted in this new Case Management App.