Administration And Configuration Guide
The Administration and Configuration Guide for Red Hat JBoss BPM Suite
Kanchan Desai
kadesai@redhat.com
Doug Hoffman
Eva Kopalova
Red Hat Content Services
Joshua Wulf
jwulf@redhat.com
Abstract
Part I. Introduction
Chapter 1. Business Process Model and Notation
1.1. Components
Execution Engine
- provides the runtime environment for Processes and Business Rules. It encompasses a workflow library that can be embedded into a user web application. Runtime manager is the root object and contains the following components:Runtime Engine
- implements the core behavior of the computer language and it is provided by the runtime manager.Process Engine
- is the environment for business process model execution.Task Service
- handles human task lifecycles.
Rule Engine
- can be used with the process engine or on its own.Rules Evaluation
- executes business rules on the provided set of facts.Complex Event Processing
- applies business rules on incoming stream of events.
Business Central
- a web-based application that accommodates tooling for asset creation, management, and monitoring by providing an integrated web environment.Asset Repository
- is the central sharing location (Knowledge Store) for business assets, processes, rules, forms, etc. Users access this repository through the Project Explorer view of Business Central via Authoring → Project Authoring. By default, the product initializes a local GIT repository as its Asset Repository. However, other repositories may be added or removed as necessary.Artifact Repository
- is a Maven based repository for storage of project jar artifacts.Execution Server
- provides an execution environment for business process instances and tasks.Business Activity Monitor
- provides customizable view on business performance.
Note
1.2. Project
pom.xml
) with information on how to build the output artifact. It also contains the Module Descriptor file, kmodule.xml
, that contains the KIE Base and KIE Session configuration for the assets in the project.
1.3. Creating a project
- Open the Project Authoring perspective: on the main menu, click Authoring → Project Authoring.
- In the Project Explorer, select the organizational unit and the repository where you want to create the project.
- In the perspective menu, go to New Item → Project.
- In the Create new Project dialog window, define the project details:
- In the Project text box, enter the project name.
- The explorer refreshes to show a New Project Wizard pop-up window.
- Define the Project General Settings and Group artifact version details for this new project. These parameters are stored inside the
pom.xml
Maven configuration file.- Project Name: The name for the project; for example
MortgageProject
- Project Description: The description of the project which may be useful for the project documentation purpose.
- Group ID: group ID of the project; for example
org.mycompany.commons
- Artifact ID: artifact ID unique in the group; for example
myframework
. Avoid using a space or any special character that might lead to an invalid name. - Version ID: version of the project; for example
2.1.1
The Project Screen view is updated with the new project details as defined in the pom.xml file. Note, that you can switch between project descriptor files in the drop down-box with Project Settings and Knowledge Base Setting, and edit their contents.
1.4. Adding dependencies
- Open the Project Editor for the given project:
- In the Project Explorer view of the
Project Authoring
perspective, open the project directory. - Click on the button to open the project view.
- In the Project Screen view, select in the Project Settings drop-down box the Dependencies item.
- On the updated Project Screen, click the Add button to add a maven dependency or click the Add from repository button to add a dependency from the Knowledge Store (Artifact repository):
- When adding a maven dependency, a user has to define the Group ID, Artifact ID and the Version ID in the new row which is created in the dependency table.
- When adding a dependency from the Knowledge Store, select the dependency in the displayed dialog box: the dependency will be added to the dependency table.
- To apply the various changes, the dependencies must be saved.
Warning
Part II. Configuration
Chapter 2. Business Central Configuration
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
.
2.1. Access control
$JBOSS_HOME/standalone/deployments/business-central.war/WEB-INF/classes/userinfo.properties
.
admin
: administrates JBoss BPM Suite system and has full access rights to make any changes necessary including the ability to add and remove users from the system.developer
: implements code required for processes to work and has access to everything except administration tasks.analyst
: creates and designs processes and forms, instantiates the processes and deploys artifacts. This role is the similar to a developer, without access to asset repository and deployments.user
: claims, performs, and invokes other actions (such as, escalation, rejection, etc.) on the assigned Tasks and has no access to authoring functions.manager
: monitors the system and its statistics and only has access to the dashboard.business user
: takes action on business tasks that are required for processes to continue forward. Works primarily with the task list.
$JBOSS_HOME/add-user.sh
script and create an Application User in the ApplicationRealm
with the respectives roles.
Workbench Configuration
$JBOSS_HOME/standalone/deployments/business-central.war/WEB-INF/classes/workbench-policy.propeties
.
standalone.xml
file in EAP.
Authentication in Human Tasks
UserGroupCallback
interface to assign tasks to user.
Warning
2.2. Business Central Profile Configuration
- Full profile - default profile that is active without additional configuration required (UI and remote services e.g. REST).
- Execution server profile - disables completely UI components of the application and allows only remote access e.g. via REST interface.
- UI server profile - disables remote services e.g REST and allows only UI access to the application.
Procedure 2.1. Configuring Business Central Profiles
- Select the desired
web.xml
inside$BPMS_HOME/standalone/deployments/business-central.war/WEB-INF/
. The following files are provided.web.xml
(default) for full profileweb-exec-server.xml
for execution server profileweb-ui-server.xml
for UI server profile
- To activate a profile other than the default full profile, the web-<PROFILE>.xml file must be renamed to
web.xml
. The following steps demonstrate one way to enable the execution server profile:- Backup the
web.xml
file from the full profile$ mv web.xml web-full.xml
- Rename the
web-exec-server.xml
file:$ mv web-exec-server.xml web.xml
- Start application server with additional system property to instruct the profile manager to activate given profile.
Dorg.kie.active.profile=full
- to activate full profile or skip the property completelyDorg.kie.active.profile=exec-server
- to activate execution server profileDorg.kie.active.profile=ui-server
- to activate UI server profile
2.3. Branding the Business Central Application
- Login screenYou can customize the following attributes of the Business Central login screen:
- The background image
- The company logo
- The application logo
- Application headerYou can customize the following attributes of the Business Central application header:
- The Business Central header containing the title and banner logo
- Help pop-up windowsYou can customize the following attributes of the splash help pop-up windows:
- The splash help images
- The label text
2.3.1. Customizing Business Central Login Page
Procedure 2.2. 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 JBoss BPM Suite installation. - Navigate to
$EAP_HOME/standalone/deployments/business-central.war/styles
directory and open thelogin-screen.css
file in a text editor. - In the
login-screen.css
file, provide the location of your new background image in the followingbackground-image
attribute.background-image: url("../images/login-screen-background.jpg");
Thebackground-image
attribute points to the defaultlogin-screen-background.jpg
image.In addition to the background image, you can modify other attributes such as image size, position, and background color in thelogin-screen.css
file.
Procedure 2.3. 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 JBoss BPM Suite 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_BPMS_Logo.png
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.
2.3.2. Customizing Business Central Application Header
Procedure 2.4. 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 JBoss BPM Suite 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 islogo.png
.
2.3.3. Customizing Business Central Splash Help Windows
$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 2.5. 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 JBoss BPM Suite 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 isauthoring_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>
2.4. Deployment Descriptors
META-INF
directory of the kjar called kmodule.xml
can be used to define the knowledge bases and sessions. This kmodule.xml
file, by default, is empty.
kmodule.xml
to build the runtime representation.
kmodule.xml
file. The presence of these descriptors is optional and your deployment will proceed successfully without them. The properties that you can set using these descriptors are purely technical in nature and include meta values like persistence, auditing and runtime strategy.
kie-deployment-descriptor.xml
and place this file next to your kmodule.xml
file in the META-INF
folder. You can change this default location (and the filename) by specifying it as a system parameter:
-Dorg.kie.deployment.desc.location=file:/path/to/file/company-deployment-descriptor.xml
2.4.1. Deployment Descriptor Configuration
- server level: the main level and the one that applies to all kjars deployed on the server.
- kjar level: this allows you to configure descriptors on a per kjar basis.
- deploy time level: descriptors that apply while a kjar is being deployed.
Note
NONE
but the same mode is specified as JPA
at the kjar level, the actual mode will be JPA
for that kjar. If nothing is specified for the persistence mode in the deployment descriptor for that kjar (or if there is no deployment descriptor), it will fall back to the server level configuration, which in this case is NONE
(or to JPA
if there is no server level deployment descriptor).
Can you override this hierarchal merge mode behavior?
MERGE_COLLECTIONS
mode. But you can change it (Section 2.4.2, “Managing Deployment Descriptors”) if it doesn't suit your environment to one of the following modes:
- KEEP_ALL: in this mode, all higher level values override all lower level values (server level values replace kjar level values)
- OVERRIDE_ALL: in this mode, all lower level values override all higher level values (kjar values replace server level values)
- OVERRIDE_EMPTY: in this mode, all non empty configuration items from lower levels replace those at higher levels, including items that are represented as collections.
- MERGE_COLLECTIONS (DEFAULT): in this mode, all non empty configuration items from lower level replace those from higher levels (like in OVERRIDE_EMPTY), but collection properties are merged (combined).
Do I need to provide a full Deployment Descriptor for all kjars?
What can you configure?
Table 2.1. Deployment Descriptors
Configuration | XML Entry | Permissible Values | Default Value |
---|---|---|---|
Persistence unit name for runtime data | persistence-unit | Any valid persistence package name | org.jbpm.domain |
Persistence unit name for audit data | audit-persistence-unit | Any valid persistence package name | org.jbpm.domain |
Persistence mode | persistence-mode | JPA, NONE | JPA |
Audit mode | audit-mode | JPA, JMS or NONE | JPA |
Runtime Strategy | runtime-strategy | SINGLETON, PER_REQUEST or PER_PROCESS_INSTANCE | SINGLETON |
List of Event Listeners to be registered | event-listeners | Valid listener class names as ObjectModel | No default value |
List of Task Event Listeners to be registered | task-event-listeners | Valid listener class names as ObjectModel | No default value |
List of Work Item Handlers to be registered | work-item-handlers | Valid Work Item Handler classes given as NamedObjectHandler | No default value |
List of Globals to be registered | globals | Valid Global variables given as NamedObjectModel | No default value |
Marshalling strategies to be registered (for pluggable variable persistence) | marshalling-strategies | Valid ObjectModel classes | No default value |
Required Roles to be granted access to the resources of the kjar | required-roles | String role names | No default value |
Additional Environment Entries for Knowledge Session | environment-entries | Valid NamedObjectModel | No default value |
Additional configuration options of Knowledge Session | configurations | Valid NamedObjectModel | No default value |
How do you provide values for collections based configuration items?
ObjectModel
or NamedObjectModel
. Both are similar and provide a definition of the object to be built or created at runtime, with the exception that the NamedObjectModel
object details name the object to be looked. Both these types are defined using an identifier, optional parameters and resolver (to resolve the object).
- identifier - defines all the information about the object, such as fully qualified class name, Spring bean id or an MVEL expression.
- parameters - optional parameters that should be used while creating instances of objects from this model.
- resolver - identifier of the resolver that will be used to create object instances from the model - (reflection, mvel or Spring).
ObjectModel
, with the identifier being com.mycompany.MyStrategy
, resolver being reflection (the easiest and the default) and any parameters that are required for your strategy to work. Reflection will then be used to create an instance of this strategy using the fully qualified class name that you have provided as the identifier.
<marshalling-strategy> <resolver>reflection</resolver> <identifier>com.myCompany.MyStrategy</identifier> <parameters> <parameter xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"> param </parameter> </parameters> </marshalling-strategy>
<marshalling-strategy> <resolver>mvel</resolver> <identifier>new com.myCompany.CustomStrategy(runtimeManager)</identifier> </marshalling-strategy>
<marshalling-strategy> <resolver>spring</resolver> <identifier>customStrategy</identifier> </marshalling-strategy>
2.4.2. Managing Deployment Descriptors
META-INF
folder in the File Explorer. Click on the kie-deployment-descriptor.xml
file to edit it manually.
kie-deployment-descriptor.xml
file is generated with default values as described earlier.
Overriding Hierarchical Merge Mode Behavior
- Set the system property org.kie.dd.mergemode to one of these values. This merge mode will become default for all kjars deployed in the system, unless you override it at a kjar level via the next method.
- When deploying a new deployment unit via Business Central (Deploy → Deployments) you can select what merge mode should be used for that particular kjar.
- When deploying via the REST API, you can add mergemode query parameter to the command URL to one of these modes to set the merge mode for that deployment.
Restricting access to the Runtime Engine
2.5. Managing Deployment Override Policy
false
by default. Change it to true
to enable overwriting of deployments with the same GAV by providing it at startup time of your server (-Dorg.kie.override.deploy.enabled=true
).
2.6. Extending Business Central
Plugin Management
.
2.6.1. Plugin Management
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 up any of these and you will see the existing plugins in each category, including the uneditable system generated ones.
- 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
Note
<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.
main
, on_close
and on_open
. For this demo, select the on_open
and enter the following: function () { alert('Hello World'); }
Adding a new Perspective
HelloWorldPerspective
. This will open up the Perspective plugin editor, similar to the Screen plugin editor. .
6 6
grid on the right hand side to the left hand side.
HelloWorldJS
). Click the OK button and then click the Save button to save this perspective. To tag your perspective, enter Home
in the tag name field and click the Tags button. Click the OK button and save the changes.
Adding a new menu
Hello World
.
Working with Apps (Optional)
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.
2.6.2. The JavaScript (JS) API for Extensions
plugins
folder of the Business Central webapp (typically: {INSTALL_DIR}/business-central.war/plugins/) or it can be loaded via regular JavaScript calls.
- 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 toon_startup
andon_open
methods seen in the previous example, the API exposes the following callback events for managing the editor's lifecycle:You can display this editor via an html template:- 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;
<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 theangular.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 })
2.7. Configuring Table Columns
Adding and Removing Columns
Resizing Columns
Moving Columns
Sorting Columns
Chapter 3. Repository Hooks
3.1. Configuring Git Hooks
Note
post-commit
hook is supported. Post-commit
hooks are triggered after finishing the entire commit process.
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 3.1. An invalid SCP-style SSH URL.
- User Name: your Git user name
- Password: your Git password
- Go 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. - 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 torwxr--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 and then New Item → Guided Rule below. Fill in the required information in the displayed Create new Guided Rule window and click Ok.All of the changes should be pushed automatically.
org.uberfire.nio.git.hooks
. Its value determines a directory with default hook files that 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 4. Command line configuration
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 bykie-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
(a kind of installer style) - creates and manipulates the system repository directly on the server (there is no discard option).
- Go to the Red Hat Customer Portal and log in.
- Click Downloads → Products Downloads.
- In the Product Downloads page that opens, click Red Hat JBoss BPM Suite.
- From the Version drop-down menu, select 6.2.
- In the displayed table, navigate to the Supplementary Tools row and then click Download.
kie-config-cli-6.MINOR_VERSION-redhat-x-dist
with file kie-config-cli.sh
.
4.1. 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
git://kie-wb-host:9148/system
4.2. Starting the kie-config-cli tool in offline mode
- 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
.niogit
) is located. If .niogit does not yet exist, the folder value can be left empty and a brand new setup is created.
4.3. Commands available for the kie-config-cli tool
add-deployment
- adds a new deployment unitadd-repo-org-unit
- adds a repository to the organizational unitadd-role-org-unit
- adds role(s) to an organizational unitadd-role-project
- adds role(s) to a projectadd-role-repo
- adds role(s) to a repositorycreate-org-unit
- creates new organizational unitcreate-repo
- creates a new git repositorydiscard
- does not publish local changes, cleans up temporary directories and closes the toolexit
- publishes work, cleans up temporary directories and closes the toolfetch-changes
- fetches changes from upstream repositoryhelp
- prints available commands with descriptionslist-deployment
- lists available deploymentslist-org-units
- lists available organizational unitslist-repo
- lists available repositoriespush-changes
- pushes changes to upstream repository (in online mode only)remove-deployment
- removes existing deploymentremove-org-unit
- removes existing organizational unitremove-repo
- removes an existing repository from config onlyremove-repo-org-unit
- removes a repository from the organizational unitremove-role-org-unit
- removes role(s) from an organizational unitremove-role-project
- removes role(s) from a projectremove-role-repo
- removes role(s) from a repository
Chapter 5. Migration
- 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.
5.1. Data Migration
- Download the migration tool by logging in at the Red Hat Customer Portal and then navigating to Red Hat JBoss BPM Suite Software Downloads section. Click on Red Hat JBoss BPM Suite 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 theexport-from-JCR
part of the migration.vfs-importer-libs
- contains the libs specific to theimport-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>
- <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.
-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
Note
Importing the repository in JBDS
- Start JBoss Developer Studio.
- Start the Red Hat JBoss BPM Suite 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.
5.2. Runtime Migration
- Set the system property
jbpm.v5.id.strategy
to true in the JBoss BPM Suitestandalone.xml
file:<property name="jbpm.v5.id.strategy" value="true"/>
- Load the KieSession as shown here:
KieSession ksession = JPAKnowledgeService.loadStatefulKnowledgeSession(sessionID, kbase, sessionConf, env);
- Continue the normal execution of the process using KieSession methods:
ksession.signalEvent("SomeEvent", null);
5.3. API and Backwards Compatibility
Migrating to Version 6.1
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 JBoss BPM Suite 6.0.
knowledge-api.jar
), please migrate (rewrite) the API calls to the new KIE API. Please be aware that several other APIs have changed between JBoss BRMS 5.x and JBoss BPM Suite 6.x, namely the task service API and the REST API.
Migrating to Version 6.0
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.
5.4. Migrating task service
LocalHTWorkItemHandler
.
Chapter 6. Data management
6.1. Data backups
- any customized deployment descriptors (such as,
web.xml
,jboss-web.xml
,jboss.xml
) - any customized properties files
Note
Consider backing up the entirebusiness-central.war
anddashbuilder.war
files.
6.2. Setup Indexes
Setup foreign key indexes
Setup indexes for Process and Task Dashboard
processinstancelog
and bamtasksummary
.
6.3. Setting up the Database
- Postgres
- The following sql sentence is used to create a Postgres database:
CREATE DATABASE dashbuilder WITH ENCODING='UTF8' OWNER=dashbuilder CONNECTION LIMIT=-1
Note
The database encoding must be UTF8 - DB2
- DB2 database can be created using the following sql sentence:
CREATE DATABASE dashb PAGESIZE 16384
Note
The default pagesize for DB2 systems is 4k which is not enough for the dashbuilder table columns size. The pagesize should be forced to 16384 as shown in the above sentence.
<datasource jndi-name="java:jboss/datasources/jbpmDS" enabled="true" use-java-context="true" pool-name="postgresqlDS"> <connection-url>jdbc:postgresql://localhost/test</connection-url> <driver>postgresql</driver> <pool></pool> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> <drivers> <driver name="postgresql" module="org.postgresql"> <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> </driver> </drivers>
6.4. Editing the Database
java:jboss/datasources/ExampleDS
standalone.xml
.
Note
Procedure 6.1. Changing Database
- Install the database driver on JBoss (refer to JBoss driver documentation).
- Create an empty database and a JBoss data source which connects to the database driver.
- Modify the file
dashbuilder.war/WEB-INF/jboss-web.xml
:<jboss-web> <context-root>/dashbuilder</context-root> <resource-ref> <res-ref-name>jdbc/dashbuilder</res-ref-name> <res-type>javax.sql.DataSource</res-type> <jndi-name>java:jboss/datasources/myDataSource</jndi-name> </resource-ref> ...
- Replace the jndi-name parameter value by the JNDI path of the JBoss data source you've just created.
- Modify the file
dashbuilder.war/WEB-INF/jboss-deployment-structure.xml
- Add the following snippet of configuration inside the
deployment
tag, wherejdbcDriverModuleName
is the name of the JBoss JDBC driver module:<dependencies> <module name="jdbcDriverModuleName" /> </dependencies>
6.5. DDL Scripts
ddl-scripts
folder. Database scripts are provided for DB2, H2, MySQL5, Oracle, PostgreSQL and SQLServer.
Chapter 7. Asset repository
Project Explorer
from the unified environment of Red Hat JBoss BPM Suite.
7.1. Creating an Organizational Unit
kie-config-cli
tool or the REST API calls.
Creating an Organizational Unit in Business Central
Important
admin
role can create organizational units.
Procedure 7.1. 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 7.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
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.
kie-config-cli
tool, see Chapter 4, Command line configuration.
Creating an Organizational Unit Using the REST API
POST
REST API call. Details of the organizational unit are defined by the JSON entity.
OrganizationalUnit
instance. Call returns a CreateOrganizationalUnitRequest
instance.
Example 7.1. Creating an Organizational Unit Using the Curl Utility
{ "name" : "helloWorldUnit", "description" : "Organizational unit for the helloworldrepo repository.", "owner" : "tester", "repositories" : ["helloworldrepo"] }
curl -X POST 'localhost:8080/business-central/rest/organizationalunits/' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name":"helloWorldUnit","description":"Organizational unit for the helloworldrepo repository.","owner":"tester","repositories":["helloworldrepo"]}'
7.2. Creating a repository
kie-config-cli
tool or the REST API calls.
Creating a Repository in Business Central
Important
admin
role can create repositories.
Procedure 7.2. 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 7.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.
Creating a Repository Using the kie-config-cli
Tool
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.
kie-config-cli
tool, see Chapter 4, Command line configuration.
Creating a Repository Using the REST API
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.
RepositoryRequest
instance. Returns a CreateOrCloneRepositoryRequest
instance.
Example 7.2. Creating a Repository Using the Curl Utility
{ "name" : "newRepository", "description" : "Repository for the Hello World project.", "userName" : null, "password" : null, "gitURL" : null, "requestType" : "new", "organizationalUnitName" : "helloWorldUnit" }
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":"Repository for the Hello World project.","username":null,"password":null,"requestType":"new","gitURL":null,"organizationalUnitName":"helloWorldUnit"}'
7.3. Cloning a Repository
kie-config-cli
tool cannot be used to clone arbitrary repositories - run git clone
or one of the following options instead.
Cloning a Repository in Business Central
Important
admin
role can clone repositories.
Procedure 7.3. 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 7.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
orgit://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. After clicking Ok, the repository is being indexed. Some workbench features may be unavailable until indexing has completed.
Cloning a Repository Using the REST API
POST
REST API call. This call creates or clones (according to the value of the requestType
parameter) the repository defined by the JSON entity.
RepositoryRequest
instance. Returns a CreateOrCloneRepositoryRequest
instance.
Example 7.3. Cloning a Repository Using the Curl Utility
{ "name" : "clonedRepository", "description" : null, "userName" : null, "password" : null, "requestType" : "clone", "gitURL" : "git://localhost:9418/example-repository", "organizationalUnitName" : "helloWorldUnit" }
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,"username":null,"password":null,"requestType":"clone","gitURL":"git://localhost:9418/example-repository","organizationalUnitName":"helloWorldUnit"}'
7.4. Removing a Repository
Removing a Repository in Business Central
Procedure 7.4. 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 and click 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
kie-config-cli
tool as well. To do so, run the remove-repo
command.
kie-config-cli
tool, see Chapter 4, Command line configuration.
Removing a Repository Using the REST API
DELETE
REST API call. Make sure you established an authenticated HTTP session before executing this command.
RemoveRepositoryRequest
instance.
Example 7.4. Removing a Repository Using the Curl Utility
curl -X DELETE 'localhost:8080/business-central/rest/repositories/REPOSITORY_NAME' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json'
7.5. Managing Assets
Note
kiemgmt
.
Managed and Unmanaged Repositories
Managed Branches
Repository Structure
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:
Warning
release
7.6. Maven Repository
- Builds
- Documentation
- Reporting
- Dependencies
- Releases
- SCMs
- Distribution
- 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.
7.7. Configuring Deployment to a Remote Nexus Repository
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>
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.
settings-security.xml
file, using a master password. By default, this file is in ~/.m2
folder, unless you have changed its location by modifying the kie.maven.settings.custom
system property.
<servers> <server> <id>deployment</id> <username>admin</username> <password>admin.123</password> </server> </servers>
Important
settings.xml
file is not recommended. All the information should be hashed with a master password in the settings-security.xml
file.
pom.xml
file.
7.8. System Configuration
Procedure 7.5. 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>
org.uberfire.nio.git.dir
: Location of the directory .niogit. Default: working directoryorg.uberfire.nio.git.daemon.enabled
: Enables/disables GIT daemon. Default: trueorg.uberfire.nio.git.daemon.host
: If GIT daemon enabled, uses this property as the localhost identifier. Default: localhostorg.uberfire.nio.git.daemon.port
: If GIT daemon is enabled, uses this property as the port number. Default: 9418org.uberfire.nio.git.ssh.enabled
: Enables/Disables SSH daemon. Default: trueorg.uberfire.nio.git.ssh.host
: If SSH daemon is enabled, uses this property as the localhost identifier. Default: localhostorg.uberfire.nio.git.ssh.port
: If SSH daemon is enabled, uses this property as the port number. Default: 8001org.uberfire.nio.git.ssh.cert.dir
: Location of the.security
directory where local certificates will be stored. Default: working directoryorg.uberfire.metadata.index.dir
: Location of the.index
folder for Lucene. Default: working directoryorg.uberfire.cluster.id
: Name of the Helix cluster, for example: kie-clusterorg.uberfire.cluster.zk
: Connection string to Zookeeper. This is of the formhost1: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-vfsorg.uberfire.cluster.autostart
: Delays VFS clustering until the application is fully initialized to avoid conflicts when all cluster members create local clones. Default: falseorg.uberfire.sys.repo.monitor.disabled
: Disable configuration monitor (do not disable unless you know what you're doing). Default: falseorg.uberfire.secure.key
: Secret password used by password encryption. Default: org.uberfire.adminorg.uberfire.secure.alg
: Crypto algorithm used by password encryption. Default: PBEWithMD5AndDESorg.guvnor.m2repo.dir
: Place where Maven repository folder will be stored. Default: working-directory/repositories/kieorg.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. Default: Not used.org.kie.demo
: Enables external clone of a demo application from GitHub. This system property takes precedence over org.kie.example. Default: true.org.kie.example
: Enables example structure composed by Repository, Organization Unit and Project. Default: false
Chapter 8. Process export and import
8.1. Creating a Process definition
- Open the Project Authoring perspective (Authoring → Project Authoring).
- In
Project Explorer
(Project Authoring → Project Explorer), navigate to the project where you want to create the Process definition (in the Project view, select the respective repository and project in the drop-down lists; in the Repository view, navigate toREPOSITORY/PROJECT/src/main/resources/
directory).Note
It is recommended to create your resources, including your Process definitions, in a package of a Project to allow importing of resources and their referencing. To create a package, do the following:- In the Repository view of the Project Explorer, navigate to the
REPOSITORY/PROJECT/src/main/resources/
directory. - Go to New Item → Package.
- In the New resource dialog, define the package name and check the location of the package in the repository.
- From the perspective menu, go to New Item → Business Process.
- In the New Processes dialog box, enter the Process name and click OK. Wait until the Process Editor with the Process diagram appears.
8.2. Importing a Process definition
- In the Project Explorer, select a Project and the respective package to which you want to import the Process definition.
- Create a new Business Process to work in by going to New Item → Business Process.
- In the Process Designer toolbar, click the Import icon in the editor toolbar and pick the format of the imported process definition. Note that you have to choose to overwrite the existing process definition in order to import.
- From the Import window, locate the Process file and click Import.
Figure 8.1. Import Window
8.3. Importing jPDL 3.2 to BPMN2
Figure 8.2. Migrate jPDL 3.2 to BPMN2
Figure 8.3. Migrate to BPMN2 dialog box
Important
8.4. Exporting a process
Procedure 8.1. Exporting a business process
- Open the Project Authoring perspective: on the main menu, click Authoring → Project Authoring.
- Select the business process which is to be exported, to view it in the Process Designer.
- Click on the ( ) button of the process designer toolbar and select View Process Sources from the drop-down options.
- The Process Sources window is displayed
- Click on the Download BPMN2 button and save the business process at the desired location.
Part III. Integration
Chapter 9. Deploying Red Hat JBoss BPM Suite artifacts to SOA Repository Artifact Model and Protocol (S-RAMP) repository
9.1. Deploying Red Hat JBoss BPM Suite artifacts to SOA Repository Artifact Model and Protocol (S-RAMP) using Maven
pom.xml
file as shown below:
<build> <extensions> <extension> <groupId>org.overlord.sramp</groupId> <artifactId>s-ramp-wagon</artifactId> <version>${s-ramp-wagon.version}</version> </extension> </extensions> </build>
- Clone the git repository where you have saved the BPM Suite project by running this command:
git clone http://localhost:8001/REPOSITORY_NAME
- On the command line, move into the folder that contains the project.
- Follow the instructions in Red Hat JBoss Fuse Service Works 6 Development Guide, Volume 3: Governance, section Deploying to S-RAMP. Use the URL from the example below:
<distributionManagement> <repository> <id>local-sramp-repo</id> <name>S-RAMP Releases Repository</name> <url>sramp://S-RAMP_SERVER_URL/s-ramp-server/</url> </repository> <snapshotRepository> <id>local-sramp-repo-snapshots</id> <name>S-RAMP Snapshots Repository</name> <url>sramp://S-RAMP_SERVER_URL/s-ramp-server/</url> </snapshotRepository> </distributionManagement>
With these settings, Maven deployments are sent directly to the S-RAMP repository using the S-RAMP API. Note that artifacts are added to the S-RAMP repository with an artifact type based on the Maven type of the project. You can override this behavior by adding a query parameter to the repository URL in thepom.xml
file. For example:<distributionManagement> <repository> <id>local-sramp-repo</id> <name>S-RAMP Releases Repository</name> <url>sramp://S-RAMP_SERVER_URL/s-ramp-server/?artifactType=KieJarArchive</url> </repository> </distributionManagement>
The above example causes the Maven artifact to be uploaded with an S-RAMP artifact type of KieJarArchive. - Amend the maven plug-in in file
pom.xml
and add a dependency to it as follows in case the project does not contain decision tables:<plugins> <plugin> <groupId>org.kie</groupId> <artifactId>kie-maven-plugin</artifactId> <version>6.0.2-redhat-6</version> <extensions>true</extensions> <dependencies> <dependency> <groupId>org.jbpm</groupId> <artifactId>jbpm-bpmn2</artifactId> <version>6.0.2-redhat-6</version> </dependency> </dependencies> </plugin> </plugins>
If the project contains decision tables, use this dependency for the kie-maven-plugin instead:<plugins> <plugin> <groupId>org.kie</groupId> <artifactId>kie-maven-plugin</artifactId> <version>6.0.2-redhat-6</version> <extensions>true</extensions> <dependencies> <dependency> <groupId>org.drools</groupId> <artifactId>drools-decisiontables</artifactId> <version>6.0.2-redhat-6</version> </dependency> </dependencies> </plugin> </plugins>
- Run a clean Maven deployment using the following command:
mvn -s sramp-settings.xml deploy
.
Note
settings.xml
file. For further details on the credentials, refer to Red Hat JBoss Fuse Service Works (FSW) documentation on Authentication.
9.2. Deploying Red Hat JBoss BPM Suite artifacts to SOA Repository Artifact Model and Protocol (S-RAMP) using graphical user interface (GUI)
- In a web browser, navigate to http://localhost:8080/s-ramp-ui/. If the user interface has been configured to run from a domain name, substitute
localhost
for the domain name. For example http://www.example.com:8080/s-ramp-ui/. - Click on Artifacts.
- In the Manage Artifacts section, select Import.
- Locate the kie archive you want to deploy. In the dialog that opens, fill out
KieJarArchive
as the type, and select Import. - The deployment then creates these entries in the S-RAMP repository:
KieJarArchive
, from which it derives:KieXmlDocument
(if the archive containskmodule.xml
)BpmnDocument
(if the archive containsbpmn
definitions)DroolsDocument
(if the archive containsdrl
definitions)
Chapter 10. Integrating Red Hat JBoss BPM Suite with Red Hat JBoss Fuse
features.xml
files:
drools-karaf-features-<version>-features.xml
This file provides core JBoss BPM Suite and JBoss BRMS features, which defines the OSGi features that can be deployed into JBoss Fuse. This file is a part of the JBoss BPM Suite and JBoss BRMS product. OSGi users can install features from this file in order to install JBoss BRMS engine or JBoss BPM Suite engine into Fuse and use it in their applications.karaf-features-<version>-features.xml
This file provides additional features used for integrating JBoss BPM Suite and JBoss BRMS with Camel, primarily in Fuse. This file is part of the Integration Pack and it defines OSGi features that enable integration with Camel and SwitchYard. In addition to the karaf-features xml, the Integration Pack also contains a features.xml file for quickstarts.
10.1. Core JBoss BPM Suite and JBoss BRMS features
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
Table 10.1. Features and Use Case Examples
Feature | Use Case |
---|---|
drools-module | Use the JBoss BRMS engine for rules evaluation, without requiring persistence, processes, or decision tables. |
drools-jpa | Use the 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 JBoss BRMS engine with decision tables. |
jbpm | Use the JBoss BPM Suite (or 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 JBoss BPM Suite (or JBoss BRMS engine with processes) with Human Task. |
Core engine jars and kie-ci . | Use JBoss BRMS or JBoss BPM Suite with KieScanner (KIE-CI) to download kJARs from a Maven repository. |
kie-spring | Use KIE-Spring integration. |
kie-spring and kie-aries-blueprint . | Use KIE-Aries-Blueprint integration. |
10.2. Additional Features for SwitchYard and Camel Integration
- fuse-bxms-switchyard-common-knowledge
- fuse-bxms-switchyard-rules
- fuse-bxms-switchyard-bpm
- kie-camel
- jbpm-workitems-camel
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 JBoss Fuse 6.2 out of the box in installDir/etc/org.ops4j.pax.url.mvn.cfg
.
10.3. Install/Update Core Integration Features
Note
drools-karaf-features-<version>-features.xml
file. For additional integration features, refer to Section 10.4, “Install Additional Integration Features”.
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 10.1. Removing an Existing drools-karaf-features
Installation
- Start the Fuse console using:
$ ./installDir/bin/fuse
- Unistall old features/apps 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/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 Fuse.
drools-karaf-features
:
Procedure 10.2. Install core JBoss BPM Suite and JBoss BRMS features
- Configure required repositories
- Edit the
installDir/etc/org.ops4j.pax.url.mvn.cfg
file in your JBoss Fuse installation and add the following entry to theorg.ops4j.pax.url.mvn.repositories
variable, noting that entries are separated by ‘, \
’:- http://maven.repository.redhat.com/product-ga/@id=bxms-product-repo
- Start JBoss Fuse:
$ ./installDir/bin/fuse
- Add a reference to the core features file by running the following console command:
JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/<version>/xml/features
For example:features:addurl mvn:org.drools/drools-karaf-features/6.3.0.Final-redhat-7/xml/features
- You can now install the features provided by this file by running, for example, the following console command:
JBossFuse:karaf@root> features:install jbpm
10.4. Install Additional Integration Features
Procedure 10.3. SwitchYard and Camel Integration
- Download the
fuse-integration
package that is aligned with your version of JBoss Fuse.Note
For instance, if you want to use the 6.2.0.redhat-117 version of JBoss Fuse, you need to install thefuse-6.2.0.redhat-117
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.drools/drools-karaf-features/<DROOLS_VERSION>/xml/features JBossFuse:karaf@root> features:addurl mvn:org.jboss.integration.fuse/karaf-features/1.0.0.redhat-<version>/xml/features
- You can now install the features provided for SwitchYard and 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
10.5. Configuring Dependencies
- 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 BRMS and BPM Suite bundles and then import them in your application.
10.6. Install JBoss Fuse Integration Quickstart Applications
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
installDir/etc/org.ops4j.pax.url.mvn.cfg
.
Procedure 10.4. Installing the Quickstart Application
- 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 quickstart 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 10.5. Downloading and Installing the Quickstart ZIP Files
- Download the quickstart application ZIP file.
- Unpack the contents of the quickstarts directory into your existing
installDir/quickstarts
directory. - Unpack the contents of the system directory into your existing
installDir/system
directory.
10.6.1. Testing Your First Quickstart Application
Procedure 10.6. Testing the Quickstart Application
- Start JBoss Fuse:
$ ./installDir/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 webservice request to invoke the SOAP gateway.
- Open a terminal window and navigate to the associated quickstart directory that was unpacked from the quickstart 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 yoursettings.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 11. Integrating with Spring
11.1. Configuring Red Hat JBoss BPM Suite with Spring
jboss-bpms-engine.zip
file and is called kie-spring-VERSION-redhat-MINORVERSION.jar
.
As a Self Managed Process Engine
RuntimeManager
API, perfect synchronization between process engine and task service is managed internally and the end user does not have to deal with the internal code to make these two work together.
As a Shared Task Service
TaskService
, you have more flexibility in configuring the task service instance as it is independent of the RuntimeManager
. Once configured it is then used by the RuntimeManager when requested.
org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean
class. This factory class is responsible for producing instances of RuntimeEnvironment
that are consumed by RuntimeManager upon creation. Illustrated below is a configured RuntimeEnvironment with the entity manager, transaction manager, and resources for the class org.kie.spring.factorybeans.RuntimeEnvironmentFactoryBean
:
<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>
- DEFAULT - default (most common) configuration for RuntimeManager
- EMPTY - completely empty environment to be manually populated
- DEFAULT_IN_MEMORY - same as DEFAULT but without persistence of the runtime engine
- DEFAULT_KJAR - same as DEFAULT but knowledge asset are taken from KJAR identified by releaseid or GAV
- DEFAULT_KJAR_CL - build directly from classpath that consists kmodule.xml descriptor
- knowledgeBase
- assets
- releaseId
- groupId, artifactId, version
entity manager factory
and transaction manager
. Illustrated below is an example RuntimeManager for org.kie.spring.factorybeans.RuntimeManagerFactoryBean
:
<bean id="runtimeManager" class="org.kie.spring.factorybeans.RuntimeManagerFactoryBean" destroy-method="close"> <property name="identifier" value="spring-rm"/> <property name="runtimeEnvironment" ref="runtimeEnvironment"/> </bean>
Chapter 12. CDI Integration
12.1. CDI Integration
- entity manager and entity manager factory
- user group callback for human tasks
- identity provider to pass authenticated user information to the services
public class EnvironmentProducer { @PersistenceUnit(unitName = "org.jbpm.domain") private EntityManagerFactory emf; @Inject @Selectable private UserGroupCallback userGroupCallback; @Produces public EntityManagerFactory getEntityManagerFactory() { return this.emf; } @Produces @RequestScoped public EntityManager getEntityManager() { EntityManager em = emf.createEntityManager(); return em; } public void close(@Disposes EntityManager em) { em.close(); } @Produces public UserGroupCallback produceSelectedUserGroupCalback() { return userGroupCallback; } @Produces public IdentityProvider produceIdentityProvider { return new IdentityProvider() { // implement IdentityProvider }; } }
deployments/business-central.war/WEB-INF/beans.xml
file may be configured to change the current settings of the new usergroupcallback
implementation.
<beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://docs.jboss.org/cdi/beans_1_0.xsd"> <alternatives> <class>org.jbpm.services.task.identity.JAASUserGroupCallbackImpl</class> </alternatives> </beans>
Note
org.jbpm.services.task.identity.JAASUserGroupCallbackImpl
is just an example here to demonstrate the settings of the application server regardless of what it actually is (LDAP, DB, etc).
Chapter 13. Persistence
Note
- Session state: this includes the session ID, date of last modification, the session data that business rules would need for evaluation, state of timer jobs.
- Process instance state: this includes the process instance ID, process ID, date of last modification, date of last read access, process instance start date, runtime data (the execution status including the node being executed, variable values, etc.)and the eventtypes.
- Work item runtime state: this includes the work item ID, creation date, name, process instance ID, and the work item state itself.
13.1. Session
SessionInfo
entities. These persist the state of the runtime KIE session, and store the following data:
Table 13.1.
Field | Description | Nullable |
---|---|---|
id
|
primary key
|
false
|
lastmodificationdate
|
last saved to data store
|
N/A
|
rulesbytearray
|
binary dataset with session state (binary blob
|
false
|
startdate
|
session start
| |
optlock
|
version number used to lock value for optimistic locking
| |
13.2. Process Instance
ProcessInstanceInfo
entities, which persist the state of a process instance on runtime and store the following data:
Table 13.2.
Field | Description | Nullable |
---|---|---|
instanceid
|
primary key
|
false
|
lastmodificationdate
|
last saved to data store
|
N/A
|
lastreaddate
|
last read from data store
|
N/A
|
processid
|
ID of the process the instance is based on
|
false
|
processinstancebytearray
|
binary dataset with process instance state (binary blob)
|
false
|
startdate
|
Process instance start date
| |
optlock
|
version number used lock value for optimistic locking
| |
state
|
Process instance state
|
false
|
ProcessInstanceInfo
has a 1:N relationship to the EventTypes
entity.
EventTypes
entity contains the following data:
Table 13.3.
Field | Description | Nullable |
---|---|---|
instanceid
|
reference to the Process instance (foreign key to the
processinstanceinfo )
|
false
|
element
|
text field related to an event the Process instance has undergone
| |
Pessimistic Locking Support
import org.kie.api.runtime.Environment; import org.kie.api.runtime.EnvironmentName; import org.kie.api.runtime.manager.RuntimeManager; import org.kie.api.runtime.manager.RuntimeManagerFactory; ... // here env is an instance of org.kie.api.runtime.Environment env.set(EnvironmentName.USE_PESSIMISTIC_LOCKING, true); // now create your Runtime Manager using this enviornment RuntimeManager manager = RuntimeManagerFactory.Factory.get().newPerRequestRuntimeManager(environment);
13.3. Work Item
workiteminfo
entities, which persist the state of the particular work item instance on runtime and store the following data:
Table 13.4.
Field | Description | Nullable |
---|---|---|
workitemid
|
primary key
|
false
|
name
|
work item name
| |
processinstanceid
|
parent Process instance id
|
false
|
state
|
integer representing work item state
|
false
|
optlock
|
version number used lock value for optimistic locking
| |
workitembytearray
|
binary dataset with work item state (binary blob
)
|
false
|
creationDate
|
timestampe on which the work item was created
|
false
|
13.4. Persistence configuration
13.4.1. Persistence configuration
JBPMHelper
class after you create a session or using the JPAKnowledgeService
to create your session. The latter option provides more flexibility, while JBPMHelper
has a method to create a session, and uses a configuration file to configure this session.
13.4.2. Configuring persistence using JBPMHelper
- Define your application to use an appropriate JBPMHelper session construtor:
KieSession ksession = JBPMHelper.newKieSession(kbase);
KieSession ksession = JBPMHelper.loadKieSession(kbase, sessionId);
- Configure the persistence in the
jBPM.properties
file.Example 13.1. A sample jBPM.properties file with persistence for the in-memory H2 database
# for creating a datasource persistence.datasource.name=jdbc/jbpm-ds persistence.datasource.user=sa persistence.datasource.password= persistence.datasource.url=jdbc:h2:tcp://localhost/~/jbpm-db persistence.datasource.driverClassName=org.h2.Driver # for configuring persistence of the session persistence.enabled=true persistence.persistenceunit.name=org.jbpm.persistence.jpa persistence.persistenceunit.dialect=org.hibernate.dialect.H2Dialect # for configuring the human task service taskservice.enabled=true taskservice.datasource.name=org.jbpm.task taskservice.transport=mina taskservice.usergroupcallback=org.jbpm.task.service.DefaultUserGroupCallbackImpl
JBPMHelper.startH2Server();
method call and register it with the engine using JBPMHelper.setupDataSource();
method call.
13.4.3. Configuring persistence using JPAKnowledgeService
- Define your application to use the knowledge session created by JPAKnowledgeService:
- Define the session based on a knowledge base, a knowledge session configuration, and an environment. The environment must contain a reference to your Entity Manager Factory:
// create the entity manager factory and register it in the environment EntityManagerFactory emf = Persistence.createEntityManagerFactory( "org.jbpm.persistence.jpa" ); Environment env = KnowledgeBaseFactory.newEnvironment(); env.set( EnvironmentName.ENTITY_MANAGER_FACTORY, emf ); // create a new knowledge session that uses JPA to store the runtime state KieSession ksession = JPAKnowledgeService.newKieSession( kbase, null, env ); int sessionId = ksession.getId(); // invoke methods on your method here ksession.startProcess( "MyProcess" ); ksession.dispose();
- Define the session based on a specific session id.
// recreate the session from database using the sessionId ksession = JPAKnowledgeService.loadKieSession(sessionId, kbase, null, env );
- Configure the persistence in the
META-INF/persistence.xml
file: configure JPA to use Hibernate and the respective database.Information on how to configure data source on your application server should be available in the documentation delivered with the application server. For this information for JBoss Enterprise Application Platform, see the Administration and Configuration Guide for this product.Example 13.2. A sample persistence.xml file with persistence for an H2 data source
jdbc/jbpm-ds
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <persistence version="1.0" xsi:schemaLocation= "http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd" xmlns:orm="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/persistence"> <persistence-unit name="org.jbpm.persistence.jpa" transaction-type="JTA"> <provider>org.hibernate.ejb.HibernatePersistence</provider> <jta-data-source>jdbc/jbpm-ds</jta-data-source> <mapping-file>META-INF/JBPMorm.xml</mapping-file> <class>org.drools.persistence.info.SessionInfo</class> <class>org.jbpm.persistence.processinstance.ProcessInstanceInfo</class> <class>org.drools.persistence.info.WorkItemInfo</class> <properties> <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/> <property name="hibernate.max_fetch_depth" value="3"/> <property name="hibernate.hbm2ddl.auto" value="update"/> <property name="hibernate.show_sql" value="true"/> <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.BTMTransactionManagerLookup"/> </properties> </persistence-unit> </persistence>
JBPMHelper.startH2Server();
method call and register it with the engine using JBPMHelper.setupDataSource();
method call.
Note
PoolingDataSource ds = new PoolingDataSource(); ds.setUniqueName("jdbc/jbpm-ds"); ds.setClassName("bitronix.tm.resource.jdbc.lrc.LrcXADataSource"); ds.setMaxPoolSize(3); ds.setAllowLocalTransactions(true); ds.getDriverProperties().put("user", "sa"); ds.getDriverProperties().put("password", "sasa"); ds.getDriverProperties().put("URL", "jdbc:h2:tcp://localhost/~/jbpm-db"); ds.getDriverProperties().put("driverClassName", "org.h2.Driver"); ds.init();
Chapter 14. Transactions
14.1. Transactions
14.2. Defining transactions
- Register the transaction manager in your environment.
Example 14.1. Code with transaction manager registration
// create the entity manager factory EntityManagerFactory emf = EntityManagerFactoryManager.get().getOrCreate("org.jbpm.persistence.jpa"); TransactionManager tm = TransactionManagerServices.getTransactionManager(); Environment env = EnvironmentFactory.newEnvironment(); env.set(EnvironmentName.ENTITY_MANAGER_FACTORY, emf); env.set(EnvironmentName.TRANSACTION_MANAGER, tm); // setup the runtime environment RuntimeEnvironment environment = RuntimeEnvironmentBuilder.Factory.get() .newDefaultBuilder() .addAsset(ResourceFactory.newClassPathResource("MyProcessDefinition.bpmn2"), ResourceType.BPMN2) .addEnvironmentEntry(EnvironmentName.TRANSACTION_MANAGER, tm) .addEnvironmentEntry(EnvironmentName.PERSISTENCE_CONTEXT_MANAGER, new JpaProcessPersistenceContextManager(env)) .addEnvironmentEntry(EnvironmentName.TASK_PERSISTENCE_CONTEXT_MANAGER, new JPATaskPersistenceContextManager(env)) .get();
- Initialize the KieSession:
// get the KieSession RuntimeManager manager = RuntimeManagerFactory.Factory.get().newPerProcessInstanceRuntimeManager(environment); RuntimeEngine runtime = manager.getRuntimeEngine(ProcessInstanceIdContext.get()); KieSession ksession = runtime.getKieSession();
- Define the transaction manager in
jndi.properties
.Example 14.2. Definition of Bitronix transaction manager in jndi.properties
java.naming.factory.initial=bitronix.tm.jndi.BitronixInitialContextFactory
Note
To use a different JTA transaction manager, edit the hibernate.transaction.manager_lookup_class, the transaction manager property, in thepersistence.xml
file to load your transaction manager.Example 14.3. JBoss Transaction Manager set as transaction manager
<property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.JBossTransactionManagerLookup"/>
- Define the start and the end of the transaction.
// start the transaction UserTransaction ut = InitialContext.doLookup("java:comp/UserTransaction"); ut.begin(); // perform multiple commands inside one transaction ksession.insert( new Person( "John Doe" ) ); ksession.startProcess("MyProcess"); // commit the transaction ut.commit();
14.3. Container Managed Transactions
org.jbpm.persistence.jta.ContainerManagerTransactionManager
class. This is because the default implementation of the transaction manager in JBoss BPM Suite is based on the UserTransaction
class getting the transaction status. However, some application servers in a CMT mode do not allow accessing the UserTransaction
instance from JNDI.
ContainerManagedTransactionManager
class expects that the transaction is always active (returning ACTIVE
to the getStatus()
method).
Note
Configuring the Transaction Manager
ContainerManagedTransactionManager
, it needs to be inserted into the environment before you create or load a session:
Environment env = EnvironmentFactory.newEnvironment(); env.set(EnvironmentName.ENTITY_MANAGER_FACTORY, emf); env.set(EnvironmentName.TRANSACTION_MANAGER, new ContainerManagedTransactionManager()); env.set(EnvironmentName.PERSISTENCE_CONTEXT_MANAGER, new JpaProcessPersistenceContextManager(env));
persistence.xml
file. For example if using IBM WebSphere:
<property name="hibernate.transaction.factory_class" value="org.hibernate.transaction.CMTTransactionFactory"/> <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.WebSphereExtendedJTATransactionLookup"/>
Disposing the KSession in a CMT
dispose()
method). Doing so will cause exceptions on transaction completion as the Process Engine needs to clean up the state after the invocation has finished.
org.jbpm.persistence.jta.ContainerManagedTransactionDisposeCommand
's execute()
method. Using this command ensures that the ksession will be disposed when the transaction is actually complete.
afterDisposal
phase of the transaction instead of executing it directly. If there is no active transaction or if there is no active transaction, the ksession is disposed immediately.
Chapter 15. Logging
- Process instance as
processinstancelog
- Element instance as
nodeinstancelog
- Variable instance as
variableinstancelog
Table 15.1. Fields of the ProcessInstanceLog table
Field | Description | Nullable |
---|---|---|
id
|
The primary key of the log entity
|
No
|
end_date
|
The end date of the process instance
|
Yes
|
processid
|
The name (id) of the underlying process
|
Yes
|
processinstanceid
|
The id of the process instance
|
No
|
start_date
|
The start date of the process instance
|
Yes
|
status
|
The status of the process instance
|
Yes
|
parentProcessInstanceId
|
The process instance id of the parent process instance if applicable
|
Yes
|
outcome
|
The outcome of the process instance (details on the process finish, such as error code)
|
Yes
|
Table 15.2. Fields of the NodeInstanceLog table
Field | Description | Nullable |
---|---|---|
id
|
The primary key of the log entity
|
No
|
log_date
|
The date of the event
|
Yes
|
nodeid
|
The node id of the underlying Process Element
|
Yes
|
nodeinstanceid
|
The id of the node instance
|
Yes
|
nodename
|
The name of the underlying node
|
Yes
|
processid
|
The id of the underlying process
|
Yes
|
processinstanceid
|
The id of the parent process instance
|
No
|
type
|
The type of the event (
0 = enter event, 1 = exit event)
|
No
|
Table 15.3. Fields of the VariableInstanceLog table
Field | Description | Nullable |
---|---|---|
id
|
The primary key of the log entity
|
No
|
log_date
|
The date of the event
|
Yes
|
processid
|
The name (id) of the underlying process
|
Yes
|
processinstanceid
|
The id of the process instance
|
No
|
value
|
The value of the variable at log time
|
Yes
|
variableid
|
The variable id as defined in the process definition
|
Yes
|
variableinstanceid
|
The id of the variable instance
|
Yes
|
outcome
|
The outcome of the process instance (details on the process finish, such as error code)
|
Yes
|
15.1. Logging events to database
- Map the Log classes to the data source, so that the given data source accepts the log entries. On Red Hat JBoss EAP, edit the data source properties in the
persistence.xml
file.Example 15.1. The ProcessInstanceLog, NodeInstanceLog and VariableInstanceLog classes enabled for processInstanceDS
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <persistence version="1.0" xsi:schemaLocation= "http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd" xmlns:orm="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/persistence"> <persistence-unit name="org.jbpm.persistence.jpa"> <provider>org.hibernate.ejb.HibernatePersistence</provider> <jta-data-source>jdbc/processInstanceDS</jta-data-source> <class>org.drools.persistence.info.SessionInfo</class> <class>org.jbpm.persistence.processinstance.ProcessInstanceInfo</class> <class>org.drools.persistence.info.WorkItemInfo</class> <class>org.jbpm.process.audit.ProcessInstanceLog</class> <class>org.jbpm.process.audit.NodeInstanceLog</class> <class>org.jbpm.process.audit.VariableInstanceLog</class> <properties> <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/> <property name="hibernate.max_fetch_depth" value="3"/> <property name="hibernate.hbm2ddl.auto" value="update"/> <property name="hibernate.show_sql" value="true"/> <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.BTMTransactionManagerLookup"/> </properties> </persistence-unit> </persistence>
- Register a logger on your Kie Session.
Example 15.2. Import the Loggers
import org.jbpm.process.audit.AuditLogService; import org.jbpm.process.audit.AuditLoggerFactory; import org.jbpm.process.audit.AuditLoggerFactory.Type; import org.jbpm.process.audit.JPAAuditLogService; ...
Example 15.3. Registering a Logger to a Kie Session
@PersistenceUnit(unitName = PERSISTENCE_UNIT_NAME) private EntityManagerFactory emf; private AuditLogService auditLogService; @PostConstruct public void configure() { auditLogService = new JPAAuditLogService(emf); ((JPAAuditLogService) auditLogService).setPersistenceUnitName(PERSISTENCE_UNIT_NAME); if( emf == null ) { ((JPAAuditLogService) auditLogService).setPersistenceUnitName(PERSISTENCE_UNIT_NAME); } RuntimeEngine runtime = singletonManager.getRuntimeEngine(EmptyContext.get()); KieSession ksession = runtime.getKieSession(); AuditLoggerFactory.newInstance(Type.JPA, ksession, null); }
- Optionally, call the method
addFilter
on the logger to filter out irrelevant information. Only information accepted by all filters appears in the database. - Logger classes can be viewed in the Audit View:
<dependency> <groupId>org.jbpm</groupId> <artifactId>jbpm-audit</artifactId> <version>6.0.1.Final</version> </dependency>
15.2. Logback Functionality
logback
functionality for logging configuration.
<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.
15.3. Configuring Logging
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>
- org.guvnor
- org.jbpm
- org.kie
- org.slf4j
- org.dashbuilder
- org.uberfire
- org.errai
- etc...
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
15.4. Managing log files
- Process instances data, which is removed upon process instance completion.
- Work items data, which is removed upon work item completion.
- Task instances data, which is removed upon completion of a process to which given task belongs.
- Singleton strategy ensures that session information runtime data will not be automatically removed.
- Per request strategy allows automatic removal when a given request terminates.
- Per process instances will be automatically removed when process instance mapped to a given session completes or is aborted.
- Automatic clean-up
- Manual clean-up
15.4.1. Automatic Clean-Up
LogCleanupCommand
executor command, which consists of logic to clean up all or selected data automatically. An advantage of the automatic clean-up method is the ability to schedule repeated clean-ups by using reoccurring job feature of the JBoss BPM Suite executor. This means that when one job completes, it provides information to the JBoss BPM Suite executor if and when the next instance of this job should be executed. By default, LogCleanupCommand
is executed once a day but can be reconfigured to run on different intervals.
LogCleanupCommand
command:
Table 15.4. LogCleanupCommand parameters table
Name
|
Description
|
Is Exclusive
|
---|---|---|
SkipProcessLog
|
Indicates if the clean-up of process instances, node instances and variables log cleanup should be omitted (default: false)
|
No, can be used with other parameters
|
SkipTaskLog
|
Indicates if the task audit and the task event log clean-up should be omitted (default: false)
|
No, can be used with other parameters
|
SkipExecutorLog
|
Indicates if the JBoss BPM Suite executor entries clean-up should be omitted (default: false)
|
No, can be used with other parameters
|
SingleRun
|
Indicates if the job routine should run only once (default: false)
|
No, can be used with other parameters
|
NextRun
|
Sets a date for the next run. For example, 12h is set for jobs to be executed every 12 hours. If the option is not given, the next job will run 24 hours after the completion of the current job
|
Yes, cannot be used when the OlderThanPeriod parameter is used
|
OlderThan
|
Causes logs older than the given date to be removed. The date format is YYYY-MM-DD. Usually, this parameter is used for single run jobs
|
Yes, cannot be used when the NextRun parameter is used
|
OlderThanPeriod
|
Causes logs older than the given timer expression should be removed. For example, set 30d to remove logs older than 30 day from current time
|
No, can be used with other parameters
|
ForProcess
|
Specifies process definition ID for which logs should be removed
|
No, can be used with other parameters
|
ForDeployment
|
Specifies deployment ID for which logs should be removed
|
No, can be used with other parameters
|
EmfName
|
Persistence unit name that shall be used to perform operation deletion
|
N/A
|
Note
Warning
15.4.2. Setting up Automatic Clean-up Job
- Open Business Central in your web browser (if running locally http://localhost:8080/business-central) and log in as a user with the
admin
role. - Go to Deploy → Jobs.
- Click on next to Action and select New Job.
- Enter a name, due date and time. Enter the following into the Type text field:
org.jbpm.executor.commands.LogCleanupCommand
- Click on Add Parameter if you wish to use parameters listed above. In the key section, enter a parameter name. In the value section, enter true or false, depending on the desired outcome.
- Click Create to finalize the job creation wizard. You have successfully created an automatic clean-up job.
15.4.3. Manual Clean-Up
- Process audit, which is used to clean up process, node and variables logs, accessible in the
jbpm-audit
module - Task audit, which is used to clean up tasks and task events, accessible in the
jbpm-human-task-audit
module - Executor jobs, which is used to clean up executor jobs and errors, accessible in the
jbpm-executor
module
org.jbpm.process.audit.JPAAuditLogService
org.jbpm.services.task.audit.service.TaskJPAAuditService
org.jbpm.executor.impl.jpa.ExecutorJPAAuditService
Example 15.4. Removal of completed process instance logs
import org.jbpm.process.audit.JPAAuditLogService; import org.kie.internal.runtime.manager.audit.query.ProcessInstanceLogDeleteBuilder; import org.kie.api.runtime.process.ProcessInstance; JPAAuditLogService auditService = new JPAAuditLogService(emf); ProcessInstanceLogDeleteBuilder updateBuilder = auditService.processInstanceLogDelete().status(ProcessInstance.STATE_COMPLETED); int result = updateBuilder.build().execute();
Example 15.5. Task audit logs removal for the org.jbpm:HR:1.0 deployment
import org.jbpm.services.task.audit.service.TaskJPAAuditService; import org.kie.internal.task.query.AuditTaskDeleteBuilder; TaskJPAAuditService auditService = new TaskJPAAuditService(emf); AuditTaskDeleteBuilder updateBuilder = auditService.auditTaskDelete().deploymentId("org.jbpm:HR:1.0"); int result = updateBuilder.build().execute();
Example 15.6. Executor error and requests removal
import org.jbpm.executor.impl.jpa.ExecutorJPAAuditService; import org.kie.internal.runtime.manager.audit.query.ErrorInfoDeleteBuilder; import org.kie.internal.runtime.manager.audit.query.RequestInfoLogDeleteBuilder; ExecutorJPAAuditService auditService = new ExecutorJPAAuditService(emf); ErrorInfoDeleteBuilder updateBuilder = auditService.errorInfoLogDeleteBuilder().dateRangeEnd(new Date()); int result = updateBuilder.build().execute(); RequestInfoLogDeleteBuilder updateBuilder2 = auditService.requestInfoLogDeleteBuilder().dateRangeEnd(new Date()); result = updateBuilder.build().execute();
Note
Warning
Chapter 16. Localization and customization
16.1. Available Languages
- United States English (
en_US
) - Spanish (
es_ES
) - Japanese (
ja_JP
) - Chinese (
zh_CN
) - Portuguese (
pt_BR
) - French (
fr_CA
) - German (
de_DE
)
Note
16.2. Changing language settings
Changing the User Interface Language in Business Central
http://localhost:8080/business-central/?locale=pt_BR
Changing the User Interface Language in Dashbuilder
- Log into the dashbuilder after the server has been successfully started by navigating to http://localhost:8080/dashbuilder in a web browser.
- Select the language of your choice by clicking on the available locales on the top center of the dashbuilder user interface to change the language.
Setting a Default User Interface Language in Dashbuilder
Procedure 16.1. Setting the default language as French
- Navigate to
jboss-eap-6.4/standalone/configuration
and define the following in thestandalone.xml
file.<system-properties> <property name="org.jboss.dashboard.LocaleManager.installedLocaleIds" value="en,es,de,fr,ja,pt,zh"/> <property name="org.jboss.dashboard.LocaleManager.defaultLocaleId" value="fr"/> </system-properties>
- The default user interface language of the dashbuilder is now set to French.
Defining the Installed Locales in Dashbuilder
Procedure 16.2. Defining the installed locale
- Navigate to
jboss-eap-6.4/standalone/configuration
and define the following in thestandalone.xml
file.<system-properties> <property name="org.jboss.dashboard.LocaleManager.installedLocaleIds" value="en,es,de,fr,ja,pt"/> <property name="org.jboss.dashboard.LocaleManager.defaultLocaleId" value="fr"/> </system-properties>
Note
16.3. Running the JVM with UTF-8 Encoding
Part IV. Execution
Chapter 17. Process Execution Server Configuration
17.1. Assignment rules
17.1.1. Defining assignment rules
- 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 createddefault-complete-task.drl
with the rules to be checked when the Human Task is completed
- Define the rules in the file.
Example 17.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
Mary
, the task will be automatically assigned to the user mary
.
Example 17.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
Mary
, the task will be automatically assigned to the user mary
.
17.2. Mail session
17.2.1. Setting up mail session
- Open the respective profile configuration file (
standalone.xml
orhost.xml
) for editing. - Add the mail session to the
urn:jboss:domain:mail:1.1
subsystem.Example 17.3. New mail session on localhost
<subsystem xmlns="urn:jboss:domain:mail:1.1"> <!-- omitted code --> <mail-session jndi-name="java:/mail/bpmsMailSession" debug="true" from="bpms@company.com"> <smtp-server outbound-socket-binding-ref="bpmsMail"/> </mail-session> </subsystem>
- Define the session outbound socket in the profile configuration file.
Example 17.4. Outbound socket definition
<outbound-socket-binding name="bpmsMail"> <remote-destination host="localhost" port="12345"/> </outbound-socket-binding>
Chapter 18. Plug-in for Red Hat JBoss Developer Studio
18.1. Plug-in
Part V. Monitoring
Chapter 19. Process monitoring
19.1. JBoss Operations Network
com.sun.management.jmxremote.*
parameters must be passed to the JBoss application via the pom.xml
configuration file.
19.2. Installing the JBoss BRMS Plug-in into JBoss ON
Procedure 19.1. 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.
Procedure 19.2. 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.
19.3. Monitoring Kie Bases and Kie Sessions
-kie.mbeans = enabled
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 occured in the updated version.
Chapter 20. Managing Security for Red Hat JBoss BPM Suite Dashbuilder
20.1. Accessing Red Hat JBoss BPM Suite Dashbuilder
20.2. Managing security
- admin - Administrates the Red Hat JBoss BPM Suite system. Has full access rights to make any changes necessary. Also has the ability to add and remove users from the system.
- developer - Implements code required for process to work. Mostly uses the JBDS connection to view processes, but may use the web tool occasionally.:
- analyst - Responsible for creating and designing processes into the system. Creates process flows and handles process change requests. Needs to test processes that they create. Also creates forms and dashboards.
- user - Daily user of the system to take actions on business tasks that are required for the processes to continue forward. Works primarily with the task lists.
- manager - Viewer of the system that is interested in statistics around the business processes and their performance, business indicators, and other reporting of the system and people who interact with the system.
20.3. Workspace permissions
Procedure 20.1. Accessing Workspace Permissions
- Log into Business Dashboards from Business Central (as described in the Accessing Red Hat JBoss BPM Suite Dashbuilder topic).
- Select the appropriate Dashboard from the Wokspace drop-down.
Figure 20.1. Dashbuilder Workspace
- Click the Edit selected workspace properties button to access the Workspace Dashboard.
- Click the Permissions label to view the permission management screen.
Figure 20.2. Permissions Screen
- Access: permission to login into the application.
- Administrate: permission to access the toolbar and system configuration features.
- Create pages: ability to create new project pages.
- Edit: permission to change the workspace properties.
- Clear: ability to delete the workspace.
- Edit permissions: ability to grant/deny permissions.
- Change allowed panels: permission to restrict the type of panels that can be used in this workspace.
Figure 20.3. Permissions Assignation
- Target roles (who): What user will be granted/denied with the permissions defined.
- Allowed actions: depending on the type of the resource we can enable/disable what the user can do on this resource.
- Reverse (optional): when we have a set of roles and we want to grant/deny a permission to all the roles but one.
Note
20.4. Page permissions
- To access Page permissions, locate the Pages drop-down under the jBPM Dashboard (or whatever Dashboard you selected).
- After expanding Pages, expand the Process dashboard option.
- Select the Page permissions option.
Figure 20.4. Page Permissions
- Visualize: permission to make the page visible.
- Edit: ability to change the page properties.
- Clear: ability to delete the page.
- Edit permissions: ability to grant/deny permissions for the page.
20.5. Panel permissions
- To access the Panel permissions page, expand the Panel instances option under the jBPM Dashboard (or whatever Dashboard you are using).
- Expand the Dashboard option and then expand the Process dashboard.
- Expand the Panels choice and select the appropriate process.
- Open the Panel permissions page.
Figure 20.5. Panel permissions configuration screen
- Visualize: make the panel visible.
- Edit: change the panel properties.
- Edit permissions: ability to grant/deny permissions for the panel.
Appendix A. Revision History
Revision History | |||
---|---|---|---|
Revision 6.2.0-5 | Thu Apr 28 2016 | Tomas Radej | |
| |||
Revision 6.2.0-4 | Thu Apr 28 2016 | Tomas Radej | |
| |||
Revision 6.2.0-3 | Tue Mar 29 2016 | Tomas Radej | |
| |||
Revision 6.2.0-2 | Mon Nov 30 2015 | Tomas Radej | |
| |||
Revision 6.2.0-1 | Mon Nov 30 2015 | Tomas Radej | |
|