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 BRMS.
4. From the Version drop-down menu, select version 6.4.
5. Select Red Hat JBoss BRMS 6.4.0 Deployable for EAP 6 and then click Download.

1. Set up location and users.

   Navigate to the folder where you downloaded the installer file in a command prompt and execute the following command:

   java -jar jboss-brms-VERSION-installer.jar

   Note

   When running the installer on Windows, you may be prompted to provide administrator credentials during the installation. To prevent this, add the izpack.mode=privileged option to the installation command:

   java -Dizpack.mode=privileged -jar jboss-brms-VERSION-installer.jar

   Furthermore, when running the installer with a 32-bit Java Virtual Machine, you can encounter memory limitations. To solve the issue, run

   java -XX:MaxHeapSize=4g -jar jboss-brms-VERSION-installer.jar

2. The graphical installer will execute and display a splash screen and a license agreement page. Read and accept the license to proceed.
3. In the next screen, provide the parent location of an existing Red Hat JBoss EAP where you want to install Red Hat JBoss BRMS.

4. In the next two screens, create two users: the first one for the management console of the Red Hat JBoss EAP (ManagementRealm) and the second one for managing Red Hat JBoss BRMS itself (ApplicationRealm).

   Creation of the first user for the management console of Red Hat JBoss EAP is optional and you may skip it if it is not required.

   Make a note of these user names and passwords as you will need them to access the Red Hat JBoss EAP server (if you do decide to create it) and the Red Hat JBoss BRMS application respectively.

   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.

   Note

   The passwords that you create must have at least 8 characters and must contain at least one number and one non-alphanumeric character (not including the character &).

   Note

   The application role assigned to the second user that you create is the admin role. This is the only role that can be assigned to this newly created user. You can create more users with narrow roles afterwards by using the command line.

5. Set up security environment.

   Next, you will set up the security environment of your new Red Hat JBoss BRMS install. Decide to enable or disable the Java Security Manager in this step by clicking the check box. The Java Security Manager makes your system more secure but may downgrade performance. You need to make a decision based on your environment.

6. Choose whether you want to set up pure IPv6 configuration on the server that the installation is taking place. This will enable you to set up runtime IPv6 specific configurations later.

7. Configure runtime environment.

   This step provides the option of using a default configuration or specifying an advanced configuration.

   1. Default Configuration

      Choose Perform default configuration for the runtime environment in the next step and click Next to review the installation details. If you are happy with the details, click Next to start the actual installation or click Previous to go back and make changes.

   2. Advanced Configuration

      Choose to enable advanced configuration options. Select Perform advanced configuration and choose the advanced configuration options you want to enable for your environment using the check boxes.

   1. Configure Password Vault

      Vault passwords are used to obfuscate passwords in the various server descriptors using a Java secret key generated during the installation process, or manually using the keytool. This prevents passwords from being stored as plain text in the descriptors. The Iteration count and Salt are both parameters to the encryption process.

      For more information about vault passwords, see the Red Hat JBoss EAP Security Guide.

   2. SSL Security

      The SSL Security screen enables you to add the <ssl> and <truststore> elements to the ManagementRealm security realm using the provided keystore.

      • The <ssl> element causes the server to present the certificate within the keystore as its identity, which enables the user to apply their official certificate.
      • The <truststore> element enables Client-Cert authentication. This means that, if a remote client attempts to connect to any resource managed by the ManagementRealm, the client can present a certificate, and if an entry in the truststore matches, will be authenticated without needing to provide a user name/password.

      The end result is an encrypted connection that is secure between the client and the server for the ManagementRealm.

   3. LDAP Connection

      This step in the installer enables the user to define an LDAP server, which in turn defines users which should be allowed to authenticate with the ManagementRealm. This replaces the default configuration.

      The LDAP Connection screen enables users to define how to connect to the LDAP server.

      • Distinguished Name (DN): the user that can connect to the LDAP server. Typically the DN will uniquely define a special user for this purpose.

      LDAP Security (Management Console)

      The Management Console LDAP Configuration screen enables you to set up a security realm. This defines the <security-realm> element to be added to the descriptors, and utilizes the connection defined previously.

      • Base DN: Will typically define a 'base search' or 'root context' to begin searching for users.
      • Filter Type: Tells Red Hat JBoss EAP how to find the LDAP attribute that defines a user; it is can be a simple attribute, but can also be a complex LDAP filter.
      • Username filter: The LDAP attribute which holds the user name values. A user name entered in this field is used for search queries as a value of the uid attribute. If a user chooses LDAP Syntax Query as a filter type, this query must be specified in this field.
      • Recursive directory search: If enabled, Red Hat JBoss EAP will traverse the LDAP tree recursively, starting at Base DN. Otherwise, the search will be limited to Base DN.

      LDAP Security (Business Central)

      Most of the values on the Business Central LDAP Configuration screen are similar to the Base DN values. Contexts are used to search for roles, which enables it to perform authorization in addition to authentication. Otherwise, the context fields are analogous to the Base DN from the previous, and attribute fields are analogous to user name attribute. The filters enable fine grained control over which values of the given attribute will be accepted.

      Input values from the Business Central LDAP Configuration page are used to configure a new security domain, which make use of the LdapExtended login module. This security domain is set as default for Business Central web application. For more information about security domains and login modules, see the Red Hat JBoss EAP Security Guide.

   4. Security Domain and JSSE Configuration

      The Security Domain screen enables you to configure all of the elements of the <security-domain> security subsystem for managing security information, including JSSE configuration. For more detailed information about configuring security domains, see the Red Hat JBoss EAP Security Guide.

   5. Configure Clustering

      Selecting this option installs Red Hat JBoss BRMS ready for clustered operation. For more information, see Section 6.5, “Clustering on Red Hat JBoss EAP”.

   6. Business Central Datasource Setup

      After cluster configuration, the next screen enables you to configure the Business Central data source.

   7. Configure Business Resource Planner

      The Configure Business Resource Planner screen enables you to configure Business Resource Planner.

   8. Configure Optaplanner Execution Server

      Optaplanner is enabled by default. To disable Optaplanner, select Configure Optaplanner Execution Server then select Disable Optaplanner Execution Server on the Configure Optaplanner screen.

   9. Configure KIE Server Management

      Select Enable KIE server management if you want Business Central to manage the Realtime Decision Server.

      Managing the Realtime Decision Server using the Business Central requires a password vault to be configured. If you did not configure one, a vault with default values is created See Configuring Password Vault for further information. The password to the keystore is the same as for the user brmsAdmin.

8. The installer will go through the steps to install Red Hat JBoss BRMS and will perform post installation configuration steps when you click Next. The installer will also start the Red Hat JBoss BRMS server and connect to it to validate the installation. Click Next to get to the last screen where you can generate the installation script and properties file. Click Done to quit the installer.

1. Navigate to the folder where you downloaded the installer file in a command prompt and execute the following command.

   java -jar jboss-brms-VERSION-installer.jar -console

2. The command-line interactive process will start and display the End-User license agreement. You will be prompted to select an option at the end of this license:

   press 1 to continue, 2 to quit, 3 to redisplay.

3. Enter 1 to begin the installation and type in the parent directory of an existing Red Hat JBoss EAP installation.

   The location below must specify the JBOSS_HOME of an existing EAP installation.
   
   [/home/user/BRMS-VERSION/jboss-eap-6.4]

   The installer will verify the location of the Red Hat JBoss EAP installation at the provided location.

   press 1 to continue, 2 to quit, 3 to redisplay.

   Enter 1 to confirm and continue.

4. Create an administrative user.

   Create an administrative user
   This user will be added to the host container's management realm for administrative purposes. It can be used to access the management console, the management CLI or other applications secured in this realm.
   
   The password must be at least eight characters long, with one alphabetic character, one digit, and one non-alphanumeric character not including &.
   
   Create an administrative user.
   0  [x] Skip new administrative user creation.
   1  [ ] Create a new administrative user.

5. Create and confirm a password for the user of the EAP management console:

   Admin password: []
   **********
   Confirm admin password: [**********]
   **********

6. After the passwords have been entered, choose an option from the prompt below:

   press 1 to continue, 2 to quit, 3 to redisplay.

7. Enter 1 and create a Red Hat JBoss BRMS user:

   Create a Business Rules Management System Admin User
   Create a BRMS admin user. The user will be added to the ApplicationRealm, and can be used to access the Business Central Console. The User will be assigned the 'admin' application role. The BRMS username cannot be any of the following: 'admin', 'analyst', 'user', 'manager' or 'developer'.
   
   The password must be at least eight characters long, with one alphabetic character, one digit, and one non-alphanumeric character not including &.
   
   BRMS username: [brmsAdmin]

   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.

8. Create and confirm a password for the Red Hat JBoss BRMS user:

   BRMS password: []
   **********
   Confirm BRMS password: [**********]
   **********

9. After the passwords have been entered, choose an option from the prompt below:

   press 1 to continue, 2 to quit, 3 to redisplay.

10. Configure the Java Security Manager.

    A Java security manager offers JVM level security beyond what is provided by the application container. It enforces access rules at the JVM runtime based on one or more security policies.
    
    This installer will place two security policies in the installation directory with the filenames 'security.policy' and 'kie.policy' regardless of choice. Those policies will be enabled at runtime if the option below is selected.
    
    Please note that a security manager imposes a significant performance overhead when enabled. It is suggested the included policies be applied in production if user requirements call for a stronger measure than what is already provided by the application container's authentication and authorization mechanism.
    
    Please see the JBoss Business Rules Management System administrative documentation for further details and consideration.
    [ ] Enable the Java security manager
    Input 1 to select, 0 to deselect:

11. After the Java Security Manager choice, choose an option from the prompt below:

    press 1 to continue, 2 to quit, 3 to redisplay.

12. Next, select whether to enable the IPv6 configuration.

    IPv6 configuration
    
    If this computer is using a pure IPv6 configuration, please check the box below. A pure IPv6 setup requires additional configuration at runtime to ensure the proper bindings of the management and http interfaces.
    [ ] Enable pure IPv6 configuration
    Input 1 to select, 0 to deselect:

13. After the IPv6 configuration choice, choose an option from the prompt below:

    press 1 to continue, 2 to quit, 3 to redisplay.

14. Configure the runtime environment by either choosing the default configuration or inputting advanced options.

    Configure runtime environment
    Red Hat JBoss Business Rules Management System can be further customized at this time.
    0  [x] Perform default configuration
    1  [ ] Perform advanced configuration
    Input Selection:

    If you select 1, Perform advanced configuration, complete the following configurations:

    1.   [ ] Install password vault
       Input 1 to select, 0 to deselect:

    2.   [ ] Enable SSL security
       Input 1 to select, 0 to deselect:

    3.   [ ] Secure EAP Management Console with LDAP
       Input 1 to select, 0 to deselect:

    4.   [ ] Secure Business Central and Dashbuilder with LDAP
       Input 1 to select, 0 to deselect:

    5.   [ ] Add a security-domain
       Input 1 to select, 0 to deselect:

    6.   [ ] Install Business-Central Datasource
       Input 1 to select, 0 to deselect:

    7.   [ ] Configure Optaplanner Execution Server
       Input 1 to select, 0 to deselect:

    8.   [ ] Configure KIE Server management
       Input 1 to select, 0 to deselect:

15. Next, choose an option from the prompt below:

    press 1 to continue, 2 to quit, 3 to redisplay.

16. The .jar file begins the unpacking and configuration.

17. After a successful installation, the command line will ask you if you would like to generate an automatic installation script and properties file.

    Installation has completed successfully.
    Application installed on /home/user/BRMS-VERSION/jboss-eap-6.4
    Would you like to generate an automatic installation script and properties file?
    (y/n) [n]:

18. If you select y, provide a path for the automatic installation script:

    Select path for the automatic installation script: [/home/user/BRMS-VERSION/jboss-eap-6.4/AUTO_SCRIPT_FILENAME]

    This generated script will enable the user to run the installer in the following way for future installations:

    java -jar jboss-brms-VERSION-installer.jar AUTO_SCRIPT_FILENAME

    Note

    Running the installer in this way will result in an installation identical to the installation from which the auto script was generated. Note that sensitive values, such as passwords, will need to be provided from an external file or provided at auto installation time. The optional argument below enables the user to provide these values automatically:

    -variablefile VARIABLE_FILENAME

    Sensitive values can also be provided using the following argument:

    -variables key1=value1,key2=value2

19. The command-line will provide the following message upon a successful auto script creation and/or console installation:

    XML written successfully.
    [ Console installation done ]
    [BRMS_Installer]$

20. Start Red Hat JBoss EAP by running standalone.sh in the jboss-eap-6.4/bin directory.

    ./standalone.sh

21. Navigate to http://localhost:8080/business-central in a web browser.
22. Log in with the correct user name/password as given to the Red Hat JBoss BRMS user in the Create and confirm a password for the Red Hat JBoss BRMS user step.

1. Download the Red Hat JBoss Enterprise Application Platform 6.4.0 or Red Hat JBoss Enterprise Application Platform 7.0 ZIP file from the Customer Portal.
2. Extract the ZIP file. This location is your EAP_HOME.

3. Patch the Red Hat JBoss EAP to the supported version for your Red Hat JBoss BRMS version.

   • See Red Hat JBoss BPM Suite 6 Supported Configurations to verify which patch is applicable for your Red Hat JBoss BRMS version.
   • See Patching a Zip/Installer Installation from the Red Hat JBoss EAP Installation Guide for further information about applying patches.
4. Download the Red Hat JBoss BRMS 6.4.0 Deployable for EAP 6 ZIP file.

5. Extract the file and copy jboss-eap-6.4/bin/* into EAP_HOME/bin/*. When asked, merge the directories.

   1. If you want to run Red Hat JBoss BRMS in the standalone mode:

      • Copy jboss-eap-6.4/standalone/configuration/* into EAP_HOME/standalone/configuration/.

      • Copy jboss-eap-6.4/standalone/deployments/* into EAP_HOME/standalone/deployments/.

        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 BRMS deployments.

   2. If you want to run Red Hat JBoss BRMS in the domain mode:

      • Copy jboss-eap-6.4/domain/configuration/* into EAP_HOME/domain/configuration/.

        Warning

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

6. Add an application user:

   ./EAP_HOME/bin/add-user.sh -a --user bpmsAdmin --password password@1 --role kie-server,admin,rest-all,analyst

1. Change into EAP_HOME/bin.

2. Execute:

   In a Unix environment:

   ./standalone.sh

   In a Windows environment:

   standalone.bat

1. Package the application directories into archives:

   1. Extract the following files from the Red Hat JBoss BRMS 6.4.0 Deployable for EAP 6 ZIP file:

      • jboss-eap-6.4/standalone/deployments/business-central.war
      • jboss-eap-6.4/standalone/deployments/kie-server.war
      • jboss-eap-6.4/standalone/deployments/dashbuilder.war

   2. Create a ZIP file with the content of the business-central.war, kie-server.war, and kie-server.war directories, for example:

      1. Change into the directory:

          cd business-central.war

      2. Execute zip -r business-central.war . to create a ZIP file of the content of the business-central.war directory.

      3. Repeat this procedure for all the web applications you want to deploy.

         This ensures that business-central.war, kie-server.war, and dashbuilder.war are archives, not directories.

2. Deploy the archives:

   1. Add a management user:

      ./EAP_HOME/bin/add-user.sh -b --user mgmtAdmin --password password@1 --role admin

   2. Execute ./EAP_HOME/bin/domain.sh.
   3. Log into http://localhost:9990/ using your management user.
   4. Click Deployments → Content Repository → Add.
   5. Select and upload the web archive from the file system.

   6. Select the deployment and click Assign.

      Note

      If you want to deploy multiple Red Hat JBoss BRMS nodes on a single machine, set ports and other properties before assigning the deployment to a server. See the section called “Red Hat JBoss BRMS Settings for Red Hat JBoss EAP” for more information.

   7. Select the server group.

Procedure: Installing Generic Deployable Package

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, choose Red Hat JBoss BRMS.
4. From the Version drop-down menu, select version 6.4.

5. Select Red Hat JBoss BRMS 6.4 Deployable for All Supported Containers package and click Download.

   Also select and download the Red Hat JBoss BRMS Core Engine files (jboss-brms-VERSION-engine.zip).

6. Extract business-central.war and kie-server.war from the generic deployable archive and copy to tomcat7/webapps/ folder.
7. Remove the .war extensions from the business-central.war and kie-server.war folders.
8. Move the kie-tomcat-integration-VERSION.jar file from the Red Hat JBoss BRMS Core Engine distribution to tomcat7/lib.

9. Define users and roles in tomcat7/conf/tomcat-users.xml as shown below.

   Important

   Make sure that the selected user name does not conflict with any known title of a role or a group. See Section 2.8, “Defining Roles” for a list of defined roles.

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

   <role rolename="admin"/>
   <role rolename="analyst"/>
   <user username="user" password="password" roles="admin,analyst"/>

10. Install the transaction manager.

    Warning

    Please note that the following section describes the setup of a transaction manager, Bitronix, that is not officially supported by Red Hat.

    Copy the following transaction manager JAR libraries from the lib folder to $TOMCAT_DIR/lib/ directory. These JARs are available in jboss-brms-VERSION-deployable-generic.zip and jboss-brms-VERSION-engine.zip.

    • btm-VERSION.jar
    • btm-tomcat55-lifecycle-VERSION.jar
    • h2-VERSION.jar
    • jta-VERSION.jar
    • slf4j-api-VERSION.jar
    • slf4j-jdk14-VERSION.jar

    Additionally, download the following library and copy it into the $TOMCAT_DIR/lib/ folder: javax.security.jacc-api.jar.

    Add Valve configuration into TOMCAT_HOME/conf/server.xml inside the <host> element as last Valve definition:

    <Valve className="org.kie.integration.tomcat.JACCValve" />

11. Create the transaction manager configuration files in $TOMCAT_DIR/conf/:

    • btm-config.properties

      bitronix.tm.serverId=tomcat-btm-node0
      bitronix.tm.journal.disk.logPart1Filename=${btm.root}/work/btm1.tlog
      bitronix.tm.journal.disk.logPart2Filename=${btm.root}/work/btm2.tlog
      bitronix.tm.resource.configuration=${btm.root}/conf/resources.properties

    • resources.properties (the resource.ds1.uniqueName defines the data source name used in Tomcat resource definition later — make a note of this value).

      Example 2.1. H2 Data Source Definition

      resource.ds1.className=bitronix.tm.resource.jdbc.lrc.LrcXADataSource
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=10
      resource.ds1.maxPoolSize=20
      resource.ds1.driverProperties.driverClassName=org.h2.Driver
      resource.ds1.driverProperties.url=jdbc:h2:file:~/jbpm
      resource.ds1.driverProperties.user=sa
      resource.ds1.driverProperties.password=
      resource.ds1.allowLocalTransactions=true

      Example 2.2. MySQL 5.5 Data Source Definition

      resource.ds1.className=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:mysql://localhost:3306/sampledb
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

      Example 2.3. DB2 Type 4 Data Source Definition

      resource.ds1.className=com.ibm.db2.jcc.DB2Driver
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:db2://localhost:50000/sampledb
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

      Example 2.4. Oracle Data Source Definition

      resource.ds1.className=oracle.jdbc.xa.client.OracleXADataSource
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:oracle:thin:@//localhost:1521/bpms
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

      Example 2.5. Microsoft SQL Server Data Source Definition

      resource.ds1.className=com.microsoft.sqlserver.jdbc.SQLServerDriver
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:sqlserver://localhost:1433;databaseName=bpms;
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

12. If you are using a data source other than the default provided by the underlying H2 database, you will need to set up persistence. If you are using the default H2 database, then you can ignore the rest of the steps in this procedure.

    In this procedure, you configure a data source with the JNDI name jdbc/myDatasource as defined in uniqueName=jdbc/jbpm in the Bitronix resources.properties file earlier (for the MySQL option).

    1. In business-central/META-INF/context.xml, replace the data source JNDI name in the <Resource> element. The uniqueName attribute refers to the resource.ds1.uniqueName property set in resources.properties:

       <Resource name="jdbc/myDatasource" uniqueName="jdbc/jbpm" auth="Container" removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource"/>

    2. In business-central/WEB-INF/web.xml, replace the data source JNDI name in the <res-ref-name> element with your data source name:

       <resource-ref>
         <description>Console DS</description>
         <res-ref-name>jdbc/myDatasource</res-ref-name>
         <res-type>javax.sql.DataSource</res-type>
         <res-auth>Container</res-auth>
       </resource-ref>

    3. Change business-central/WEB-INF/classes/META-INF/persistence.xml.

       In this file, change the name of the Hibernate dialect used for your database, if using a different database other than H2. The code below demonstrates the original database information for persistence.xml:

       <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>

       This information can be updated in the following manner (as demonstrated with MySQL database below):

       <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>

       Note

       The dialect for DB2 is org.hibernate.dialect.DB2Dialect, for DB2 on AS/400 is org.hibernate.dialect.DB2400Dialect, for Oracle is org.hibernate.dialect.Oracle10gDialect, and for Microsoft SQL Server is org.hibernate.dialect.SQLServerDialect.

    4. Change business-central/WEB-INF/classes/META-INF/persistence.xml file so that Red Hat JBoss BPM Suite process engine can use the new database.

       The code below demonstrates the original data source information for persistence.xml:

       <jta-data-source>java:comp/env/jdbc/jbpm</jta-data-source>

       Change this value to the data source defined earlier:

       <jta-data-source>java:comp/env/jdbc/myDatasource</jta-data-source>

13. Set up the transaction manager listener in $TOMCAT_DIR/conf/server.xml to start and stop Bitronix on container startup and shutdown.

    Add the following element as the last <Listener> element into the <Server> element:

    <Listener className="bitronix.tm.integration.tomcat55.BTMLifecycleListener" />

14. Define the btm.root system property and location where Bitronix configuration file is placed in:

    In the $TOMCAT_DIR/bin/, create a readable setenv.sh file with the following content:

    CATALINA_OPTS="-Xmx512M -XX:MaxPermSize=512m -Djava.security.auth.login.config=$CATALINA_HOME/webapps/business-central/WEB-INF/classes/login.config -Dbtm.root=$CATALINA_HOME -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties -Dorg.jbpm.designer.perspective=RuleFlow -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry -Dorg.jboss.logging.provider=jdk -Dorg.jbpm.server.ext.disabled=true -Dorg.jbpm.ui.server.ext.disabled=true"

    The property org.jbpm.designer.perspective is set to RuleFlow to allow the default perspective for the designer to be RuleFlow rather than Full. Grant the file execute permissions if applicable.

    Note

    The -XX:MaxPermSize=512m JVM property is valid only for JDK 6 and 7. It is not valid for JDK 8+.

    Important

    On Microsoft Windows systems, replace the $CATALINA_HOME value in the content of the file with the equivalent environment variable name, or use the absolute path and add the values in setenv.bat file as shown here in the following example:

    set "CATALINA_OPTS=-Xmx512m -XX:MaxPermSize=512m -Djava.security.auth.login.config=C:\apache-tomcat\webapps\business-central\WEB-INF\classes\login.config -Dbtm.root=C:\apache-tomcat -Dbitronix.tm.configuration=C:\apache-tomcat\conf\btm-config.properties -Dorg.jbpm.designer.perspective=RuleFlow -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry -Dorg.jbpm.server.ext.disabled=true -Dorg.jbpm.ui.server.ext.disabled=true"

15. Install the driver to your database — copy the JAR file with the relevant database driver to $TOMCAT_DIR/lib/.

    Driver to Embedded H2 Database

    If using the embedded H2 database, the driver is available in business-central/WEB-INF/lib/.

16. Start JBoss Web Server by running startup.sh in the tomcat7/bin directory.

    ./startup.sh

    Wait a few minutes and check the server log ($TOMCAT_DIR/tomcat7/logs) for any errors. If there are no errors, proceed to the next step.

17. Navigate to http://localhost:8080/business-central in a web browser.
18. Login with the user name/password defined in the tomcat-users.xml file.

1. Copy the JAR file with the relevant database driver to $TOMCAT_DIR/lib/. If you are using an H2 database, this step has already been done during the Business Central installation.

2. Add the data source into the resources.properties file. Note that the actual values may differ, based on the underlying database.

   resource.ds2.className=bitronix.tm.resource.jdbc.lrc.LrcXADataSource
   resource.ds2.uniqueName=jdbc/kieserver
   resource.ds2.minPoolSize=10
   resource.ds2.maxPoolSize=20
   resource.ds2.driverProperties.driverClassName=org.h2.Driver
   resource.ds2.driverProperties.url=jdbc:h2:file:~/bpm630tomcat7kieserver
   resource.ds2.driverProperties.user=sa
   resource.ds2.driverProperties.password=
   resource.ds2.allowLocalTransactions=true

3. Register a new resource in the kie-server/META-INF/context.xml:

   <Resource name="jdbc/kieserver"
             uniqueName="jdbc/kieserver"
             auth="Container"
             removeAbandoned="true"
             factory="bitronix.tm.resource.ResourceObjectFactory"
             type="javax.sql.DataSource" />

4. Update the $TOMCAT_DIR/bin/setenv.sh file. Add the following data source-related properties for kie-server:

   -Dorg.kie.server.persistence.ds=java:comp/env/jdbc/kieserver
   -Dorg.kie.server.persistence.tm=org.hibernate.service.jta.platform.internal.BitronixJtaPlatform

Procedure: Creating New Users

1. Go to the Red Hat JBoss 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.8, “Defining Roles”).

   Note that Business Central users need to have the analyst or 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.

1. Prepare your database:

   1. Go to the Product Downloads on the Customer Portal and select Red Hat JBoss BRMS.
   2. Download Red Hat JBoss BRMS 6.4.0 Supplementary Tools.
   3. Unzip jboss-brms-bpmsuite-6.4-supplementary-tools/ddl-scripts, for example into /tmp/ddl.

   4. Import the DDL script for your database into the database you want to use, for example:

      psql jbpm < /tmp/ddl/postgresql/postgresql-jbpm-schema.sql

2. Issue the following command to install the Java Database Connectivity (JDBC) driver onto your application platform:

   ./jboss-cli.sh (no need to actually connect to the server)
   module add --name=org.postgresql --resources=/path/to/postgresql-jdbc-driver.jar --dependencies=javax.api,javax.transaction.api

   For further information about deploying JDBC drivers, see Install a JDBC Driver as a Core Module of the Red Hat JBoss Enterprise Application Platform Administration and Configuration Guide.

3. Connect to the running server and create the driver and data source, for example:

   ./jboss-cli.sh --connect --controller=HOST:PORT
   /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
   xa-data-source add --driver-name=postgresql --password=SOME_PASSWORD --user-name=SOME_USERNAME --xa-datasource-properties=url=jdbc:postgresql://localhost:5432/jbpm --name=PostgresqlDS --jndi-name=java:jboss/datasources/PostgresqlDS

   Note

   Always use a distributed (XA) data source with the JBoss BPM Suite persistence service.

   In general, you should use an XA data source when multiple resources are involved in a single transaction. For example, if you are using a Java Messege Service (JMS) executor (which is used by default when asynchronous tasks are included) or timers based on Quartz, you should use an XA data source.

4. Register the data source in Business Central:

   1. Open EAP_HOME/standalone/deployments/business-central.war/WEB-INF/classes/META-INF/persistence.xml.

   2. Locate the <jta-data-source> tag and change it to the JNDI name of your data source, for example:

      <jta-data-source>java:jboss/datasources/PostgresqlDS</jta-data-source>

   3. Locate the <properties> tag and change the hibernate.dialect property, for example:

      <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect" />

Procedure: Cloning Repository

1. Open the Administration perspective: on the main menu, click Authoring → Administration.

2. On the perspective menu, click Repository → Clone repository.

   The Clone Repository pop-up window is displayed.

   Figure 4.1. Clone Repository Pop-up

   

3. Enter the mandatory details:

   • A repository name.
   • Select an organizational unit in which the repository is to be created from the Organizational Unit drop-down option.
   • Enter a Git URL.
   • Enter a user name and a password.
4. Click Clone.

1. Download the migration tool from Red Hat Customer Portal and unzip the downloaded ZIP archive.
2. For production databases, copy the JDBC driver for the database that is used by the JCR repository into the libs directory of the migration tool.

3. On the command line, move into the bin/ directory of the exploded ZIP archive.

   In a Unix environment, run:

   ./runMigration.sh -i SOURCE_PATH -o DESTINATION_PATH -r REPOSITORY_NAME

   In a Windows environment, run:

   ./runMigration.bat -i SOURCE_PATH -o DESTINATION_PATH -r REPOSITORY_NAME

   Where:

   • SOURCE_PATH is the path to the source JCR repository.
   • DESTINATION_PATH is the path to the destination Git VFS.
   • REPOSITORY_NAME is an arbitrary name for the new repository.

   The repository is then migrated to the specified location.

1. On the command line, change to the EAP_HOME_/bin/ directory.

2. In a Unix environment, run:

   ./standalone-secure.sh

   In a Windows environment, run:

   ./standalone-secure.bat

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Decision Manager
   • Version: 6.4
2. Download the Red Hat JBoss BRMS 6.4.0 Deployable for EAP 7 (jboss-brms-6.4.0.GA-deployable-eap7.x.zip) file.
3. Extract the jboss-brms-6.4.0.GA-deployable-eap7.x.zip file to a temporary directory. In the following commands this directory is called TEMP_DIR.
4. Back up your EAP 7 installation, referred to as EAP_HOME in the following commands.
5. Copy the contents of TEMP_DIR/bin to EAP_HOME/bin and merge the files if prompted.

6. Edit the kie.policy file as required for your application. In the following example, replace AllPermission with the security policy that you require:

   grant {
   permission java.security.AllPermission;
   };

1. 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.
2. Log in with the user credentials that were created during installation. For example, user: helloworlduser and password: Helloworld@123.

1. Configuring the cluster using Apache ZooKeeper and Apache Helix. This is required only for design-time clustering.
2. Configuring clustering on your container. Red Hat JBoss BRMS Installation Guide provides only clustering instructions for Red Hat JBoss EAP 6.

1. Download the following ZIP archives containing the required repositories:

   • https://access.redhat.com/jbossnetwork/restricted/softwareDetail.html?softwareId=48311&product=brms&version=&downloadType=distributions
2. Unzip the downloaded ZIP files into an arbitrary location in a local file system.

3. Add entries for the unzipped repositories to Maven’s ~/.m2/settings.xml file. The following code sample contains a profile with the repositories, configuration of authentication for access to the repositories, and an activation entry for the profile:

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/xsd/settings-1.0.0.xsd">
     <localRepository/>
     <profiles>
     <!-- Profile with local repositories required by
          Red Hat JBoss BRMS/Red Hat JBoss BPM Suite -->
       <profile>
         <id>brms-bpms-local-profile</id>
         <repositories>
           <repository>
             <id>jboss-brms-bpmsuite-repository</id>
             <name>BRMS/BPMS 6.4.0 GA Repository</name>
             <url>
               <!-- path to the repository -->
               file:///jboss-brms-bpmsuite-6.4.0.GA-maven-repository/maven-repository
             </url>
             <layout>default</layout>
             <releases>
               <enabled>true</enabled>
               <updatePolicy>never</updatePolicy>
             </releases>
             <snapshots>
               <enabled>false</enabled>
               <updatePolicy>never</updatePolicy>
             </snapshots>
           </repository>
         </repositories>
         <pluginRepositories>
           <pluginRepository>
             <id>jboss-brms-bpmsuite-repository</id>
             <name>BRMS/BPMS 6.4.0.GA Repository</name>
             <url>
               <!-- path to the repository -->
               file:///jboss-brms-bpmsuite-6.4.0.GA-maven-repository/maven-repository
             </url>
             <layout>default</layout>
             <releases>
               <enabled>true</enabled>
               <updatePolicy>never</updatePolicy>
             </releases>
             <snapshots>
               <enabled>false</enabled>
               <updatePolicy>never</updatePolicy>
             </snapshots>
           </pluginRepository>
         </pluginRepositories>
       </profile>
     </profiles>
   
     <servers>
       <!-- Configuring pre-emptive authentication for the repository server -->
       <server>
         <id>brms-bpms-m2-repo</id>
         <username>admin</username>
         <password>admin</password>
         <configuration>
           <wagonProvider>httpclient</wagonProvider>
           <httpConfiguration>
             <all>
               <usePreemptive>true</usePreemptive>
             </all>
           </httpConfiguration>
         </configuration>
       </server>
   
       <!-- Alternative to enabling pre-emptive authentication - configuring
            the Authorization HTTP header with Base64-encoded credentials
       <server>
         <id>brms-bpms-m2-repo</id>
         <configuration>
           <httpHeaders>
             <property>
               <name>Authorization</name>
               <value>Basic YWRtaW46YWRtaW4=</value>
             </property>
           </httpHeaders>
         </configuration>
       </server>
       -->
     </servers>
   
     <activeProfiles>
       <!-- Activation of the Red Hat JBoss BRMS/Red Hat JBoss BPM Suite profile -->
       <activeProfile>brms-bpms-local-profile</activeProfile>
     </activeProfiles>
   </settings>

Procedure: Configuring Maven to Use Online Repositories

1. Add entries for the online repositories and configuration of authentication for accessing them to Maven’s settings.xml file as in the code sample below:

   <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                                 http://maven.apache.org/xsd/settings-1.0.0.xsd">
     <profiles>
       <!-- Profile with online repositories required by BRMS/BPMS -->
       <profile>
         <id>brms-bpms-online-profile</id>
         <repositories>
           <repository>
             <id>jboss-ga-repository</id>
             <url>https://maven.repository.redhat.com/ga/</url>
             <releases>
               <enabled>true</enabled>
             </releases>
             <snapshots>
               <enabled>false</enabled>
             </snapshots>
           </repository>
         </repositories>
         <pluginRepositories>
           <pluginRepository>
             <id>jboss-ga-plugin-repository</id>
             <url>https://maven.repository.redhat.com/ga/</url>
             <releases>
               <enabled>true</enabled>
             </releases>
             <snapshots>
               <enabled>false</enabled>
             </snapshots>
           </pluginRepository>
         </pluginRepositories>
       </profile>
     </profiles>
   
     <servers>
       <!-- Configuring pre-emptive authentication for the repository server -->
       <server>
         <id>brms-bpms-m2-repo</id>
         <username>admin</username>
         <password>admin</password>
         <configuration>
           <wagonProvider>httpclient</wagonProvider>
           <httpConfiguration>
             <all>
               <usePreemptive>true</usePreemptive>
             </all>
           </httpConfiguration>
         </configuration>
       </server>
   
       <!-- Alternative to enabling pre-emptive authentication - configuring
            the Authorization HTTP header with Base64-encoded credentials
       <server>
         <id>brms-bpms-m2-repo</id>
         <configuration>
           <httpHeaders>
             <property>
               <name>Authorization</name>
               <value>Basic YWRtaW46YWRtaW4=</value>
             </property>
           </httpHeaders>
         </configuration>
       </server>
       -->
     </servers>
   
     <activeProfiles>
       <!-- Activation of the BRMS/BPMS profile -->
       <activeProfile>brms-bpms-online-profile</activeProfile>
     </activeProfiles>
   
   </settings>

2. If you modified the settings.xml file while Red Hat JBoss Developer Studio was running, you must refresh Maven settings in the IDE. From the menu, choose Window → Preferences. In the Preferences window, expand Maven and choose User Settings. Click the Update Settings button to refresh the Maven user settings in Red Hat JBoss Developer Studio.

   Figure 7.1. Update Maven User Settings

   

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

1. Start Red Hat JBoss Developer Studio.
2. Select Help → Install 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.redhat.com/9.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 and accept it by selecting the appropriate radio button, and click Finish.
8. Once the plug-in installation is complete, restart Red Hat JBoss Developer Studio.

Procedure: Configuring Red Hat JBoss BRMS and Red Hat JBoss BPM Suite Runtimes

1. Extract the runtime JAR files located in the jboss-brms-VERSION-engine.zip or jboss-bpmsuite-VERSION-engine.zip archive that you can download from the Red Hat Customer Portal.
2. From the Red Hat JBoss Developer Studio menu, select Window and click Preferences.

3. To install the Drools runtime, select Drools → Installed Drools Runtimes.

   To install the jBPM runtime, select jBPM → Installed jBPM Runtimes.

4. Click Add…​, provide a name and a version of the new runtime, and click Browse to navigate to the directory where you extracted the runtime files in the first step. Click OK to register the selected runtime in Red Hat JBoss Developer Studio.
5. Mark the runtime you have created as the default runtime by clicking on the check box next to it.
6. 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.

Procedure: Configuring Server

1. Open the Drools view by selecting Window → Open Perspective → Other. Select Drools and click OK.
2. Add the server view by selecting Window → Show View → Other…​ and select Server → Servers.
3. Open the server menu by right clicking the Servers panel and select New → Server.
4. Define the server by selecting JBoss Enterprise Middleware → JBoss Enterprise Application Platform 6.4+ and click Next.
5. Set the home directory by clicking the Browse button. Navigate to and select the installation directory for JBoss EAP 6.4 which has Red Hat JBoss BRMS installed.
6. Provide a name for the server in the Name field, make sure that the configuration file is set, and click Finish.

Procedure: Cloning Remote Git Repository

1. Start the Red Hat JBoss BRMS server by selecting the server from the Servers tab and click the start icon.

2. Simultaneously, start the Secure Shell server, if not running already, by using the following command. The command is Linux and Mac specific only. On these platforms, 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, select File → Import…​ 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.
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 BRMS server by selecting the server from the Servers tab and click the start icon.
2. In Red Hat JBoss Developer Studio, select File → Import…​ 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.
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 and click Next. Name the project and click Finish.

1. Navigate to the Red Hat Customer Portal and log in with your user credentials.
2. Select DOWNLOADS at the top of the page.
3. In the Product Downloads page that opens, select Red Hat JBoss BRMS.
4. From the Version drop-down menu, select version 6.4.
5. Select Red Hat JBoss BRMS 6.4.0 Business Resource Planner and click Download.

1. On the command line, move into the examples/ directory.

2. In a Unix environment, run the following command:

   ./runExamples.sh

   In a Windows environment, run the following command:

   ./runExamples.bat

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

1. Navigate to the Software Downloads section of the Customer Portal.
2. Click Security Advisories.