Chapter 2. Installation Options

Red Hat JBoss BPM Suite comes in two versions:

  • Executable JAR installer for installation on Red Hat JBoss Enterprise Application Platform (EAP) 6.4.

  • ZIP file install which itself comes in two versions:

    • jboss-bpmsuite-6.3.0.GA-deployable-eap6.x.zip: version adapted for deployment on Red Hat JBoss Enterprise Application Platform.
    • jboss-bpmsuite-6.3.0.GA-deployable-generic.zip: the deployable version with additional libraries adapted for deployment on Red Hat JBoss Web Server (EWS), Apache Tomcat 6, and Apache Tomcat 7.

Depending on your environment, you may choose the installation option best suited for your project needs.

Note

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

Important

From Red Hat JBoss BPM Suite 6.1 onwards, you must have Red Hat JBoss EAP 6.4 or better already installed before attempting to install Red Hat JBoss BPM Suite.

2.1. EAP 6 Bundle Installation

This section describes installing the Red Hat JBoss BPM Suite package deployable for Red Hat JBoss Enterprise Application Platform (EAP).

Note

The minimum supported version of Red Hat JBoss EAP for Red Hat JBoss BPM Suite installation is 6.4.

2.1.1. Downloading Red Hat JBoss EAP 6 Package

To download the deployable Red Hat JBoss BPM Suite package for JBoss Enterprise Application Platform, do the following:

  1. Go to the Red Hat Customer Portal and log in.
  2. Click DOWNLOADS at the top of the page.
  3. In the Product Downloads page that opens, click Red Hat JBoss BPM Suite.
  4. From the Version drop-down menu, select version 6.3.
  5. On the Software Downloads page that opens, navigate to the Red Hat JBoss BPM Suite 6.3.0 Deployable for EAP 6 row and click Download.

2.1.2. Installing Red Hat JBoss EAP 6 Package

Installation on Fresh Red Hat JBoss EAP Instance

To install the deployable package for the Red Hat JBoss EAP that has yet to be configured, do the following:

  1. Extract the ZIP package deployable for Red Hat JBoss EAP you downloaded from the Red Hat Customer Portal.

  2. Merge the extracted ZIP package deployable for JBoss EAP into the JBoss EAP SERVER_HOME directory.

    Warning

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

  3. In this process, multiple files in the Red Hat JBoss EAP SERVER_HOME directory will be overwritten and you must let the unzip process overwrite these files.
  4. Make sure that the SERVER_HOME/bin/product.conf file contains the string slot=bpms.

In Red Hat Enterprise Linux, you can use the following command to extract the Red Hat JBoss BPM Suite ZIP file and merge it into your server directory correctly in one step, if you execute this command in the directory where you have downloaded the ZIP file: 

unzip -u jboss-bpmsuite-VERSION_TYPE.zip -d SERVER_HOME_PARENT_DIRECTORY

Example 2.1. The unzip Command

unzip -u jboss-bpmsuite-6.3.0.GA-deployable-eap6.x.zip -d /home/john/myServers/

On server start-up, Red Hat JBoss BPM Suite will be deployed.

Installation on Existing Red Hat JBoss EAP Configuration
Warning

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

To install the deployable package for a previously configured Red Hat JBoss EAP, do the following:

  1. Extract the ZIP package deployable for Red Hat JBoss EAP you downloaded from the Red Hat Customer Portal.

  2. Unzip the downloaded ZIP archive; however, do not overwrite all of the files. Manually merge the following files into the SERVER_HOME directory.

    • jboss-eap-6.4/domain/configuration/* (Please be aware that Red Hat JBoss BMP Suite requires JMS, so JMS is added by default into all profiles in domain.xml provided by Red Hat JBoss BPM Suite distribution.)
    • jboss-eap-6.4/standalone/configuration/* (Please be aware that Red Hat JBoss BPM Suite requires JMS, so JMS is added by default into all profiles configuration files — especially into standalone.xml and standalone-ha.xml — provided by Red Hat JBoss BPM Suite distribution.)
    • jboss-eap-6.4/modules/layers.conf
    • jboss-eap-6.4/bin/product.conf
  3. Ensure the target Red Hat JBoss EAP does not include a deployment with a colliding name. Copy the folder jboss-eap-6.4/standalone/deployments into the EAP_HOME directory from the Red Hat JBoss BPM Suite distribution.
  4. Make sure no JBoss EAP module layer is already called Red Hat JBoss BPM Suite and copy the folder jboss-eap-6.4/modules/system/layers/bpms into the EAP 6.4 folder.

2.1.3. Defining Roles

Before starting the server and logging onto Business Central, you will 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, they can create, build and deploy projects and they can even use Red Hat JBoss Developer Studio to view processes. Only certain administrative functions like creating and cloning a new repository are hidden for the developer role.
  • analyst: An analyst role has access to all high-level features to model and execute their projects. However, Authoring → Administration access is unavailable to users with the analyst role. Certain lower-level features targeted towards developers, like the Deployment → Artifact 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: 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 is a viewer of 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.
Note

Enter the above mentioned roles during the user creation process. For further information about roles, see the Access Control section from Red Hat JBoss Administration and Configuration Guide. For further information about roles and task interactions, see the User Task section of Red Hat JBoss BPM Suite User Guide.

2.1.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. Go to the EAP bin directory.

  2. On a Unix system, run the following command: 

    ./add-user.sh

    On a Windows system, run: 

    ./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, you should 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 (see Section 2.1.3, “Defining Roles”).

    Note that Business Central users need to have at least the analyst role, while the Dashboard Builder users need to have the admin role assigned. Roles should be entered as a comma-separated list.

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