Standard JBoss configuration

<< Click to Display Table of Contents >>

Navigation:  Bizagi Engine > Bizagi system administration > Bizagi server configuration > Bizagi Engine JEE platform configuration > Configuring a JEE application server to work with Bizagi > JBoss configuration >

Standard JBoss configuration

Overview

When using Bizagi Engine in a JEE platform, your processes can be configured to run in different JEE Application servers, such JBoss. The configuration procedure for an Application Server to work with Bizagi may vary slightly according to each server's differences.

 

This section focuses on configuring JBoss to work with Bizagi, either in a Test or Production environment, or as a standalone instance (no load balancing).

 

 

JBoss_EAP_standalone

 

Note that in the Development environment (Bizagi Studio) no configuration steps are required because Bizagi JEE Edition installs a bundled JBoss Server which is automatically configured.

 

Further information about JBoss and its system requirements, refer to JBoss community official web page.

 

Prerequisites

To configure your JBoss Application Server in a Test or Production environment, the following are required:

Installed JAVA SE's JDK. It is strongly recommended to use JDK 7.

JAVA_HOME environment variable properly configured (the path must contains no spaces).

The configuration and deployment files delivered by Bizagi (BizAgi-ear-JBoss-dist.zip).

It is required that this BizAgi-ear-JBoss-dist.zip (provided when downloading Bizagi Engine JEE JBoss) matches the version you used in your development environment (i.e Bizagi Studio's version and JEE Plugin).

JBoss installed.

The supported version is EAP 6.4.

Further information about JBoss (i.e system requirements) and its download can be reviewed JBoss community web page (you may also choose to use the JBoss files as provided by the JEE Plugin in your development environment).

JBOSS_HOME environment variable, properly configured.

 

About JBoss

Installing JBoss (once its prerequisites are met) simply requires extracting the JBoss file (jboss-eap-6.4.0.zip) into a local folder on your server.

It is important that the names for this local folder and path do not contain spaces.

We’ll reference the local folder that you choose to extract JBoss into as <JBOSS_HOME> from this point on.

 

To learn more about the JBoss installation process, we recommend reading the guides published on the official JBoss web site.

Before using JBoss, let’s take a quick look at some basic commands to start or stop the service.

 

Starting the Server

To start JBoss Application Server, locate the <JBOSS_HOME>/bin folder and run the standalone executable file.

 

 

In a Unix-like OS such as Linux, run the standalone.sh file from a command prompt with the following parameters:

standalone.sh  -b 0.0.0.0

 

In a Windows OS, run the standalone.bat file from a command prompt with the following parameters:

standalone.bat  -b 0.0.0.0

 

ConsolaJBoss

 

 

You may check that JBoss has started successfully and is running by opening the following URL in a browser:

http://localhost:8080/

 

The following screen should load:

 

JBossStarted

 

 

Notice that 8080 corresponds to the port number on which your JBoss service was set up to respond to HTTP requests.

 

Stopping the Server

To stop JBoss Application Server, locate the <JBOSS_HOME>/bin folder and run the jboss-cli executable file.

 

 

In a Unix-like OS such as Linux:

Run jboss-cli.sh from a command prompt with the following parameters:

jboss-cli.sh  --connect command=:shutdown

 

In a Windows OS:

Run the jboss-cli.bat in a command prompt with the following parameters:

jboss-cli.bat  --connect command=:shutdown

 

 

What you need to do

To configure JBoss EAP 6.4 to work with Bizagi, the following steps must be performed:

 

1. Extract module files used by Bizagi into JBoss.

2. Install the orig file.

3. Set environment variables.

4. Create a JBoss Administrator User

5. Configure Authentication

 

After these steps, your JBoss installation will be configured for Bizagi processes and ready to be deployed into a JEE application (Work Portal).

 

Procedure

The following steps describe in detail how to configure and modify default JBoss installation settings so that the service will work with Bizagi.

 

note_pin

Always use the names and information precisely as shown below and keep in mind they are case-sensitive.

Bear in mind that Bizagi Studio automatically install a JBoss server to run JEE projects in development. Therefore, some of the following files might be already decompressed and configured for development environment.

 

1. Extract module files used by Bizagi into JBoss

In this step, some module files used by Bizagi need to be included in JBoss. These module files are not included by default in a clean JBoss EAP 6.2 installation.

 

1.1 Extracting BizAgi-ear-JBoss-dist.zip

Extract BizAgi-ear-JBoss-dist.zip into a local folder on your server.

 

It is important that the names for this local folder and path does not contain spaces.

 

We’ll reference the local folder that you choose to extract these files into as <BIZAGI_JEE_HOME> from now on. In it, you’ll notice a folder called BizagiBPMJEE:

 

Window_1

 

In this example, the path to <BIZAGI_JEE_HOME> is C:\BizagiJEE\. Your extracted zip should contain the following folder structure and files:

 

Window_2

 

 

1.2 Extracting BizagiJbossModules.zip

Locate BizagiJbossModules.zip in the BizagiBPMJEE/configuration folder in your <BIZAGI_JEE_HOME> folder.

 

Window_4

 

Select Extract All and then choose your <JBOSS_HOME>/modules/system/layers/base/ folder as the target folder into which files will be extracted.

 

ExtractModules

 

You will see that in the <JBOSS_HOME>/modules/system/layer/base/ folder, additional files will be added to the "com" and "org" folders of the original JBoss installation.

 

ComAndOrgFiles

 

 

The following image shows details of the new files and folders extracted into the JBoss modules. In the left panel (1), you can see the default folders and files:

 

CompareRoot

 

 

2. Install the orig file

The orig file is delivered by Bizagi in order to configure the following modules in the JBoss server.

Authentication

Data access and the corresponding drivers

Data source for your project

Messaging service (JMS)

JTA configuration

HTTP Compression

SAP connection (when is required).

 

Copy the file standalone-bizagi.orig delivered by Bizagi in the configuration and deployment files onto <JBOSS_HOME>/standalone/configuration folder.

 

3.Set environment variables

In a clean installation, JBoss will start up its service with some variables set up by default.

However, when doing this for Bizagi processes in a production environment, it is required to define certain environment variables for instance to include JiNet for JBoss service startup, or to tune up the assigned memory used by JBoss for its service.

 

This is done by editing the JBoss executable's parameters file.

 

StandaloneConfBatPath

 

 

In a Unix-like OS such as Linux, this file is located at

<JBOSS_HOME>/bin/standalone.conf.

 

In a Windows OS, this file is located at

<JBOSS_HOME>/bin/standalone.conf.bat.

 

Details on how to edit this file for your operating system are specified below.

 

For a Unix-like OS such as Linux:

To edit the <JBOSS_HOME>/bin/standalone.conf file for starting up JBoss by including the following environment variables:

DiNET_HOME: Should have the path to the JiNET home (e.g <BIZAGI_JEE_HOME>/BizagiBPMJEE/JiNET).

DAPP_SERV: Should have the JBOSS value.

Djava.net.preferIPv4Stack: Should be set to true

Dbizagi.scheduler.external.enabled: Should be set to false for a standalone JBoss configuration.

Duser.language: Should set your default language (i.e, en)

Duser.country: Should set your default culture setting for the language (i.e, us).

Dfile.encoding: Should be set to UTF-8

Dbizagi-config: Should have the path to the bizagi-config folder where the bizagi.extended.properties file is located.

 

You may do this in the last part of the line, after the line having "Reduce the RMI GCs..." so that you include:

 

You may do this at the end of the file:

# Bizagi Configuration

JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv4Stack=true -DiNET_HOME=<BIZAGI_JEE_HOME>/BizagiBPMJEE/JiNET –DAPP_SERV=JBOSS -Duser.language=en -Duser.country=us -Dfile.encoding=UTF-8 -Dbizagi-config=<BIZAGI_JEE_HOME>/BizagiBPMJEE/bizagi-config"

JAVA_OPTS="$JAVA_OPTS -Xms1024m -Xmx1024m -XX:MaxPermSize=1024m"

 

Remember to replace <BIZAGI_JEE_HOME> with the corresponding home path of your installed Bizagi JBoss distribution files.

Also, note that you must use the slash character (/) instead of backslashes (\) for the path.

 

note_pin

You can see that in the second line, the minimum required memory for startup is 1G for the first and second parameter, and 512M for the other parameter.

It is recommended to increase the assigned memory as required, but must take into consideration your server's hardware capabilities.

 

At the end, the <JBOSS_HOME>/bin/standalone.conf file should look like:

 

StandaloneLinuxv3

 

 

For a Windows OS:

To edit the <JBOSS_HOME>/bin/standalone.conf.bat file in Windows OS for starting up JBoss, follow these steps:

 

1. Edit this file by modifying the set memory for startup after the line JVM memory allocation (approximately in line #49).

set "JAVA_OPTS=-Xms1024M -Xmx1024M -XX:MaxPermSize=1024M"

 

note_pin

You can see that the minimum required memory for startup is 1G for the first and second parameter, and 512M for the other parameter.

It is recommended to increase the assigned memory as required, but must take into consideration your server's hardware capabilities.

 

2. Edit this file by including the following environment variables:

DiNET_HOME: Should have the path to the JiNET home (e.g <BIZAGI_JEE_HOME>/BizagiBPMJEE/JiNET).

DAPP_SERV: Should have the JBOSS value.

Djava.net.preferIPv4Stack: Should be set to true

Dbizagi.scheduler.external.enabled: Should be set to false for a standalone JBoss configuration.

Duser.language: Should set your default language (i.e, en)

Duser.country: Should set your default culture setting for the language (i.e, us).

Dfile.encoding: Should be set to UTF-8

Dbizagi-config: Should have the path to the bizagi-config folder where the bizagi.extended.properties file is located.

 

You may do this in the last part of the line, after the line having "Reduce the RMI GCs..." so that you include:

-Djava.net.preferIPv4Stack=true -DiNET_HOME=<BIZAGI_JEE_HOME>/BizagiBPMJEE/JiNET –DAPP_SERV=JBOSS -Duser.language=en -Duser.country=us -Dfile.encoding=UTF-8 -Dbizagi-config=<BIZAGI_JEE_HOME>/BizagiBPMJEE/bizagi-config

 

Remember you must replace <BIZAGI_JEE_HOME> with the corresponding home path of your installed Bizagi JBoss distribution files.

Also. note you must use the slash character (/) instead of backslashes (\) for the path.

 

 

At the end, the <JBOSS_HOME>/bin/standalone.conf.bat file should look like this:

 

Variables_1_v3

 

4. Create a JBoss Administrator User

JBoss needs a user to manage the console and launch Bizagi. The creation of this user is mandatory and the procedure to create it, is as follows:

 

4.1 Locate the <JBOSS_HOME>/bin folder and run the add-user executable file.

 

In a Unix-like OS such as Linux, run in a command prompt:

add-user.sh

 

In a Windows OS, run in a command prompt:

add-user.bat

 

4.2 Choose the type of user to be added. As we are creating an Administrator user, we should select Management User. To do this, type 'a'.

 

AddUser_1

 

4.3 Create the credentials for the user.

Make sure you specify bizagi as the name of the user, followed by a password with at least one number and one character.

It is required that you at least create the administrator user with the following information:

Username: bizagi

Password: password1!

 

AddUser_2

 

note_pin

The user cannot be changed; these credentials must be used.

The exclamation sign in password must be included. Use only lowercase for the username and password.

 

In the next step, press Enter key when you are asked for the groups to which the user will be added.

Type 'y' for the next two options to finish the process

 

AddUser_3

 

5. Configure Authentication

Authentication is handled from Bizagi Engine. Therefore, it does not depend on the configuration of the application server or security modules. According to the Authentication type, it will be necessary to take into account the following aspects:

 

Bizagi and LDAP Authentication

Verify a user's session using the .BIZAUTH cookie which contains encrypted information. A 128-bit key is required in order to encrypt such information, such key must be configured as follows:

 

1.Create a text files with the 128-bit (16 characters) encryption key with restricted access (Only the user running the server should have access).

2.In the bizagi-extended.properties file (located in <CONFIGURATION_INPUTS>\bizagi-config\bizagi-extended.properties), include the cookie_encryptionkey_file key with the full path of the file created above.

 

note_pin

By default, the installation includes the cookie_crypt.key file that contains a key for encryption. In case the key is not configured in the bizagi-extended.properties file, the engine will attempt to load the cookie_cript.key file. It is recommended to configure your own encryption file to avoid identity spoofing.

 

What is next?

After finishing these steps, your JBoss installation is configured to work with Bizagi Processes!

You may now start up JBoss EAP 6.4 which will launch Bizagi and your Bizagi Processes in an application.

 

For more information about this option, refer to deploying the application into JBoss Application Server.