Getting Started Guide

Red Hat JBoss BPM Suite 6.4

The Getting Started Guide for Red Hat JBoss BPM Suite.

Red Hat Customer Content Services

Emily Murphy

Gemma Sheldon

Michele Haglund

Mikhail Ramendik

Stetson Robinson

Vidya Iyengar

Abstract

This guide provides information for getting started with Red Hat JBoss BPM Suite.

Chapter 1. Quick Start with Red Hat JBoss BPM Suite

This section describes how to download, install, and run Red Hat JBoss BPM Suite. For more detailed steps and alternative methods of installation, see the Red Hat JBoss BPM Suite Installation Guide.

Prerequisites

  • A supported Java version installed on your system. See the Red Hat JBoss BPM Suite 6 Supported Configurations section of the Red Hat Customer Portal for a list of supported Java versions.
  • A Red Hat JBoss EAP server installation, version 6.4 or higher. If you are using the installer file, you must have Red Hat JBoss EAP 6 version 6.4.7 or higher.
Note

It may be necessary for you to update your Red Hat JBoss EAP server. If the installer informs you of such need, download the newest patch from the Red Hat Customer Portal and follow the instructions for updating in the Red Hat JBoss EAP Installation Guide.

Procedure: Red Hat JBoss BPM Suite Quick Start

  1. Download the installer from the Software Downloads section of the Red Hat Customer Portal.
  2. Run installer by executing the following command:

    java -jar jboss-bpmsuite-VERSION-installer.jar
  3. Finish the installation process. Note the user name and password for accessing the Red Hat JBoss BPM Suite application after installation.
  4. After successful installation, in a command prompt, change into the EAP_HOME directory where you have installed Red Hat JBoss BPM Suite.
  5. Start the server:

    bin/standalone.sh
  6. Open a web browser and enter http://localhost:8080/business-central/. Log in using the user name and password for accessing the Red Hat JBoss BPM Suite application that you created at installation time.

You have successfully installed and run Red Hat JBoss BPM Suite.

Next Steps

If you want more details about installation on both Red Hat JBoss EAP and other containers, see Red Hat JBoss BPM Suite Installation Guide.

Chapter 2. Installation

This section describes installation of Red Hat JBoss BPM Suite on an already installed instance of Red Hat JBoss EAP 6.4 or later. If you use a different container, see the Red Hat JBoss BPM Suite Installation Guide.

If you followed Chapter 1, Quick Start with Red Hat JBoss BPM Suite, you have already installed Red Hat JBoss BPM Suite using the JAR installer. See Next Steps for further instructions.

Note

Red Hat JBoss BPM Suite is designed to work with UTF-8 encoding. If your JVM uses a different encoding system, unexpected errors may occur. To ensure UTF-8 is used by the JVM, use the following system property "-Dfile.encoding=UTF-8".

2.1. Downloading Red Hat JBoss BPM Suite for Red Hat JBoss EAP

  1. Open the DOWNLOADS section of the Red Hat Customer Portal in your browser.
  2. In the Product Downloads page that opens, click Red Hat JBoss BPM Suite and log in.
  3. From the Version drop-down menu, select version 6.4.
  4. Select Red Hat JBoss BPM Suite 6.4.0 Deployable for EAP 6 and click Download. If you use Red Hat JBoss EAP 7.0, select Red Hat JBoss BPM Suite 6.4.0 Deployable for EAP 7.

2.2. Installing Red Hat JBoss BPM Suite on Red Hat JBoss Enterprise Application Platform

2.2.1. Installation on a New Red Hat JBoss EAP Instance

To install the deployable package for a Red Hat JBoss Enterprise Application Platform:

  1. Move the ZIP archive you downloaded in Section 2.1, “Downloading Red Hat JBoss BPM Suite for Red Hat JBoss EAP” to the parent directory of the Red Hat JBoss Enterprise Application Platform home directory (referred to as EAP_HOME; the jboss-eap-6.4 directory).
  2. Unzip the downloaded ZIP archive and ensure it is merged into the EAP_HOME directory (jboss-eap-6.4).

    Warning

    Perform this step with the same user account that was used to install Red Hat JBoss EAP. This account must not be a superuser account.

  3. When prompted, overwrite the files that already exist in the EAP_HOME directory with with files from the downloaded ZIP archive.

2.2.2. Installation on an Existing Red Hat JBoss EAP Configuration

Warning

These instructions are for installing, and not for updating an existing Red Hat JBoss BRMS instance. Make sure that there is no existing Red Hat JBoss BRMS install in the target EAP.

To install the deployable package on a previously configured Red Hat JBoss EAP:

  1. Extract the ZIP package deployable for Red Hat JBoss EAP you downloaded in Section 2.1, “Downloading Red Hat JBoss BPM Suite for Red Hat JBoss EAP”.
  2. Unzip the downloaded ZIP archive; however, do not overwrite all of the files. Manually merge the following files into the EAP_HOME directory (jboss-eap-6.4):

    • jboss-eap-6.4/domain/configuration/* Be aware that Red Hat JBoss BPM Suite requires JMS, so JMS is added by default into all profiles in domain.xml provided by the Red Hat JBoss BPM Suite distribution.
    • jboss-eap-6.4/standalone/configuration/* Be aware that Red Hat JBoss BPM Suite requires JMS, so JMS is added by default into all profiles configuration files, including standalone.xml and standalone-ha.xml, provided by the Red Hat JBoss BPM Suite distribution.
    Warning

    Make sure this step is performed by the same user account that was used to install EAP. This account must not be a superuser account.

  3. Copy the folder jboss-eap-6.4/standalone/deployments into the EAP_HOME directory from the Red Hat JBoss BPM Suite distribution.

    Note

    If you already have deployments on your Red Hat JBoss EAP, ensure that your current deployments do not have colliding names with Red Hat JBoss BPM Suite deployments.

2.3. Defining Roles

Before starting the server and logging into Business Central, you need to create some user accounts. This section describes the different user roles that are used in Red Hat JBoss BPM Suite:

  • admin: The users with admin role are the administrators of the application. Administrators can manage users, manage the repositories (create and clone) and have full access to make the required changes in the application. Admins have access to all areas within the system.
  • developer: A developer has access to almost all features and can manage rules, models, process flows, forms and dashboards. They can manage the asset repository, create, build, and deploy projects. They can also use Red Hat JBoss Developer Studio to view processes. Only administrative functions, such as creating and cloning a new repository, are hidden for the developer role.
  • analyst: An analyst role has access to all features to model and execute projects. However, AuthoringAdministration access is unavailable to users with the analyst role. Certain lower-level features targeted towards developers, like the DeploymentArtifact Repository view, are not accessible for this role. However, the Build & Deploy button is available for the analyst role while using the Project Editor.
  • user: A user or a business user work on the business task lists that are used to operate a certain process. A user with this role can access the dashboard and manage processes.
  • manager: A manager supervises the system and is interested in statistics around the business processes and their performance, business indicators, and other reporting of the system. A user with this role has access to the BAM only.

For further information about roles, see section Access Control of the Red Hat JBoss Administration and Configuration Guide. For further information about roles and task interactions, see section User Task of Red Hat JBoss BPM Suite User Guide.

Other roles you can encounter:

  • REST API access control roles. For further information, see section Control of REST API of the Red Hat JBoss BPM Suite Development Guide.
  • The Intelligent Process Server kie-server role. For further information, see chapter Intelligent Process Server and Realtime Decision Server of the Red Hat JBoss BPM Suite Development Guide.
  • The kiemgmt role for the managed repository feature. See section Managing Assets of the Red Hat JBoss BPM Suite Administration and Configuration Guide.
Note

Enter the above mentioned roles during the user creation process.

2.4. Creating Users

To start adding new users, you will need to run the add-user.sh script on a Unix system or the add-user.bat file on a Windows system from the EAP bin directory.

Procedure: Creating New Users

  1. Change into the EAP_HOME directory.
  2. On a Unix system, run the following command:

    bin/add-user.sh

    On a Windows system, run:

    bin\add-user.bat
  3. Enter b to select the application user and press Enter.
  4. Accept the default realm (ApplicationRealm) by pressing Enter.
  5. At the user name prompt, enter the user name and confirm. For example: helloworlduser.

    Important

    Make sure that the selected user name does not conflict with any known title of a role or a group.

    For example, if there is a role called admin, do not create a user with the user name admin.

  6. Create the user password at the password prompt and reenter the password. For example: Helloworld@123.

    Note

    The password should be at least 8 characters in length and should contain upper and lower case alphabetic characters (A-Z, a-z), at least one numerical character (0-9) and at least one special character (for example ~ ! @ # $ % ^ * ( ) - _ + =).

  7. Enter a comma-separated list of roles the user will need at the roles prompt. For more information, see Section 2.3, “Defining Roles”.

    Note that Business Central users need to have the analyst or the admin role assigned,while the Dashboard Builder users need to have the admin role assigned.

  8. Confirm that you want to add the user.
  9. Enter yes at the next prompt to enable clustering in the future.

2.5. Starting Server

You can start your server in one of two modes:

  • Standalone, using the standalone.sh script.
  • Standalone-secure, using the standalone-secure.sh script.
Note

If you are starting the server in the domain mode, the corresponding scripts are domain.sh and domain-secure.sh respectively.

The default starting script is standalone.sh. It is optimized for performance. To run your server in the performance mode:

  1. On the command line, change into the EAP_HOME directory:
  2. In a Unix environment run:

    bin/standalone.sh

    In a Windows environment run:

    bin\standalone.bat

The standalone-secure.sh script is optimized for security. This script applies a security policy that protects you against a known security vulnerability.

Note

It is recommended that production environments use the standalone-secure.sh script.

Warning

The use of a security manager imposes a significant performance penalty. Consideration your individual circumstances to decide which script to use. For further information, see Section 2.6, “Java Security Manager and Performance Management”.

To start your server in the secure mode:

  1. On the command line, move into the EAP_HOME directory.
  2. In a Unix environment run:

    bin/standalone-secure.sh

    In a Windows environment run:

    bin\standalone-secure.bat
Note

If you installed Red Hat JBoss BPM Suite using the JAR installer, you can choose to apply the security policy during the installation. The installer does not provide a separate standalone-secure.sh script.

2.6. Java Security Manager and Performance Management

Enabling the Java Security Manager (JSM) to sandbox the evaluation of MVEL scripts in Red Hat JBoss BPM Suite causes a performance hit in high-load environments. When deploying a Red Hat JBoss BPM Suite application, consider the performance needs in your environment. Use the following guidelines to deploy secure and high performance Red Hat JBoss BPM Suite applications.

In high-load environments where performance is critical:

  • Deploy applications that have been developed on other systems and properly reviewed.
  • Do not create any users with the analyst role on such systems.

If these safeguards are followed, it is safe to leave JSM disabled on these systems so it does not introduce any performance degradation.

In testing and development environments without high loads, or in environments where rule and process authoring is exposed to external networks:

  • Enable JSM in order to achieve security benefits of properly sandboxed evaluation of MVEL.
  • Do not allow users with the analyst role to log in to the Business Central console with JSM disabled. This practice is not secure and not recommended.

Chapter 3. Logging into Business Central

To log into Business Central:

  1. Start the server with Red Hat JBoss BPM Suite.
  2. Navigate to http://localhost:8080/business-central in a web browser. 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/business-central.
  3. Log in with the user credentials that were created during installation. For example, user: helloworlduser and password: Helloworld@123.

Chapter 4. Hello World Project

This chapter instructs you on how to set up the Hello World project with a Hello World business process.

The business process will display the Hello World! message and finish its execution. For additional examples that use the full when-then rule functionality, see the Getting Started with Rules and Facts chapter from the Red Hat JBoss BPM Suite Development Guide.

In the following chapters, you will be instructed to do the following:

  1. Create a repository.
  2. Create the Hello World project.
  3. Model the Hello World process.
  4. Build and deploy the project on the locally running Execution Engine.
  5. Run the Hello World process.
  6. Monitor the process execution.

4.1. Creating Repository Structure

All business assets are located in repositories, which are associated with organizational units. The artifact repository does not contain any organizational unit by default. To create business assets, such as a business process, first create an organizational unit and a Git repository.

The repository contains projects. A project can contain an arbitrary package structure, which enables you to structure its content into a directory-like structure. Any package can contain your business assets. For more information on the artifact repository, see the Red Hat JBoss BPM Suite User Guide.

To create the repository structure, do the following:

  1. Open Business Central in your web browser and log in as a user with the admin role, for example helloworlduser.
  2. Create an organizational unit:

    1. Click AuthoringAdministration.
    2. On the perspective menu, click Organizational UnitsManage Organizational Units.
    3. In the displayed Organizational Unit Manager view, click Add.

      In the displayed Add New Organizational Unit dialog box, define the unit properties and click Ok:

      • Name: Loan Application
      • Owner: finance-dept@company.org
  3. Create a new repository in the Loan Application organizational unit:

    1. Click AuthoringAdministration.
    2. On the perspective menu, click RepositoriesNew repository.
    3. In the displayed New Repository dialog box, define the repository properties:

      • Repository Name: helloworldrepo
      • Organizational Unit: Loan Application
    4. Click Finish.
  4. Click AuthoringProject Authoring.
  5. In the Project Explorer in the organizational unit drop-down box, select Loan Application, and in the repository drop-down box select helloworldrepo.

    Figure 4.1. Selecting the helloworldrepo Repository in the Loan Application Organizational Group in Project Explorer

    project explorer
  6. Create a project in the helloworld repository:

    1. On the perspective menu, click New ItemProject.
    2. In the displayed New Project wizard, define your project properties:

      • Project Name: Hello World
      • Group ID: org.bpms
      • Artifact ID: HelloWorld
      • Version ID: 1.0
    3. Click Finish.

Chapter 5. Hello World Process

This chapter continues with the Hello World example. See the instructions to create an end to end business process to demonstrate the creation of a basic Hello World process.

5.1. Creating Business Process

To create a new business process definition, do the following:

  1. Click AuthoringProject Authoring to display the Project Authoring perspective.
  2. In the Project Explorer view on the left, select the Loan Application organizational unit, the helloworldrepo repository, and the Hello World project.
  3. On the perspective menu, click New ItemBusiness Process and define the process definition details:

    • Enter the name of the business process as Hello World.
    • Select the org.bpms.helloworld package. This defines the location where you will create your business process definition.
  4. Click Ok.

The Process Designer with the canvas of the created process definition opens.

5.2. Modeling Business Process

After you create the business process definition, design the business process in the Business Process Designer. The Business Process Designer should be open in a tab on the right. If you closed the tab, in the Project Explorer, click HelloWorld under BUSINESS PROCESSES to re-open the Business Process Designer. Ensure you select the correct package (org.bpms.helloworld).

To design the process content:

  1. Click the Start Event element ( startevent ) to see the quick linker items appear around the node. start event element
  2. Click the Task ( 3899 ) icon to create an outgoing Sequence Flow and a Task element connected to the Start Event.
  3. Click 3898 in the upper left corner of the Business Process Designer tab to expand the Object Library palette.
  4. Drag-and-drop the Timer from the palette (under Catching Intermediate Events) and connect the Task to the Timer Element using the Edge element from the quick linker menu.
  5. Create an End Event element connected to the Timer Event element (either using the quick linker feature or dragging it from the palette).

Figure 5.1. Draft of the Hello World Process

3900

5.3. Defining Element Properties

To define the element properties:

  1. Click the arrow ( 3897 ) in the upper right hand corner to expand the Properties tab.
  2. Click on an empty spot on the canvas. The Properties tab displays the properties of the Hello World process.

    The required properties are pre-defined. However, you can change their values if necessary.

  3. The Start Element and End Element have only optional properties. However, tasks must have a type with type-specific properties defined. Click the task and define the required properties:

    • Name: ScriptTask
    • Task Type: Script
    • Script Language: java
    • Script: Click 6563 and enter: System.out.println("Hello World!");

    You have defined a task that will perform a script on execution. The script is defined in Java and executes System.out.println("Hello World!"), which means it will write Hello World! to the standard output of the server. By default, the standard output of the server is the console the server was started in.

  4. Define properties of the Timer to make the process wait during runtime, so you can inspect its execution. Click on the Timer and define the time it will wait for execution:

    • Time Duration: Click 6563 and enter: 5m.

    The process will wait for 5 minutes on the Timer Event after it executes the Script Task.

  5. Click the Timer element and enter Name: Timer and then save your process by clicking Save at the top of the Business Process Editor.
  6. The Save this item prompt is displayed. Enter the Check-in comment.

    Note

    The check-in comment would be a short description of the kind of change you made and has to be entered every time an asset is saved.

  7. Click 3137 on the toolbar of the Process Designer with the process and select Start validating to ensure the defined process is valid. The outline of any element with one or multiple validation mistakes turns orange. For information on the validation feature, see the Red Hat JBoss BPM Suite User Guide.

Further information on Process Elements and their properties is available in the Red Hat JBoss BPM Suite User Guide.

5.4. Building and Deploying

Before you can instantiate your Hello World process, build and deploy the project to the Execution Server:

  1. On the main menu of Business Central, click AuthoringProject Authoring.
  2. In the Project Explorer, locate the Hello World project.
  3. Open the project in the Project Editor: in Project Explorer, click Open Project Editor.
  4. Check that the correct project details are displayed on the project screen and choose BuildBuild & Deploy in the upper right hand corner of the project screen view.

    Figure 5.2. Project Editor with the Hello World Project Properties

    Project Editor with the Hello World Project Properties.

A green notification appears in the upper part of the screen informing you that the project has been built and deployed to the Execution Server and is available for instantiation.

5.5. Instantiating Business Process

To create an instance of the Hello World process, that is, to run the business process, do the following:

  1. Click Process ManagementProcess Definitions on the main menu.
  2. On the displayed Process Definitions tab, locate the Hello World process definition. If none is available, click the Refresh button to have the process definition displayed on the list.
  3. Click Start ( start button ) next to the process definition entry and in the dialog box, click Submit to confirm that you want to instantiate the process.

    The process is instantiated with the currently logged-in user as the process owner and the process form is displayed. When you define the form for your business process, it serves to request input from a user during process instantiation. See the Red Hat JBoss BPM Suite User Guide for further information.

The Process Instance Details view is displayed with details about the started process instance. The Hello World! message appears in standard output, typically the terminal emulator in which the server was started. Then the process instance waits for the Timer to finish.

Click OptionsProcess Model to see the current execution status.

Figure 5.3. HelloWorld Realtime Execution Diagram: the Timer Event Being Executed

process model

5.6. Aborting Business Process

If you followed Section 5.5, “Instantiating Business Process”, the Execution Server contains an active Hello World process instance. You can check process instances in the Process Instances view:

To display the view, click Process ManagementProcess Instances.

In the Process Instances view, you can view the instance details by clicking on the row of a chosen process. Also, you can perform basic administration actions, such as sending a signal to a process instance ( signal button ) or aborting it ( abort button ).

After a business process is instantiated, it is waiting for the Timer Event. To abort the instance, click abort button on the row with the instance information. The instance will disappear from the list of Active process instances and appear in the Aborted list.

Figure 5.4. List of Aborted Process Instances

List of Aborted Process Instances.

Chapter 6. Hello World Business Rule

Since Red Hat JBoss BPM Suite comes with Red Hat JBoss BRMS integrated, this chapter provides an introduction to how business rules work and integrate into Red Hat JBoss BPM Suite.

You will add a new Business Rule Task to the Hello World process, which will fire a business rule of a particular business rule group.

Note that this is a very simple integration case and in production you may need to use a more advanced concept and techniques. For more information on business rules, see the Red Hat JBoss BPM Suite Development Guide.

6.1. Creating Business Rule

Business rules are defined as when-then statements: when something is true, then something happens. For example, when the person is older than 18, then particular content becomes available. Business rules are stored in DRL files.

To define the helloworldrule business rule in the Hello World project, do the following:

  1. In Project Explorer, select the Loan Application organizational unit, the helloworldrepo repository, the Hello World project, and the default package.
  2. Create the DRL file:

    1. On the perspective menu, click New ItemDRL file.
    2. In the Create new DRL file dialog box, define the resource name as helloworldrule and check that the package is set to default.
    3. Click Ok.
  3. In the displayed DRL editor with the helloworldrule.drl file, define the rule:

    rule "helloworldrule"
    ruleflow-group "helloworldgroup"
    
    when
    then
      System.out.println("Hello World!");
    end

    This rule does not define any when condition, that is, it will always be true when fired (called to execute) and the Hello World! phrase will be printed.

  4. Click Save.
  5. The Save this item prompt is displayed. Enter the Check-in comment and click Save.

6.2. Adding Business Rule Task

A Business Rule Task is a task which fires rules that belong to a certain ruleflow group.

To add a Business Rule Task to your process, do the following:

  1. In Project Explorer, click the arrow next to the organizational unit path.
  2. Expand BUSINESS PROCESSES and select`HelloWorld`.

    Note: If you are creating your project on a fresh installation, the BUSINESS PROCESSES menu is not visible until you click the arrow.

    Figure 6.1. The Hello World organizational unit path

    expand explorer
  3. In the displayed Business Process Designer with the Hello World process, expand the Object Library palette with Process Elements. Click the double-arrow button ( 3898 ) in the upper left hand corner of the Business Process Designer tab to do so.
  4. Expand the Tasks menu and drag-and-drop the Business Rule Task to the canvas on the right.

    Adjust flow connections so as to integrate the task into the workflow.

  5. Select the Business Rule Task and define its properties in the Properties panel:

    • Name: BusinessRule
    • Ruleflow Group: helloworldgroup

      The Ruleflow Group property defines the group of rules that should be fired when the task is being executed. In this example, only one rule, the helloworldrule rule defined in the helloworldrule.drl file, is present in the helloworldgroup group.

    Figure 6.2. The Hello World Process with the Business Rule Task and Its Properties

    business processes
  6. Click the save button to save the changes.

6.3. Building and Deploying

Build the project and deploy it to the Execution Server:

  1. On the main menu of Business Central, click AuthoringProject Authoring.
  2. In the Project Explorer, locate the Hello World project.
  3. Open the project in the Project Editor: in Project Explorer, click Open Project Editor.
  4. Set Version to 1.0.1.
  5. Click Save and confirm the dialogue to save your changes.
  6. Check that the correct project details are displayed on the project screen and click BuildBuild & Deploy in the upper right hand corner of the project screen view.

A green notification appears in the upper part of the screen informing you that the project has been built and deployed to the Execution Server and is available for instantiation.

6.4. Instantiating Business Process

To create an instance of the Hello World process, do the following:

  1. Click Process ManagementProcess Definitions on the main menu.
  2. On the displayed Process Definitions tab, locate the new Hello World process definition, that is org.bpms:HelloWorld:1.0.1. If it is not available, click Refresh to have the process definition displayed.
  3. Click the Start ( start button ) next to the process definition entry and in the dialog box, click Submit to confirm that you want to instantiate the process.

    The process is instantiated with the currently logged-in user as the process owner and the process form is displayed. When you define the form for your business process, it serves to request input from a user during process instantiation. For further information, see the Red Hat JBoss BPM Suite User Guide.

The Process Instance Details view is displayed with details about the started process instance. The Hello World! message appears in standard output twice, typically the terminal emulator in which the server was started. Then the process instance waits on the Timer Event.

Click OptionsProcess Model to see the current execution status.

Figure 6.3. Hello World Realtime Execution Diagram: the Timer Event Being Executed

process model2

Chapter 7. BAM

7.1. Accessing Red Hat JBoss BPM Suite Dashbuilder

Dashbuilder is the Red Hat JBoss BPM Suite web-based user interface for Business Activity Monitoring. To access the Dashbuilder from Business Central, click DashboardsProcess & Task Dashboards.

The displayed dashboard provides statistics on runtime data selected on the left. You can create your own dashboard in the Dashbuilder. To do so, display the Dashbuilder by clicking DashboardsBusiness Dashboards.

7.2. Monitoring Instances

The Dashbuilder provides a special dashboard that allows you to monitor the status of runtime data (process instances and tasks) on your Execution Engine.

To view this data, go to DashboardsProcess & Task Dashboard.

Figure 7.1. Process and Task Dashboard

3907

Click on an entity to display its statistics.

Chapter 8. Red Hat JBoss Developer Studio

Red Hat JBoss Developer Studio is the JBoss Integrated Development Environment (IDE) based on Eclipse. Get the latest Red Hat JBoss Developer Studio from the DOWNLOADS section of the Red Hat Customer Portal. Red Hat JBoss Developer Studio provides plug-ins with tools and interfaces for Red Hat JBoss BRMS and Red Hat JBoss BPM Suite. These plugins are based on the community version of these products. The Red Hat JBoss BRMS plug-in is called the Drools plug-in and the Red Hat JBoss BPM Suite plug-in is called the jBPM plug-in.

See the Red Hat JBoss Developer Studio documentation for the Red Hat JBoss Developer Studio installation and setup instructions.

Warning

Because of an issue in the way multi-byte rule names are handled, you must ensure that the instance of Red Hat JBoss Developer Studio is started with the file encoding set to UTF-8. You can do this by editing the $JBDS_HOME/studio/jbdevstudio.ini file and adding the following property: "-Dfile.encoding=UTF-8".

8.1. JBoss Central

When you first start the Red Hat JBoss Developer Studio, JBoss Central is displayed in the main window of the workbench. From JBoss Central, it is possible to create new projects by selecting the menu options under Start from scratch. Example projects can be started by selecting the links under Start from a sample.

Note

Due to issues in GWT3, Red Hat JBoss Developer Studio should be configured to not use it. You can do this by setting the system property to 0:

# Do not use GTK 3.
export SWT_GTK3=0

Figure 8.1. JBoss Central

3148

8.2. Installing Red Hat JBoss Developer Studio Plug-ins

The Drools and jBPM plug-ins for Red Hat JBoss Developer Studio are available through the update site.

Procedure: Installing Drools and jBPM Red Hat JBoss Developer Studio Plug-in

  1. Start Red Hat JBoss Developer Studio.
  2. Click HelpInstall New Software.
  3. Click Add to enter the Add Repository menu.
  4. Give the software site a name next to Name field and add the following URL in the Location field: https://devstudio.jboss.com/10.0/stable/updates/integration-stack/.
  5. Click OK.
  6. Select the JBoss Business Process and Rule Development feature from the available options and click Next and then Next again.
  7. Read the license, accept it by selecting the appropriate radio button, and click Finish.
  8. After the installation completes, restart Red Hat JBoss Developer Studio.

8.3. Setting Drools Runtime

In order to use the Red Hat JBoss BRMS plug-in with Red Hat JBoss Developer Studio, it is necessary to set up the runtime.

A runtime is a collection of JAR files that represents a specific release of the software and provides libraries needed for compilation and running of your business assets.

Procedure: Configuring Red Hat JBoss BRMS Runtime

  1. Open the DOWNLOADS section of the Red Hat Customer Portal.
  2. Click Red Hat JBoss BRMS and log in.
  3. Download the Red Hat JBoss BRMS 6.4.0 Core Engine archive.
  4. Extract the runtime JAR files located in the jboss-brms-VERSION-engine.zip.
  5. From the Red Hat JBoss Developer Studio menu, click WindowPreferences.
  6. Click DroolsInstalled Drools Runtimes.
  7. Click Add…​; provide a name for the new runtime, and click Browse to navigate to the directory where you extracted the runtime files. Click OK to register the selected runtime in Red Hat JBoss Developer Studio.
  8. Mark the runtime you have created as the default Drools runtime by clicking on the check box next to it.
  9. Click OK. If you have existing projects, a dialog box will indicate that you have to restart Red Hat JBoss Developer Studio to update the Runtime.

8.4. Setting Red Hat JBoss BPM Suite Runtime

If you have previously downloaded the Red Hat JBoss BPM Suite Generic Deployable ZIP archive from Red Hat Customer Portal, the JAR files that make up the runtime are located in the jboss-bpms-engine.zip archive.

Procedure: Configuring jBPM Runtime

  1. Open the DOWNLOADS section of the Red Hat Customer Portal.
  2. Click Red Hat JBoss BPM Suite and log in.
  3. Download the Red Hat JBoss BPM Suite 6.4.0 Core Engine archive.
  4. From the Red Hat JBoss Developer Studio menu, click WindowPreferences.
  5. Click jBPMInstalled jBPM Runtimes.
  6. Click Add…​ ; provide a name for the new runtime, and click Browse to navigate to the directory where the runtime is located.
  7. Click OK, select the new runtime and click OK again. If you have existing projects, a dialog box will indicate that you have to restart Red Hat JBoss Developer Studio to update the Runtime.

8.5. Configuring Red Hat JBoss BPM Suite Server

Red Hat JBoss Developer Studio can be configured to run the Red Hat JBoss BPM Suite Server.

Procedure: Configuring Server

  1. Open the jBPM view by clicking WindowPerspectiveOpen PerspectiveOther, then jBPM, and click OK.
  2. Add the Server view by clicking WindowShow ViewOther…​ and then ServerServers.
  3. Open the server menu by right clicking the Servers panel and select NewServer.
  4. Define the server by selecting JBoss Enterprise MiddlewareJBoss Enterprise Application Platform 6.1+ and clicking Next.
  5. Click JBoss EAP 6.4 Runtime and select Create new runtime (next page). Click Next.
  6. Set the home directory by clicking Browse. Navigate to and select the installation directory for Red Hat JBoss EAP 6.4 which has Red Hat JBoss BPM Suite installed.
  7. Provide a name for the server in the Name field, ensure that the configuration file is set, and click Finish.

8.6. Kie Navigator

Kie Navigator enables you to browse, change, and deploy the content of your Red Hat JBoss BPM Suite server. Thus, you can seemlessly integrate Red Hat JBoss Developer Studio with Red Hat JBoss BPM Suite.

Configuring Kie Navigator

  1. In Red Hat JBoss Developer Studio, click WindowShow ViewOther…​.
  2. Type Kie Navigator and select the Kie Navigator option.
  3. If you have no server with Red Hat JBoss BPM Suite configured in your Red Hat JBoss Developer Studio, you will be asked to configure a server first. See Section 8.5, “Configuring Red Hat JBoss BPM Suite Server” for more information.
  4. Right click your server name you want to use and select Properties.
  5. Enter username and pasword that has a kie role, for example kie-server.
  6. Enter the following:

    • KIE Application Name: business-central
    • HTTP Port: 8080
    • Git Port: 8001

      Note

      The values above are the default values. If you changed the default values of Git or Business Central ports, use your values.

  7. Check Use default Git Repository Path and click Apply.
  8. Start your server in the Servers tab and wait until the server has started.
  9. In the Kie Navigator tab, right click your server name and click Refresh. You will see the contents of the Red Hat JBoss BPM Suite git repository. Double click a project to import it into your Red Hat JBoss Developer Studio.
kienav

Kie Navigator Features

In the Kie Navigator tree, you can see four levels:

  • Server ( kienav server )
  • Organizational Unit ( kienav org )
  • Repository ( kienav repo )
  • Project ( kienav project )

Kie Navigator Server Level

Right clicking kienav server gives you the following options:

Refresh
Makes a REST call to update the entire tree.
Create Organization
Enables you to create a new Organizational Unit.
Properties
Displays the server properties.

Kie Navigator Organizational Unit Level

Right clicking kienav org gives you the following options:

Add Repository…
Enables you to add a repository that is not associated with another Organizational Unit.
Create Repository…
Enables you to create a repository.
Delete Organization…
Enables you to delete selected Organizational Unit.
Properties
Displays properties of selected Organziational Unit.

Kie Navigator Repository Level

Right clicking kienav repo gives you the following options:

Import Repository
Clones the Repository and makes it available in the Git Repository View. This menu action is available if the Repository has not already been cloned.
Create Project…
Enables you to create a project.
Remove Repository…
Enables you to remove selected repository.
Show in Git Repository View
Opens the Git Repositories View and highlights selected Repository.
Properties
Displays properties of selected repository.

Kie Navigator Project Level

Right clicking kienav project gives you the following options:

Import Project
Imports the project into your Red Hat JBoss Developer Studio.
Delete Project…
Enables you to deletes selected Project.
Properties
Displays project properties.

8.7. Importing Projects from Git Repository into Red Hat JBoss Developer Studio

Note

This is an additional feature not required for working with Red Hat JBoss Developer Studio.

You can configure Red Hat JBoss Developer Studio to connect to a central Git asset repository. The repository stores rules, models, functions, and processes.

You can either clone a remote Git repository or import a local Git repository.

Procedure: Cloning Remote Git Repository

  1. Start the Red Hat JBoss BPM Suite server by selecting the server from the Server tab and clicking the start icon.
  2. Start the Secure Shell server, if not running already, by using the following command. The command is specific to Linux and Mac environments. If sshd has already been started, this command fails. In that case, you may safely ignore this step.

    /sbin/service sshd start
  3. In Red Hat JBoss Developer Studio , click FileImport…​ and navigate to the Git folder. Open the Git folder to select Projects from Git and click Next.
  4. Select the repository source as Clone URI and click Next.
  5. Enter the details of the Git repository in the next window and click Next.

    Figure 8.2. Git Repository Details

    getting started guide 4912
  6. Select the branch you wish to import in the following window and click Next.
  7. To define the local storage for this project, enter (or select) a non-empty directory, make any configuration changes and click Next.
  8. Import the project as a general project in the following window and click Next. Name the project and click Finish.

Procedure: Importing Local Git Repository

  1. Start the Red Hat JBoss BPM Suite server by selecting the server from the Server tab and click the start icon.
  2. In Red Hat JBoss Developer Studio, click FileImport…​ and navigate to the Git folder. Open the Git folder to select Projects from Git and click Next.
  3. Select the repository source as Existing local repository and click Next.

    Figure 8.3. Git Repository Details

    getting started guide 4257
  4. Select the repository that is to be configured from the list of available repositories and click Next.
  5. In the dialog that opens, select the radio button Import as general project from the Wizard for project import group and click Next. Name the project and click Finish.

    Figure 8.4. Wizard for Project Import

    getting started guide 6110

8.8. Creating Drools Project

Procedure: Creating New Red Hat JBoss Developer Studio Project

  1. From the main menu, click FileNewProject.
  2. Click DroolsDrools Project and click Next.
  3. For now, choose the second option. Red Hat JBoss Developer Studio creates a project with a Red Hat JBoss BPM Suite example. Click Next.
  4. Enter a name for the project into the Project name: text box and click Finish.

To test the project:

  1. Navigate to the src/main/java directory and expand the com.sample package.
  2. Right click a Java class and select Run AsJava Application.

    The output will be displayed on the console tab.

8.9. Creating Red Hat JBoss BPM Suite Project

Procedure: Creating New Red Hat JBoss BPM Suite Project in Red Hat JBoss Developer Studio

  1. From the main menu, select FileNewProject.
  2. Select jBPMjBPM Project and click Next.
  3. For now, choose the second option. Red Hat JBoss Developer Studio creates a project with a Red Hat JBoss BPM Suite example. Click Next.
  4. Enter a name for the project into the Project name: text box and check the Also include a sample JUnit test for the process option.
  5. Click Finish.

To test the project:

  1. Navigate to the src/main/java directory and expand the com.sample package.
  2. Right click ProcessTest.java and select Run AsJUnit Test.

    The output will be displayed in the console tab.

Chapter 9. Business Resource Planner

Business Resource Planner is a lightweight, embeddable planning engine that optimizes planning problems. It helps Java™ developers solve planning problems efficiently. It combines optimization heuristics and metaheuristics with very efficient score calculations.

The planner helps to solve various use cases, for example:

  • Employee/Patient Rosters: the planner helps to create timetables for nurses and keeps track of patient bed management.
  • Educational Timetables: the planner helps to schedule lessons, courses, exams, and conference presentations.
  • Shop Schedules: the planner tracks car assembly lines, machine queue planning, and workforce task planning.
  • Cutting Stock: the planner minimizes waste by reducing the consumption of resources such as paper and steel.

9.1. Installing Business Resource Planner

  1. Open the DOWNLOADS section of the Red Hat Customer Portal.
  2. Click Red Hat JBoss BPM Suite and log in.
  3. From the Version drop-down menu, select version 6.4.
  4. Select Red Hat JBoss BPM Suite 6.4.0 Business Resource Planner and click Download.

9.2. Running Business Resource Planner Examples

  1. On the command line, change into the examples/ directory.
  2. In a Unix environment, execute:

    ./runExamples.sh

    In a Windows environment, execute:

    runExamples.bat
  3. Pick an example from the Examples GUI application that opens and run it in your favorite IDE.

Appendix A. Versioning information

Documentation last updated on: Monday, May 13, 2019.

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.