Red Hat JBoss BRMS 6.4

Administration and Configuration Guide

The Administration and Configuration Guide for Red Hat JBoss BRMS

Red Hat Content Services

Gemma Sheldon

<gsheldon@redhat.com>

Klara Kufova

<kkufova@redhat.com>

Marek Czernek

<mczernek@redhat.com>

Tomas Radej

<tradej@redhat.com>

Vidya Iyengar

<viyengar@redhat.com>

Copyright © 2016 Red Hat, Inc.

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract

A guide for administrators and advanced users dealing with Red Hat JBoss BRMS setup, configuration, and advanced usage.

Part I. Introduction

Chapter 1. Asset Repository

Business Rules and other assets and resources created in Business Central are stored in asset repository, which is otherwise known as the Knowledge Store.

Knowledge Store is a centralized repository for your business knowledge. It connects with the Git repository that allows you to store different kinds of knowledge assets and artifacts at a single location. Business Central provides a web front-end that allows you to view and update the stored content. You can access it using the Project Explorer from the unified environment of Red Hat JBoss BRMS.

All business assets are stored in repositories. These repositories are then saved in directories called organizational units. By default, the Artifact repository does not contain any organizational unit. Therefore, to be able to create your own business assets, you need to create an organizational unit and a repository first.

Creating an Organizational Unit

It is possible to create an organizational unit either in the Administration perspective of Business Central, using the kie-config-cli tool or the REST API calls.

Creating an Organizational Unit in Business Central

Important

Note that only users with the admin role in Business Central can create organizational units.

Procedure: Using Business Central to Create an Organizational Unit

In Business Central, go to Authoring → Administration.

On the perspective menu, click Organizational Units → Manage Organizational Units.

In the Organization Unit Manager view, click Add.

The Add New Organizational Unit dialog window opens.

Figure 1.1. Add New Organizational Unit_Dialog Window

Enter the two mandatory parameters (name and default group ID) and click Ok.

Creating an Organizational Unit Using the kie-config-cli Tool

Organizational units can be created using the kie-config-cli tool as well. To do so, run the create-org-unit command. The tool then guides you through the entire process of creating an organizational unit by asking for other required parameters. Type help for a list of all commands.

For more information about the kie-config-cli tool, see Chapter 6, Command Line Configuration.

⁠⁠Creating an Organizational Unit Using the REST API

Important

Note that only users with the rest-all role can create organizational units.

To create an organizational unit in Knowledge Store, issue the POST REST API call. Details of the organizational unit are defined by the JSON entity.

Input parameter of the call is a OrganizationalUnit instance. Call returns a CreateOrganizationalUnitRequest instance.

Example 1.1. Creating an Organizational Unit Using the Curl Utility

Example JSON entity containing details of an organizational unit to be created:

{
  "name"         : "helloWorldUnit",
  "owner"        : "tester",
  "description"  :  null,
  "repositories" :  []
}

Execute the following command:

curl -X POST 'localhost:8080/business-central/rest/organizationalunits/' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name":"helloWorldUnit","owner":"tester","description":null,"repositories":[]}'

For further information, refer to chapter Knowledge Store REST API, section Organizational Unit Calls of Red Hat JBoss BPM Suite Development Guide.

Creating a Repository

There are three ways to create a repository: through the Administration perspective of Business Central, the kie-config-cli tool, or using the REST API calls.

⁠Creating a Repository in Business Central

Important

Note that only users with the admin role in Business Central can create repositories.

Procedure: Using Business Central to Create a Repository

In Business Central, go to Authoring → Administration.

On the perspective menu, click Repositories → New repository.

The New Repository pop-up window is displayed.

Figure 1.2. New Repository Dialog Window

Specify the two mandatory parameters:

Repository name

Note

Make sure that the repository name is a valid file name. Avoid using a space or any special character that might lead to an invalid name.

Organizational unit: Specifies the location of the newly created repository.

Click Finish.

You can view the newly created repository either in the File Explorer or the Project Explorer.

⁠Creating Repository Using kie-config-cli Tool

To create a new Git repository using the kie-config-cli tool, run the create-repo command. The tool then guides you through the entire process of creating a repository by asking for other required parameters. Type help for a list of all commands.

For more information about the kie-config-cli tool, see Chapter 6, Command Line Configuration.

⁠⁠Creating Repository Using REST API

Important

Note that only users with the rest-all role can create repositories.

To create a repository in the Knowledge Store, issue the POST REST API call. Details of the repository are defined by the JSON entity. Make sure you established an authenticated HTTP session before executing this call.

Input parameter of the call is a RepositoryRequest instance. Call returns a CreateOrCloneRepositoryRequest instance.

Example 1.2. Creating Repository Using Curl Utility

Example JSON entity containing details of a repository to be created:

{
  "name"                   : "newRepository",
  "description"            :  null,
  "gitURL"                 :  null,
  "requestType"            : "new",
  "organizationalUnitName" : "helloWorldUnit"
}

Execute the following command:

curl -X POST 'localhost:8080/business-central/rest/repositories/' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name":"newRepository","description":null,"requestType":"new","gitURL":null,"organizationalUnitName":"helloWorldUnit"}'

For further information, refer to chapter Knowledge Store REST API, section Repository Calls of Red Hat JBoss BPM Suite Development Guide.

Cloning a Repository

It is possible to clone a repository either in Business Central or using the REST API calls. The kie-config-cli tool cannot be used to clone arbitrary repositories. Run git clone, or use one of the following options instead:

Cloning a Repository in Business Central

Important

Note that only users with the admin role in Business Central can clone repositories.

Procedure: Using Business Central to Clone a Repository

In Business Central, go to Authoring → Administration.

On the perspective menu, choose Repositories → Clone repository.

The Clone Repository pop-up window is displayed.

Figure 1.3. Clone Repository Dialog Window

In the Clone Repository dialog window, enter the repository details:

Enter the Repository Name to be used as the repository identifier in the Asset repository and select the Organizational Unit it should be added to.

Enter the URL of the Git repository:

For a local repository, use file:///PATH_TO_REPOSITORY/REPOSITORY_NAME.

For a remote or preexisting repository, use https://github.com/USERNAME/REPOSITORY_NAME.git or git://HOST_NAME/REPOSITORY_NAME.

Important

It is important to use the HTTPS or Git protocol instead of a SCP-style SSH URL. Business Central does not support the basic SSH URL and fails with Invalid URL format.

Note

The file protocol is only supported for READ operations. WRITE operations are not supported.

If applicable, enter the User Name and Password of your Git account to be used for authentication.

Click Clone.

A confirmation prompt with the notification that the repository was created successfully is displayed.

Click Ok.

The repository is now being indexed. Some workbench features may be unavailable until the indexing has completed.

You can view the cloned repository either in the File Explorer or the Project Explorer.

Note

If you are deploying Business Central on WebLogic server, set the following Java system property in the setDomainEnv.sh file (for Linux) or setDomainEnv.cmd file (for Windows):

JAVA_OPTIONS="%JAVA_OPTIONS% -DUseSunHttpHandler=true"

This enables the WebLogic server to use the HTTP handlers.

Cloning a Repository Using the REST API

To clone a repository, issue the POST REST API call. This call creates or clones (according to the value of the requestType parameter) the repository defined by the JSON entity.

The input parameter of the call is a RepositoryRequest instance. The Call returns a CreateOrCloneRepositoryRequest instance.

Important

Note that, only users with the rest-all role can clone repositories.

Example 1.3. Cloning a Repository Using the Curl Utility

Example JSON entity containing details of a repository to be cloned:

{
  "name"                   : "clonedRepository",
  "description"            :  null,
  "requestType"            : "clone",
  "gitURL"                 : "git://localhost:9418/newRepository",
  "organizationalUnitName" : "helloWorldUnit"
}

Execute the following command:

curl -X POST 'localhost:8080/business-central/rest/repositories/' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name":"clonedRepository","description":null,"requestType":"clone","gitURL":"git://localhost:9418/newRepository","organizationalUnitName":"helloWorldUnit"}'

For further information, refer to chapter Knowledge Store REST API, section Repository Calls of Red Hat JBoss BPM Suite Development Guide.

Removing a Repository

Repositories can be removed using any of the following procedures.

Removing a Repository in Business Central

The simplest way to remove a repository is using the RepositoryEditor in Business Central.

Procedure: Using Business Central to Remove a Repository

In Business Central, go to Authoring → Administration.

Select Repositories from the tree menu on the left.

In the RepositoryEditor on the right side of the page, locate the repository you want to delete from the list of available repositories.

From the drop-down menu, select master → Delete.

The following message will appear:

Are you sure you want to remove Repository "REPOSITORY_NAME"? Some editors may become inoperable if their content is inaccessible.

Press OK to delete the repository.

Removing a Repository Using the kie-config-cli Tool

Repositories can be removed using the kie-config-cli tool as well. To do so, run the remove-repo command.

For further information about the kie-config-cli tool, see Chapter 6, Command Line Configuration.

Removing a Repository Using the REST API

Important

Note that only users with the rest-all role can remove repositories.

To remove a repository from the Knowledge Store, issue the DELETE REST API call. Make sure you established an authenticated HTTP session before executing this call.

The call returns a RemoveRepositoryRequest instance.

Example 1.4. Removing a Repository Using the Curl Utility

Execute the following command:

curl -X DELETE 'localhost:8080/business-central/rest/repositories/REPOSITORY_NAME' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json'

For further information, refer to chapter Knowledge Store REST API, section Repository Calls of Red Hat JBoss BPM Suite Development Guide.

Managing Assets

Note

To activate and use the feature described below, login to Business Central with a user that has the kiemgmt role assigned.

To make management of projects easier, Red Hat JBoss BRMS now provides a way to manage multiple projects based on standards. This allows you to create repository structures using industry standard best practices for maintenance, versioning and distribution of your projects.

To start with, repositories can now be managed or unmanaged.

Managed and Unmanaged Repositories

Unmanaged Repositories are the repository structures that you are used to. They can contain multiple unrelated projects.

Managed Repositories, on the other hand, provide version control at the project level and project branches for managing the release cycle. Further, Managed Repositories can be restricted to just a single project or encompass multiple projects. When you create a Managed Repository, the asset management configuration process is automatically launched in order to create the repository branches. Corresponding project structure is created as well.

Procedure: Creating an Unmanaged Repository

In Business Central, go to Authoring → Administration.

Click Repositories → New Repository.

The New Repository window is displayed.

Enter the repository name and select an organizational unit the repository belongs to.

Click Finish.

Procedure: Creating a Managed Repository

In Business Central, go to Authoring → Administration.

Click Repositories → New Repository.

The New Repository window is displayed.

Enter the repository name and select an organizational unit the repository belongs to.

Select the Managed Repository check box and click Next to enter additional details of the Managed Repository.

Choose either the Single-project Repository or the Multi-project Repository radio button.

If the project you are creating is simple and self-contained, select the Single-project Repository radio button. Note that you will not be able to add more projects to this repository later.

For more complex projects, where there is likely to be a parent project that encompasses smaller ones, select the Multi-project Repository radio button.

Enter the details of the managed project along with the GAV (Group, Artifact, Version) details.

Note that all projects created in a Multi-project Repository will be managed together, with their version numbers being incremented together as well. Details of the parent project will be inherited by all future projects that you create in this Managed Repository.

Click Finish .

Managed Branches

With Managed Repositories comes the added advantage of Managed Branches. As in Git, you can choose to work on different branches of your project (for example: master, dev and release). This process of branching can also be automated for you, by selecting the checkbox while creating a new Managed Repository (for both single and multi-projects).

You can switch between branches by selecting the desired branch while working in the Project Explorer.

Repository Structure

If you do not select automatic branch management while creating a repository, you can create branches manually afterwards. For Managed Repositories, you can do so by using the Configure button. This button, along with Promote and Release buttons, is provided in the Repository Structure view. You can access this view, by clicking on Repository → Repository Structure in the Project Explorer perspective menu.

Clicking on the Configure button allows you to create branches or edit automatically created ones.

You can promote assets from the master branch to other branches using the Promote button. Similarly, you can Release branches and deploy them on the server using the Release button.

Both these functions are controlled internally by the use of pre-defined processes that are deployed on your instance. For example, when you click on Promote button after having done work on your development branch, a Promote Changes process is started in the background. A user, with the role of kiemgmt will have a user task appear in this task list to review the assets being promoted. This user can claim this task, and decide to promote all, some or none of the assets. The underlying process will cherry-pick the commits selected by the user to a release branch. This user can also request another review of these assets and this process can be repeated multiple times till all the assets are ready for release. The flow for this process is shown below:

Similarly, when you click on the Release button, a release process flow is initiated. This process flow builds the project and updates all the Maven artifacts to the next version, and deploys the project to the runtime, if runtime deployment details are supplied.

Warning

Project branches to be released must start with the keyword release.

Warning

Do not use Deploy To Runtime with Red Hat JBoss BRMS as it causes deploy failure. This function can only be used with Red Hat JBoss BPM Suite.

Maven Repository

Maven is a software project management tool which uses a project object model (POM) file to manage:

Builds

Documentation

Reporting

Dependencies

Releases

SCMs

Distribution

A Maven repository is used to hold or store the build artifacts and project dependencies and is generally of two types:

Local

Refers to a local repository where all the project dependencies are stored and is located with the current installation in the default folder as "m2". It is a cache of the remote downloads, and also contains the temporary build artifacts which have not yet been released.

Remote

Refers to any other type of repository that can be accessed by a variety of protocols such as file:// or http://. These repositories can be at a remote location set up by a third-party for downloading of artifacts or an internal repository set up on a file or HTTP server, used to share private artifacts between the development teams for managing internal releases.

Configuring Deployment to a Remote Nexus Repository

Nexus is a repository manager frequently used in organizations to centralize storage and management of software development artifacts. It is possible to configure your project so that artifacts produced by every build are automatically deployed to a repository on a remote Nexus server.

To configure your project to deploy artifacts to a remote Nexus repository, add a distributionManagement element to your project’s pom.xml file as demonstrated in the code example below.

<distributionManagement>
  <repository>
    <id>deployment</id>
    <name>Internal Releases</name>
    <url>http://your_nexus_host:8081/nexus/content/repositories/releases</url>
  </repository>
  <snapshotRepository>
    <id>deployment</id>
    <name>Internal Releases</name>
    <url>http://your_nexus_host:8081/nexus/content/repositories/snapshots/</url>
  </snapshotRepository>
</distributionManagement>

Replace the URLs in the example with real URLs of your Nexus repositories. The repository specified in the snapshotRepository element is used when the -SNAPSHOT qualifier is appended to the project’s current version number. In other cases the repository specified in the repository element is used.

If your Nexus server requires authentication, you will also need to modify your projects Maven settings to add your credentials in the settings-security.xml file, using a master password. By default, this file is in the $M2_HOME/conf folder, unless you have changed its location by modifying the kie.maven.settings.custom system property. It is also possible to create new user-specific settings.xml and settings-security.xml files in the ~/.m2 folder. In that case, these files will override the original ones.

See the following example of the settings-security.xml:

<servers>
  <server>
    <id>deployment</id>
    <username>admin</username>
    <password>{COQLCE6DU6GtcS5P=}</password>
  </server>
</servers>

Important

Note that keeping your server authentication credentials (for example the passwords) as a plain text in the settings.xml file is not recommended. All the information should be hashed with a master password in the settings-security.xml file.

For further information about password encryption and creating a master password, see the Apache Maven documentation, article Password Encryption.

With this configuration in place, clicking the Build & Deploy button in Business Central executes a Maven build and deploys the built artifacts both to the local repository and to one of the Nexus repositories specified in the pom.xml file.

System Configuration

In JBoss EAP, to change a Business Central property, such as the configuration for SSH, do the following:

Procedure: Changing System Properties

Edit the file JBOSS_HOME/domain/configuration/host.xml

Locate the XML elements server that belong to the main-server-group and add the system property. For example:

<system-properties>
  <property name="org.uberfire.nio.git.dir" value="..." boot-time="false"/>
  ...
</system-properties>

Here is a list of all the available system properties:

Table 1.1. Available System Properties

Property
Usage
Default

org.uberfire.nio.git.dir

Location of the directory .niogit.

Working directory

org.uberfire.nio.git.daemon.enabled

Enables or disables the Git daemon.

true

org.uberfire.nio.git.daemon.host

If the Git daemon is enabled, it uses this property as the localhost identifier.

localhost

org.uberfire.nio.git.daemon.port

If the Git daemon is enabled, it uses this property as the internal port number.

9418

org.uberfire.nio.git.daemon.hostport

If the Git daemon is enabled, it uses this property as the external port number.

9418

org.uberfire.nio.git.ssh.enabled

Enables or disables the SSH daemon.

true

org.uberfire.nio.git.ssh.host

If the SSH daemon is enabled, it uses this property as the localhost identifier.

localhost

org.uberfire.nio.git.ssh.port

If the SSH daemon is enabled, it uses this property as the external port number.

8001

org.uberfire.nio.git.ssh.hostport

If the SSH daemon is enabled, it uses this property as the internal port number.

8001

org.uberfire.nio.git.ssh.cert.dir

Location of the .security directory where local certificates will be stored.

Working directory

org.uberfire.metadata.index.dir

Location of the .index folder for Lucene.

Working directory

org.uberfire.cluster.id

Name of the Helix cluster, for example: kie-cluster

org.uberfire.cluster.zk

Connection string to Zookeeper. This is of the form host1:port1,host2:port2,host3:port3. For example: localhost:2188.

org.uberfire.cluster.local.id

Unique id of the Helix cluster node. Note that ':' is replaced with '_'. For example: node1_12345.

org.uberfire.cluster.vfs.lock

Name of the resource defined on the Helix cluster, for example: kie-vfs

org.uberfire.cluster.autostart

Delays VFS clustering until the application is fully initialized to avoid conflicts when all cluster members create local clones.

false

org.uberfire.sys.repo.monitor.disabled

Disable configuration monitor (do not disable unless you know what you’re doing).

false

org.uberfire.secure.key

Secret password used by password encryption.

org.uberfire.admin

org.uberfire.secure.alg

Crypto algorithm used by password encryption.

PBEWithMD5AndDES

org.guvnor.m2repo.dir

Place where Maven repository folder will be stored.

working-directory/repositories/kie

org.kie.example.repositories

Folder from where demo repositories will be cloned. The demo repositories need to have been obtained and placed in this folder. This system property takes precedence over org.kie.demo and org.kie.example properties.

Not used.

org.kie.demo

Enables external clone of a demo application from GitHub. This system property takes precedence over org.kie.example.

true

org.kie.example

Enables example structure composed by Repository, Organization Unit and Project.

false

org.kie.build.disable-project-explorer

Disables automatic project building when navigating the Project Explorer.

false

Chapter 2. Business Central Configuration

As Business Central is a web application, any configuration settings are loaded from DEPLOY_DIRECTORY/business-central.war/WEB-INF/web.xml and the referenced files, and if deployed on Red Hat JBoss EAP 6, also in jboss-web.xml and jboss-deployment-structure.xml.

Note that the entire application can be run in different profiles (refer to the Red Hat JBoss BRMS Installation Guide).

Access Control

Workbench Configuration

Within Red Hat JBoss BRMS, users may set up roles using LDAP to modify existing roles. Users may modify the roles in the workbench configuration to ensure the unique LDAP based roles conform to enterprise standards by editing the deployments directory located at JBOSS_HOME/standalone/deployments/business-central.war/WEB-INF/classes/workbench-policy.propeties.

If authenticating user via LDAP over Git, administrators must set system property org.uberfire.domain to the name of login module it should use to authenticate users via the Git service. This must be set in the standalone.xmlfile in EAP.

Note

You can further customize Business Central with parameters no_build or no_search. The parameters disable the build and search functionality. Include one or both parameters in the Business Central URL, for example http://SERVER:PORT/business-central/kie-wb.jsp?no_build&no_search.

Branding the Business Central Application

The Business Central web application enables you to customize its look and feel by allowing you to override some of its default styles. The ability to customize the Business Central branding allows you to get a consistent appearance across all your applications thereby improving the user experience. It also helps in cases when multiple teams are using the application. Each team can develop their own customized user interface. The customizable elements are built using cascading style sheets (CSS), images, and HTML files, providing an easy and flexible approach to customize without having to recompile the code.

You can modify the following elements in the Business Central application to make it inline with your company’s brand:

Login screen

You can customize the following attributes of the Business Central login screen:

The background image

The company logo

The application logo

Application header

You can customize the following attributes of the Business Central application header:

The Business Central header containing the title and banner logo

Help pop-up windows

You can customize the following attributes of the splash help pop-up windows:

The splash help images

The label text

Customizing Business Central Login Page

Procedure: Changing the Business Central Login Page Background Image

Start the EAP server and open http://localhost:8080/business-central in a web browser.

Copy the new background image to the EAP_HOME/standalone/deployments/business-central.war/images directory in your Red Hat JBoss BRMS installation.

Navigate to EAP_HOME/standalone/deployments/business-central.war/styles directory and open the login-screen.css file in a text editor.

In the login-screen.css file, provide the location of your new background image in the following background-image attribute:

background-image: url("../images/login-screen-background.jpg");

The background-image attribute points to the default login-screen-background.jpg image.

In addition to the background image, you can modify other attributes such as image size, position, and background color in the login-screen.css file.

Refresh the Business Central login page to view your changes.

Procedure: Changing the Business Central Login Page Company Logo and Project Logo

Start the EAP server and open http://localhost:8080/business-central in a web browser.

Navigate to the EAP_HOME/standalone/deployments/business-central.war/images directory in your Red Hat JBoss BRMS installation.

Replace the default image login-screen-logo.png with a new one. This is the company logo that appears on the top right hand corner of the login page.

Replace the default image RH_JBoss_BRMS_Logo.png with a new one.

This is the project logo that appears on the center left hand side of the login page.

Refresh the Business Central login page to view your changes.

Customizing Business Central Application Header

Procedure: Changing the Business Central Application Header (Banner)

Start the EAP server and open http://localhost:8080/business-central in a web browser.

Log in to the Business Central application with your user credentials.

Copy your new application header image to the EAP_HOME/standalone/deployments/business-central.war/banner directory in your Red Hat JBoss BRMS installation.

Open EAP_HOME/standalone/deployments/business-central.war/banner/banner.html file in a text editor.

In the banner.html file, edit the following <img> tag to provide the name of your new header image:

<img src="banner/logo.png"/>

The default image is logo.png.

Refresh the Business Central Home page to view your changes.

Customizing Business Central Splash Help Windows

The EAP_HOME/standalone/deployments/business-central.war/plugins directory contains the splash pages and the corresponding html files. Each splash page holds the name of the html file, which contains information about the image(s) and the text to be displayed. For example, the authoring_perspective.splash.js splash page points to the authoring_perspective.splash.html file. The authoring_perspective.splash.html contains the names and location of all the image files that appear on the Authoring Perspective splash help and also their captions. You can customize the images and the corresponding captions of the existing splash help pop-up windows.

Procedure: Changing the Business Central Splash Help Pop-Up Images and Captions

Start the EAP server and open http://localhost:8080/business-central in a web browser.

Log in to the Business Central application with your user credentials.

Copy your new splash help image(s) to the EAP_HOME/standalone/deployments/business-central.war/images directory in your Red Hat JBoss BRMS installation.

Open the corresponding html file from EAP_HOME/standalone/deployments/business-central.war/plugins directory in a text editor.

Edit the html file to point to your new splash help image. For example, to change the first image that appears in the Authoring Perspective splash help, edit the following <img> tag in the authoring_perspective.splash.html file to add your new image:

<img src="images/authoring_perspective1.png" alt="">

The default image is authoring_perspective1.png, which appears on the first page of the Authoring Perspective splash help.

To change the image caption that appears on the splash help, edit the <h4> and <p> tag contents below the <img> tag:

<h4>Authoring</h4>
<p>Modularized and customizable workbench</p>

Refresh the Business Central Home page and access the splash help pop-up windows to view your changes.

Extending Business Central

Starting with version 6.1 of Red Hat JBoss BRMS, Business Central can be configured to add new screens, menus, editors, splashscreens and perspectives by the Administrator. These elements can extend functionality of Business Central and can be accessed through the Extensions → Plugin Management.

You can now define your own Javascript and HTML based plugins to extend Business Central and add them without having to worry about copying files in the underlying filesystem. Let us add a new screen in the system to show you the basics of this functionality.

Plugin Management

You access the Plugin Management screen by clicking on Extensions → Plugin Management. This brings up the Plugin Explorer screen that lists all the existing plugins under their respective categories:

Perspective Plugin

Screen Plugin

Editor Plugin

Splashscreen Plugin

and Dynamic Menu

Open any of these, and you will see the existing plugins in each category, including the uneditable system generated ones.

Let us create a new plugin that echoes "Hello World" when users visit the screen for that plugin. In general, the steps to creating a new plugin are:

Create a new screen

Create a new perspective (and add the new screen to it)

Create a new menu (and add the new perspective to it)

Apps (optional)

Adding a New Screen

Click the button and select New Screen. You will be prompted to enter the name of this new screen. Enter "HelloWorldJS" and press the OK button. The Screen plugin editor will open, divided into 4 sections: Template, CSS, JavaScript and Media.

Note

All manually created elements go into their respective categories in case you want to edit them later. In this case, to open the Screen plugin editor again if you close it, open the Screen Plugin category and scroll past the system generated screens to your manually created plugin and click on it to open the Screen plugin editor again.

Template is where your HTML goes, CSS is for styling, JavaScript is for your functions and Media is for uploading and managing images.

Since we are making a simple Hello World plugin, enter the following code in the Template section: <div>My Hello World Screen</div>. This can be any HTML code, and you can use the supplied Angular and Knockout frameworks. For the purposes of this example, we are not using any of those frameworks, but you can choose to by selecting them from the drop down in the Template section.

Enter your JavaScript code in the JavaScript section. Some common methods and properties are defined for you, including main, on_close and on_open. For this demo, select the on_open and enter the following: function () { alert('Hello World'); }

Click the Save button to finish creating the screen. After you save the screen, refresh business central so that the Screen Plugin is listed in the Screen Component of Perspective plugin.

Adding New Perspective

Once a screen has been created, you need to create a perspective on which this screen will reside. Perspectives can also be created similar to the way a screen is created by clicking on the New button and then selecting New Perspective. You can now provide a name for this perspective, say HelloWorldPerspective. This will open the Perspective plugin editor, similar to the Screen plugin editor.

The Perspective Editor is like a drag and drop grid builder for screens and HTML components. Remove any existing grids and then drag a 6×6 grid on the right hand side to the left hand side.

Next, open the Components category and drag a Screen Component on the right hand side to the left hand side (in any grid). This will open the Edit Component dialog box that allows you to select the screen created in the previous step (HelloWorldJS). Click the OK button and then click Save to save this perspective. To tag your perspective, enter Home in the tag name field and click Tags. Click OK and save the changes.

You can open this perspective again from the Perspective plugins listed on the left hand side.

Adding New Menu

The final step in creating our plugin is to add a dynamic menu from where the new screen/perspective can be called up. To do so, go to Extensions → Plugin Management and then click on the New button to select New Dynamic Menu. Give this dynamic menu a name (HelloWorldMenu) and then click the OK button. The dynamic menu editor opens up.

Enter the perspective name (HelloWorldPerspective) as the Activity Id and the name for the drop down menu (HelloWorldMenuDropDown). Click OK and then Save.

This new menu will be added to your workbench the next time you refresh Business Central. Refresh it now to see HelloWorldMenu added to your top level menu. Click on it to reveal HelloWorldMenuDropDown, which when clicked will open your perspective/screen with the message Hello World.

You have created your first Plugin!

Working with Apps (Optional)

If you create multiple plugins, you can use the Apps directory feature to organize your own components and plugins, instead of having to rely on just the top menu entries.

When you save a new perspective, you can add labels (tags) for them and these labels (tags) are used to associate a perspective with an App directory. You can open the App directories by clicking on Extensions → Apps.

The Apps directory provides an alternate way to open your perspective. When you created your HelloWorldPerspective, you entered the tag Home. The Apps directory by default contains a single directory called Home with which you associated your perspective. This is where you will find it when you open the Apps directory. You can click on it to run the perspective now.

You can create multiple directories and associate perspectives with those directories depending on functional and vertical business requirements. For example, you could create an HR directory and then associate all HR related perspectives with that directory to better manage Apps.

You can create a new directory by clicking the button.

The JavaScript (JS) API for Extensions

The extensibility of Business Central is achieved by an underlying JavaScript (JS) API which is automatically loaded if it is placed in the plugins folder of the Business Central webapp (typically: INSTALL_DIR/business-central.war/plugins/), or it can be loaded via regular JavaScript calls.

This API is divided into multiple sets depending on the functionality it performs.

Register Perspective API

Allows for the dynamic creation of perspectives. The example below creates a panel using the registerPerspective method:

$registerPerspective({
    id: "Home",
    is_default: true,
    panel_type: "org.uberfire.client.workbench.panels.impl.MultiListWorkbenchPanelPresenter",
    view: {
        parts: [
            {
                place: "welcome",
                min_height: 100,
                parameters: {}
            }
        ],
        panels: [
            {
                width: 250,
                min_width: 200,
                position: "west",
                panel_type: "org.uberfire.client.workbench.panels.impl.MultiListWorkbenchPanelPresenter",
                parts: [
                    {
                        place: "YouTubeVideos",
                        parameters: {}
                    }
                ]
            },
            {
                position: "east",
                panel_type: "org.uberfire.client.workbench.panels.impl.MultiListWorkbenchPanelPresenter",
                parts: [
                    {
                        place: "TodoListScreen",
                        parameters: {}
                    }
                ]
            },
            {
                height: 400,
                position: "south",
                panel_type: "org.uberfire.client.workbench.panels.impl.MultiTabWorkbenchPanelPresenter",
                parts: [
                    {
                        place: "YouTubeScreen",
                        parameters: {}
                    }
                ]
            }
        ]
    }
});

Editor API

Allows you to dynamically create editors and associate them with a file type. The example below creates a sample editor and associates it with filename file type.

$registerEditor({
    "id": "sample editor",
    "type": "editor",
    "templateUrl": "editor.html",
    "resourceType": "org.uberfire.client.workbench.type.AnyResourceType",
    "on_concurrent_update":function(){
        alert('on_concurrent_update callback')
        $vfs_readAllString(document.getElementById('filename').innerHTML, function(a) {
            document.getElementById('editor').value= a;
        });
    },
    "on_startup": function (uri) {
        $vfs_readAllString(uri, function(a) {
            alert('sample on_startup callback')
        });
    },
    "on_open":function(uri){
        $vfs_readAllString(uri, function(a) {
            document.getElementById('editor').value=a;
        });
        document.getElementById('filename').innerHTML = uri;
    }
});

In addition to on_startup and on_open methods seen in the previous example, the API exposes the following callback events for managing the editor’s lifecycle:

on_concurrent_update;

on_concurrent_delete;

on_concurrent_rename;

on_concurrent_copy;

on_rename;

on_delete;

on_copy;

on_update;

on_open;

on_close;

on_focus;

on_lost_focus;

on_may_close;

on_startup;

on_shutdown;

You can display this editor via an HTML template:

<div id="sampleEditor">
    <p>Sample JS editor (generated by editor-sample.js)</p>
    <textarea id="editor"></textarea>

    <p>Current file:</p><span id="filename"></span>
    <button id="save" type="button" onclick="$vfs_write(document.getElementById('filename').innerHTML, document.getElementById('editor').value,  function(a) {});">Save</button>
    <br>

    <p>This button change the file content, and uberfire send a callback to the editor:</p>
    <button id="reset" type="button" onclick="$vfs_write(document.getElementById('filename').innerHTML, 'Something else',  function(a) {});">Reset File</button>
</div>

PlaceManager API

The methods of this API allow you to request that the Business Central display a particular component associated with a target: $goToPlace("componentIdentifier");

Register plugin API

The methods of this API allow you to create dynamic plugins (that will be transformed in Business Central screens) via the JS API.

$registerPlugin( {
    id: "my_angular_js",
    type: "angularjs",
    templateUrl: "angular.sample.html",
    title: function () {
        return "angular " + Math.floor(Math.random() * 10);
    },
    on_close: function () {
        alert("this is a pure JS alert!");
    }
});

The plugin references the angular.sample.html template:

<div ng-controller="TodoCtrl">
    <span>{{remaining()}} of {{todos.length}} remaining</span>
    [ <a href="" ng-click="archive()">archive</a> ]
    <ul class="unstyled">
        <li ng-repeat="todo in todos">
            <input type="checkbox" ng-model="todo.done">
            <span class="done-{{todo.done}}">{{todo.text}}</span>
        </li>
    </ul>
    <form ng-submit="addTodo()">
        <input type="text" ng-model="todoText" size="30" placeholder="add new todo here">
        <input class="btn-primary" type="submit" value="add">
    </form>
    <form ng-submit="goto()">
        <input type="text" ng-model="placeText" size="30" placeholder="place to go">
        <input class="btn-primary" type="submit" value="goTo">
    </form>
</div>

A plugin can be hooked to Business Central events via a series of JavaScript callbacks:

on_concurrent_update;

on_concurrent_delete;

on_concurrent_rename;

on_concurrent_copy;

on_rename;

on_delete;

on_copy;

on_update;

on_open;

on_close;

on_focus;

on_lost_focus;

on_may_close;

on_startup;

on_shutdown;

Register splash screens API

use the methods in this API to create splash screens.

$registerSplashScreen({
    id: "home.splash",
    templateUrl: "home.splash.html",
    body_height: 325,
    title: function () {
        return "Cool Home Splash " + Math.floor(Math.random() * 10);
    },
    display_next_time: true,
    interception_points: ["Home"]
});

Virtual File System (VFS) API

with this API, you can read and write a file saved in the file system using an asynchronous call.

$vfs_readAllString(uri,  function(a) {
  //callback logic
});

$vfs_write(uri,content,  function(a) {
  //callback logic
})

Configuring Table Columns

Business Central allows you to configure views that contain lists of items in the form of tables. You can resize columns, move columns, add or remove the default list of columns and sort the columns. This functionality is provided for all views that contain tables.

Once you make changes to the columns of a table view, these changes are persisted for the current logged in user.

Adding and Removing Columns

Tables that allow columns to be configured have the button in the top right corner. Clicking on this button opens up the list of columns that can added or removed to the current table with a check box next to each column:

Resizing Columns

To resize columns, place your cursor between the edges of the column header and move in the direction that you want:

Moving Columns

To re-order and drag and drop a column in a different position, hover your mouse over the rightmost area of the column header:

You can now grab the column and move it:

Drop it over the column header that you want to move it to.

Sorting Columns

To sort columns, click on the desired column’s header. To reverse-sort, click on the header again.

Chapter 3. Realtime Decision Server

The Realtime Decision Server is a standalone, out-of-the-box component that can be used to instantiate and execute rules through interfaces available for REST, JMS, or a Java client side application. Created as a web deployable WAR file, this server can be deployed on any web container. The current version of the Realtime Decision Server ships with default extensions for both Red Hat JBoss BRMS and Red Hat JBoss BPM Suite.

This server has a low footprint, with minimal memory consumption, and therefore, can be deployed easily on a cloud instance. Each instance of this server can open and instantiate multiple KIE Containers which allows you to execute multiple rule services in parallel.

You can provision the Realtime Decision Server instances through Business Central. In this chapter, you will go through the steps required to set up the Realtime Decision Server, provision and connect to this server through Business Central, control what rule artifacts go in each instance, and go through its lifecycle.

Note

For further information, see chapter Intelligent Process Server and Realtime Decision Server of Red Hat JBoss BPM Suite Development Guide.

Deploying the Realtime Decision Server

The Realtime Decision Server is distributed as a web application archive (WAR) file with the name of kie-server.war. When you install Red Hat JBoss BRMS, this WAR file is installed and deployed in your web container by default.

You can copy this WAR file and deploy it in any other web container (Red Hat JBoss Web Server or another Red Hat JBoss EAP install, for example) and have this server available from other web containers. Note that you must deploy the WAR file that is compatible for your web container.

Once you have deployed the WAR file (or if you have it deployed on the same web container where Red Hat JBoss BRMS is deployed), create a user with the role of kie-server in this web container.

Test that you can access the decision engine by navigating to the endpoint in a browser window: http://SERVER:PORT/kie-server/services/rest/server/ with the web container running. You will be prompted for your username/password that you created in the previous step.

Once authenticated, you will see an XML response in the form of engine status, similar to this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response type="SUCCESS" msg="Kie Server info">
 <kie-server-info>
  <capabilities>BPM</capabilities>
	<capabilities>KieServer</capabilities>
	<capabilities>BRM</capabilities>
	<location>http://localhost:8230/kie-server/services/rest/server</location>
	<name>KieServer@/kie-server</name>
	<id>15ad5bfa-7532-3eea-940a-abbbbc89f1e8</id>
	<version>6.4.0.Final-redhat-5</version>
	</kie-server-info>
</response>

Installing the Realtime Decision Server in Other Containers

JBoss Web Server 2.x/3.x, Tomcat 8.x/9.x

Use the following procedure to install the Realtime Decision Server in a Tomcat container.

Procedure:

Download and unzip the Tomcat distribution.

Download kie-server-6.4.0.Final-webc.war and place it into TOMCAT_HOME/webapps.

Configure user(s) and role(s). Make sure that TOMCAT_HOME/conf/tomcat-users.xml contains the following username and role definition. The username and password should be unique, however ensure that the user has the role kie-server:

<role rolename="kie-server"/>
<user username="serveruser" password="my.s3cr3t.pass" roles="kie-server"/>

Start the server by running TOMCAT_HOME/bin/startup.[sh|bat]. You can check out the Tomcat logs in TOMCAT_HOME/logs to see if the application deployed successfully. See the section called “Bootstrap Switches” for the bootstrap switches that can be used to properly configure the instance. For instance:

$ ./startup.sh -Dorg.kie.server.id=first-kie-server -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server

Verify the server is running. Access http://SERVER:PORT/kie-server/services/rest/server/ and type the specified username and password. You should see simple XML message with basic information about the server.

Important

You cannot leverage the JMS interface when running on Tomcat, or any other Web container. The Web container version of the WAR contains only the REST interface.

Realtime Decision Server Setup

Bootstrap Switches

The Realtime Decision Server accepts a number of bootstrap switches (system properties) to configure the behavior of the server. The following is a table of all the supported switches.

Note that some properties are marked as required when using a controller. Thus, you need to set these properties when you handle Realtime Decision Server container creation, and removal in Business Central. If you use the Realtime Decision Server separately, without any interaction with Business Central, you do not have to set these properties.

Table 3.1. Realtime Decision Server Bootstrap Switches

Property
Value
Default Value
Description

org.drools.server.ext.disabled

boolean

false

If true, disables the BRM support (for example rules support).

org.jbpm.server.ext.disabled

boolean

false

If true, disables the BPM support (for example processes support).

org.optaplanner.server.ext.disabled

boolean

false

If true, disables the BRP support (for example planner support).

org.jbpm.ui.server.ext.disabled

boolean

false

If true, disables the Realtime Decision Server UI extension.

org.kie.server.id

string

–

An arbitrary ID to be assigned to this server. If a remote controller is configured, this is the ID under which the server will connect to the controller to fetch the KIE container configurations. If not provided, the ID is automatically generated.

org.kie.server.user

string

kieserver

A user name used to connect with the KIE server from the controller, required when running in managed mode. This property need to be set in Business Central system properties and is required when using a controller.

org.kie.server.pwd

string

kieserver1!

A password used to connect with the KIE server from the controller, required when running in managed mode. This property need to be set in Business Central system properties and is required when using a controller.

org.kie.server.token

string

–

This property allows you to use a token-based authentication between the controller and the KIE server instead of the basic user name/password authentication. The controller sends the token as a parameter in the request header. Note that long-lived access tokens are required, as the tokens are not refreshed.

org.kie.server.controller

list

–

A comma-separated list of URLs to controller REST endpoints, for example http://localhost:8080/business-central/rest/controller. This property is required when using a controller.

org.kie.server.controller.user

string

kieserver

A user name used to connect to the controller REST API. This property is required when using a controller.

org.kie.server.controller.pwd

string

kieserver1!

A password used to connect to the controller REST API. This property is required when using a controller.

org.kie.server.controller.token

string

–

This property allows you to use a token-based authentication between the KIE server and the controller instead of the basic user name/password authentication. The KIE server sends the token as a parameter in the request header. Note that long-lived access tokens are required, as the tokens are not refreshed.

org.kie.server.location

URL

–

URL of Realtime Decision Server instance used by the controller to call back on this server, for example: http://localhost:8230/kie-server/services/rest/server. This property is required when using a controller.

org.kie.server.domain

string

–

JAAS LoginContext domain that shall be used to authenticate users when using JMS.

org.kie.server.bypass.auth.user

boolean

false

Allows to bypass the authenticated user for task related operations, for example queries.

org.kie.server.repo

path

.

A valid file system path to the location where Realtime Decision Server state files will be stored.

org.kie.server.persistence.ds

string

–

A data source JNDI name. This property is required if the BPM support is enabled.

org.kie.server.persistence.tm

string

–

A transaction manager platform for Hibernate properties set. This property is required if the BPM support is enabled.

org.kie.server.persistence.dialect

string

–

A Hibernate dialect to be used. This property is required if the BPM support is enabled.

org.kie.server.persistence.schema

string

–

A database schema to be used.

org.jbpm.ht.callback

string

jaas

One of the supported callbacks for the Task Service.

org.jbpm.ht.custom.callback

string

–

Custom implementation of UserGroupCallback in case the org.jbpm.ht.callback was set to custom.

kie.maven.settings.custom

path

–

Location of a custom settings.xml file for Maven configuration.

org.kie.executor.interval

integer

3

A number of time units between polls by executor.

org.kie.executor.pool.size

integer

1

A number of threads in the pool for asynchronous work.

org.kie.server.sync.deploy

boolean

false

Instructs the KIE server to hold the deployment until the controller provides the containers deployment configuration. This property affects only the KIE servers running in a managed mode.

If false, connection to the controller is asynchronous. The application starts, connects to the controller and once successful, deploys the containers. The application accepts requests even before the containers are available.

If true, deployment of the KIE server application joins the controller connection thread with the main deployment and awaits its completion. This option can lead to a potential deadlock in case more applications are on the same server instance. It is strongly recommended to use only one application (the KIE server) on a server instance.

org.kie.executor.retry.count

integer

3

A number of retries to handle errors.

org.kie.executor.timeunit

TimeUnit

SECONDS

A TimeUnit representing interval.

org.kie.executor.disabled

boolean

false

Disables the executor completely.

kie.server.jms.queues.response

string

queue/KIE.SERVER.RESPONSE

A JNDI name of response queue for JMS.

org.kie.server.controller.connect

long

10000

Waiting time in milliseconds between repeated attempts to connect Realtime Decision Server to the controller when Realtime Decision Server starts up.

org.drools.server.filter.classes

boolean

false

If set to true, Drools Realtime Decision Server extension accepts custom classes being annotated by XmlRootElement or Remotable annotations only.

Important

Make sure the new data source for the Realtime Decision Server points to a different database schema than the data source used by Business Central by modifying the org.kie.server.persistence.ds property in order to avoid conflicts.

Managed Realtime Decision Server

A managed instance requires an available controller to start the Realtime Decision Server.

A controller manages the Realtime Decision Server configuration in a centralized way. Each controller can manage multiple configurations at once, and there can be multiple controllers in the environment. Managed Realtime Decision Server can be configured with a list of controllers, but will only connect to one at a time.

Important

Controllers should be synchronized to ensure that the same set of configuration is provided to the server, regardless of the controller to which it connects.

When the Realtime Decision Server is configured with a list of controllers, it will attempt to connect to each of them at startup until a connection is successfully established with one of them. If a connection cannot be established, the server will not start, even if there is a local storage available with configuration. This ensures consistence and prevents the server from running with redundant configuration.

Note

To run the Realtime Decision Server in standalone mode without connecting to controllers, see the section called “Unmanaged Realtime Decision Server”.

Configuring Realtime Decision Server Managed by Business Central

Warning

This section provides a sample setup that you can use for testing purposes. Some of the values are unsuitable for a production environment, and are marked as such.

Configure the Business Central to manage a Realtime Decision Server instance by performing the following steps:

Configuring Realtime Decision Server Managed by Business Central

Make sure users with the following roles exist:

In Business Central, a user with the role rest-all.

On the Realtime Decision Server, a user with the role kie-server.

Note

In production environments, use two distinct users, each with one role. In this sample situation, we use only one user named controllerUser that has both the rest-all and the kie-server roles.

If such users do not exist, create them.

On Red Hat JBoss EAP, go to EAP_HOME/bin/ and execute:

$ ./add-user.sh -a --user controllerUser --password controllerUser1234; --role kie-server,rest-all

Warning

Plain-text passwords are not secure. For production environments, use a password vault. For more information, see the Password Vault chapter of the Red Hat JBoss Enterprise Application Platform 6.4 How To Configure Server Security guide.

On Red Hat JBoss Web Server, see the section called “JBoss Web Server 2.x/3.x, Tomcat 8.x/9.x”.

On IBM WebSphere Application Server, see the Creating Users and Groups section of the Red Hat JBoss BRMS IBM WebSphere Installation and Configuration Guide.

On Oracle WebLogic Server, see the Configuring Security Settings section of the Red Hat JBoss BRMS Oracle Weblogic Installation and Configuration Guide.

Set the following JVM properties. The location of Business Central and the Realtime Decision Server may be different. In such case, ensure you set the properties on the correct server instances.

On Red Hat JBoss EAP, modify the <system-properties> section in:

EAP_HOME/standalone/configuration/standalone*.xml for standalone mode.

EAP_HOME/domain/configuration/domain.xml for domain mode.

On Red Hat JBoss Web Server, see the section called “JBoss Web Server 2.x/3.x, Tomcat 8.x/9.x”.

On IBM WebSphere Application Server, see section Adding Custom JVM Properties of the Red Hat JBoss BRMS IBM WebSphere Installation and Configuration Guide.

On Oracle WebLogic Server, see section Setting Environment Variables of the Red Hat JBoss BRMS Oracle WebLogic Installation and Configuration Guide.

Table 3.2. JVM Properties set on Managed Realtime Decision Server instance

Property
Value
Note

org.kie.server.id

default-kie-server

The Realtime Decision Server ID.

org.kie.server.controller

http://localhost:8080/business-central/rest/controller

The location of Business Central.

org.kie.server.controller.user

controllerUser

The user name from the previous step (with the role rest-all).

org.kie.server.controller.pwd

controllerUser1234;

The password from the previous step.

Table 3.3. JVM Properties set on Business Central instance

Property
Value
Note

org.kie.server.location

http://localhost:8080/kie-server/services/rest/server

The location of the Realtime Decision Server.

org.kie.server.user

controllerUser

The user name from the previous step (with the role kie-server).

org.kie.server.pwd

controllerUser1234;

The password from the previous step.

Verify the successful start of the Realtime Decision Server by sending a GET request to http://SERVER:PORT/kie-server/services/rest/server/. Once authenticated, you get an XML response similar to this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response type="SUCCESS" msg="Kie Server info">
    <kie-server-info>
        <capabilities>BRM</capabilities>
        <capabilities>BPM-UI</capabilities>
        <capabilities>BPM</capabilities>
        <capabilities>BRP</capabilities>
        <capabilities>KieServer</capabilities>
        <location>http://localhost:8080/kie-server/services/rest/server</location>
        <messages>
            <content>Server KieServerInfo{serverId='local-server-123', version='6.4.0.Final-redhat-3', location='http://localhost:8080/kie-server/services/rest/server'}started successfully at Fri Jun 03 13:48:44 CEST 2016</content>
            <severity>INFO</severity>
            <timestamp>2016-06-03T13:48:44.606+02:00</timestamp>
        </messages>
        <name>local-server-123</name>
        <id>local-server-123</id>
        <version>6.4.0.Final-redhat-3</version>
    </kie-server-info>
</response>

Verify successful registration by logging into Business Central and selecting Deploy → Execution Servers. If successful, you can see the registered server ID.

Unmanaged Realtime Decision Server

An unmanaged Realtime Decision Server is a standalone instance, and therefore must be configured individually using REST/JMS API from the Realtime Decision Server itself. There is no controller involved. The configuration is automatically persisted by the server into a file and that is used as the internal server state, in case of restarts.

The configuration is updated during the following operations:

Deploy KIE Container

Undeploy KIE Container

Start KIE Container

Stop KIE Container

Note

If the Realtime Decision Server is restarted, it will attempt to re-establish the same state that was persisted before shutdown. Therefore, KIE Containers that were running will be started, but the ones that were stopped will not.

Creating a Container

Once your Realtime Decision Server is registered, you can start adding containers to it. Containers are self-contained environments that have been provisioned to hold instances of your packaged and deployed rule instances. To create a container, follow these steps:

Log into Business Central.

Click Deploy → Rule Deployment.

In the SERVER TEMPLATES section on the left, select your server.

Click Add Container to see the New Container wizard.

Add a name of your container under Name.

Click Search and select a built project you wish to deploy into the container.

Alternatively, enter Group Name, Artifact Id and Version manually.

Warning

When you enter the container version number, do not use the LATEST or RELEASE keywords. This feature has been deprecated and can cause deployment issues.

Click Next to configure Runtime strategy, Kie Base and Kie Session for your container.

Alternatively, click Finish to skip configuration of Runtime strategy, Kie Base and Kie Session for your container.

Click Finish.

After you successfully create your container, click Start.

Figure 3.1. Container in Started Mode

To verify the container is up and running, send a [GET] request to the endpoint.

Example 3.1. Server Response

<response type="SUCCESS" msg="Info for container myContainer">
  <kie-container container-id="myContainer" status="STARTED">
    <messages>
      <content>
        Container myContainer successfully created with module org.jbpm:CustomersRelationship:1.0.
      </content>
      <severity>INFO</severity>
      <timestamp>2016-03-02T11:43:40.806+01:00</timestamp>
    </messages>
    <release-id>
      <artifact-id>CustomersRelationship</artifact-id>
      <group-id>org.jbpm</group-id>
      <version>1.0</version>
    </release-id>
    <resolved-release-id>
      <artifact-id>CustomersRelationship</artifact-id>
      <group-id>org.jbpm</group-id>
      <version>1.0</version>
    </resolved-release-id>
    <scanner status="DISPOSED"/>
  </kie-container>
</response>

Managing Containers

Containers within the Realtime Decision Server can be started, stopped, and updated from within Business Central.

Starting, Stopping, and Deleting a Container

A container is stopped by default. To start it, follow these steps:

Log into Business Central.

Click Deploy → Rule Deployment.

In the SERVER TEMPLATES section on the left, click on your Realtime Decision Server ID.

In the KIE CONTAINERS section, click on the container you want to start.

Click Start. Alternatively, click Stop to stop a running container. Once a container is stopped, you can click Remove to remove it.

Upgrading a Container

You can update deployed containers without needing to restart the Realtime Decision Server. This is useful in cases where the business rule changes cause new versions of packages to be provisioned. You can have multiple versions of the same package provisioned and deployed. To upgrade a container, follow these steps:

Log into Business Central.

Click Deploy → Execution Servers.

In the KIE CONTAINERS section, click on the container you want to upgrade.

Click on the Version Config tab.

Enter the new version in the Version textfield and click Upgrade.

Optionally, if you want a deployed container to always have the latest version of your deployment without manually editing it, set the Version field value to LATEST and click Scan Now button. This ensures that the deployed container contains the latest version of your deployment. Clicking the Scan Now button scans through the repositories only once. If it finds a newer version of container deployment in the repository, the container is automatically upgraded to this newer version. You can optionally start the scanner in the background by clicking the Start Scanner button and specify the scan interval (in milliseconds) as well.

Note that, you can even set the Version field value to LATEST when you are creating the deployment for the first time.

Managing Multiple Containers

You can create and provision multiple containers on your Realtime Decision Server.

Select your server in the REMOTE SERVERS section to view all the containers on your server and their status.

Figure 3.2. Managing Multiple Containers

Chapter 4. Logging

Logback Functionality

Red Hat JBoss BRMS provides logback functionality for logging configuration.

Accordingly, everything configured is logged to the Simple Logging Facade for Java SLF4J, which delegates any log to Logback, Apache Commons Logging, Log4j or java.util.logging. Add a dependency to the logging adaptor for your logging framework of choice. If you are not using any logging framework yet, you can use Logback by adding this Maven dependency:

<dependency>
   <groupId>ch.qos.logback</groupId>
   <artifactId>logback-classic</artifactId>
   <version>1.x</version>
</dependency>

Note

slf4j-nop and slf4j-simple are ideal for a light environment.

Configuring Logging

To configure the logging level of the packages, create a logback.xml file in business-central.war/WEB-INF/classes/logback.xml. To set the logging level of the org.drools package to "debug" for verbose logging, you would need to add the following line to the file:

<configuration>
  <logger name="org.drools" level="debug"/>

  ...
<configuration>

Similarly, you can configure logging for packages such as the following:

org.guvnor

org.jbpm

org.kie

org.slf4j

org.dashbuilder

org.uberfire

org.errai

etc…​

If configuring with log4j, the log4j.xml can be located at business-central.war/WEB-INF/classes/log4j.xml and can be configured in the following way:

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

  <category name="org.drools">
    <priority value="debug" />
  </category>

  ...

</log4j:configuration>

Note

Additional logging can be configured in the individual container. To configure logging for JBoss Enterprise Application Platform, please refer to the Red Hat JBoss Enterprise Application Platform Administration and Configuration Guide.

Chapter 5. Repository Hooks

In Business Central, it is possible to trigger a chosen action every time a particular event happens. For this purpose, you can configure the repository to use scripts called hooks.

Configuring Git Hooks

Business Central can automatically push changes to a remote repository using the Git hooks. Git hooks support has been introduced with the release of Red Hat JBoss BRMS 6.2.0.

Note

Please note that currently only the post-commit hook is supported. Post-commit hooks are triggered after finishing the entire commit process.

The following procedure shows how to configure the post-commit hook to automatically push your changes to the remote repository.

In Business Central, go to Authoring → Administration.

Below the main menu, click Repositories → Clone repository.

In the displayed Clone repository dialog box, fill in the repository information:

Repository Name

Organizational Unit

Git URL: For example https://github.com/USERNAME/REPOSITORY_NAME.git

Important

It is important to use the HTTPS or Git protocol instead of a SCP-style SSH URL. Business Central does not support the basic SSH URL and fails with Invalid URL format.

Figure 5.1. An invalid SCP-style SSH URL.

User Name: your Git user name

Password: your Git password

Change to the created repository:

cd JBOSS_HOME/bin/.niogit/REPOSITORY_NAME.git

Change the remote URL:

git remote set-url origin git@github.com:USERNAME/REPOSITORY_NAME.git

Make sure that you can access the remote repository through command line using SSH. For example, the private SSH key for the repository should exist under the ~/.ssh/ directory.

If you created a new repository, you may encounter the following error:

fatal: No such remote 'origin'

To resolve it, add the remote origin URL:

git remote add origin git@github.com:USERNAME/REPOSITORY_NAME.git

Verify that the remote repository was successfully added:

git remote -v

The command should list the following:

origin  git@github.com:USERNAME/REPOSITORY_NAME.git (fetch)
origin  git@github.com:USERNAME/REPOSITORY_NAME.git (push)

Create a file named post-commit with the permissions set to rwxr--r-- under JBOSS_HOME/bin/.niogit/REPOSITORY_NAME.git/hooks with the following content:

#!/bin/sh
git push origin master

Make sure that the configuration was successful by creating a new guided rule in Business Central:

Go to Authoring → Project Authoring → New Item → Guided Rule.

Fill in the required information in the displayed Create new Guided Rule window.

Click Ok.

All of the changes should be pushed automatically.

For further information about remote Git repositories, see How to configure the BxMS 6 server to use a remote Git repository for storing assets?.

It is also possible to specify the system property org.uberfire.nio.git.hooks. Its value determines a directory with default hook files, which will be copied to the newly created Git repositories. See the example of a standalone.xml file with this setting below:

<system-properties>
  <property name="org.uberfire.nio.git.hooks" value="/opt/jboss-as/git-hooks">
  </property>
  ...
</system-properties>

Chapter 6. Command Line Configuration

The kie-config-cli tool is a command line configuration tool that provides capabilities to manage the system repository from the command line and can be used in an online or offline mode.

Online mode (default and recommended)

On startup, the tool connects to a Git repository using a Git server provided by kie-wb. All changes are made locally and published to upstream only after explicitly executing the push-changes command. Use the exit command to publish local changes. To discard local changes on exit, use the discard command.

Offline mode (installer style)

Creates and manipulates the system repository directly on the server (there is no discard option).

The tool is available on the Red Hat Customer Portal. To download the kie-config-cli tool, do the following:

Go to the Red Hat Customer Portal and log in.

Click DOWNLOADS at the top of the page.

In the Product Downloads page that opens, click Red Hat JBoss BRMS.

From the Version drop-down menu, select 6.4.0.

In the displayed table, navigate to the Supplementary Tools row and then click Download.

Extract the zip package for supplementary tools you downloaded from the Red Hat Customer Portal. It contains the directory kie-config-cli-6.MINOR_VERSION-redhat-x-dist with file kie-config-cli.sh.

Starting the kie-config-cli Tool in Online Mode

To start the kie-config-cli tool in online mode, navigate to the kie-config-cli-6.MINOR_VERSION-redhat-x-dist directory where you installed the tool and then execute the following command.

In a Unix environment run:

./kie-config-cli.sh

In a Windows environment run:

./kie-config-cli.bat

By default, the tool starts in online mode and asks for user credentials and a Git URL to connect to (the default value is git://localhost/system). To connect to a remote server, replace the host and port with appropriate values.

Example: git://kie-wb-host:9148/system

Starting the kie-config-cli Tool in Offline Mode

To operate in offline mode, append the offline parameter to the command as below.

Navigate to the kie-config-cli-6.MINOR_VERSION-redhat-x-dist directory where you installed the tool.

In a Unix environment, run:

./kie-config-cli.sh offline

In a Windows environment, run:

./kie-config-cli.bat offline

Executing this command changes the tool’s behaviour and displays a request to specify the folder where the system repository (.niogit) is located. If .niogit does not yet exist, the folder value can be left empty and a brand new setup is created.

Commands Available for the kie-config-cli Tool

The following commands are available for managing the Git repository using the kie-config-cli tool:

add-deployment: Adds a new deployment unit

add-repo-org-unit: Adds a repository to the organizational unit

add-role-org-unit: Adds role(s) to an organizational unit

add-role-project: Adds role(s) to a project

add-role-repo: Adds role(s) to a repository

create-org-unit: Creates new organizational unit

create-repo: Creates a new git repository

discard: Does not publish local changes, cleans up temporary directories and closes the tool

exit: Publishes work, cleans up temporary directories and closes the tool

fetch-changes: Fetches changes from upstream repository

help: Prints available commands with descriptions

list-deployment: Lists available deployments

list-org-units: Lists available organizational units

list-repo: Lists available repositories

push-changes: Pushes changes to upstream repository (in online mode only)

remove-deployment: Removes existing deployment

remove-org-unit: Removes existing organizational unit

remove-repo: Removes an existing repository from config only

remove-repo-org-unit: Removes a repository from the organizational unit

remove-role-org-unit: Removes role(s) from an organizational unit

remove-role-project: Removes role(s) from a project

remove-role-repo: Removes role(s) from a repository

Chapter 7. Migration

Migrating your projects from Red Hat JBoss BRMS 5 to Red Hat JBoss BRMS 6 requires careful planning and step by step evaluation of the various issues. You can plan for migration either manually, or by using automatic processes. Most real world migration will require a combination of these two processes.

Because Red Hat JBoss BRMS 6 uses Git for storing assets, artifacts and code repositories including processes and rules, you should start by creating an empty project in Red Hat JBoss BRMS 6 as the basis for your migration with dummy files as placeholders for the various assets and artifacts. Running a Git clone of this empty project into your favorite IDE will initiate the migration process.

Based on the placeholder files in your cloned project, you can start adding assets at the correct locations. The Red Hat JBoss BRMS 6 system is smart enough to pick these changes and apply them correctly. Ensure that when you are importing old rule files that they are imported with the right package name structure.

Since Maven is used for building projects, the projects assets like the rules, processes and models are accessible as a simple JAR file.

This section lists the generally accepted step by step ways to migrate your project. These are just guidelines though, and actual migration may vary a lot from this.

In general, you should:

Migrate the data first: These are your business assets.

Next, migrate your runtime processes.

Finally, convert old API calls to new ones one by one.

Let us look at these steps in more detail in the next few sections:

Data Migration

To migrate data from Red Hat JBoss BRMS 5, do the following:

Download the migration tool by logging in at the Red Hat Customer Portal and then navigating to Red Hat JBoss BRMS Software Downloads section. Click on Red Hat JBoss BRMS Migration Tool to download the zip archive.

Unzip the downloaded zip archive in a directory of your choice and navigate to this directory in a command prompt. This directory contains four folders:

bin - contains the launch scripts.

jcr-exporter-libs - contains the libs specific to the export-from-JCR part of the migration.

vfs-importer-libs - contains the libs specific to the import-into-Git part of the migration.

conf - contains global migration tool configuration.

For production databases, copy the JDBC driver for the database that is used by the JCR repository into the jcr-exporter-libs directory of the migration tool.

Execute the following command:

./bin/runMigration.sh -i <source-path> -o <destination-path> -r <repository-name>

Where:

<source-path> is a path to a source JCR repository.

<desintation-path> is a path to a destination Git VFS. This folder must not exist already.

<repository-name> an arbitrary name for the new repository.

The repository is migrated at the specified destination.

Besides the -i command, you can also use -h to print out a help message and -f which forces an overwrite of the output directory, thus eliminating the need for manual deletion of this directory.

Importing the Repository in Business Central

The repository can be imported in business central by cloning it. In the Administration perspective, click on the Repositories → Clone Repository menu to start the process.

Note

Assets can also be migrated manually as they are all just text files. The BPMN2 specification and the DRL syntax did not change between the different versions.

Importing the Repository in JBDS

To import the repository in JBoss Developer Studio, do the following

Start JBoss Developer Studio.

Start the Red Hat JBoss BRMS server (if not already running) by selecting the server from the server tab and click the start icon.

Select File → Import…​ and navigate to the Git folder. Open the Git folder to select Projects from Git and click next.

Select the repository source as Existing local repository and click next.

Select the repository that is to be configured from the list of available repositories.

Import the project as a general project in the next window and click next. Name this project and click Finish.

API and Backwards Compatibility

Migrating to Version 6.1

In version 6.1, 5.X APIs are no longer officially supported.

Red Hat JBoss BRMS no longer provides backward compatibility with the rule, event, and process application programming interface (API) from Red Hat JBoss BRMS 5. The content of the knowledge-api JAR file is no longer supported in version 6.1 and is replaced by APIs contained in the kie-api JAR file that were introduced in Red Hat JBoss BRMS 6.0.

If you used the legacy 5.x API (located in knowledge-api.jar), please migrate (rewrite) the API calls to the new KIE API. Please be aware that several other APIs have changed between Red Hat JBoss BRMS 5.x and Red Hat JBoss BRMS 6.x, namely the task service API and the REST API.

Migrating to Version 6.0

The Red Hat JBoss BRMS 6 system provides backward compatibility with the rule, event and process interactions from JBoss BRMS 5. You should eventually migrate (rewrite) these interactions to the all new revamped core API because this backward compatibility is likely to be deprecated.

If you cannot migrate your code to use the new API, then you can use the API provided by the purpose built knowledge-api JAR for backwards compatible code. This API is the public interface for working with JBoss BPM Suite and JBoss BRMS and is backwards compatible.

If you are instead using the REST API in Red Hat JBoss BRMS 5, note that this has changed as well and there is no mechanism in it for backwards compatibility.

Part II. Integration

Chapter 8. Integrating Red Hat JBoss BRMS with Red Hat JBoss Fuse

Red Hat JBoss Fuse integration allows users of Red Hat JBoss Fuse to complement their integration solution with additional features provided by Red Hat JBoss BPM Suite and Red Hat JBoss BRMS.

Red Hat JBoss BRMS integration is provided by two features.xml files:

drools-karaf-features-VERSION-features.xml

This file provides core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS features, which defines the OSGi features that can be deployed into Red Hat JBoss Fuse. This file is a part of the Red Hat JBoss BPM Suite and Red Hat JBoss BRMS product. OSGi users can install features from this file in order to install Red Hat JBoss BRMS engine or Red Hat JBoss BPM Suite engine into Red Hat JBoss Fuse and use it in their applications.

karaf-features-VERSION-features.xml

This file provides additional features used for integrating Red Hat JBoss BPM Suite and Red Hat JBoss BRMS with Apache Camel, primarily in Red Hat JBoss Fuse. This file is part of the Integration Pack and it defines OSGi features that enable integration with Apache Camel and SwitchYard. In addition to the karaf-features XML file, the Integration Pack also contains a features.xml file for quick starts.

For further information about integration of Red Hat JBoss BRMS with Red Hat JBoss Fuse, see the Install Integration Pack chapter of the Red Hat JBoss Fuse Integration Guide.

Core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS Features

Core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS features are provided by the drools-karaf-features-VERSION-features.xml file present in your product Maven repository or the jboss-brms-bpmsuite-VERSION-redhat-VERSION-fuse-features.zip file. It provides the following features:

drools-common

drools-module

drools-templates

drools-decisiontable

drools-jpa

kie

kie-ci

kie-spring

kie-aries-blueprint

jbpm-commons

jbpm-human-task

jbpm

droolsjbpm-hibernate

h2

The following table provides example of use cases for some of the features listed above.

Table 8.1. Features and Use Case Examples

Feature
Use Case

drools-module

Use the Red Hat JBoss BRMS engine for rules evaluation, without requiring persistence, processes, or decision tables.

drools-jpa

Use the Red Hat JBoss BRMS engine for rules evaluation with persistence and transactions, but without requiring processes or decision tables. The drools-jpa feature already includes drools-module, however you may also need to install the droolsjbpm-hibernate feature, or ensure there is a compatible hibernate bundle installed.

drools-decisiontable

Use the Red Hat JBoss BRMS engine with decision tables.

jbpm

Use the Red Hat JBoss BPM Suite (or Red Hat JBoss BRMS engine with processes). The jbpm feature already includes drools-module and drools-jpa. You may also need to install the droolsjbpm-hibernate feature, or ensure that there is a compatible hibernate bundle installed.

jbpm and jbpm-human-task

Use the Red Hat JBoss BPM Suite (or Red Hat JBoss BRMS engine with processes) with Human Task.

core engine JARs and kie-ci

Use Red Hat JBoss BRMS or Red Hat JBoss BPM Suite with KieScanner (KIE-CI) to download kJARs from a Maven repository.

kie-spring

Use KIE-Spring integration. See the section called “kie-spring Feature Further Information” for more information.

kie-spring and kie-aries-blueprint

Use KIE-Aries-Blueprint integration.

kie-spring Feature Further Information

Use org.drools.osgi.spring.OsgiKModuleBeanFactoryPostProcessor instead of org.kie.spring.KModuleBeanFactoryPostProcessor to postprocess KIE elements in an OSGi environment.

Do not install the drools-module feature before the kie-spring feature. Otherwise, the drools-compiler bundle does not detect packages exported by kie-spring.

Run osgi:refresh drools-compiler_bundle_ID if you have installed the features in the incorrect order to force drools-compiler to rebuild its Import-Package metadata.

Additional Features for SwitchYard and Apache Camel Integration

The following additional features for integration with SwitchYard and Apache Camel on Red Hat JBoss Fuse are provided by the integration pack:

fuse-bxms-switchyard-common-knowledge

fuse-bxms-switchyard-rules

fuse-bxms-switchyard-bpm

kie-camel

jbpm-workitems-camel

The integration pack features are defined in the karaf-features-VERSION-features.xml file. This file (and supporting repositories) is located in http://repository.jboss.org/nexus/content/repositories/public, which is already configured for use on Red Hat JBoss Fuse 6.2 out of the box in INSTALLATION_DIRECTORY/etc/org.ops4j.pax.url.mvn.cfg.

The file can also be downloaded from either the Red Hat JBoss Fuse 6.2 or Red Hat JBoss BRMS product page in the Red Hat Customer Portal.

Installing and Updating Core Integration Features

Note

This section refers to features in the drools-karaf-features-VERSION-features.xml file. For additional integration features, see the section called “Installing Additional Integration Features”.

If you have already installed an older version of the core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS features (for example, drools-karaf-features-6.2.0.Final-redhat-6-features.xml ), you need to remove them and all associated files before installing the most recent features.xml file.

Procedure: Removing Existing drools-karaf-features Installation

Start the Red Hat JBoss Fuse console using:

$ ./INSTALLATION_DIRECTORY/bin/fuse

Unistall old features or applications that used the previous features.xml file. For example:

JBossFuse:karaf@root> features:uninstall drools-module
JBossFuse:karaf@root> features:uninstall jbpm
JBossFuse:karaf@root> features:uninstall kie-ci

Search for references of bundles using drools, kie, or jbpm and remove them:

karaf@root> list -t 0 -s | grep drools
karaf@root> list -t 0 -s | grep kie
karaf@root> list -t 0 -s | grep jbpm

To remove the bundles:

karaf@root> osgi:uninstall BUNDLE_ID

Remove the old drools-karaf-features URL:

karaf@root> features:removeurl mvn:org.drools/drools-karaf-features/6.2.0.Final-redhat-VERSION/xml/features

Restart Red Hat JBoss Fuse.

To install the drools-karaf-features:

Procedure: Installing Core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS Features

Configure required repositories:

Edit the INSTALLATION_DIRECTORY/etc/org.ops4j.pax.url.mvn.cfg file in your Red Hat JBoss Fuse installation and add the following entry to the org.ops4j.pax.url.mvn.repositories variable (note that entries are separated by , \):

https://maven.repository.redhat.com/ga/

Start Red Hat JBoss Fuse:

$ ./INSTALLATION_DIRECTORY/bin/fuse

Add a reference to the core features file by running the following console command:

For Red Hat JBoss Fuse 6.2.1, use:

JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features

For Red Hat JBoss Fuse 6.3.0, use:

JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features-fuse-6_3

For example:

features:addurl mvn:org.drools/drools-karaf-features/6.4.0.Final-redhat-10/xml/features-fuse-6_3

To see the current drools-karaf-features version, see Supported Component Versions of the Red Hat JBoss BRMS Installation Guide.

You can now install the features provided by this file by running, for example, the following console command:

JBossFuse:karaf@root> features:install drools-module

Installing Additional Integration Features

Use the following procedure for additional integration with SwitchYard and Apache Camel.

Procedure: SwitchYard and Apache Camel Integration

Download the fuse-integration package that is aligned with your version of Red Hat JBoss Fuse.

Note

For instance, if you want to use the 6.2.0.redhat-117 version of Red Hat JBoss Fuse, you need to install the fuse-6.2.0.redhat-117 Red Hat JBoss Fuse integration features.

Add the remote Maven repository that contains the fuse dependencies to your karaf instance:

Edit the FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg

Update the Drools features URL:

JBossFuse:karaf@root> features:addurl mvn:org.switchyard.karaf/mvn:org.switchyard.karaf/switchyard/SWITCHYARD_VERSION/xml/core-features
JBossFuse:karaf@root> features:addurl mvn:org.jboss.integration.fuse/karaf-features/1.0.0.redhat-VERSION/xml/features

Additionally, update the drools-karaf-features URL. For Red Hat JBoss Fuse 6.2.1, use:

JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features

For Red Hat JBoss Fuse 6.3.0, use:

JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features-fuse-6_3

To see the current drools-karaf-features version, see Supported Component Versions of the Red Hat JBoss BRMS Installation Guide.

You can now install the features provided for SwitchYard and Apache Camel integration by running, for example, the following console command:

JBossFuse:karaf@root> features:install fuse-bxms-switchyard-rules
JBossFuse:karaf@root> features:install kie-camel
JBossFuse:karaf@root> features:install jbpm-workitems-camel

Configuring Dependencies

When you configure KIE, Red Hat JBoss BRMS, or Red Hat Jboss BPM Suite in your application, you can follow one of the following approaches to build your OSGi application bundles:

Bundle required dependencies into your application bundle. In this approach, you declare all required artifacts as runtime dependencies in your pom.xml. Hence, you need not import the packages that provide these artifacts that you have already added as dependencies.

Import the required dependencies into the application bundle. This is a preferred approach for building OSGi bundles as it adheres to the principles of OSGi framework. In this approach, you declare only the API JARs (such as org.kie:kie-api) as dependencies in your application bundle. You will need to install the required Red Hat JBoss BRMS and Red Hat JBoss BPM Suite bundles and then import them in your application.

Warning

The MVELUserGroupCallback class fails to initialize in an OSGi environment. Do not use or include MVELUserGroupCallback as it is not designed for production purposes.

Installing Red Hat JBoss Fuse Integration Quick Start Applications

The following features for Red Hat JBoss Fuse integration quick start applications are provided by org/jboss/integration/fuse/quickstarts/karaf-features/1.0.0.redhat-VERSION/karaf-features-1.0.0.redhat-VERSION-features.xml:

fuse-bxms-switchyard-quickstart-bpm-service

fuse-bxms-switchyard-quickstart-rules-camel-cbr

fuse-bxms-switchyard-quickstart-rules-interview

fuse-bxms-switchyard-quickstart-rules-interview-container

fuse-bxms-switchyard-quickstart-rules-interview-dtable

fuse-bxms-switchyard-demo-library

fuse-bxms-switchyard-demo-helpdesk

fuse-bxms-camel-blueprint-drools-decision-table

fuse-bxms-camel-spring-drools-decision-table

fuse-bxms-jbpm-workitems-camel-quickstart

fuse-bxms-spring-jbpm-osgi-example

This file (and supporting repositories) is located in http://repository.jboss.org/nexus/content/repositories/public, which is already configured for use on Red Hat JBoss Fuse 6.2 out of the box in INSTALLATION_DIRECTORY/etc/org.ops4j.pax.url.mvn.cfg.

Procedure: Installing Quick Start Applications

Add a reference to the features file by running the following console command:

JBossFuse:karaf@root> features:addurl mvn:org.jboss.integration.fuse.quickstarts/karaf-features/1.0.0.redhat-VERSION/xml/features

You can now install the quick start applications provided by this features file by running, for example, the following console command:

JBossFuse:karaf@root> features:install fuse-bxms-switchyard-quickstart-bpm-service

Procedure: Downloading and Installing Quick Start ZIP Files

Download the quick start application ZIP file.

Unpack the contents of the quick starts directory into your existing INSTALLATION_DIRECTORY/quickstarts directory.

Unpack the contents of the system directory into your existing INSTALLATION_DIRECTORY/system directory.

Testing Your First Quick Start Application

Procedure: Testing Quick Start Application

Start Red Hat JBoss Fuse:

$ ./INSTALLATION_DIRECTORY/bin/fuse

Install and start the switchyard-bpm-service by running the following console command:

JBossFuse:karaf@root> features:install fuse-bxms-switchyard-quickstart-bpm-service

Note

Any dependent features specified by the application’s features file will be installed automatically.

Submit a web service request to invoke the SOAP gateway.

Open a terminal window and navigate to the associated quick start directory that was unpacked from the quick start application ZIP file (in this case, switchyard-bpm-service).

Run the following command:

$ mvn clean install

Note

You will need the following repositories configured in your settings.xml file:

http://maven.repository.redhat.com/ga/

http://repository.jboss.org/nexus/content/repositories/public/

Run the following command:

$ mvn exec:java -Pkaraf

You will receive the following response:

SOAP Reply:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <ns2:submitOrderResponse xmlns:ns2="urn:switchyard-quickstart:bpm-service:1.0">
      <orderId>test1</orderId>
      <accepted>true</accepted>
      <status>Thanks for your order, it has been shipped!</status>
    </ns2:submitOrderResponse>
  </soap:Body>
</soap:Envelope>

Chapter 9. Integrating Red Hat JBoss BRMS with Red Hat Single Sign-On

Red Hat Single Sign-On (RH-SSO) is a Single Sign-On solution that you can use for securing your browser applications and your REST web services. This chapter describes how you can integrate RH-SSO with Red Hat JBoss BRMS and leverage its features.

Integrating with RH-SSO brings an integrated SSO and IDM (Identity Management) environment for Red Hat JBoss BRMS. The session management feature of RH-SSO allows you to use different Red Hat JBoss BRMS environments on the web by authenticating only once.

For more information on RH-SSO, see the RH-SSO documentation.

Red Hat Single Sign On Integration Points

You can integrate RH-SSO with Realtime Decision Servers using the following integration points:

Business Central authentication through an RH-SSO server

Authenticating Red Hat JBoss BRMS Business Central through RH-SSO involves securing both the Business Central web client and remote services through RH-SSO. This integration enables you to connect to Business Central using either web interface or a remote service consumer through RH-SSO.

Realtime Decision Server authentication through an RH-SSO server

Authenticating Red Hat JBoss BRMS Realtime Decision Server through RH-SSO involves securing the remote services provided by the Realtime Decision Server as it does not provide a web interface for server authentication. This enables any remote Red Hat JBoss BRMS service consumer (user or a service) to authenticate through RH-SSO.

Third-party client authentication through an RH-SSO server

Authenticating a third-party client through an RH-SSO server involves third-party clients to authenticate themselves using RH-SSO to consume the remote service endpoints provided by Business Central and Realtime Decision Server, such as the REST API or remote file system services.

The following sections describe how to achieve RH-SSO integration through these integration points:

Business Central Authentication through RH-SSO

To authenticate Business Central through RH-SSO:

Set up and run an RH-SSO server with a realm client for Business Central.

Install and set up the RH-SSO client adapter for EAP.

Secure Business Central Remote Service using RH-SSO.

Setting Up RH-SSO with Realm Client for Business Central

Security realms are used to restrict access for the different applications resources. It is advised to create a new realm whether your RH-SSO instance is private or shared amongst other products. You can keep the master realm as a place for super administrators to create and manage the realms in your system. If you are integrating with an RH-SSO instance that is shared with other product installations to achieve Single Sign-On with those applications, all those applications must use the same realm.

Here is how you can install an RH-SSO server and create a security realm for Business Central:

Procedure: Setting Up RH-SSO with Realm Client

Install and configure a basic RH-SSO standalone server. To do this, follow the instructions in the RH-SSO Installation Guide.

Note

If you want to run both RH-SSO and Red Hat JBoss BRMS servers on the same machine, ensure that you avoid port conflicts. To do so, do one of the following:

Update the RHSSO_HOME/standalone/configuration/standalone.xml file and set a port offset to 100. For example:

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:100}">

Use an environment variable to run the server:

bin/standalone.sh -Djboss.socket.binding.port-offset=100

Start the RH-SSO server using the following command from RHSSO_HOME/bin:

./standalone.sh

Once the RH-SSO server starts, open http://localhost:8180/auth/admin in a web browser and log in using your admin credentials that you created while installing RH-SSO. When you login for the first time, you can set up the initial user using the new user registration form.

On the RH-SSO admin console, click Realm Settings tab.

On the Realm Settings page, click Add Realm.

The Add realm page opens.

On the Add realm page, provide a name for the realm and click Create.

Click Client tab from the main admin console menu and click Create.

The Add Client page opens.

On the Add Client page, provide the required information to create a new client for your realm. For example:

Client ID: kie

Client protocol: openid-connect

Root URL: http://localhost:8080/business-central

Click Save to save your changes.

Once you create a new client, its access value is public by default. Change it to confidential.

At this point, the RH-SSO server is configured with a realm with a client for Red Hat JBoss BRMS applications (Business Central, in this example) and running and listening for HTTP connections at localhost:8180. This realm provides different users, roles, and sessions for the Red Hat JBoss BRMS applications.

Setting Up RH-SSO Client Adapter for EAP

To set up the RH-SSO client adapter for EAP:

Install the RH-SSO adapter for EAP.

Configure the Red Hat JBoss BRMS application and the RH-SSO client adapter.

Procedure: Installing the RH-SSO Adapter for Red Hat JBoss EAP 6 and 7

Install Red Hat JBoss EAP 6.4.X or 7.0.

For version 6, see Chapter 2. Installation Instructions from the Red Hat JBoss Enterprise Application Platform Installation Guide.

For version 7, see Red Hat JBoss Enterprise Application Platform Installation Guide.

Install Red Hat JBoss BRMS in the freshly installed JBoss EAP.

If you configure RH-SSO adapter by making changes in standalone.xml, and then unzip Red Hat JBoss BRMS, you may overwrite and lose the RH-SSO adapter configuration.

Download the EAP adapter from the Red Hat Customer Portal.

Unzip and install the adapter. For installation instructions, see Installing Adapters for Red Hat Single Sign-On in the RH-SSO Installation Guide.

For version 7, go to EAP_HOME/standalone/configuration and open the standalone.xml and standalone-full.xml files. Delete the <single-sign-on/> element from both of them.

You do not need to perform this step for Red Hat JBoss EAP 6.

Procedure: Configuring the RH-SSO Adapter

Navigate to EAP_HOME/standalone/configuration in your EAP installation and edit standalone.xml to add the RH-SSO subsystem configuration. For example:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
 <secure-deployment name="business-central.war">
   <realm>demo</realm>
   <realm-public-key>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB</realm-public-key>
   <auth-server-url>http://localhost:8180/auth</auth-server-url>
   <ssl-required>external</ssl-required>
   <enable-basic-auth>true</enable-basic-auth>
   <resource>kie</resource>
   <credential name="secret">759514d0-dbb1-46ba-b7e7-ff76e63c6891</credential>
   <principal-attribute>preferred_username</principal-attribute>
 </secure-deployment>
</subsystem>

Here,

secure-deployment name: Name of your application’s WAR file.

realm: Name of the realm that you created for the applications to use.

realm-public-key: The public key of the realm you created. You can find it in the Keys tab in the Realm settings page of the realm you created in the RH-SSO admin console. If you do not provide a value for realm-public-key, the server retrieves it automatically.

auth-server-url: The URL for the RH-SSO authentication server.

enable-basic-auth: The setting to enable basic authentication mechanism, so that the clients can use both token-based and basic authentication approaches to perform the requests.

resource: The name for the client that you created.

credential name: The secret key for the client you created. You can find it in the Credentials tab on the Clients page of the RH-SSO admin console.

principal-attribute: The login name of the user. If you do not provide this value, your User Id is displayed in the application instead of your user name.

Note

The RH-SSO server converts the user names to lowercase. Therefore, after integration with RH-SSO, your user name will appear in lowercase in Business Central. If you have user names in upper-case letters hard coded in business processes, the application may not be able to identify the upper-case user.

Add the following sub element under the <extensions> section of standalone.xml:

<extension module="org.keycloak.keycloak-adapter-subsystem"/>

This secures the application using the urn:jboss:domain:keycloak subsystem in standalone.xml as opposed to securing it through web.xml file inside each WAR.

Navigate to EAP_HOME/bin/ and start the EAP server using the following command:

./standalone.sh

Note

You can also configure RH-SSO adapter for EAP by updating your applications WAR file to use the RH-SSO security subsystem. However, the recommended approach is configuring the adapter through the RH-SSO subsystem. This means that you are updating EAP configuration instead of applying the configuration on each WAR file.

Adding a New User

To add new users and assign them a role to access Business Central:

Login to the RH-SSO Admin console and open the realm you wish to add a user to.

Click Users under Manage section in the left menu bar.

An empty user list page called Users opens.

Click the Add User button on the empty user list to start creating your new user.

An Add user page opens.

Provide user information on the Add user page and click Save.

Set new password under the Credentials tab.

Assign the new user one of the roles that allow access to Business Central (For example, admin or analyst role for Red Hat JBoss BRMS and admin or developer role for Red Hat JBoss BPM Suite).

Define the roles as realm roles in the Roles page under the Configure section.

Click Role Mappings tab on the Users page to assign roles.

You can now login to your Red Hat JBoss BRMS application (in this example, Business Central) once the server is running using the user credentials you just created.

Securing Business Central Remote Service Using RH-SSO

Business Central provides different remote service endpoints that can be consumed by third-party clients using remote API. To authenticate those services through RH-SSO, you must disable a security filter called BasicAuthSecurityFilter. To do this, follow these steps:

Procedure: Disabling BasicAuthSecurityFilter

Open your application deployment descriptor file (WEB-INF/web.xml) and apply the following changes to it:

Remove the following lines to remove the servlet filter and its mapping for class org.uberfire.ext.security.server.BasicAuthSecurityFilter:

<filter>
  <filter-name>HTTP Basic Auth Filter</filter-name>
  <filter-class>org.uberfire.ext.security.server.BasicAuthSecurityFilter</filter-class>
  <init-param>
    <param-name>realmName</param-name>
    <param-value>KIE Workbench Realm</param-value>
  </init-param>
</filter>

<filter-mapping>
  <filter-name>HTTP Basic Auth Filter</filter-name>
  <url-pattern>/rest/*</url-pattern>
  <url-pattern>/maven2/*</url-pattern>
  <url-pattern>/ws/*</url-pattern>
</filter-mapping>

Add the following lines to add the security-constraint for the url-patterns that you have removed from the filter mapping:

<security-constraint>
  <web-resource-collection>
    <web-resource-name>remote-services</web-resource-name>
    <url-pattern>/rest/*</url-pattern>
    <url-pattern>/maven2/*</url-pattern>
    <url-pattern>/ws/*</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>rest-all</role-name>
  </auth-constraint>
</security-constraint>

Save your changes.

Securing Business Central File System Services Using RH-SSO

To consume other remote services, such as file systems (for example a remote GIT service), you need to specify a correct RH-SSO login module for the application’s security domain in the EAP_HOME/standalone/configuration/standalone.xml file.

By default, the security domain in Business Central is set to other. Replace the default values of the login-module in this security domain with the ones presented in the example below:

<security-domain name="other" cache-type="default">
  <authentication>
    <login-module code="org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule" flag="required">
      <module-option name="keycloak-config-file" value="$EAP_HOME/kie-git.json"/>
    </login-module>
  </authentication>
</security-domain>

The JSON file specified in the module-option element contains a client used for securing the remote services. Replace the $EAP_HOME/kie-git.json value of the module-option element with the absolute path or the class path (classpath:/EXAMPLE_PATH/kie-git.json) to this JSON configuration file.

To generate the JSON configuration file:

Navigate to the KC Administration Console located at http://localhost:8080/auth/admin.

Click Clients in the main menu on the left.

Create a new client with the following settings:

Set Client ID as kie-git.

Set Access Type as confidential.

Disable the Standard Flow Enabled option.

Enable the Direct Access Grants Enabled option.

Click Save.

Click the Installation tab at the top of the client configuration screen and choose Keycloak OIDC JSON as a Format Option.

Click Download.

Move the downloaded JSON file to an accessible directory in the server’s file system or add it to the application class path.

Specify the file as a value in the module-option element with the keycloak-config-file argument.

For more information, see chapter JAAS plugin of the Keycloak Securing Applications and Services Guide.

At this point, all users authenticated through the RH-SSO server can clone internal GIT repositories using the following command:

git clone ssh://admin@localhost:8001/system

Realtime Decision Server Authentication through RH-SSO

The Red Hat JBoss BRMS Realtime Decision Server provides a REST API for third-party clients. You can integrate the Realtime Decision Server with RH-SSO to delegate the third-party clients identity management to the RH-SSO server.

Once you have created a realm client for Business Central and set up the RH-SSO client adapter for EAP, you can repeat the same steps to integrate the Realtime Decision Server with RH-SSO.

Creating Client for Realtime Decision Server on RH-SSO

To create a new client on your already created realm on RH-SSO admin console:

Procedure: Creating a Client for the Realtime Decision Server

On the RH-SSO admin console, open the security realm that you created.

Click Client tab from the main menu and click Create.

The Add Client page opens.

On the Add Client page, provide the required information to create a new client for your realm. For example:

Client ID: kie-execution-server

Root URL: http://localhost:8080/kie-server

Client protocol: openid-connect

Navigate to the Credentials tab and copy the secret key and and paste it on the kie-execution-server client configuration screen.

Click Save to save your changes.

Once you create a new client, its access value is public by default. Change it to confidential.

Installing and Setting Up Realtime Decision Server with Client Adapter

To consume the Realtime Decision Server remote service endpoints, you must first create and assign the kie-server role in the RH-SSO admin console.

Procedure: Setting Up the Realtime Decision Server

Navigate to EAP_HOME/standalone/configuration in your EAP installation and edit standalone.xml to add the RH-SSO subsystem configuration. For example:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
  <secure-deployment name="kie-server.war">
     <realm>demo</realm>
     <realm-public-key>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB</realm-public-key>
     <auth-server-url>http://localhost:8180/auth</auth-server-url>
     <ssl-required>external</ssl-required>
     <resource>kie-execution-server</resource>
     <enable-basic-auth>true</enable-basic-auth>
     <credential name="secret">03c2b267-7f64-4647-8566-572be673f5fa</credential>
     <principal-attribute>preferred_username</principal-attribute>
  </secure-deployment>
</subsystem>

<system-properties>
  <property name="org.kie.server.sync.deploy" value="false"/>
</system-properties>

Here,

secure-deployment name: Name of your application WAR file.

realm: Name of the realm that you created for the applications to use.

realm-public-key: The public key of the realm you created. You can

find it in the Keys tab in the Realm settings page of the realm you created in the RH-SSO admin console. If you do not provide a value for this public key, the server retrieves it automatically.

auth-server-url: The URL for the RH-SSO authentication server.

resource: The name for the server client that you created.

enable-basic-auth: The setting to enable basic authentication mechanism, so that the clients can use both token-based and basic authentication approaches to perform the requests.

credential name: The secret key of the server client you created. You can find it in the Credentials tab on the Clients page of the RH-SSO admin console.

principal-attribute: The login name of the user. If you do not provide this value, your User Id is displayed in the application instead of your user name.

Save your configuration changes in standalone.xml.

Use the following command to restart the EAP server and run the Realtime Decision Server.

EXEC_SERVER_HOME/bin/standalone.sh -Dorg.kie.server.id=<ID> -Dorg.kie.server.user=<USER> -Dorg.kie.server.pwd=<PWD> -Dorg.kie.server.location=<LOCATION_URL> -Dorg.kie.server.controller=<CONTROLLER_URL> -Dorg.kie.server.controller.user=<CONTROLLER_USER> -Dorg.kie.server.controller.pwd=<CONTOLLER_PASSWORD>

Here is an example:

EXEC_SERVER_HOME/bin/standalone.sh -Dorg.kie.server.id=kieserver1 -Dorg.kie.server.user=kieserver -Dorg.kie.server.pwd=password -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server -Dorg.kie.server.controller=http://localhost:8080/business-central/rest/controller -Dorg.kie.server.controller.user=kiecontroller -Dorg.kie.server.controller.pwd=password

Once the Realtime Decision Server is running, you can check the server status using the following command:

curl http://kieserver:password@localhost:8080/kie-server/services/rest/server/

Token-based authorization is also supported for communication between Business Central and the Realtime Decision Server. You can use the complete token as system property, instead of the username and password, for your applications. However, you must ensure that the token does not expire for the period of interaction between the applications, as it is not automatically refreshed.

For the Business Central to manage the Realtime Decision Server using the tokens:

Set the org.kie.server.token property.

In such case, do not set the org.kie.server.user and org.kie.server.pwd properties. The Business Central will then use the Authorization: Bearer $TOKEN authentication method.

If you want to use the REST API using the token-based authentication:

Set the org.kie.server.controller.token property.

In such case, do not set the org.kie.server.controller.user and org.kie.server.controller.pwd properties.

Third-Party Client Authentication through RH-SSO

To use the different remote services provided by the Red Hat JBoss BRMS or by a Realtime Decision Server, your client must be authenticated on the RH-SSO server and have a valid token to perform the requests. To use the remote services, the authenticated user must have assigned the following roles:

rest-all: For using the Business Central remote services

Note

The rest-all role must have user specified in org.kie.server.controller.user property.

kie-server: For using the Realtime Decision Server remote services

Use the RH-SSO Administrator Console to create these roles and assign them to the users that will consume the remote services.

To achieve third-party client authentication through RH-SSO, you can choose between one of these options:

Basic authentication (if the application’s client supports it)

Token-based authentication

Basic Authentication

If you have enabled the basic authentication in the RH-SSO client adapter configuration for both Business Central and Realtime Decision Server, you can avoid the token grant/refresh calls and call the services as shown in the examples below:

For web based remote repositories endpoint:

 curl http://admin:password@localhost:8080/business-central/rest/repositories

For the Realtime Decision Server:

curl http://admin:password@localhost:8080/kie-server/services/rest/server/

Token-Based Authentication

If you want to opt for a more secure option of authentication, you can consume the remote services from both Business Central and Realtime Decision Server using a granted token provided by a new RH-SSO client.

Procedure: Obtaining and Using Token for Authorizing Remote Calls

Click Client tab from the main admin console menu and click Create to create a new client.

The Add Client page opens.

On the Add Client page, provide the required information to create a new client for your realm. For example:

Client ID: kie-remote

Client protocol: openid-connect

Click Save to save your changes.

Obtain a token from Realm Settings:

On the RH-SSO admin console, click Realm Settings tab.

Click Tokens tab.

Change the value for Access Token Lifespan to 15 minutes.

This gives you enough time to obtain a token and invoke the service before it expires.

Click Save to save your changes.

Once a public client for your remote clients is created, you can now obtain the token by making an HTTP request to the RH-SSO server’s token endpoint using:

RESULT=`curl --data "grant_type=password&client_id=kie-remote&username=admin&password=password" http://localhost:8180/auth/realms/demo/protocol/openid-connect/token`

The user used in the command above is an RH-SSO user with the role kie-server assigned. For further information, see the section called “Adding a New User”.

To view the token obtained from the RH-SSO server, use the following command:

TOKEN=`echo $RESULT | sed 's/.*access_token":"//g' | sed 's/".*//g'`

You can now use this token to authorize the remote calls. For example, if you want to check the internal Red Hat JBoss BRMS repositories, use the token as shown below:

curl -H "Authorization: bearer $TOKEN" http://localhost:8080/business-central/rest/repositories

Chapter 10. Integration with Spring

Configuring Red Hat JBoss BRMS with Spring

The jboss-brms-engine.zip file contains the Spring module, which is called kie-spring-VERSION-redhat-MINOR_VERSION.jar.

You can configure the Spring modules:

As a Self Managed Process Engine

If you require a single runtime manager instance, use the RuntimeManager API. The RuntimeManager API synchronizes the process engine and task service internally.

As a Shared Task Service

If you require multiple runtime manager instances, use the jBPM services.

Integrating Spring with Runtime Manager API

To integrate Spring with the Runtime Manager API, include the following factory beans:

org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean

org.kie.spring.factorybeans.RuntimeManagerFactoryBean

org.kie.spring.factorybeans.TaskServiceFactoryBean

Note

TaskServiceFactoryBean is required only for shared task service.

RuntimeEnvironmentFactoryBean

RuntimeEnvironmentFactoryBean produces RuntimeEnvironment instances consumed by RuntimeManager.

You can create the following types of RuntimeEnvironment instances:

DEFAULT: The default type.

EMPTY: An empty environment.

DEFAULT_IN_MEMORY: Same as DEFAULT with no persistence of the runtime engine.

DEFAULT_KJAR: Same as DEFAULT with knowledge assets taken from kJAR and identified by releaseID or GAV (Group, Artifact, Version).

DEFAULT_KJAR_CL: Built from class path that consists of a kmodule.xml descriptor.

Knowledge information is required for all the RuntimeEnvironment types. Provide one or more of the following:

knowledgeBase

assets

releaseId

groupId, artifactId, version

For the DEFAULT, DEFAULT_KJAR, DEFAULT_KJAR_CL types, configure persistence using entity manager factory or transaction manager.

RuntimeManagerFactoryBean

RuntimeManagerFactoryBean creates RuntimeManager instances based on runtimeEnvironment. You can create the following runtimeEnvironment instances:

SINGLETON (default)

PER_REQUEST

PER_PROCESS_INSTANCE

Every RuntimeManager instance must have a unique ID. You can dispose of any RuntimeManager instance created by RuntimeManagerFactoryBean by calling the close() method.

TaskServiceFactoryBean

TaskServiceFactoryBean creates TaskService instance based on the given properties. Creates a single instance only.

Properties required:

entity manager factory

transaction manager

When using the TaskServiceFactoryBean, provide the Spring transaction manager. When using a shared entity manager from Spring, you can also provide EntityManager instance instead of entity manager factory.

Optional properties:

userGroupCallback: MVELUserGroupCallbackImpl by default.

userInfo: DefaultUserInfo by default.

listener: List of TaskLifeCycleEventListener instances.

Sample RuntimeManager Configuration with Spring

To create a single runtime manager Spring configuration:

Configure the entity manager factory and the transaction manager, for example:

<bean id="jbpmEMF" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
  <property name="persistenceUnitName" value="org.jbpm.persistence.spring.jta"/>
</bean>

<bean id="btmConfig" factory-method="getConfiguration" class="bitronix.tm.TransactionManagerServices"></bean>

<bean id="BitronixTransactionManager" factory-method="getTransactionManager"
      class="bitronix.tm.TransactionManagerServices" depends-on="btmConfig" destroy-method="shutdown" />

<bean id="jbpmTxManager" class="org.springframework.transaction.jta.JtaTransactionManager">
  <property name="transactionManager" ref="BitronixTransactionManager" />
  <property name="userTransaction" ref="BitronixTransactionManager" />
</bean>

This configuration provides:

JTA transaction manager, backed by Bitronix for unit tests or servlet containers.

The org.jbpm.persistence.spring.jta entity manager factory for persistence unit.

Configure resources you use, for example a business process:

<bean id="process" factory-method="newclass pathResource" class="org.kie.internal.io.ResourceFactory">
  <constructor-arg>
    <value>jbpm/processes/sample.bpmn</value>
  </constructor-arg>
</bean>

The sample.bpmn process is included from the class path.

Configure RuntimeEnvironment using your entity manager, transaction manager, and resources:

<bean id="runtimeEnvironment" class="org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean">
  <property name="type" value="DEFAULT"/>
  <property name="entityManagerFactory" ref="jbpmEMF"/>
  <property name="transactionManager" ref="jbpmTxManager"/>
  <property name="assets">
    <map>
      <entry key-ref="process"><util:constant static-field="org.kie.api.io.ResourceType.BPMN2"/></entry>
    </map>
  </property>
</bean>

Create RuntimeManager:

<bean id="runtimeManager" class="org.kie.spring.factorybeans.RuntimeManagerFactoryBean" destroy-method="close">
  <property name="identifier" value="spring-rm"/>
  <property name="runtimeEnvironment" ref="runtimeEnvironment"/>
</bean>

An example of complete configuration:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
                          http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd">

  <import resource="classpath:jbpm/configuration-template/assets.xml" />

  <bean id="jbpmEMF" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <property name="persistenceUnitName" value="org.jbpm.persistence.spring.jta"/>
    <property name="persistenceXmlLocation" value="classpath:jbpm/persistence-jta.xml"/>
  </bean>

  <bean id="btmConfig" factory-method="getConfiguration" class="bitronix.tm.TransactionManagerServices"/>

  <bean id="BitronixTransactionManager" factory-method="getTransactionManager"
        class="bitronix.tm.TransactionManagerServices" depends-on="btmConfig" destroy-method="shutdown" />

  <bean id="jbpmTxManager" class="org.springframework.transaction.jta.JtaTransactionManager">
    <property name="transactionManager" ref="BitronixTransactionManager" />
    <property name="userTransaction" ref="BitronixTransactionManager" />
  </bean>

  <bean id="runtimeEnvironment" class="org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean">
    <property name="type" value="DEFAULT"/>
    <property name="entityManagerFactory" ref="jbpmEMF"/>
    <property name="transactionManager" ref="jbpmTxManager"/>
    <property name="assets" ref="assets"/>
  </bean>

  <bean id="logService" class="org.jbpm.process.audit.JPAAuditLogService" depends-on="runtimeEnvironment">
    <constructor-arg value="#{runtimeEnvironment.environment}" />
    <constructor-arg value="STANDALONE_JTA" />
  </bean>
</beans>

Spring and jBPM Services

If you require multiple runtime managers, you can use jBPM services directly in your application. Due to the dynamic nature of jBPM services, processes and other assets can be added and removed without restarting your application.

To configure jBPM services, implement the IdentityProvider interface:

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import org.kie.internal.identity.IdentityProvider;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;

public class SpringSecurityIdentityProvider implements IdentityProvider {

	public String getName() {

		Authentication auth = SecurityContextHolder.getContext().getAuthentication();
		if (auth != null && auth.isAuthenticated()) {
			return auth.getName();
		}
		return "system";
	}

	public List<String> getRoles() {
		Authentication auth = SecurityContextHolder.getContext().getAuthentication();
		if (auth != null && auth.isAuthenticated()) {
			List<String> roles = new ArrayList<String>();

			for (GrantedAuthority ga : auth.getAuthorities()) {
				roles.add(ga.getAuthority());
			}

			return roles;
		}

		return Collections.emptyList();
	}

	public boolean hasRole(String role) {
		return false;
	}

}

To configure jBPM services in a Spring application:

Configure the transaction manager:

<context:annotation-config />
<tx:annotation-driven />
<tx:jta-transaction-manager />

<bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager" />

Configure JPA and persistence:

<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean" depends-on="transactionManager">
   <property name="persistenceXmlLocation" value="classpath:/META-INF/jbpm-persistence.xml" />
</bean>

Configure security providers:

<util:properties id="roleProperties" location="classpath:/roles.properties" />

<bean id="userGroupCallback" class="org.jbpm.services.task.identity.JBossUserGroupCallbackImpl">
  <constructor-arg name="userGroups" ref="roleProperties"></constructor-arg>
</bean>

<bean id="identityProvider" class="org.jbpm.spring.SpringSecurityIdentityProvider"/>

Configure the runtime manager factory:

<bean id="runtimeManagerFactory" class="org.kie.spring.manager.SpringRuntimeManagerFactoryImpl">
  <property name="transactionManager" ref="transactionManager"/>
  <property name="userGroupCallback" ref="userGroupCallback"/>
</bean>

<bean id="transactionCmdService" class="org.jbpm.shared.services.impl.TransactionalCommandService">
  <constructor-arg name="emf" ref="entityManagerFactory"></constructor-arg>
</bean>

<bean id="taskService" class="org.kie.spring.factorybeans.TaskServiceFactoryBean" destroy-method="close">
  <property name="entityManagerFactory" ref="entityManagerFactory"/>
  <property name="transactionManager" ref="transactionManager"/>
  <property name="userGroupCallback" ref="userGroupCallback"/>
  <property name="listeners">
    <list>
      <bean class="org.jbpm.services.task.audit.JPATaskLifeCycleEventListener">
        <constructor-arg value="true"/>
      </bean>
    </list>
  </property>
</bean>

The runtime manager factory is Spring context aware and can interact with Spring containers.

Configure jBPM services as Spring beans:

<!-- definition service -->
<bean id="definitionService" class="org.jbpm.kie.services.impl.bpmn2.BPMN2DataServiceImpl"/>

<!-- runtime data service -->
<bean id="runtimeDataService" class="org.jbpm.kie.services.impl.RuntimeDataServiceImpl">
  <property name="commandService" ref="transactionCmdService"/>
  <property name="identityProvider" ref="identityProvider"/>
  <property name="taskService" ref="taskService"/>
</bean>

<!-- -- deployment service -->
<bean id="deploymentService" class="org.jbpm.kie.services.impl.KModuleDeploymentService" depends-on="entityManagerFactory" init-method="onInit">
  <property name="bpmn2Service" ref="definitionService"/>
  <property name="emf" ref="entityManagerFactory"/>
  <property name="managerFactory" ref="runtimeManagerFactory"/>
  <property name="identityProvider" ref="identityProvider"/>
  <property name="runtimeDataService" ref="runtimeDataService"/>
</bean>

<!-- process service -->
<bean id="processService" class="org.jbpm.kie.services.impl.ProcessServiceImpl" depends-on="deploymentService">
  <property name="dataService" ref="runtimeDataService"/>
  <property name="deploymentService" ref="deploymentService"/>
</bean>

<!-- user task service -->
<bean id="userTaskService" class="org.jbpm.kie.services.impl.UserTaskServiceImpl" depends-on="deploymentService">
  <property name="dataService" ref="runtimeDataService"/>
  <property name="deploymentService" ref="deploymentService"/>
</bean>

<!-- register runtime data service as listener on deployment service so it can receive notification about deployed and undeployed units -->
<bean id="data" class="org.springframework.beans.factory.config.MethodInvokingFactoryBean" depends-on="deploymentService">
  <property name="targetObject" ref="deploymentService"></property>
  <property name="targetMethod"><value>addListener</value></property>
  <property name="arguments">
  <list>
      <ref bean="runtimeDataService"/>
  </list>
  </property>
</bean>

Chapter 11. Integration with Aries Blueprint

This chapter explains the integration elements of Red Hat JBoss BRMS specific to Apache Aries Blueprint.

KIE Namespace

KieModule

The <kie:kmodule> element defines a collection of a KieBase and its associated KieSessions.

Attribute
Description

id

The name to which other beans refer. Blueprint ID semantics applies. This attribute is required.

Possible children:

kie:kbase

KieBase

The <kie:kbase> element has the following attributes:

Attribute
Description

name

The name of the KieBase. This attribute is required.

packages

A comma-separated list of the resource packages to be included in the KieBase.

includes

KieBase names to be included. All resources from the corresponding KieBases are included in the parent KieBase.

default

A Boolean. Sets the kbase as default. Set to false by default.

scope

Possible values: prototype or singleton. Set to singleton by default.

eventProcessingMode

Event Processing Mode. Possible values: STREAM or CLOUD.

equalsBehavior

Possible values: IDENTITY or EQUALITY.

Possible children:

kie:ksession

The kmodule element can contain multiple kbase elements.

Example 11.1. kbase Definition Example

<kie:kmodule id="sample_module">
   <kie:kbase name="kbase1" packages="org.drools.blueprint.sample">
     ...
   </kie:kbase>
</kie:kmodule>

When you define a kbase or a ksession, you can set the bean scope:

Set scope to prototype to instantiate a new bean instance every time the bean is called.

Set scope to singleton to use the same bean instance every time the bean is called.

KieSession

The <kie:ksession> element defines both stateful and stateless KieSessions. It has the following parameters:

Attribute
Description

name

The name of the KieSession. This attribute is required.

type

Possible values: stateful or stateless. Set to stateful by default.

default

A Boolean. Sets the ksession as default. Set to false by default.

scope

Possible values: prototype or singleton. Set to singleton by default.

clockType

Possible values: REALTIME or PSEUDO.

listeners-ref

Specifies the reference to the event listeners group. For more information, see the section called “Defining a Group of Listeners”.

Example 11.2. ksession definition example

<kie:kmodule id="sample-kmodule">
  <kie:kbase name="drl_kiesample3" packages="drl_kiesample3">
    <kie:ksession name="ksession1" type="stateless"/>
    <kie:ksession name="ksession2"/>
  </kie:kbase>
</kie:kmodule>

Kie:ReleaseId

The kie:releaseId element represents Maven GAV (Group ID, Artifact ID, and Version). kie:releaseId requires the following properties:

Attribute
Description

id

The name to which other beans refer. Blueprint ID semantics applies.

groupId

Maven groupId.

artifactId

Maven artifactId.

version

Maven version.

Example 11.3. releaseId Definition Example

<kie:releaseId id="beanId" groupId="org.kie.blueprint"
            artifactId="named-artifactId" version="1.0.0-SNAPSHOT"/>

Kie:Import

Red Hat JBoss BRMS now supports kie-aries-blueprint importing KIE objects from KJARs. The kie:import element supports the following attributes:

Attribute
Description

releaseId

Reference to a bean ID. Standard Blueprint ID semantics applies.

enableScanner

Enable Scanner. This attribute is used only if releaseId is specified.

scannerInterval

Scanning Interval in milliseconds. This attribute is used only if releaseId is specified.

Red Hat JBoss BRMS supports two modes of importing KIE objects:

Global Import

The kie:import element uses the KieServices.getKieClasspathContainer() method to import KIE objects. For further information about KIE methods, see the KIE Api section of the Red Hat JBoss BPM Suite Development Guide.

Global Import

<kie:import />

Specific Import - ReleaseId

When using the releaseId-ref attribute on the import tag, only KIE objects identified by the referenced releaseId element are initialized and imported into the Blueprint context.

KIE Objects Import Using releaseId

<kie:import releaseId-ref="namedKieSession"/>
<kie:releaseId id="namedKieSession" groupId="org.drools"
            artifactId="named-kiesession" version="{revnumber}"/>

You can enable the KIE scanning feature, enableScanner, for KieBases imported with a specific releaseId. This feature is currently not available for global imports.

Import KIE Objects using a releaseId - Enable Scanner

<kie:import releaseId-ref="namedKieSession"
            enableScanner="true" scannerInterval="1000"/>

<kie:releaseId id="namedKieSession" groupId="org.drools"
            artifactId="named-kiesession" version="{revnumber}"/>

If you define and enable a scanner, a KieScanner object is created with default values and inserted into the Blueprint container. You can get the KieScanner object from the Blueprint container using the -scanner suffix.

Retriving the KieScanner from a Blueprint Container

// the implicit name would be releaseId-scanner
KieScanner releaseIdScanner = (KieScanner)container.getComponentInstance("namedKieSession-scanner");
releaseIdScanner.scanNow();

Note

kie-ci must be available on the classpath for the releaseId importing feature to work.

Event Listeners

Red Hat JBoss BRMS supports adding 3 types of listeners to KieSessions:

AgendaListener

WorkingMemoryListener

ProcessEventListener

The kie-aries-blueprint module allows you to configure the listeners for KIE sessions using XML tags. The tags have identical names to the listener interfaces:

<kie:agendaEventListener>

<kie:ruleRuntimeEventListener>

<kie:processEventListener>

The kie-aries-blueprint module allows you to define listeners as standalone listeners or as a group.

Defining Standalone Listeners

Standalone listeners support the following parameters:

Attribute
Description

ref

A reference to a bean.

Example 11.4. Listener Configuration Using bean:ref

<bean id="mock-agenda-listener" class="mocks.MockAgendaEventListener"/>
<bean id="mock-rr-listener" class="mocks.MockRuleRuntimeEventListener"/>
<bean id="mock-process-listener" class="mocks.MockProcessEventListener"/>

<kie:kmodule id="listeners_kmodule">
  <kie:kbase name="drl_kiesample" packages="drl_kiesample">
    <kie:ksession name="ksession2">
      <kie:agendaEventListener ref="mock-agenda-listener"/>
      <kie:processEventListener ref="mock-process-listener"/>
      <kie:ruleRuntimeEventListener ref="mock-rr-listener"/>
    </kie:ksession>
  </kie:kbase>
</kie:kmodule>

Defining Multiple Listeners of One Type

You can also define multiple listeners of one type for a KIE session.

Example 11.5. Listener Configuration: Multiple Listeners of One Type.

<bean id="mock-agenda-listener1" class="mocks.MockAgendaEventListener"/>
<bean id="mock-agenda-listener2" class="mocks.MockAgendaEventListener"/>

<kie:kmodule id="listeners_module">
  <kie:kbase name="drl_kiesample" packages="drl_kiesample">
    <kie:ksession name="ksession1">
      <kie:agendaEventListener ref="mock-agenda-listener1"/>
      <kie:agendaEventListener ref="mock-agenda-listener2"/>
    </kie:ksession>
  </kie:kbase>
</kie:kmodule>

Defining a Group of Listeners

The kie-aries-blueprint module allows you to group listeners. This is useful when you define a set of listeners that you want to attach to multiple sessions, or when switching from testing to production use. The following attribute is required:

Attribute
Description

ID

Unique identifier

Possible children:

kie:agendaEventListener

kie:ruleRuntimeEventListener

kie:processEventListener

Note

The declaration order does not matter. Only one declaration of each type is allowed in a group.

Example 11.6. Group of Listeners

<bean id="mock-agenda-listener" class="mocks.MockAgendaEventListener"/>
<bean id="mock-rr-listener" class="mocks.MockRuleRuntimeEventListener"/>
<bean id="mock-process-listener" class="mocks.MockProcessEventListener"/>

<kie:kmodule id="listeners_module">
  <kie:kbase name="drl_kiesample" packages="drl_kiesample">
    <kie:ksession name="statelessWithGroupedListeners" type="stateless"
             listeners-ref="debugListeners"/>
  </kie:kbase>
</kie:kmodule>

  <kie:eventListeners id="debugListeners">
  <kie:agendaEventListener ref="mock-agenda-listener"/>
  <kie:processEventListener ref="mock-process-listener"/>
  <kie:ruleRuntimeEventListener ref="mock-rr-listener"/>
</kie:eventListeners>

Loggers

Red Hat JBoss BRMS supports the following loggers:

ConsoleLogger

FileLogger

The kie-aries-blueprint module allows you to configure the loggers using XML tags with identical names:

<kie:consoleLogger>

<kie:fileLogger>

Defining a Console Logger

The <kie:consoleLogger/> element has no attributes and must be present directly under a <kie:ksession> element.

Example 11.7. Defining a Console Logger

<kie:kmodule id="loggers_module">
  <kie:kbase name="drl_kiesample" packages="drl_kiesample">
    <kie:ksession name="ConsoleLogger-statefulSession" type="stateful">
      <kie:consoleLogger/>
    </kie:ksession>
  </kie:kbase>
</kie:kmodule>

Defining a File Logger

The <kie:fileLogger/> element supports the following attributes:

Attribute
Description

ID

Unique identifier. This attribute is required.

file

Path to the log file on the disk. This attribute is required.

threaded

Possible values: true or false. Set to false by default.

interval

An Integer. Specifies the interval for flushing the contents from memory to the disk.

Example 11.8. Defining a File Logger

<kie:kmodule id="loggers_module">
  <kie:kbase name="drl_kiesample" packages="drl_kiesample">
    <kie:ksession name="ConsoleLogger-statefulSession" type="stateful">
      <kie:fileLogger id="fl_logger" file="#{ systemProperties['java.io.tmpdir'] }/log1"/>
      <kie:fileLogger id="tfl_logger" file="#{ systemProperties['java.io.tmpdir'] }/log2"
                          threaded="true" interval="5"/>
    </kie:ksession>
  </kie:kbase>
</kie:kmodule>

Closing a FileLogger

It is recommended to close the <kie:fileLogger> logger to prevent memory leaks:

LoggerAdaptor adaptor = (LoggerAdaptor) container.getComponentInstance("fl_logger");
adaptor.close();

Defining Batch Commands

The <kie:batch> element allows you to define a set of batch commands for a given KIE session. The <kie:batch> element has no attributes and must be placed under a <kie:ksession> element.

Supported Parameters for Initialization Batch Commands

insert-object

ref: String. This parameter is optional.

Anonymous bean.

set-global

identifier: String. This parameter is required.

reg: String. This parameter is optional.

Anonymous bean.

fire-all-rules

max: Integer.

fire-until-halt

start-process

identifier: String. This parameter is required.

ref: String. This parameter is optional.

Anonymous bean.

signal-event

ref: String. This parameter is optional.

event-type: String. This parameter is required.

process-instance-id: Integer. This parameter is optional.

Example 11.9. Batch Commands Example

<kie:kmodule id="batch_commands_module">
  <kie:kbase name="drl_kiesample" packages="drl_kiesample">
    <kie:ksession name="ksessionForCommands" type="stateful">
      <kie:batch>
        <kie:insert-object ref="person2"/>
        <kie:set-global identifier="persons" ref="personsList"/>
        <kie:fire-all-rules max="10"/>
      </kie:batch>
    </kie:ksession>
  </kie:kbase>
</kie:kmodule>

Chapter 12. Localization and Customization

Available Languages

The Red Hat JBoss BRMS web user interface can be viewed in multiple languages:

United States English (en_US)

Spanish (es_ES)

Japanese (ja_JP)

Simplified Chinese (zh_CN)

Traditional Chinese (zh_TW)

Portuguese (pt_BR)

French (fr_CA)

German (de_DE)

Note

If a language is not specified, US English is used by default.

Changing Language Settings

Changing the User Interface Language in Business Central

By default, Business Central uses the system locale. If you need to change it, then append the required locale code at the end of the Business Central URL. For example, the following URL will set the locale to Portuguese (pt_BR).

http://localhost:8080/business-central/?locale=pt_BR

Running the JVM with UTF-8 Encoding

Red Hat JBoss BRMS is designed to work with UTF-8 encoding. If a different encoding system is being used by the JVM, unexpected errors might occur.

To ensure UTF-8 is used by the JVM, use the JVM option -Dfile.encoding=UTF-8.

Chapter 13. Process Execution Server Configuration

Assignment Rules

Assignment rules are rules executed automatically when a Human Task is created or completed. This mechanism can be used, for example, to assign a Human Task automatically to a particular user of a group or prevent a user from completing a Task if data is missing.

Defining Assignment Rules

To define assignment rules, do the following:

Create a file that will contain the rule definition on the Business Central classpath (the recommended location is DEPLOY_DIR/standalone/deployments/business-central.war/WEB-INF/classes/):

default-add-task.drl with the rules to be checked when the Human Task is created

default-complete-task.drl with the rules to be checked when the Human Task is completed

Define the rules in the file.

Example 13.1. The default-add-task.drl Content

package defaultPackage

import org.kie.api.task.model.Task;
import org.kie.api.task.model.User;
import org.kie.api.task.model.Status;
import org.kie.api.task.model.PeopleAssignments;
import org.jbpm.services.task.rule.TaskServiceRequest;
import org.jbpm.services.task.exception.PermissionDeniedException;
import org.jbpm.services.task.impl.model.*;
import java.util.HashMap;
import java.util.List;

global TaskServiceRequest request;

rule "Don't allow Mary to complete task when rejected"
    when
        $task : Task()
        $actualOwner : User( id == 'mary') from $task.getTaskData().getActualOwner()
        $params : HashMap(this["approved"] == false)
    then
        request.setAllowed(false);
        request.setExceptionClass(PermissionDeniedException.class);
        request.addReason("Mary is not allowed to complete task with approved false");
end

If the potential owners of a Human Task will contain the user Mary, the task will be automatically assigned to the user mary.

Example 13.2. The default-complete-task.drl Content

package defaultPackage

import org.kie.api.task.model.Task;
import org.kie.api.task.model.User;
import org.kie.api.task.model.Status;
import org.kie.api.task.model.PeopleAssignments;
import org.jbpm.services.task.rule.TaskServiceRequest;
import org.jbpm.services.task.exception.PermissionDeniedException;
import org.jbpm.services.task.impl.model.*;
import java.util.HashMap;
import java.util.List;

global TaskServiceRequest request;

rule "Don't allow Mary to complete task when rejected"
    when
        $task : Task()
        $actualOwner : User( id == 'mary') from $task.getTaskData().getActualOwner()
        $params : HashMap(this["approved"] == false)
    then
        request.setAllowed(false);
        request.setExceptionClass(PermissionDeniedException.class);
        request.addReason("Mary is not allowed to complete task without approval.");
end

If the potential owners of a Human Task will contain the user Mary, the task will be automatically assigned to the user mary.

Mail Session

Mail session defines the mail server properties that are used for sending emails if required by the application, such as, escalation or notification mechanisms (refer to the Red Hat JBoss BRMS User Guide).

Setting up Mail Session

To set up the mail session for your execution engine, do the following:

Open the respective profile configuration file (standalone.xml or host.xml) for editing.

Add the mail session to the urn:jboss:domain:mail:1.1 subsystem.

Example 13.3. New Mail Session on localhost

<subsystem xmlns="urn:jboss:domain:mail:1.1">
  <!-- omitted code -->

  <mail-session jndi-name="java:/mail/brmsMailSession" debug="true" from="brms@company.com">
    <smtp-server outbound-socket-binding-ref="brmsMail"/>
  </mail-session>
</subsystem>

Define the session outbound socket in the profile configuration file.

Example 13.4. Outbound Socket Definition

<outbound-socket-binding name="brmsMail">
  <remote-destination host="localhost" port="12345"/>
</outbound-socket-binding>

Chapter 14. Monitoring

JBoss Operations Network

A JBoss Operations Network plug-in can be used to monitor rules sessions for Red Hat JBoss BRMS.

Due to a limitation of passing the JVM monitoring arguments via the Maven command line, all com.sun.management.jmxremote.* parameters must be passed to the Red Hat JBoss BRMS application via the pom.xml configuration file.

Please refer to the JBoss Operations Network Installation Guide for installation instructions for the JBoss ON server.

Downloading Red Hat JBoss BRMS for JBoss EAP

Go to the Red Hat Customer Portal and log in.

At the top of the page, click DOWNLOADS.

In the Product Downloads page that opens, click Red Hat JBoss BRMS.

From the Version drop-down menu, select version 6.4.0.

Select Red Hat JBoss BRMS 6.4.0 Deployable for EAP 6 and then click Download.

Installing the JBoss BRMS Plug-in into JBoss ON

Red Hat JBoss BRMS plug-in for JBoss Operations Network can be installed by either copying the plug-in JAR files to the JBoss Operations Network plug-in directory or through the JBoss Operations Network GUI.

The following procedure guides a user to copy the plug-in JAR files to the JBoss Operations Network plug-in directory:

Procedure: Copying the JBoss BRMS plug-in JAR files

Extract the JBoss BRMS plug-in pack archive to a temporary location. This creates a subdirectory with the name jon-plugin-pack-brms-bpms-3.3.0.GA. For example:

[root@server rhq-agent]# unzip jon-plugin-pack-brms-bpms-3.3.0.GA.zip -d /tmp

Copy the extracted JBoss BRMS plug-in JAR files from the jon-plugin-pack-brms-bpms-3.2.0.GA/ directory to the JBoss ON server plug-in directory. For example:

[root@server rhq-agent]# cp /tmp/jon-plugin-pack-brms-bpms-3.3.0.GA/*.jar /opt/jon/jon-server-3.3.0.GA1/plugins

Start the JBoss Operations Network server to update the JBoss BRMS plug-in.

To upload the JBoss BRMS plug-in through the JBoss Operations Network GUI, following is the procedure

Procedure: Uploading the JBoss BRMS plug-in through GUI

Start the JBoss Operations Network Server and Log in to access the GUI.

In the top navigation of the GUI, open the Administration menu.

In the Configuration area on the left, select the Server Plugins link.

At the bottom of the list of loaded server plug-ins, click the Upload a plugin button and choose the BRMS plugin.

The JBoss BRMS plug-in for JBoss Operations Network is now uploaded.

Monitoring Kie Bases and Kie Sessions

In order for JBoss Operations Network to monitor KieBases and KieSessions, MBeans must be enabled.

MBeans can be enabled either by passing the parameter -kie.mbeans = enabled or via the API:

KieBaseConfiguration kbconf = KieServices.Factory.get().newKieBaseConfiguration();
    kbconf.setOption(MBeansOption.ENABLED);

Note

Kie Services have been implemented for JBoss BRMS 6; for JBoss BRMS 5, Drools Services was the naming convention used and it had different measurements on sessions. For example, activation → match renaming occurred in the updated version.

Please refer to the JBoss Operations Network Resource Monitoring and Operations Reference guide for information on importing Kie Sessions into the Inventory View for monitoring purposes.

The JBoss Rules Kie Base Monitoring Service

The JBoss Rules Kie Base Monitoring Service can configure the KieBase by providing the KieBase ID as a connection property.

The JBoss Rules knowledge base monitoring service provides the following operations:

Start all internal MBeans: Starts the internal MBeanServer that will register all the knowledge sessions created from the knowledge base. The resources can be knowledge bases and stateful knowledge sessions. This displays the knowledge base configuration and entry points related to that information.

Stop all internal MBeans: Stops previously started internal MBeans.

The JBoss Rules Kie Session Monitoring Service

The JBoss Rules Kie Sessions Monitoring Service can configure the kie base and kie session by providing the kie base ID and kie session ID as connection properties.

The JBoss Rules Kie Session Monitoring Service provides the following operations:

Reset all metrics counters: Resets all the metric statistics with regard to rule/process/process instance specific information.

Return statistics for a specific rules: Provides a description of the total number of fired/created/canceled activations generated by a rule.

Get statistics for a specific process: Provides a description of the total number of fired/created/canceled activations generated by a process.

Get statistics for a specific process instance: Provides a description of the total number of fired/created/canceled activations generated by each process instance.

The JBoss Rules Kie Session Monitoring Service provides the following metrics:

The total number of facts in working memory.

The total number of matches created since the last reset.

The total number of matches fired since the last reset.

The total number of matches canceled since the last reset.

The total time spent firing rules since the last reset.

The total number of process instances started since the last reset.

The total number of process instances completed since the last reset.

The timestamp of the last reset operation.

Appendix A. Revision History

Note that revision numbers relate to the edition of this manual, not to version numbers of Red Hat JBoss BRMS.

Table A.1. Revision History

Revision
Date
Author

6.4.0-2

Fri Dec 23 2016

Tomas Radej

Rebuilt with updates.

6.4.0-1

Mon Nov 28 2016

Tomas Radej

Initial build for release 6.4.0 of Red Hat JBoss BRMS.