ILOG JRules™ 6.

6 Installing the JRules Modules on WebSphere Application Server

COPYRIGHT NOTICE
Copyright © 1987-2007, by ILOG S.A., 9 Rue de Verdun, 94253 Gentilly Cedex, France, and ILOG, Inc., 1195 West Fremont Avenue, Sunnyvale, California 94087-3832, USA. All rights reserved. General Use Restrictions This document and the software described in this document are the property of ILOG and are protected as ILOG trade secrets. They are furnished under a license or nondisclosure agreement, and may be used or copied only within the terms of such license or nondisclosure agreement. No part of this work may be reproduced or disseminated in any form or by any means, without the prior written permission of ILOG S.A, or ILOG, Inc. Trademarks ILOG, the ILOG design, CPLEX, and all other logos and product and service names of ILOG are registered trademarks or trademarks of ILOG in France, the U.S. and/or other countries. All other company and product names are trademarks or registered trademarks of their respective holders. Java and all Java-based marks are either trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Microsoft, Windows, and Windows NT are either trademarks or registered trademarks of Microsoft Corporation in the United States and other countries.

C

O

N

T

E

N

T

S

Contents

Installing the JRules Modules on WebSphere Application Server
Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Installing Rule Team Server on WebSphere Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . 9
Installing Rule Team Server on WebSphere Application Server 5.1 . . . . . . . . . . . . . . . . . . 10 Installing Rule Team Server on WebSphere Application Server 6.0 . . . . . . . . . . . . . . . . . . 24 Installing Rule Team Server on WebSphere Application Server 6.1 . . . . . . . . . . . . . . . . . . 41 Database User Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Completing the Installation Using the Installation Manager . . . . . . . . . . . . . . . . . . . . . . . . 57 Completing the Installation Using Ant Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Opening Rule Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Installing Rule Execution Server on WebSphere Application Servers . . . . . . . . . . . . . . . . . . . . 79
Installing Rule Execution Server on WebSphere Application Server 5.1 . . . . . . . . . . . . . . 79 Installing Rule Execution Server on WebSphere Application Server 6.0 . . . . . . . . . . . . . 103 Installing Rule Execution Server on WebSphere Application Server 6.1 . . . . . . . . . . . . . 124 Rule Execution Server Database Driver Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148 Cloudscape XA Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Null Default Resource Provider Error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Rule Execution Server Deployment on Clusters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Installing Rule Scenario Manager on WebSphere Application Servers . . . . . . . . . . . . . . . . . . 155
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

3

Installing Rule Scenario Manager on WebSphere Application Server 5.1 . . . . . . . . . . . . 155 Installing Rule Scenario Manager on WebSphere Application Server 6.0 . . . . . . . . . . . . 169 Installing Rule Scenario Manager on WebSphere Application Server 6.1 . . . . . . . . . . . . 183

4

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

P

R

E

F

A

C

E

Preface

This section contains instructions on how to install the JRules modules on the WebSphere Application Server, Versions 5.1, 6.0, and 6.1. The intended audience for this guide is the person who develops, assembles, and deploys J2EE applications in a corporate enterprise. This guide assumes you are familiar with the following topics:
◆ J2EE specification ◆ HTML ◆ Java programming ◆ Java APIs as defined in the Java Servlet, JavaServer Pages (JSP), Enterprise JavaBeans

(EJB), and Java Database Connectivity (JDBC) specifications
◆ Structured database query languages such as SQL ◆ Relational database concepts ◆ Software development processes, including debugging and source code control

This guide is organized as follows:
◆ Installation Overview—Provides a description of some basic concepts involved in the

installation.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

5

◆ Installing Rule Team Server on WebSphere Application Servers—Provides instructions

for installing Rule Team Server on WebSphere Application Servers.
◆ Installing Rule Execution Server on WebSphere Application Servers—Provides

instructions for installing Rule Execution Server on WebSphere Application Servers.
◆ Installing Rule Scenario Manager on WebSphere Application Servers—Provides

instructions for installing Rule Scenario Manager on WebSphere Application Servers.

6

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installation Overview

This section contains instructions on how to install the JRules modules on the supported application servers. To use any of the JRules modules on the J2EE platform, you will need to install a set of components on one of the supported application servers. Each of the JRules modules requires that you first prepare your application server for installation. Preparing your application server will involve creating a data source and configuring the necessary security. Installation will consist of deploying an archive (or a set of archives), enabling the online help, and in the case of Rule Team Server an additional configuration step. This configuration step includes:
◆ Configuring the database. ◆ Uploading message files. ◆ Uploading roles. ◆ Setting the persistence locale. ◆ Adding configuration parameters.

It is also possible to customize the behavior of Rule Team Server. For more information, see Customizing Rule Team Server in the JRules developer documentation. The following sections provide a basic introduction to archive deployment and security.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

7

In this Section

Archive Deployment Security Archive Deployment The archive files (EAR/WAR/RAR) included in the application server installers can be deployed to a server in different ways. You should refer to the application server documentation for a full understanding of the different options. Security Configuration of a secure mode on an application server provides ways to increase the security of the application that you deploy. In secure mode an application server:
◆ Checks access to the resources (access to a class using the reflection mechanism is not

permitted without the correct security rights).
◆ Manages access rights (the Rule Execution Server Console access is managed with this

mechanism). By default, Rule Execution Server is installed with a minimum of security. The Rule Execution Server Console application defines a specific role bres_admin. This role controls the access to the various JSP/Servlets. There are no specific permissions implementation for Rule Execution Server MBeans. All that is required to access the MBeans using JMX is the right credentials. Note: Security configuration of the Rule Execution Server may relate to your application/ domain or server scoped enterprise security policy. You should review security settings for applications that call the Rule Execution Server with your J2EE application architect/ system administrator as appropriate. The installation of Rule Team Server is completed using an installation manager. This ensures that you create the right groups in your application server when you setup security access.

8

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Servers

This section provides instructions on installing the Rule Team Server JRules module on WebSphere Application Servers.
In this Section

Installing Rule Team Server on WebSphere Application Server 5.1 Installing Rule Team Server on WebSphere Application Server 6.0 Installing Rule Team Server on WebSphere Application Server 6.1 Database User Permissions Completing the Installation Using the Installation Manager Completing the Installation Using Ant Tasks Opening Rule Team Server ILOG provides a specific integration extension for the IBM WebSphere Process Server (WPS) platform: http://www.ilog.com/solutions/business/bpm/ibmwps.cfm

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

9

Installing Rule Team Server on WebSphere Application Server 5.1
Please take note of the introductory information in Installation Overview. The following section describes how to prepare your WebSphere Application Server 5.1:
◆ Step 1. Creating a Data Source and Connection Pool on WebSphere 5.1 ◆ Step 2. Configuring Security on WebSphere 5.1 ◆ Step 3. Deploying the Rule Team Server EAR on WebSphere 5.1 ◆ Step 4. Deploying the Online Help on WebSphere 5.1

With your application server configured, you will finish the installation by Completing the Installation Using the Installation Manager. Once your installation is finished, Rule Team Server will be ready to use (see Opening Rule Team Server) but will not contain a rule project. You will have to publish a project (see Publish a Project) from Rule Studio. Note: If you have rule projects created before the 6.6 version of JRules, you will have to migrate the database schema, as described in the About ILOG JRules 6.6 guide.

Step 1. Creating a Data Source and Connection Pool on WebSphere 5.1 Creating a data source assumes that your database is already running (see the Readme for more information on supported databases). Creating a data source and connection pool on WebSphere Application Server 5.1 requires that you:
◆ Create a JDBC provider. ◆ Create the data source and connection pool.

Note: When WebSphere Application Server 5.1 is used in cluster mode, the data source needs to be defined at node level in the cluster (as opposed to cluster level). To create a JDBC provider
1. Log in to the WebSphere Administrative Console. 2. In the left frame of the console, click + to expand Resources. 3. Click JDBC Providers in the left frame.

10

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 5.1
4. To set the default scope of the provider used by Rule Team Server, in the right frame of the console select Server1 and click Apply. Some default providers may appear:

5. Create your JDBC provider if it does not appear in the list.

To create a data source and a connection pool
1. In the JDBC Providers table, click on the name of the provider. 2. Under Additional Properties click Data Sources. 3. Click New to create a new data source. 4. Give a name to your data source and enter jdbc/ilogDataSource for the JNDI name,

otherwise Rule Team Server will not be able to use the data source.

5. Click Apply. A connection pool is created and associated with the data source.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

11

6. Under Additional Properties click Custom Properties.

Depending on the database you want to connect to, you have different properties to define, such as the username and password for the database. The following table presents the minimum set of properties required to define the supported databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.
Table 1 Database Driver Properties Database DB2 Universal JDBC Driver Properties Properties include: ◆ databaseName – Database name if the driverType is set to 4, or a locally cataloged database name if driverType is set to 2

driverType – 2 or 4

The following properties are required if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – for example, Sample.

DB2 legacy CLI-based Type 2 Cloudscape JDBC Driver

Parameter: ◆ databaseName – Path to the directory where the files of the database are stored (for example, c:\dir\subdir\mydb) Optional parameters: ◆ createDatabase – Since the value for databaseName usually points to a directory that does not exist, you may want to set this parameter to create.

Cloudscape Network Server using JDBC driver

databaseName – Actual name of the database (not the path to the database directory) driverType – Only value is 4 serverName – TCP/IP address or host name portNumber – TCP/IP port number retrieveMessagesfromServerOnGetMessage – Required by WebSphere, not the database server. Default value is false. Set to true to enable SQLException.getMessage(). URL – For example, jdbc:oracle:oci:@sample

◆ ◆ ◆ ◆

Oracle JDBC Driver

7. Click OK and Save (near the top) and Save again to apply changes to the master

configuration. Before moving on, test the connection to your database:

12

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 5.1
1. Click JDBC Providers in the left frame. 2. Click the name of your provider. 3. Under Additional Properties click Data Sources. 4. Click the name of your data source. 5. Click the Test Connection button.

The status of the connection is indicated at the top.

Step 2. Configuring Security on WebSphere 5.1 Rule Team Server access is managed by the application server security. To access Rule Team Server in WebSphere Application Server 5.1, you need to:
◆ Define a User Registry ◆ Enable Global Security

Define a User Registry WebSphere uses various kinds of user registries (OS, LDAP, or custom). This section explains how to configure a custom user registry as follows:
1. Create the Groups and Users Files ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

13

2. Define a Custom Registry

Any user of Rule Team Server must belong to at least one of the mandatory groups rtsAdministrator, rtsConfigManager, rtsInstaller, and rtsUser. Adherence to these groups determines what parts of Rule Team Server a user can access. You must create all of these in the application server. For testing purposes, it is recommended that you also create a default user/password for each of these groups. In addition, if you wish to perform the Rule Team Server permissions tutorial in your own installation, you will have to create two custom groups (Validator and Eligibility). All this is summarized in the following table:
Group rtsAdministrator rtsConfigManager rtsUser rtsInstaller Validator Eligibility Use Mandatory, gives the user administrator access. Mandatory, gives the user configuration manager access. Mandatory, gives a user standard access. Mandatory, gives the user access to the Installation Manager. Optional custom group, used in the Rule Team Server permissions tutorial. Optional custom group, used in the Rule Team Server permissions tutorial. Default User/Password rtsAdmin/rtsAdmin rtsConfig/rtsConfig rtsUser1/rtsUser1 rtsAdmin/rtsAdmin Val/Val Eli/Eli

Create the Groups and Users Files

WebSphere provides a custom registry approach that enables the definition of the username/ passwords/groups in text files without encryption.
1. Create a ${USER_INSTALL_ROOT}/jrules directory in which you will put the groups

and users property files. In these property files, you will define a websphere user as part of the wasadmin group for the WebSphere Administrative Console authentication, and also the groups and users that enable access to the Rule Team Server login page.
2. Create the groups.props file, which contains the groups definition, in ${USER_INSTALL_ROOT}/jrules, and configure it as follows, adding any custom

groups you may have:
# # # # # Format: name:gid:users:display name where name = groupId of the group gid = uniqueId of the group users = list of all the userIds that the group contains

14

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 5.1
# display name = a (optional) display name for the group. # wasadmin:0:1:WebSphere Administrative Group rtsUser:2:2,5,6:Rule Team Server Policy Manager Group rtsAdministrator:3:3:Rule Team Server Administrator Group rtsConfigManager:4:4:Rule Team Server Configuration Manager Group rtsInstaller:5:3:Rule Team Server Installer Group Validator:6:5:Rule Team Server Tutorial Validator Group Eligibility:7:6:Rule Team Server Tutorial Eligibility Group

Note: Any custom groups, including Validator and Eligibility, will also have to be added to the deployment descriptors (as described in Step 3. Deploying the Rule Team Server EAR on WebSphere 5.1) as well as uploaded to the database (see Completing the Installation Using the Installation Manager) if you wish to use the Rule Team Server permissions mechanism.
3. Create the users.props file, which contains the users definition, in ${USER_INSTALL_ROOT}/jrules, and configure it as follows, adding any custom

users you may have. Make sure the Rule Team Server administrator is part of both the rtsAdministrator and rtsInstaller groups:
# Format: # name:passwd:uid:gids:display name # where name = userId/userName of the user # passwd = password of the user # uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user. # websphere:websphere:1:0:Websphere Administrator rtsUser1:rtsUser1:2:2:Rule Team Server User1 rtsAdmin:rtsAdmin:3:3,5:Rule Team Server Administrator rtsConfig:rtsConfig:4:4:Rule Team Server Config User Val:Val:5:2,6,7:Rule Team Server Tutorial Validator User Eli:Eli:6:2,7:Rule Team Server Tutorial Eligibility User

Note: The first uncommented line (websphere:websphere...) can be replaced with any login/password you want to define for the WebSphere administrator. The following table presents the above configuration in a more readable format:
User rtsAdmin rtsConfig Password rtsAdmin rtsConfig Part of groups... rtsAdministrator, rtsInstaller rtsConfigManager

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

15

User rtsUser1 Val Eli

Password rtsUser1 Val Eli

Part of groups... rtsUser Validator, Eligibility, rtsUser Eligibility, rtsUser

Reminder: Users Val and Eli and the groups Validator and Eligibility are only necessary if you wish to do the Rule Team Server permissions tutorial in your installation.
Define a Custom Registry 1. In the WebSphere Administrative Console, click Security. Open User Registries and

click Custom to open the following:

Enter websphere for both the Server User ID and Server User Password. These must be the same as those you declared in your users.props file.
2. Under Additional Properties click Custom Properties. 3. To define the path to your groups and users properties files, click New. 4. The usersFile property defines the path to the file that contains your user definition.

16

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 5.1

Set the Name to usersFile and for Value enter ${USER_INSTALL_ROOT}/jrules/ users.props. Click OK. The definition will appear as follows.

5. Click New and define the groupsFile property, which defines the path to the file that

contains your group definition. Set the Name to groupsFile and enter the Value ${USER_INSTALL_ROOT}/jrules/ groups.props. Click OK.
6. At the top of the page click Save and the Save button to update the master repository

with your changes. Your user registry is now ready, but will not take effect until you enable global security.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

17

Enable Global Security After the configuration of your user registry, you must enable global server security:
1. Click Security and Global Security. 2. Check Enabled.

Enforce Java 2 Security is selected automatically.
3. For Active User Registry select Custom. 4. Click Apply. At the top of the page click Save. Click the Save button to confirm a save

to the master configuration.
5. Restart your server.

Once you restart your server you will have to log in to the WebSphere Administrative Console with the username/password that you declared for the wasadmin group when you created your user registry. Step 3. Deploying the Rule Team Server EAR on WebSphere 5.1 Deploying the Rule Team Server EAR requires you to complete the following:
1. Declare Custom Groups 2. Deploy the EAR on WebSphere 5.1 3. Change the Class Loader Mode on WebSphere 5.1

Important: Deploying the Rule Team Server EAR sets the persistence locale. Once you save a rule to the database, you should no longer change the persistence locale. If you wish to install Rule Team Server in a language other than English, take note of the instructions provided in Step 4: Set Persistence Locale. Declare Custom Groups The Rule Team Server EAR references the basic groups (rtsUser, rtsConfigManager, rtsAdministrator, and rtsInstaller). However, you must add any custom groups that you declared in the previous step (Step 2. Configuring Security on WebSphere 5.1), including the Validator and Eligibility groups used for the Rule Team Server tutorials, by editing deployment descriptor files in the EAR before deploying.

18

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 5.1 To add your custom groups to the deployment descriptors in the Rule Team Server EAR (<InstallDir>/teamserver/applicationservers/websphere5/jrulesteamserver-WAS5.ear): Note: You may want to make a copy of the EAR before modifying it.
1. Add your custom group as a role in META-INF/ejb-jar.xml of jrulesteamserver-ejb-WAS5.jar in the EAR.
... <security-role-ref> <role-name>my_custom_group</role-name> <role-link>my_custom_group</role-link> </security-role-ref>

as well as:
<security-role> <role-name>my_custom_group</role-name> </security-role> ...

2. Add your custom group to META-INF/application.xml in the EAR.
... <security-role> <role-name>my_custom_group</role-name> </security-role>

Note: To use the Rule Team Server permissions mechanism, you will also have to upload groups to the database (see Completing the Installation Using the Installation Manager) Deploy the EAR on WebSphere 5.1
1. In the WebSphere Administrative Console, in the left pane click Applications and

then Install New Application.
2. Enter the path to the Rule Team Server EAR: <InstallDir>/teamserver/applicationservers/websphere5/jrulesteamserver-WAS5.ear

Click Next.
3. In the Preparing for the application installation page, click Generate Default

Bindings.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

19

Click Next.
4. Click Continue to accept the Application Security Warnings. 5. Click Next to accept the default settings for steps 1-3 of Install New Application. 6. In Step 4 select teamserver, keep default_host, as the virtual host, and click Next. 7. In Step 5 check Module to select all the modules:

Click Next.

20

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 5.1
8. In Step 6, the application server has read the roles that it found in the deployment descriptors. You must map these to the groups found in your groups.prop file.

To do so, click a role in the table and click Lookup groups. Click Search in the middle of the page to display the groups from your groups.prop file and map the group to the role you are editing by moving it to the Selected column:

Click OK and repeat for all the roles. When you have completed the assignments they should appear as follows:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

21

Click Next.
9. In Step 7 select Uncheck and click Next. 10. Click Finish. Click Save to Master Configuration and Save to save your workspace

changes to the master configuration. Change the Class Loader Mode on WebSphere 5.1 With the Rule Team Server EAR now deployed, set the class loader mode to Parent Last for the EAR and WAR files to avoid problems in generating reports, for example. To do so:
1. Select Application > Enterprise Applications and click ILOG Rule Team Server. 2. In the section Classloader Mode, select PARENT_LAST:

Click Apply.
3. Scroll down to the section Related Items.

22

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 5.1
4. Click on Web Modules and then on jrules-teamserver-web-WAS5.war.

In the section Classloader Mode, select PARENT_LAST.

Click OK.
5. Click Save to apply the changes to the master configuration and when prompted, Save

again to confirm the changes.
6. In the left pane, click Applications and Enterprise Applications. Select ILOG Rule Team Server and click Start to start the application.

Step 4. Deploying the Online Help on WebSphere 5.1 To enable online help for Rule Team Server, deploy the EAR as follows:
1. In the left pane, click Applications and then Install New Application. 2. In the right pane, select the Local path option and Browse to: <InstallDir>/teamserver/online-help/rtsonlinehelp.ear

Click Next.
3. Select Generate Default Bindings and click Next. 4. Click Continue to accept the security warning. 5. Accept the default settings for the different steps and click Finish to install. 6. Once the installation is complete, click Save to Master Configuration and then Save to

confirm.
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

23

7. In the left pane, click Applications and Enterprise Applications. Select Rule Team Server Online Help and click Start to start the application.

Note: Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this, specify an absolute URL (http:// mynonsecuredserver:mynonsecuredport/rtsonlinehelp) in the context parameter named ilog.rules.teamserver.HELP_CONTEXT in the WEB-INF/ web.xml file of jrules-teamserver-web-WAS5.war. This completes the preparation of your application server. You can now open Rule Team Server (see Opening Rule Team Server) to complete the installation (see Completing the Installation Using the Installation Manager).
Related Concepts

IBM WebSphere Clusters
Related Tasks

Opening Rule Team Server

Installing Rule Team Server on WebSphere Application Server 6.0
Please take note of the introductory information in Installation Overview. The following section describes how to prepare your application server WebSphere Application Server 6.0:
◆ Step 1. Creating a Data Source and Connection Pool on WebSphere 6.0 ◆ Step 2. Configuring Security on WebSphere 6.0 ◆ Step 3. Deploying the Rule Team Server EAR on WebSphere 6.0 ◆ Step 4. Deploying the Online Help on WebSphere 6.0

With your application server configured, you will finish the installation by Completing the Installation Using the Installation Manager. Once your installation is finished, Rule Team Server will be ready to use (see Opening Rule Team Server) but will not contain a rule project. You will have to publish a project (see Publish a Project) from Rule Studio. Note: If you have rule projects created before the 6.6 version of JRules, you will have to migrate the database schema, as described in the About ILOG JRules 6.6 guide.

24

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0

Step 1. Creating a Data Source and Connection Pool on WebSphere 6.0 Creating a data source assumes that your database is already running (see the Readme for more information on supported databases). Creating a data source and connection pool on WebSphere Application Server 6.0 requires that you:
◆ Create a JDBC provider. ◆ Create the data source and connection pool.

Note: When WebSphere Application Server 6.0 is used in cluster mode, the data source needs to be defined at node level in the cluster (as opposed to cluster level). To create a JDBC provider
1. Log in to the WebSphere Administrative Console. 2. In the left pane open Resources > JDBC Providers. 3. To set the default scope of the provider used by Rule Team Server, in the right frame select Server : server1 and click Apply. Some default providers may appear:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

25

4. Create your JDBC provider if it does not appear in the list.

To create a data source and a connection pool
1. In the JDBC Providers table, click on the name of the provider. 2. Under Additional Properties click Data Sources. 3. Click New to create a new data source. 4. Give a name to your data source and enter jdbc/ilogDataSource for the JNDI name,

otherwise Rule Team Server will not be able to use the data source. De-select Use this Data Source in container managed persistence (CMP).

26

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0

5. Under data source properties, enter the name of your database, which depends on the

database type (see Table 2 below). For example:

6. Click Apply. A connection pool is automatically created and associated with the data

source.
7. Under Additional Properties click Custom Properties.

Depending on the database you want to connect to, you have different properties to define, such as the username and password for the database. The following table presents the minimum set of properties required to define the supported databases. If the driver

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

27

you use is not listed, please check the documentation of WebSphere Application Server for more information.
Table 2 Database Driver Properties Database DB2 Universal JDBC Driver Properties Properties include: ◆ databaseName – Database name if the driverType is set to 4, or a locally cataloged database name if driverType is set to 2

driverType – 2 or 4

The following properties are required if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – for example, Sample.

DB2 legacy CLI-based Type 2 Cloudscape JDBC Driver

Parameter: ◆ databaseName – Path to the directory where the files of the database are stored (for example, c:\dir\subdir\mydb) Optional parameters: ◆ createDatabase – Since the value for databaseName usually points to a directory that does not exist, you may want to set this parameter to create.

Cloudscape Network Server using JDBC driver

databaseName – Actual name of the database (not the path to the database directory) driverType – Only value is 4 serverName – TCP/IP address or host name portNumber – TCP/IP port number retrieveMessagesfromServerOnGetMessage – Required by WebSphere, not the database server. Default value is false. Set to true to enable SQLException.getMessage(). URL – For example, jdbc:oracle:oci:@sample Database Name: path to the location of the database files.

◆ ◆ ◆ ◆

Oracle JDBC Driver Derby

For more information, refer to the Derby documentation. 8. Click OK and Save (near the top), then click Save again to apply changes to the master

configuration. Before moving on, test the connection to your database:
1. Click JDBC Providers in the left frame.

28

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0
2. Click the name of your provider. 3. Under Additional Properties click Data Sources. 4. Select your data source in the table and click Test Connection.

The status of the connection is indicated at the top.

Step 2. Configuring Security on WebSphere 6.0 Rule Team Server access is managed by the application server security. To access Rule Team Server in WebSphere 6.0, you need to:
◆ Define a User Registry ◆ Enable Global Security

Define a User Registry WebSphere uses various kinds of user registries (OS, LDAP, or custom). This section explains how to configure a custom user registry as follows:
1. Create the Groups and Users Files 2. Define a Custom Registry

Any user of Rule Team Server must belong to at least one of the mandatory groups rtsAdministrator, rtsConfigManager, rtsInstaller, and rtsUser. Adherence to these groups determines what parts of Rule Team Server a user can access. You must create
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

29

all of these in the application server. For testing purposes, it is recommended that you also create a default user/password for each of these groups. In addition, if you wish to perform the Rule Team Server permissions tutorial in your own installation, you will have to create two custom groups (Validator and Eligibility). All this is summarized in the following table:
Group rtsAdministrator rtsConfigManager rtsUser rtsInstaller Validator Eligibility Use Mandatory, gives the user administrator access. Mandatory, gives the user configuration manager access. Mandatory, gives a user standard access. Mandatory, gives the user access to the Installation Manager. Optional custom group, used in the Rule Team Server permissions tutorial. Optional custom group, used in the Rule Team Server permissions tutorial. Default User/Password rtsAdmin/rtsAdmin rtsConfig/rtsConfig rtsUser1/rtsUser1 rtsAdmin/rtsAdmin Val/Val Eli/Eli

Create the Groups and Users Files

WebSphere provides a custom registry approach which enables the definition of the username/passwords/groups in text files without encryption.
1. Create a ${USER_INSTALL_ROOT}/jrules directory in which you will create the

groups and users property files.

Note: You can find the value of ${USER_INSTALL_ROOT} in the WebSphere Administrative Console by clicking Environment > WebSphere Variables, and then finding the entry in the table. In these property files, you define a websphere user as part of the wasadmin group for the WebSphere Administrative Console authentication, and also the groups and users that enable access to the Rule Team Server login page.
2. Create the groups.props file, which contains the groups definition, in ${USER_INSTALL_ROOT}/jrules, and configure it as follows, adding any custom

groups you may have:
# Format: # name:gid:users:display name # where name = groupId of the group

30

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0
# gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group. # wasadmin:0:1:WebSphere Administrative Group rtsUser:2:2,5,6:Rule Team Server Policy Manager Group rtsAdministrator:3:3:Rule Team Server Administrator Group rtsConfigManager:4:4:Rule Team Server Configuration Manager Group rtsInstaller:5:3:Rule Team Server Installer Group Validator:6:5:Rule Team Server Tutorial Validator Group Eligibility:7:6:Rule Team Server Tutorial Eligibility Group

Note: Any custom groups, including Validator and Eligibility, will also have to be added to the deployment descriptors (as described in Step 3. Deploying the Rule Team Server EAR on WebSphere 6.0) as well as uploaded to the database (see Completing the Installation Using the Installation Manager) if you wish to use the Rule Team Server permissions mechanism.
3. Create the users.props file, which contains the users definition, in ${USER_INSTALL_ROOT}/jrules, and configure it as follows, adding any custom

users you may have. Make sure the Rule Team Server administrator is part of both the rtsAdministrator and rtsInstaller groups:
# Format: # name:passwd:uid:gids:display name # where name = userId/userName of the user # passwd = password of the user # uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user. # websphere:websphere:1:0:Websphere Administrator rtsUser1:rtsUser1:2:2:Rule Team Server User1 rtsAdmin:rtsAdmin:3:3,5:Rule Team Server Administrator rtsConfig:rtsConfig:4:4:Rule Team Server Config User Val:Val:5:2,6,7:Rule Team Server Tutorial Validator User Eli:Eli:6:2,7:Rule Team Server Tutorial Eligibility User

Note: The first uncommented line (websphere:websphere...) can be replaced with any login/password you want to define for the WebSphere administrator.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

31

The following table presents the above configuration in a more readable format.
User rtsAdmin rtsConfig rtsUser1 Val Eli Password rtsAdmin rtsConfig rtsUser1 Val Eli Part of groups... rtsAdministrator, rtsInstaller rtsConfigManager rtsUser Validator, Eligibility, rtsUser Eligibility, rtsUser

Reminder: Users Val and Eli and the groups Validator and Eligibility are only necessary if you wish to do the Rule Team Server permissions tutorial in your installation.
Define a Custom Registry

To define your custom registry, declare the path to your groups and users files:
1. In the WebSphere Administrative Console, click Security > Global security. 2. Under User registries click Custom to open the Custom user registry page:

Enter websphere for both Server user ID and Server user password. These must be the same as those you declared in your users.props file.
3. Under Additional Properties click Custom properties.

32

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0
4. To define the path to your groups and users properties files, click New. 5. The usersFile property defines the path to the file that contains your user definitions.

Set the Name to usersFile and for Value enter ${USER_INSTALL_ROOT}/jrules/
users.props.

Click OK. The definition will appear as follows.

6. Click New and define the groupsFile property, which defines the path to the file that

contains your group definition. Set the Name to groupsFile and enter the Value ${USER_INSTALL_ROOT}/jrules/ groups.props.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

33

Click OK.
7. At the top of the page click Save, then click the Save button to update the master

repository with your changes. Your user registry is now ready, but will not take effect until you enable global security. Enable Global Security After the configuration of your user registry, you must enable global server security:
1. Click Security > Global Security. 2. Check Enable global security.

Enforce Java 2 Security is selected automatically.
3. For the Active user registry entry, select Custom user registry. 4. Click Apply. At the top of the page click Save. Click the Save button to confirm a save

to the master configuration.
5. Restart your server.

Once you restart your server you will have to log in to the WebSphere Administrative Console with the username/password that you declared for the wasadmin group when you created your user registry. Step 3. Deploying the Rule Team Server EAR on WebSphere 6.0 Deploying the Rule Team Server EAR requires you to complete the following:
1. Declare Custom Groups 2. Deploy the EAR on WebSphere 6.0 3. Change the Class Loader Mode on WebSphere 6.0

Important: Deploying the Rule Team Server EAR sets the persistence locale. Once you save a rule to the database, you should no longer change the persistence locale. If you wish to install Rule Team Server in a language other than English, take note of the instructions provided in Step 4: Set Persistence Locale.

34

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0 Declare Custom Groups The Rule Team Server EAR references the basic groups (rtsUser, rtsConfigManager, rtsAdministrator, and rtsInstaller). However, you must add any custom groups that you declared in the previous step (Step 2. Configuring Security on WebSphere 6.0), including the Validator and Eligibility groups used for the Rule Team Server tutorials, by editing deployment descriptor files in the EAR before deploying. To add your custom groups to the deployment descriptors in the Rule Team Server EAR (<InstallDir>/teamserver/applicationservers/websphere6/jrulesteamserver-WAS6.ear): Note: You may want to make a copy of the EAR before modifying it.
1. Add your custom group as a role in META-INF/ejb-jar.xml of jrulesteamserver-ejb-WAS6.jar in the EAR.
... <security-role-ref> <role-name>my_custom_group</role-name> <role-link>my_custom_group</role-link> </security-role-ref> ...

as well as:
<security-role> <role-name>my_custom_group</role-name> </security-role> ...

2. Add your custom group to META-INF/application.xml in the EAR.
... <security-role> <role-name>my_custom_group</role-name> </security-role>

Note: To use the Rule Team Server permissions mechanism, you will also have to upload groups to the database (see Completing the Installation Using the Installation Manager) Deploy the EAR on WebSphere 6.0
1. In the WebSphere Administrative Console, in the left pane click Applications and

then Install New Application.
2. Enter the path to the Rule Team Server EAR:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

35

<InstallDir>/teamserver/applicationservers/websphere6/jrulesteamserver-WAS6.ear

Click Next.
3. In the Preparing for the application installation page, click Generate Default

Bindings.

Click Next.
4. Click Continue to accept the Application Security Warnings. 5. Click Next to accept the default settings for Step 1 of the Install New Application. 6. In Step 2 select all the modules:

36

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0

7. Click Next until you reach Step 5, where you select teamserver and keep default_host

as Virtual host.

8. In Step 6, the application server has read the roles that it found in the deployment descriptors. You must map these to the groups found in your groups.prop file.

To do so, click a role in the table and click Look up groups. Click Search in the middle of the page to display the groups from your groups.prop file and map the group to the role you are editing by moving it to the Selected column.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

37

Click OK and repeat for all the roles. When you have completed the assignments they should appear as follows:

38

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.0
9. Click Next. In Step 7 select Uncheck and click Next. 10. Click Finish. 11. Click Save to Master Configuration and Save to save your workspace changes to the

master configuration. Change the Class Loader Mode on WebSphere 6.0 The Rule Team Server application does not support the default ‘parent first’ configuration. To change the class loading sequence:
1. In the left pane, open Applications > Enterprise Applications. Click ILOG Rule

Team Server.
2. In the section Class Loading and File Update Detection, for Class loader mode select

Parent Last.

Click Apply.
3. In the section Related Items, click on Web modules and then on jrulesteamserver-web-WAS6.war. 4. In the section Class loader mode, select Parent Last. Click OK.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

39

5. Click Save to save your workspace changes to the master configuration and click Save

again to confirm the changes.
6. In the left pane, open Applications > Enterprise Applications. 7. Select the checkbox next to ILOG Rule Team Server and click Start to start the

application. Step 4. Deploying the Online Help on WebSphere 6.0 To enable online help for Rule Team Server, deploy the EAR as follows:
1. In the left pane, open Applications and click Install New Application. 2. Enter the path to the Rule Team Server online help: <InstallDir>/teamserver/online-help/rtsonlinehelp.ear

Click Next.
3. Select Generate Default Bindings and click Next. 4. Click Continue to accept the security warning. 5. In Step 1 click Next. In Step 2 select the module and click Next. 6. Click Next and then click Finish to install. 7. Click Save to master configuration and click Save again to confirm the changes. 8. In the left pane, open Applications > Enterprise Applications.

40

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1
9. Select the checkbox next to Rule Team Server Online Help and click Start to start the

application.

Note: Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this, specify an absolute URL (http:// mynonsecuredserver:mynonsecuredport/rtsonlinehelp) in the context parameter named ilog.rules.teamserver.HELP_CONTEXT in the WEB-INF/ web.xml file of jrules-teamserver-web-WAS5.war. This completes the preparation of your application server. You can now open Rule Team Server (see Opening Rule Team Server) to complete the installation (see Completing the Installation Using the Installation Manager).
Related Concepts

IBM WebSphere Clusters
Related Tasks

Opening Rule Team Server

Installing Rule Team Server on WebSphere Application Server 6.1
Please take note of the introductory information in Installation Overview. The following section describes how to prepare your application server WebSphere Application Server 6.1:
◆ Step 1. Creating a Data Source and Connection Pool on WebSphere 6.1 ◆ Step 2. Configuring Security on WebSphere 6.1 ◆ Step 3. Deploying the Rule Team Server EAR on WebSphere 6.1 ◆ Step 4. Deploying the Online Help on WebSphere 6.1

With your application server configured, you will finish the installation by Completing the Installation Using the Installation Manager. Once your installation is finished, Rule Team Server will be ready to use (see Opening Rule Team Server) but will not contain a rule project. You will have to publish a project (see Publish a Project) from Rule Studio. Note: If you have rule projects created before the 6.6 version of JRules, you will have to migrate the database schema, as described in the About ILOG JRules 6.6 guide.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

41

Step 1. Creating a Data Source and Connection Pool on WebSphere 6.1 Creating a data source assumes that your database is already running (see the Readme for more information on supported databases). Creating a data source and connection pool on WebSphere Application Server 6.1 requires that you:
◆ Create a JDBC provider. ◆ Create the data source and connection pool.

Note: When WebSphere Application Server 6.1 is used in cluster mode, the data source needs to be defined at node level in the cluster (as opposed to cluster level). To create a JDBC provider
1. Log in to the Integrated Solutions Console. 2. In the left pane open Resources > JDBC and click JDBC Providers. 3. In the right pane in Scope select the Node and Server and click New. 4. In Step 1 select the database type, provider type, and a non-XA implementation type.

Enter a name (for example, Rule Team Server JDBC Provider) and click Next.
5. A summary is provided in Step 3:

6. Click Finish and Save to save the changes to the master configuration.

To create a data source and a connection pool
1. In the Integrated Solutions Console open Resources > JDBC and Data sources.

42

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1
2. In the right pane in Scope select the Node and Server and click New. 3. In Step 1, give a name to your data source and enter jdbc/ilogDataSource for the

JNDI name, otherwise Rule Team Server will not be able to use the data source.

Click Next.
4. In Step 2, select your non-XA JDBC provider and click Next. 5. In Step 3, enter specific database properties for the data source.

The following table presents the minimum set of properties required to define the supported databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.

Database DB2 Universal JDBC Driver

Properties Properties include: ◆ databaseName – Database name if driverType is set to 4, or a locally cataloged database name if driverType is set to 2

driverType – 2 or 4

The following properties are required if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – for example, Sample.

DB2 legacy CLI-based Type 2

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

43

Database Oracle JDBC Driver Derby

Properties

URL – For example, jdbc:oracle:oci:@sample Database Name: path to the location of the database files. Uncheck the option: Use this data source in container managed persistence (CMP)

◆ ◆

For more information, refer to the Derby documentation.

Click Next.
6. Step 3 displays a summary of your settings:

7. Click Finish. The connection pool is created and associated with the data source. 8. Click Save to save the changes to the master configuration.

Before moving on, test the connection to your database:
1. In Data Sources, select the Rule Team Server Data Source and click the Test

Connection button. The status of the connection is indicated at the top.

44

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1

If you need to change the custom properties of your datasource:
1. In the Integrated Solutions Console open Resources > JDBC and click Data sources. 2. Click the data source you want to customize. 3. Under Additional Properties, click Custom properties.

Step 2. Configuring Security on WebSphere 6.1 Rule Team Server access is managed by the application server security. To access Rule Team Server in WebSphere Application Server 6.1, you need to define a user registry. WebSphere uses various kinds of user registries (OS, LDAP, or custom). This section explains how to configure a custom user registry as follows:
1. Create the Groups and Users Files ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

45

2. Define a Custom Registry

Any user of Rule Team Server must belong to at least one of the mandatory groups rtsAdministrator, rtsConfigManager, rtsInstaller, and rtsUser. Adherence to these groups determines what parts of Rule Team Server a user can access. You must create all of these in the application server. For testing purposes, it is recommended that you also create a default user/password for each of these groups. In addition, if you wish to perform the Rule Team Server permissions tutorial in your own installation, you will have to create two custom groups (Validator and Eligibility). All this is summarized in the following table:
Group rtsAdministrator rtsConfigManager rtsUser rtsInstaller Validator Eligibility Use Mandatory, gives the user administrator access. Mandatory, gives the user configuration manager access. Mandatory, gives a user standard access. Mandatory, gives the user access to the Installation Manager. Optional custom group, used in the Rule Team Server permissions tutorial. Optional custom group, used in the Rule Team Server permissions tutorial. Default User/Password rtsAdmin/rtsAdmin rtsConfig/rtsConfig rtsUser1/rtsUser1 rtsAdmin/rtsAdmin Val/Val Eli/Eli

Create the Groups and Users Files WebSphere provides a custom registry approach that enables the definition of the username/ passwords/groups in text files without encryption.
1. Create a ${USER_INSTALL_ROOT}/jrules directory in which you will put the groups

and users property files.

Note: You can find the value of ${USER_INSTALL_ROOT} in the Integrated Solutions Console by clicking Environment > WebSphere Variables, and then finding the entry in the table. In these property files, you will define a websphere user as part of the wasadmin group for the Integrated Solutions Console authentication, and also the groups and users that enable access to the Rule Team Server login page.

46

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1
2. Create the groups.props file, which contains the groups definition, in ${USER_INSTALL_ROOT}/jrules, and configure it as follows, adding any custom

groups you may have:
# Format: # name:gid:users:display name # where name = groupId of the group # gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group. # wasadmin:0:1:WebSphere Administrative Group rtsUser:2:2,5,6:Rule Team Server Policy Manager Group rtsAdministrator:3:3:Rule Team Server Administrator Group rtsConfigManager:4:4:Rule Team Server Configuration Manager Group rtsInstaller:5:3:Rule Team Server Installer Group Validator:6:5:Rule Team Server Tutorial Validator Group Eligibility:7:6:Rule Team Server Tutorial Eligibility Group

Note: Any custom groups, including Validator and Eligibility, will also have to be added to the deployment descriptors (as described in Step 3. Deploying the Rule Team Server EAR on WebSphere 6.1) as well as uploaded to the database (see Completing the Installation Using the Installation Manager) if you wish to use the Rule Team Server permissions mechanism.
3. Create the users.props file, which contains the users definition, in ${USER_INSTALL_ROOT}/jrules, and configure it as follows, adding any custom

users you may have. Make sure the Rule Team Server administrator is part of both the rtsAdministrator and rtsInstaller groups:
# Format: # name:passwd:uid:gids:display name # where name = userId/userName of the user # passwd = password of the user # uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user. # websphere:websphere:1:0:Websphere Administrator rtsUser1:rtsUser1:2:2:Rule Team Server User1 rtsAdmin:rtsAdmin:3:3,5:Rule Team Server Administrator rtsConfig:rtsConfig:4:4:Rule Team Server Config User Val:Val:5:2,6,7:Rule Team Server Tutorial Validator User Eli:Eli:6:2,7:Rule Team Server Tutorial Eligibility User

Note: The first uncommented line (websphere:websphere...) can be replaced with any login/password you want to define for the WebSphere administrator.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

47

The following table presents the above configuration in a more readable format.
User rtsAdmin rtsConfig rtsUser1 Val Eli Password rtsAdmin rtsConfig rtsUser1 Val Eli Part of groups... rtsAdministrator, rtsInstaller rtsConfigManager rtsUser Validator, Eligibility, rtsUser Eligibility, rtsUser

Reminder: Users Val and Eli and the groups Validator and Eligibility are only necessary if you wish to do the Rule Team Server permissions tutorial in your installation. Define a Custom Registry To define your custom registry, declare the path to your groups and users files:
1. In the Integrated Solutions Console, in the left pane open Security > Secure

administration, applications, and infrastructure.
2. Enable Administrative and Application security and click Security Configuration

Wizard.
3. In Step 1 check Enable application security and click Next. 4. In Step 2 check Standalone custom registry and click Next. 5. In Step 3, set Primary administrative user name to websphere. (This must be the same as what you declared in your users.props file.)

To define the path to your groups and users properties files, set usersFile to ${USER_INSTALL_ROOT}/jrules/users.props and groupsFile to ${USER_INSTALL_ROOT}/jrules/groups.props.

48

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1

Click Next.
6. Click Finish. 7. At the top of the page click Save. 8. Restart your server.

Once you restart your server you will have to log in to the Integrated Solutions Console with the username/password that you declared for the wasadmin group when you created your user registry. Step 3. Deploying the Rule Team Server EAR on WebSphere 6.1 Deploying the Rule Team Server EAR requires you to complete the following:
1. Declare Custom Groups 2. Deploy the EAR on WebSphere 6.1 3. Define the Class Loading Sequence

Important: Deploying the Rule Team Server EAR sets the persistence locale. Once you save a rule to the database, you should no longer change the persistence locale. If you wish to install Rule Team Server in a language other than English, take note of the instructions provided in Step 4: Set Persistence Locale.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

49

Declare Custom Groups The Rule Team Server EAR references the basic groups (rtsUser, rtsConfigManager, rtsAdministrator, and rtsInstaller). However, you must add any custom groups that you declared in the previous step (Step 2. Configuring Security on WebSphere 6.1), including the Validator and Eligibility groups used for the Rule Team Server tutorials, by editing deployment descriptor files in the EAR before deploying. To add your custom groups to the deployment descriptors in the Rule Team Server EAR (<InstallDir>/teamserver/applicationservers/websphere6/jrulesteamserver-WAS6.ear): Note: You may want to make a copy of the EAR before modifying it.
1. Add your custom group as a role in META-INF/ejb-jar.xml of jrulesteamserver-ejb-WAS6.jar in the EAR.
... <security-role-ref> <role-name>my_custom_group</role-name> <role-link>my_custom_group</role-link> </security-role-ref> ...

as well as:
<security-role> <role-name>my_custom_group</role-name> </security-role> ...

2. Add your custom group to META-INF/application.xml in the EAR.
... <security-role> <role-name>my_custom_group</role-name> </security-role>

Note: To use the Rule Team Server permissions mechanism, you will also have to upload groups to the database (see Completing the Installation Using the Installation Manager) Deploy the EAR on WebSphere 6.1
1. In the Integrated Solutions Console, in the left pane, click Applications and then

Install New Application.
2. Enter the path to the Rule Team Server EAR:

50

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1
<InstallDir>/teamserver/applicationservers/websphere6/jrulesteamserver-WAS6.ear

Select the checkbox Show me all installation options and parameters.

Click Next.
3. Select the checkbox Generate Default Bindings and click Next. 4. Click Continue to accept the security warning. 5. In Step 1 click Next to accept the default settings. 6. In Step 2 select all the modules and click Next.

7. Click Next until you reach Step 7, where you select teamserver and keep default_host

as Virtual host.
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

51

8. Click Next until you reach Step 9. Here, the application server has read the roles that it

found in the deployment descriptors. You must map these to the groups found in your groups.prop file. To do so, click a role in the table and click Look up groups. Click Search in the middle of the page to display the groups from your groups.prop file and map the group to the role you are editing by moving it to the Selected column.

Click OK and repeat for all the roles. When you have completed the assignments they should appear as follows:

52

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1

9. Click Next to get to Step 10, then select Uncheck and click Next. 10. Click Finish. Click Save to save your workspace changes to the master configuration.

Define the Class Loading Sequence The Rule Team Server application does not support the default ‘parent first’ configuration. To change the class loading sequence:
1. In the left pane open Applications > Enterprise Applications. Click ILOG Rule Team

Server.
2. Click Class loading and update detection. 3. For Polling interval for updated files, specify 0. 4. Select the checkbox Classes loaded with application class loader first.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

53

Click OK.
5. Under Modules, click Manage Modules. 6. Click teamserver and select the item Classes loaded with application class loader

first.

Click OK.
7. Click Save to confirm the change.

54

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Team Server on WebSphere Application Server 6.1
8. In the left pane, open Applications > Enterprise Applications. 9. Select ILOG Rule Team Server and click Start to start the application.

Step 4. Deploying the Online Help on WebSphere 6.1
1. In the left pane, open Applications and click Install New Application. 2. Enter the path to the Rule Team Server online help: <InstallDir>/teamserver/online-help/rtsonlinehelp.ear 3. Select the checkbox Show me all installation options and parameters and click Next. 4. Select the checkbox Generate Default Bindings and click Next. 5. Click Continue to accept the security warning. 6. Accept the default settings for the different steps by clicking Next at each step, and then

click Finish to install.
7. Click Save to save the changes to the master configuration. 8. In the left pane, open Applications > Enterprise Applications. 9. Select Rule Team Server Online Help and click Start to start the application.

Note: Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this, specify an absolute URL (http:// mynonsecuredserver:mynonsecuredport/rtsonlinehelp) in the context parameter named ilog.rules.teamserver.HELP_CONTEXT in the WEB-INF/ web.xml file of jrules-teamserver-web-WAS6.war. This completes the preparation of your application server. You can now open Rule Team Server (see Opening Rule Team Server) to complete the installation (see Completing the Installation Using the Installation Manager).
Related Concepts

IBM WebSphere Clusters
Related Tasks

Opening Rule Team Server

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

55

Database User Permissions
The data source that contains the Rule Team Server data is always mapped to a database user. The following table highlights the database permissions you must enforce for the database user with attention given to the type of operation you wish them to perform:

Table 3 Database User Permissions Operation Create the RTS schema through installation manager or ant tasks (rtsInstaller) Yes Modify the RTS schema through installation manager or ant tasks (rtsInstaller) Yes Yes

Database Permission

Browse and edit rules (rtsUser)

Migrate schema (rtsInstaller)

CREATE ANY INDEX DROP ANY INDEX CREATE ANY ROLE CREATE ANY SEQUENCE DROP ANY SEQUENCE SELECT ANY SEQUENCE ALTER ANY TABLE CREATE ANY TABLE DROP ANY TABLE INSERT ANY TABLE SELECT ANY TABLE UPDATE ANY TABLE CREATE ANY VIEW DROP ANY VIEW Yes Yes Yes Yes

Yes Yes Yes

Yes

Yes Yes

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

Yes

Yes Yes

Yes

Yes Yes

Yes Yes Yes Yes

Yes Yes Yes Yes Yes

56

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using the Installation Manager

Note: The database privilege types differ across the supported databases. The operation of defining these privileges should be performed by a database administrator.

Completing the Installation Using the Installation Manager
The Installation Manager is available in Rule Team Server and is displayed automatically if you are completing the installation, and by clicking Admin > Installation Manager once your initial installation is complete. If you open Rule Team Server when completing the installation, only the Install tab is available.

Using the Installation Manager is the recommended way to complete/modify the installation once you have deployed the Rule Team Server EAR to your application server. Note: To access the Installation Manager, you must have administrator privileges as well as the rtsInstaller role when you log on. For example, if you followed the sample users creation steps, log on as rtsAdmin. You use the Installation Manager to:
◆ Create or modify the Database Schema - the most important step, it is mandatory when

completing the initial installation.
◆ Setup Message Files - mandatory during the installation only if you have some custom

rule model extension files.
◆ Setup Groups - you must set up the same groups declared in the application server if you

want to use the Rule Team Server security and permissions mechanisms.
◆ Change the Persistence Locale - if different from en_US. ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

57

◆ Change Configuration Parameters - optional, used in certain tasks related to customizing

Rule Team Server. Alternatively, you can use Ant tasks to perform these actions, though this requires you to configure your environment to correctly run these tasks. Once your installation is complete, Rule Team Server will be ready to use but will not contain a rule project. If you open Rule Team Server at this point you will see the following:

You will have to publish a project. More information on using the Installation Manager is available in Using the Installation Manager in the Rule Team Server Online Help (accessible by clicking Help in the top banner once you log on). Note: If you have rule projects created before the 6.6 version of JRules, you will have to migrate the database schema, as described in the About ILOG JRules 6.6 guide.
Related Tasks

Step 1: Configure Database Step 2: Setup Message Files Step 3: Setup Groups Step 4: Set Persistence Locale Step 5: Set Configuration Parameters Publish a Project Working with the Rule Team Server Ant Tasks Step 1: Configure Database Extensions to the Rule Team Server rule model are stored in two XML files (see the Customizing JRules guide for more information on defining common model extensions). One of the files contains the model description itself (usually, the .brmx extension is used),

58

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using the Installation Manager and the second one contains data to initialize enumerations and hierarchies (usually, the .brdx extension is used).
To configure the database using the Installation Manager: 1. Select the files that contain your rule model. You can use the default ones provided or

select your customized extensions.
2. Click Generate SQL to generate the script that creates the tables of your database based

on the contents of your rule model files.
3. When the script has been generated, select the Execute the SQL script checkbox, then

click Next.
4. Initialize the database tables that you created.

Once you have completed these steps, you will be able to publish rule projects to your database.
Related Tasks

Step 2: Setup Message Files Step 3: Setup Groups Step 4: Set Persistence Locale Step 5: Set Configuration Parameters Publish a Project Working with the Rule Team Server Ant Tasks Step 2: Setup Message Files Message files contain the display text associated with the extensions to the rule model contained in the .brmx and .brdx files, for example:
status=Status effectiveDate=Effective Date expirationDate=Expiration Date new=New defined=Defined

The default messages file is provided in:
<InstallDir>\teamserver\bin\defaultextensionmessages.properties

Note: The contents of the messages files must respect the ISO-LATIN-1 standard (see
http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html).

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

59

If you use the default rule model when creating your database, this default messages file will automatically be sent to the database. Otherwise, use the Installation Manager to upload your own message files. You will need a messages file for each locale that you use. Messages files are identified in the Installation Manager by their locale:

To declare a messages file in the Installation Manager, you must specify: 1. A locale. 2. The location of the messages file for that locale.

If this locale is supported by Rule Team Server, the Installation Manager will assign a locale code so you can identify it. The recommended way of managing your messages file with respect to locale is described in the Customizing JRules guide.
Related Tasks

Step 1: Configure Database Step 3: Setup Groups Step 4: Set Persistence Locale Step 5: Set Configuration Parameters Publish a Project Working with the Rule Team Server Ant Tasks Step 3: Setup Groups In addition to creating groups in your application server when you setup security access, you will have to use the Setup Groups page of the Installation Manager to upload groups to the database. Note: You only need to do this if you wish to use the Rule Team Server project access and permissions mechanisms (see the sections on Groups and Permissions in the Rule Team Server Online Help).

60

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using the Installation Manager You will need to add all the groups that you wish to see appear in the available list when enforcing project security or setting permissions in Rule Team Server. Ideally, you will not upload the default groups rtsUser and rtsConfigManager, but rather create and upload custom groups. You should not upload either the rtsAdministrator group (because the Administrator has all security access and permissions regardless) or the rtsInstaller group (because a user cannot be a member of this group only).
Related Tasks

Step 1: Configure Database Step 2: Setup Message Files Step 4: Set Persistence Locale Step 5: Set Configuration Parameters Publish a Project Working with the Rule Team Server Ant Tasks Step 4: Set Persistence Locale The persistence locale is used to determine the language in which rules are stored in the Rule Team Server database. It is set initially to en_US when you deploy the Rule Team Server EAR to your application server, which means that the rules in the database are stored in US English. Changing the persistence locale does not change the language in which rules appear in Rule Team Server. Changing the persistence locale in Rule Team Server is only necessary to match the locale of Rule Studio when synchronizing your rule projects. You should not change the persistence locale after you save a rule to the database. Note: The persistence locale is controlled by the value of the <locale> key in ilog/ rules/teamserver/preferences.properties in the lib/rts.jar and set when the EAR is deployed. The Installation Manager overrides this setting.
Related Tasks

Step 1: Configure Database Step 2: Setup Message Files Step 3: Setup Groups Step 5: Set Configuration Parameters Publish a Project 61

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Working with the Rule Team Server Ant Tasks Step 5: Set Configuration Parameters Many tasks related to customizing Rule Team Server require configuration parameters to be set or removed. The following table gives a description of the main configuration parameters available in:
lib/rts.jar (/ilog/rules/teamserver/model/preferences.properties) Parameter Used to...

<extractorValidator>.class Specify a ruleset extractor validator class to use for the given extractorValidator name. The class must implement the ilog.rules.commonbrm.extractor.IlrExtractorValidator interface. Once defined, specify this name as the extractor validator to use when defining a ruleset extractor. build.path Define where the cache of the IRL should be on the file system. The path is computed as follows: first, use this property with the name of the user who launched the server as the root for the cache (<build.path>_<username>). If it is not defined, use the system property java.io.tmpdir and add rtscache (for example, <temp dir>/rtscache_<username>). If the system property is not defined, use the server directory and add rtscache (for example, <server dir>/rtscache_<username>). Specify the list of locales for which a BAL verbalizer is defined. Specify the verbalizer class for the given locale. The class must implement the interface: ilog.rules.vocabulary.verbalization.IlrVerbalizer

brl.verbalizers brl.verbalizer.<locale>

Related Tasks

Step 1: Configure Database Step 2: Setup Message Files Step 3: Setup Groups Step 4: Set Persistence Locale Publish a Project Working with the Rule Team Server Ant Tasks

62

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using Ant Tasks

Completing the Installation Using Ant Tasks
As an alternative to using the Installation Manager, you can use the Rule Team Server Ant tasks to complete or modify your installation. Once your installation is complete, Rule Team Server will be ready to use but will not contain a rule project. You will have to publish a project from Rule Studio. Note: If you have rule projects created before the 6.6 version of JRules, you will have to migrate the database schema, as described in the About ILOG JRules 6.6 guide. This section includes the following: Working with the Rule Team Server Ant Tasks Creating the Database Schema (or dropping a database schema) Defining and Uploading Message Files (mandatory during the installation) Uploading Groups to the Database Setting the Persistence Locale Adding or Removing Configuration Parameters Repackaging the Rule Team Server EAR Erasing a Project from the Database Working with the Rule Team Server Ant Tasks To use the Ant tasks, your environment must be correctly set up. The Rule Team Server Ant tasks are defined in <installDir>/teamserver/bin/ build.xml, and executed by commands of the form:
ant <taskName> <parameters list>

Note: To execute these Ant tasks, you must use the same Java Virtual Machine version and vendor as the one used by the application server. The Ant task parameters start with -D and allow you to set some values such as:
◆ -Dserver.url=<server url> - Used to specify the URL of the application server to

connect to.
◆ -DdatasourceName=<data source name> - Used to specify the JNDI name of the data source to use for the task (default is jdbc/ilogDataSource).

For example:
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

63

ant execute-schema -Dserver.url=http://localhost:8080/teamserver/ DdatasourceName=jdbc/ilogDataSource -Dfile=my_sql_file.sql

The file <installDir>/teamserver/bin/teamserver-anttasks.properties defines the value of some common parameters and others that depend on the application server being used. You do not have to include these parameters in your Ant task command if they are properly defined in this file. This file has been configured for JBoss 4, so you will have to comment in/out and adjust the corresponding lines if you are using another application server, for example:
# Administrator settings # -----------------------------------rtsAdmin.login=rtsAdmin rtsAdmin.password=rtsAdmin # Default properties # -----------------------------------datasourceName=jdbc/ilogDataSource server.host=localhost outputFile=output.sql # JBoss 4 Settings # -----------------------------------# appserver.name=jboss40 # protocol=jnp:// # server.port=1099 # server.url=${protocol}${server.host}:${server.port} # specificPortVMSettings=Djava.naming.factory.initial=org.jnp.interfaces.NamingContextFactory Djava.naming.provider.url=${server.url} Djava.security.auth.login.config=${myenv.JBOSS_HOME}/client/auth.conf

Also, take note of any special instructions in this file concerning your application server. The appserver.name property configures the class path for the Ant tasks. If you need to add specific drivers to your class path, you can add them to <installDir>/teamserver/ lib/classpath-teamserver.xml. Note: Make sure the environment variable corresponding to your application server (for example, JBOSS_HOME) is properly set before running any Ant task.
Related Tasks

Creating the Database Schema Defining and Uploading Message Files Uploading Groups to the Database Setting the Persistence Locale Adding or Removing Configuration Parameters Repackaging the Rule Team Server EAR 64
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using Ant Tasks Erasing a Project from the Database Creating the Database Schema

Note: Running the tasks in this section requires that your environment be correctly setup, as described in Working with the Rule Team Server Ant Tasks. This section describes how to create the database schema if you are using Ant tasks to complete/configure your installation. Extensions to the Rule Team Server rule model are stored in two XML files. One of the files contains the model description itself (usually, the .brmx extension is used), and the second one contains data to initialize enumerations and hierarchies (usually, the .brdx extension is used). You can use Ant tasks to load the rule model from the two XML files and build the SQL script required to get the proper database schema.
To create or update the database schema: 1. Create the SQL script required to create or update the database schema (see Step 1 -

Create the Script).
2. Execute the SQL script that you created (see Step 2 - Execute the Script). 3. Once the schema is created, upload the extensions files in the database (Step 3 - Upload

the Extension).
4. Optionally, you can upload new roles.

For convenience, you can run the set-extensions Ant task, which runs gen-createschema + execute-schema + upload-extensions + upload-roles, with these parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ -DextensionModel=<model file> - The model description (.brmx extension). ◆ -DextensionData=<data file> - The model data description (.brdx extension). ◆ -[DdbSchemaName=<database schema name>] - An optional parameter that can be

used to specify the database schema name in which the Rule Team Server tables are stored. Rule Team Server will use the database user name as the schema name if this parameter is not specified. However, some databases allow for a given user to access several schemas, and the default schema is not always named as the user.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

65

[-Droles=<role list>] - This is an optional parameter that uploads the list of roles to Rule Team Server. This list is specified as “role1 role2 ...”. For example: ant upload-roles ... -Droles="rtsUser rtsConfigManager Eligibility Validator".

Note: To execute these Ant tasks, you must use the same Java Virtual Machine version and vendor as the one used by the application server. Alternatively, you can do this step-by-step, which is useful if you want to look at the generated SQL schema. Step 1 - Create the Script To create the SQL script required to create or update the database schema, run the gencreate-schema Ant task with these parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ -DextensionModel=<model file> - The model description (.brmx extension). ◆ -DextensionData=<data file> - The model data description (.brdx extension). ◆ -[DdbSchemaName=<database schema name>] - An optional parameter that can be

used to specify the database schema name in which the Rule Team Server tables are stored. Rule Team Server will use the database user name as the schema name if this parameter is not specified. However, some databases allow for a given user to access several schemas, and the default schema is not always named as the user.
◆ [-DoutputFile=<SQL file>] - The name of the file that stores the generated SQL script. If this parameter is not given, the task creates a file named output.sql in the directory defined as basedir in build.xml, (..) by default.

For example:
ant gen-create-schema ... -DextensionModel=my_model_file.brmx DextensionData=my_data_file.brdx -DoutputFile=my_sql_file.sql

The task connects to the given data source from the given application server. It checks if this data source points to an existing Rule Team Server database. If not, it builds the SQL script to create a fresh database schema to store the model. Otherwise, it builds the SQL script required to update the existing database schema. Step 2 - Execute the Script To execute the SQL script that you created, run the execute-schema Ant task with these parameters:
◆ -Dserver.url=<server url>

66

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using Ant Tasks
◆ -DdatasourceName=<data source name> ◆ [-Dfile=<SQL file>] - The name of the file to execute, which corresponds to the

script you created. If this parameter is not given, the task attempts to execute a file named output.sql in the directory defined as basedir in build.xml, (..) by default. For example:
ant execute-schema ... -Dfile=my_sql_file.sql

Step 3 - Upload the Extension To store the rule model description in the database schema, run the upload-extensions Ant task with these parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ -DextensionModel=<model file> - The model description (.brmx extension). ◆ -DextensionData=<data file> - The model data description (.brdx extension).

For example:
ant upload-extensions ... -DextensionModel=my_model_file.brmx DextensionData=my_data_file.brdx

The description is stored in the database so that Rule Team Server applications may load it when they start. It is also used by gen-create-schema to get the current model description in order to run a diff with the new schema. In a cluster, you will have to restart the servers. Current sessions should be kicked out. Drop a Database Schema You can drop a database schema in two steps:
1. Create the SQL script required to drop the database schema. 2. Execute the SQL script that you created.

To create the SQL script required to drop a database schema, run the gen-drop-schema Ant task with the following parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ -DextensionModel=<model file> - The description of the database schema to drop.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

67

◆ -[DdbSchemaName=<database schema name>] - An optional parameter that can be

used to specify the database schema name in which the Rule Team Server tables are stored. Rule Team Server will use the database user name as the schema name if this parameter is not specified. However, some databases allow for a given user to access several schemas, and the default schema is not always named as the user.
◆ [-DoutputFile=<SQL file>] - The name of the file that stores the generated SQL script. If this parameter is not given, the task creates a file named output.sql in the directory defined as basedir in build.xml, (..) by default.

For example:
ant gen-drop-schema ... -DextensionModel=my_model_file.brmx DoutputFile=my_sql_file.sql

The task connects to the given data source from the given application server. It reads the model description given in the parameters, and generates the SQL script required to drop the existing schema. Since many database tables are linked through foreign keys, they have to be dropped in a specific order, and the script generation will handle these constraints. To execute the SQL script that you created, run the execute-schema Ant task with these parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ [-Dfile=<SQL file>] - The name of the file to execute, which corresponds to the

script you created. If this parameter is not given, the task attempts to execute a file named output.sql in the directory defined as basedir in build.xml, (..) by default. For example:
ant execute-schema ... -Dfile=my_sql_file.sql Related Tasks

Working with the Rule Team Server Ant Tasks Defining and Uploading Message Files Uploading Groups to the Database Setting the Persistence Locale Adding or Removing Configuration Parameters Repackaging the Rule Team Server EAR Erasing a Project from the Database

68

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using Ant Tasks

Defining and Uploading Message Files This section describes how to upload messages files if you are using Ant tasks to complete/ configure your installation. Message files contain the display text associated with the extensions to the rule model contained in the .brmx and .brdx files, for example:
status=Status effectiveDate=Effective Date expirationDate=Expiration Date new=New defined=Defined

The default messages file is provided in:
<InstallDir>\teamserver\bin\defaultextensionmessages.properties

Note: The contents of the messages files must respect the ISO-LATIN-1 standard (see
http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html).

You will need a messages file for each locale that you use. Upload the messages file to Rule Team Server by running the upload-messages Ant task with these parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ -Dlocale=<locale> ◆ -DmessageFile=<message file>

For example:
ant upload-messages ... -Dlocale=en_US DmessageFile=mymessages.properties

Note: Running this task requires that your environment be correctly setup, as described in Working with the Rule Team Server Ant Tasks.
Related Tasks

Working with the Rule Team Server Ant Tasks Creating the Database Schema Uploading Groups to the Database Setting the Persistence Locale

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

69

Adding or Removing Configuration Parameters Repackaging the Rule Team Server EAR Erasing a Project from the Database Uploading Groups to the Database This section describes how to upload groups to the database if you are using Ant tasks to complete/configure your installation. In addition to creating groups in your application server when you setup security access, you will have to upload groups to the database. Note: You only need to do this if you wish to use the Rule Team Server project access and permissions mechanisms (see the sections on Groups and Permissions in the Rule Team Server Online Help). Add all the groups that you wish to see appear in the available list when enforcing project security or setting permissions in Rule Team Server. Ideally, you will not upload the default groups rtsUser and rtsConfigManager, but rather create and upload new groups. You should not upload either the rtsAdministrator group (since the Administrator has all security access and permissions regardless) or the rtsInstaller group (since a user cannot be a member of this group only). To store in the database the list of groups that will be used by the application, run the upload-roles Ant task with these parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ -Droles=<role list>

Where <role list> is the list of groups to upload to Rule Team Server, specified as “group1 group2 ...”. For example:
ant upload-roles ... -Droles="rtsUser rtsConfigManager Eligibility Validator"

Note: To execute these Ant tasks, you must use the same Java Virtual Machine version and vendor as the one used by the application server.
Related Tasks

Working with the Rule Team Server Ant Tasks

70

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using Ant Tasks Creating the Database Schema Defining and Uploading Message Files Setting the Persistence Locale Adding or Removing Configuration Parameters Repackaging the Rule Team Server EAR Erasing a Project from the Database Setting the Persistence Locale The persistence locale is used to determine the language in which rules are stored in the Rule Team Server database. It is set initially to en_US when you deploy the Rule Team Server EAR to your application server, which means that the rules in the database are stored in US English. Changing the persistence locale does not change the language in which rules appear in Rule Team Server. Changing the persistence locale in Rule Team Server is only necessary to match the locale of Rule Studio when synchronizing your rule projects. You should not change the persistence locale after you save a rule to the database. Note: The persistence locale is controlled by the value of the <locale> key in ilog/ rules/teamserver/preferences.properties in the lib/rts.jar and set when the EAR is deployed. The Installation Manager overrides this setting.
Related Tasks

Working with the Rule Team Server Ant Tasks Creating the Database Schema Defining and Uploading Message Files Uploading Groups to the Database Adding or Removing Configuration Parameters Repackaging the Rule Team Server EAR Erasing a Project from the Database Adding or Removing Configuration Parameters This section describes how to set configuration parameters if you are using Ant tasks to complete/configure your installation.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

71

Many tasks related to customizing Rule Team Server require configuration parameters to be set or removed. The following table gives a description of the main configuration parameters available in:
lib/rts.jar (/ilog/rules/teamserver/model/preferences.properties) Parameter Used to...

<extractorValidator>.class Specify a ruleset extractor validator class to use for the given extractorValidator name. The class must implement the ilog.rules.commonbrm.extractor.IlrExtractorValidator interface. Once defined, specify this name as the extractor validator to use when defining a ruleset extractor. build.path Define where the cache of the IRL should be on the file system. The path is computed as follows: first, use this property with the name of the user who launched the server as the root for the cache (<build.path>_<username>). If it is not defined, use the system property java.io.tmpdir and add rtscache (for example, <temp dir>/rtscache_<username>). If the system property is not defined, use the server directory and add rtscache (for example, <server dir>/rtscache_<username>). Specify the list of locales for which a BAL verbalizer is defined. Specify the verbalizer class for the given locale. The class must implement the interface: ilog.rules.vocabulary.verbalization.IlrVerbalizer

brl.verbalizers brl.verbalizer.<locale>

The following Ant tasks can be used to add or remove configuration parameters:
◆ set-config-param - Sets a configuration parameter for a given user. If the user is not

specified, it sets a global parameter. Parameters:

-Dserver.url=<server url> -DdatasourceName=<data source name> [-Duser=<username>] -Dkey=<parameter key> -Dvalue=<parameter value>

Example: ant set-config-param ... -Dkey=locale -Dvalue=en_US
◆ remove-config-param - Drops the given configuration parameter for a given user if

specified. Otherwise, it drops the global configuration parameter. Parameters: 72
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Completing the Installation Using Ant Tasks
-Dserver.url=<server url> -DdatasourceName=<data source name> [-Duser=<username>] -Dkey=<parameter key>

◆ print-config-param - Prints the global parameters or given user parameters if username is specified. If no key is specified, all keys are printed.

Parameters:

-Dserver.url=<server url> -DdatasourceName=<data source name> [-Duser=<username>] -Dkey=<parameter key>

Note: See Working with the Rule Team Server Ant Tasks for help on setting up your environment to correctly execute the Rule Team Server Ant tasks.
Related Tasks

Working with the Rule Team Server Ant Tasks Creating the Database Schema Defining and Uploading Message Files Uploading Groups to the Database Setting the Persistence Locale Repackaging the Rule Team Server EAR Erasing a Project from the Database Repackaging the Rule Team Server EAR

Note: See Working with the Rule Team Server Ant Tasks for help on setting up your environment to correctly execute the Rule Team Server Ant tasks. You can add new .jar files to the Rule Team Server EAR by running the repackage-ear Ant task with these parameters:
◆ -DtargetEar=<target ear> ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

73

◆ -DsourceEar=<source ear> ◆ -DdescriptorsDir=<descriptors directory> - A directory that is copied into the META-INF directory of the target EAR (not mandatory). ◆ -DadditionalJars=<“myjar1.jar myjar2.jar ... myjarn.jar”> Additional .jar files to store in the lib directory of the target EAR (not mandatory). ◆ -DtmpDir=<directory> - A directory that can be specified to store temporary files

(not mandatory).
◆ -DwebResourcesDir=<web resources directory> - A directory that is copied

into the WAR library (not mandatory). This task does not use the server.url and datasourceName parameters. Because the application may be configured with extensions, the original EAR files have to be modified to include these extensions.
Related Tasks

Working with the Rule Team Server Ant Tasks Creating the Database Schema Defining and Uploading Message Files Uploading Groups to the Database Setting the Persistence Locale Adding or Removing Configuration Parameters Erasing a Project from the Database Erasing a Project from the Database

Note: See Working with the Rule Team Server Ant Tasks for help on setting up your environment to correctly execute the Rule Team Server Ant tasks. You can erase a project from Rule Team Server, including all its content, by running the drop-project Ant task with the following parameters:
◆ -Dserver.url=<server url> ◆ -DdatasourceName=<data source name> ◆ -DprojectName=<project name>

Note that the project cannot be dropped if some other projects depend on it.

74

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Opening Rule Team Server
Related Tasks

Working with the Rule Team Server Ant Tasks Creating the Database Schema Defining and Uploading Message Files Uploading Groups to the Database Setting the Persistence Locale Adding or Removing Configuration Parameters Repackaging the Rule Team Server EAR

Opening Rule Team Server
Once you have deployed the Rule Team Server EAR on your application server, Rule Team Server can be opened by typing teamserver at the root URL. The following URL is the default for the application server:
http://localhost:9080/teamserver

If your browser is not running on the same host as the application server, replace
localhost with the address of the machine.

By default, the data source used is jdbc/ilogDataSource. If you want to specify a different data source, you have to pass it as a request parameter in the URL, for example
http://localhost:8080/teamserver?datasource=jdbc/serverextendedbrm.

The locale of the login page is English by default. You can specify a locale parameter in the teamserver URL that will switch the login page to the desired locale, for example http:// localhost:8080/teamserver?locale=es (assuming that your message files are localized). If you log in with another locale in the URL and want to change the locale afterwards, go to Options > Edit Display Options. This will save the locale and restore it the next time you log in. If you open Rule Team Server but no database exists yet, you will automatically access the Installation Manager with only the Install tab available.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

75

After completing the installation, Rule Team Server is ready to be used but does not contain a rule project. If you open Rule Team Server at this point you will get the following:

You will have to publish a rule project from Rule Studio.
Related Tasks

Publish a Project Completing the Installation Using Ant Tasks Completing the Installation Using the Installation Manager Publish a Project After completing the installation, Rule Team Server is ready to be used but does not contain a rule project. If you open Rule Team Server at this point you will get the following:

76

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Opening Rule Team Server

You will have to publish a rule project from Rule Studio. Also, if you want to carry out the tutorials found in the Rule Team Server online help, you will have to publish the following rule projects from Rule Studio:
◆ loanvalidation-rules (with loanvalidation-xom) ◆ loanvalidation-rules-dependent ◆ squery-loanvalidation-rules (with squery-loanvalidation-xom) To publish the projects needed for the Rule Team Server tutorials: 1. In Rule Studio click File > Import > General > Existing Projects into Workspace, and

click Next.
2. Click Select root directory and browse to <InstallDir>/studio/tutorials/ shared and click OK. 3. Select the projects and click Finish. Then publish them to Rule Team Server. Related Tasks

Completing the Installation Using Ant Tasks Completing the Installation Using the Installation Manager

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

77

78

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Servers

This section provides instructions on installing the Rule Execution Server JRules module on WebSphere Application Servers.
In this Section

Installing Rule Execution Server on WebSphere Application Server 5.1 Installing Rule Execution Server on WebSphere Application Server 6.0 Installing Rule Execution Server on WebSphere Application Server 6.1 Rule Execution Server Database Driver Issues Rule Execution Server Deployment on Clusters ILOG provides a specific integration extension for the IBM WebSphere Process Server (WPS) platform: http://www.ilog.com/solutions/business/bpm/ibmwps.cfm

Installing Rule Execution Server on WebSphere Application Server 5.1
Installing Rule Execution Server on WebSphere Application Server 5.1 includes:
◆ Step 1. Creating Database Resources.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

79

◆ Step 2. Creating a Cloudscape Schema. ◆ Step 3. Changing Persistence from the default database persistence to file persistence, if

required.
◆ Step 4. Creating a Data Source and Connection Pool on WebSphere 5.1. ◆ Step 5. Deploying the XU RAR on WebSphere 5.1. ◆ Step 6. Deploying the Rule Execution Server Management EAR on WebSphere 5.1. ◆ Step 7. Activating Security on WebSphere 5.1 through the definition of a custom registry,

and mapping security roles.
◆ Step 8. Deploying the Rule Execution Server Console Online Help. ◆ Step 9. Running Rule Execution Server Diagnostic to confirm connectivity. ◆ To enable optional features, refer to:

Deploying the Scenario Service Provider EAR on WebSphere 5.1. Deploying the Hosted Transparent Decision Service EAR on WebSphere 5.1.

Step 1. Creating Database Resources Before you can use Rule Execution Server with database persistence you must create a dedicated schema in the database (containing tables, views, and so on). SQL scripts are provided for this task and are located in:
<InstallDir>/executionserver/databases

A readme file in this directory provides additional information on the scripts provided. The schema_derby.sql script creates a schema named BRES, so you may need to reconfigure your datasource so that it connects to the Derby database as user BRES. For the Oracle database, in addition to tables and indexes, a sequence and a trigger are also created. The SQL scripts schema_oracle.sql and schema_oracle_plsql.sql are provided for this task. The scripts should be run in the following sequence:
1. schema_oracle.sql 2. schema_oracle_plsql.sql

When using an Oracle database, you should run all scripts in the SQL Plus client. Any tool that can handle SQL can be used to import and run the SQL scripts. The tools provided for each database include:
◆ cview – Cloudscape ◆ ij command line processor – Derby ◆ command center or db2 command line processor – IBM DB2

80

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1
◆ mysql command line processor – MySQL ◆ sqlplus command line processor – Oracle ◆ PointBase console – Pointbase ◆ Query Tool – SQL Server ◆ isql command line processor – Sybase.

To access the database, the database user must have a user ID and a password. The database user must have complete privileges on the tables and view of the schema (create, insert, delete). They must also have create index privileges. On Oracle, the database user must also have create trigger and create sequence privileges. A client should be installed for the database that you use. Please refer to the documentation of these tools for more information. Note: There is no optimization in the scripts. For better performance, you can modify the parameters that create the resources to fit your database configuration and data.

Step 2. Creating a Cloudscape Schema A sample Cloudscape schema is used in describing the installation of Rule Execution Server. To create a schema in Cloudscape:
1. Launch Cloudview (Cview) using cview.bat. 2. In Cview, select File > New > Database. 3. Enter a Name for the database and click OK. 4. Open the schema in a text editor:
<InstallDir>/executionserver/databases/cloudscape/schema_cloudscape.sql

5. In Cview, copy and paste the contents of the schema file into the window under the tab

Database.
6. Deselect Stop on Error and click execute (

).

7. In the left frame open Database_Name > Tables and check that the tables have been

created.
8. In Cview select File > Exit.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

81

Step 3. Changing Persistence By default, persistence is set to datasource. To help you change the persistence type, an Ant script is provided to create a new instance of the management and monitoring model and the Execution Unit (XU) using a specific persistence mode. The ressetup.xml file is located in:
<InstallDir>/executionserver/bin

The Ant task element attributes are as follows:

Table 4 Ant Task Element Attributes for the ressetup.xml File Element Attributes xuinput xuoutput managementinput managementoutput Description Path to input the XU .rar. Path to output the XU .rar Path to input the management .ear Path to output the management .ear Required one of the pairs input/ output is required

The Ant task element properties are as follows:

Table 5 Ant Task Element Properties for the ressetup.xml File Element Property persistence.type Description The persistence type. The possible values are: ◆ file (for a file persistence in J2SE)

Required no

datasource (for a database persistence in J2EE) jdbc (for a database persistence in J2SE)

persistence.jdbc.user

Login to use with the database connection for J2SE. no no

persistence.jdbc.crypted Password will be encrypted in the XU configuration .password.enabled file. persistence.jdbc. password persistence.jdbc.driver

A password to use with the database connection for no J2SE. A driver implementation class to establish a connection with the database. no

82

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1
Table 5 Ant Task Element Properties for the ressetup.xml File Element Property Description Required no no

persistence.datasource. The JNDI name of the datasource. jndi persistence.file.directory Where the path to the top directory containing rulesets is.

The following example creates a new XU (.rar) and a new management stack (EAR) that are configured to use file persistence:
<import file="${executionserver.home}/lib/classpath-executionserver.xml"/> <taskdef resource="res-tasks.properties" > <classpath refid="executionserver.setup.classpath"/> </taskdef> <res-setup xuinput="../applicationservers/websphere5/jrules-bres-xu-WAS5.rar" xuoutput="myxu.rar" managementInput="../applicationservers/websphere5/jrules-bresmanagement-WAS5.ear" managementOutput="mymgmt.ear" > <property name="persistence.type" value="file" /> <property name="persistence.datasource.jndi" value="java:/jdbc/ mydatasource" /> </res-setup>

Step 4. Creating a Data Source and Connection Pool on WebSphere 5.1 The data source is based on the database schema created in Step 1. Creating Database Resources. Creating a JDBC Provider To create a JDBC provider:
1. Log on to the WebSphere Administrative Console (only a User ID is required, by default this is websphere). 2. In the left pane click Resources and JDBC Providers. 3. The default scope of the provider used by Rule Execution Server is Server1. In the right

pane select Server and click Apply. Some default providers should appear if you use the default configuration.
4. Click the New button to create a new JDBC provider. It is mandatory to choose an

implementation which supports XA features.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

83

5. For JDBC Providers choose the database type and click OK. In General Properties,

check that the class path to the JAR of your driver and the implementation class are correct. Default values are usually sufficient. Click OK. Note: Some drivers (such as Oracle OCI drivers) need to access additional libraries at runtime (.dll or.so files). As a consequence, you will have to set up your working environment in order to access these libraries (PATH, LD_LIBRARY_PATH, and so on). You may have to restart your server in order to take these changes into account. Creating a Data Source and Connection Pool To create a data source and a connection pool:
1. Open Resources > JDBC Providers. Click the JDBC provider you want to define the

data source and connection pool for and under Additional Properties, click Data Sources.
2. Click New to create a new data source. 3. Enter resdatasource as the Name of the data source, jdbc/bresdatasource for the

JNDI Name. Note: The name of the data source is not important here but the JNDI name is. Be sure to set it to jdbc/bresdatasource, otherwise the Rule Execution Server will not be able to use the data source.
4. Click Apply. A connection pool is automatically created and associated with the data

source.
5. Under Additional Properties click Custom Properties.

Depending on the database you want to connect to, you have different properties to define. Table 6 presents the minimum set of properties required to define the supported

84

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1 databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.
Table 6 Database Driver Properties Database DB2 Universal JDBC Driver Properties

databaseName – Actual database name if driverType is set to 4, or a locally cataloged database name if driverType is set to 2 driverType – Possible values are 2 or 4

The following properties are required only if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – Locally cataloged database name driverType – Only value is 2 databaseName – For example, Sample databaseName – Path to the directory where the files of the database are stored (for example, c:\dir\subdir\mydb)

DB2 Universal JDBC XA Driver DB2 legacy CLI-based Type 2 Cloudscape JDBC Driver

◆ ◆

Optional parameters: ◆ createDatabase – Default value for the databaseName parameter. Usually points to a directory that does not exist. If you want to use this value, set this parameter to the value create
◆ ◆

user – Name of the user. password – The user password.

In the default script provided the user password is PBPUBLIC. Cloudscape Network Server using JDBC driver

databaseName – Actual name of the database, not the path to the database directory driverType – Only value is 4 serverName – TCP/IP address or host name portNumber – TCP/IP port number retrieveMessagesfromServerOnGetMessage – Required by WebSphere, not by the database server. Default value is false. Set it to true to enable SQLException.getMessage() URL – For example, jdbc:oracle:oci:@sample

◆ ◆ ◆ ◆

Oracle JDBC Driver

6. If you have applied IBM patch PK13771, continue to Step 7. Otherwise, click Apply and

Save at the top of the page to confirm a save to the master configuration.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

85

7. At the bottom of the page, under Related Items click J2C Authentication Data

Entries.
8. Click New. 9. Define an Alias name. For example, DbUser. 10. Define the User ID and Password used to access the database.

Click OK.
11. In the resdatasource page, for Component-managed Authentication Alias select the alias you created (DbUser). 12. Click Apply and Save at the top of the page to confirm a save to the master

configuration. Connecting to the Database To test the connection to your database:
1. Click JDBC Providers in the left frame. 2. Click the name of your provider. 3. Under Additional Properties click Data Sources. 4. Click the name of your data source. 5. Click the Test Connection button.

If the test fails, check that the information you provided (user, password, and so on) is correct. For more information on connection pools and data sources, please refer to the documentation of IBM WebSphere Application Server. Step 5. Deploying the XU RAR on WebSphere 5.1 To deploy the XU RAR on WebSphere Application Server:
1. In the left pane of the WebSphere Administrative Console, click Resources and

Resource Adapters.
2. In the right pane, click Install RAR. 3. In the right pane, select Local path and Browse to:
<InstallDir>/executionserver/applicationservers/websphere5/jrules-bres-xuWAS5.rar

4. Click Next. 5. In the right pane, configure the RAR or accept the default (an empty form) and click OK.

86

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1
6. Click Save at the top of the pane to finish the configuration. Click Save to confirm the

change.
7. In the left pane, click Resources and Resource Adapters and verify that WebSphere

Relational Resource Adapter is in the list.
8. Click XU and under Additional Properties at the bottom of the page, click J2C

Connection Factories.
9. Click New. 10. Enter the following values:

Name xu_cf JNDI name eis/XUConnectionFactory
11. Click OK. 12. At the top of the page click Save and the Save button to update the master repository

with your changes. Step 6. Deploying the Rule Execution Server Management EAR on WebSphere 5.1 To deploy the EAR on WebSphere Application Server:
1. Open the WebSphere Administrative Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane select Local path and Browse to:
<InstallDir>/executionservers/applicationservers/websphere5/jrules-bresmanagement-WAS5.ear

4. Click Next. 5. Select Generate Default Bindings and click Next to accept the default settings for the

application bindings. Click Continue to accept the security warning.
6. Click Next to accept the default settings for Step 1 of the application installation. 7. For Step 2 use the following settings:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

87

Click Next.
8. Click Next to complete Step 3. 9. Click Next to accept the default settings in Step 4. 10. In Step 5 click Next for no security.

For more information on how to activate security, see Step 7. Activating Security on WebSphere 5.1.
11. In Step 6, click Finish to complete the configuration. 12. Once the installation is complete, click Save to Master Configuration. 13. Click the Save button to confirm a save to the master configuration. 14. In the left pane, click Applications and Enterprise Applications. 15. In the Enterprise Applications page select ILOG Rule Execution Server and click

Start to start the application. Changing the Class Loader Mode on WebSphere 5.1 Once the Rule Execution Server EAR is deployed, you may need to change the class loader mode depending on the security settings you use, as described in Enabling Global Security. For example, if Enforce Java 2 Security is selected, you will need to set the EAR to PARENT_LAST and the WAR to PARENT_FIRST, as follows:
1. Select Application > Enterprise Applications and click ILOG Rule Execution

Server. 88
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1
2. In the section Classloader Mode, select PARENT_LAST:

Click Apply.
3. Scroll down to the section Related Items.

4. Click on Web Modules and then on jrules-bres-management.war.

In the section Classloader Mode, select PARENT_FIRST.

Click OK.
5. Click Save to apply the changes to the master configuration and when prompted, Save

again to confirm the changes.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

89

Step 7. Activating Security on WebSphere 5.1 WebSphere Application Server Version 5.1 provides security infrastructure and mechanisms to protect sensitive J2EE resources and administrative resources and to address enterprise end-to-end security requirements on authentication, resource access control, data integrity, confidentiality, privacy, and secure interoperability. The security layers in WebSphere Application Server are shown in the following:

WebSphere Application Server supports the J2EE model for creating, assembling, securing, and deploying applications. By default, the Rule Execution Server Console does not require security in WebSphere. However, to activate access control for Rule Execution Server in WebSphere 5.1, perform the following steps. Defining a Custom Registry WebSphere uses various kinds of user registries (OS, LDAP, or Custom). This section explains how to configure a user registry. WebSphere provides a custom registry sample named FileRegistrySample. This sample enables the definition of the username/passwords/groups in text files without encryption. The relationship between the various roles/groups/users in the proposed custom definition is as follows:

90

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1

To define a custom registry:
1. To define the path of the files, you need to define two custom properties.

In the WebSphere Administrative Console, click Security. Under User Registries click Custom to open the following:

As the Server User ID and Server User Password, enter websphere.
2. Under Additional Properties click Custom Properties.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

91

3. Click New. Define the usersFile property with the path to the file that contains the

user definition.

Set the Name to usersFile and Value to ${USER_INSTALL_ROOT}/jrules/ users.props. Click OK.
4. Click New. Define the groupsFile property with the path to the file that contains the

group definition.

Set Name to groupsFile and enter the Value ${USER_INSTALL_ROOT}/jrules/ groups.props. Click OK.
5. Click Save at the top of the page and the Save button to update the master repository

with your changes.
6. According to your USER_INSTALL_ROOT variable (WAS_HOME, by default), create a directory named bres and then create two files named users.props and groups.props in ${USER_INSTALL_ROOT}/bres.

The property files must define the following:
a. A websphere/wasadmin user for the WebSphere Administrative Console

authentication.
b. A bres/bresgroup for the Rule Execution Server Console authentication.

92

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1 The users.props file must contain the users definition:
# Format: # name:passwd:uid:gids:display name # where name = userId/userName of the user # passwd = password of the user # uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user # websphere:websphere:100:0:Websphere Administrator bres:bres:2:1:BRE Server Administrator

The groups.props file must contain the groups definition:
# Format: # name:gid:users:display name # where name = groupId of the group # gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group # wasadmin:0:websphere:Administrative Group bresgroup:1:bres:BRE Server Admin Group

Enabling Global Security After the configuration of the custom user registry, you can enable the server security. To enable security settings:
1. Click Security and Global Security. 2. Check Enabled. Note that Enforce Java 2 Security is selected automatically. If you

retain this setting you will need to change the class loading sequence of the EAR and WAR files as described in Changing the Class Loader Mode on WebSphere 5.1.
3. For Active user registry select Custom. 4. Click Apply and Save.

Note: You may be prompted to enter the Server User ID and Server User Password. By default this is websphere/websphere. Click Apply and Save.
5. Click the Save button to confirm a save to the master configuration. 6. Restart your server for the changes to take effect. You will be required to log on using a User ID/Password. By default this is websphere/websphere.

Mapping the bresgroup to the Monitor Role To access the MBeans of the Rule Execution Server model, an application must have sufficient security credentials, restricted to the Monitor role in the WebSphere authentication system.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

93

Rule Execution Server users can be given access to the MBeans of the model by configuring a mapping between the bresgroup declared in the custom registry and the Monitor role, as follows:
1. In the WebSphere Administrative Console open System Administration > Console

Groups and click Add.
2. Specify the group bresgroup. 3. In Role(s) select Monitor. 4. Click Apply. 5. Click OK. At the top of the page click Save and the Save button to update the master

repository with your changes. Restart the server. Mapping Security Roles to Users/Groups When the global security is enabled you can define the security mapping for the Rule Execution Server Console through Applications > Enterprise Applications > ILOG Rule Execution Server > Additional Properties > Map Security roles to users/groups. To define how the bres_admin role is mapped in the application server security:
1. Select the bres_admin role.

2. Click Lookup users. The following is displayed:

94

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1

3. Click Search. 4. Select the bres item. To do this click on it under Available and use >> to move it to the

Selected column.
5. Click OK to return to the Mapping Users to Roles page. 6. Select the bres_admin role. 7. Click Lookup groups. The following is displayed:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

95

8. Click Search. 9. Select the bresgroup item. To do this click on it under Available and use >> to move it

to the Selected column.
10. Click OK to return to the Mapping Users to Roles page. 11. Check the All Authenticated? checkbox.

12. Click OK. At the top of the page click Save and the Save button to update the master

repository with your changes. 96
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1 To apply these settings to the Rule Execution Server Console, you must restart the application from the list of the installed applications in the WebSphere Administrative Console. Security Policies for the Rule Execution Server Console When the global security of WebSphere is activated, the MBean server cannot be accessed from the deployed application. These security policies must be overridden for the Rule Execution Server Console because it needs to record and manage a set of MBeans. Rule Execution Server is packaged with a specific policy file that overrides the server policies. This file is packaged in an EAR file was.policy in the META-INF directory. Step 8. Deploying the Rule Execution Server Console Online Help To enable online help for Rule Execution Server:
1. Open the WebSphere Administrative Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane select Local path and Browse to: <InstallDir>/executionserver/online-help/resonlinehelp.ear

Click Next.
4. Select Generate Default Bindings and click Next to accept the default settings for the

application bindings.
5. Click Continue to accept the security warning. 6. Click Next to accept the default settings for Step 1 of the application installation. 7. For Step 2 click Next to accept the default settings. 8. Click Next to complete Step 3. 9. Step 4 provides a summary of the settings. Click Finish to install. 10. Once the installation is complete, click Save to Master Configuration and the Save

button to confirm a save to the master configuration.
11. In the left pane, click Applications and Enterprise Applications. Select Rule Execution Server Console Online Help and click Start to start the application.

Deploying Help in a Non-secure Context Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this:
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

97

1. Extract the jrules-bres-management.war from the management EAR. 2. In jrules-bres-management.war, edit the file web.xml and in the context parameter ilog.rules.res.HELP_CONTEXT, specify an absolute URL (for example, http://myserver/resonlinehelp). 3. Save the file and repackage the WAR into the EAR.

You may need to restart WebSphere and the Rule Execution Server Console for the online help to function correctly. Step 9. Running Rule Execution Server Diagnostic Verify that the Rule Execution Server has been successfully installed by launching the Rule Execution Server Diagnostic:
1. Open the Rule Execution Server Console by typing bres at the root URL on the host

machine:
http://localhost:9080/bres

If your browser is not running on the same host as the application server, you can replace localhost with <host>.
2. Sign in to the Rule Execution Server Console (the default user ID and password is bres/ bres). 3. In the Rule Execution Server Console click the Diagnostics tab. 4. Click Run Diagnostics. You should see a report similar to the following:

98

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1

Important: To let a scalable number of users access resources through the Java components, JCA assigns the task of implementing connection pooling to application server vendors. On WebSphere Application Server, the pool size is not instantiated beforehand and therefore prevents the server diagnostic from validating a Rule Execution Server before the first execution of a rule engine. The diagnostic can validate a configuration, especially in a cluster, by check invoked XUs registered with the management model. If the diagnostic is performed before any XUs have been invoked, the test is passed and a message is displayed verifying that no XU(s) have been initialized.

Deploying the Scenario Service Provider EAR on WebSphere 5.1 The scenario service provider EAR must be deployed on the same server as the XU. To deploy the EAR:
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

99

1. Open the WebSphere Administrative Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane select Local path and Browse to: <InstallDir>/executionserver/applicationservers/websphere5/ jrules-ssp-WAS5.ear 4. Click Next. 5. Select Generate Default Bindings and click Next to accept the default settings for the

application bindings.
6. Click Continue to accept the security warning. 7. Click Next to accept the default settings for Step 1. 8. For Step 2 use the following settings:

Click Next.
9. Click Next to complete Step 3. 10. Click Next to accept the default settings in Step 4. 11. In Step 5, if you have activated security select bres_admin and click Lookup groups. 12. Click Search. 13. Select the bresgroup item. To do this click on it under Available and use >> to move it

to the Selected column.
14. Click OK to return to the Mapping Users to Roles page. Click Next. 15. In Step 6, click Finish to complete the configuration. 16. Once the installation is complete, click Save to Master Configuration. 17. Click the Save button to confirm a save to the master configuration.

100

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 5.1
18. Start the Scenario Service Provider by selecting Applications > Enterprise

Applications, selecting SSP and clicking Start. The scenario service provider application can be configured in the web.xml of the Rule Execution Server Console using the parameter name:
ilog.rules.res.SSP_CONTEXT

Configuring the Scenario Service Provider The following is an example ANT task to change the configuration of the SSP archive. To update the scenario service provider archive, you must use the new library of jrulesbres-setup.jar, located in <InstallDir>/executionserver/lib/ .
<taskdef resource="bres-tasks.properties" > <classpath> <pathelement location="<InstallDir>/executionserver/lib/jrules-bressetup.jar"/> <pathelement location="<InstallDir>/executionserver/lib/jrulesengine.jar"/> </classpath> </taskdef> <property name="ssp.in" value="<InstallDir>/executionserver/applicationservers/vendor/jrules-sspvendor.ear"/> <property name="ssp.out" value="${basedir}/jrules-ssp-My.ear"/> <target name="setup"> <ssp-setup sspInput="${ssp.in}" sspOutput="${ssp.out}" verbose="true"> <xom> <fileset dir="./data"> <include name="loan.jar"/> </fileset> </xom> <configuration log4jFile="./data/log4j.properties" handler="execution.trace.Handler"/> <j2seExecution persistenceMode="file" persistenceProperties="ilog.rules.bres.xu.ruleset.fs.IlrFileRulesetInformationP rovider.repositoryDirPath=c:/res-data-v6" traceLevel="FINE" traceAutoflush="true" plugins="{pluginClass=ilog.rules.bres.ras.plugin.IlrExecutionTracePlugin}, {pluginClass=ilog.rules.res.decisionservice.plugin.IlrWsdlGeneratorPlugin}"/> </ssp-setup> </target>

Where jrules-ssp-vendor.ear and jrules-ssp-My.ear are the filenames of the application server .EAR files.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

101

Checking the Availability of Scenario Service Provider You can check on the availability of the Scenario Service Provider (SSP) as follows:
◆ Enter the URL http://<host>:<port>/ssp. A log on page will appear if SSP is

available.
◆ Through the Rule Execution Server Console. If you use the Test Ruleset feature and SSP

is not available, you will get the error message:
Host and port appear to be responsive but the service does not exist: /ssp/unsecured/XS ◆ Through the Rule Scenario Manager Console, by selecting Admin > SSP Servers.

Deploying the Hosted Transparent Decision Service EAR on WebSphere 5.1 The hosted transparent decision service must be deployed on the same node as the XU. To deploy the hosted transparent decision service EAR on WebSphere Application Server 5.1:
1. Open the WebSphere Administrative Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane select Local path and Browse to: <InstallDir>/executionserver/applicationservers/websphere5/ jrules-bres-ootbds-WAS5.ear 4. Click Next. 5. Select Generate Default Bindings and click Next to accept the default settings for the

application bindings.
6. Click Continue to accept the security warning. 7. Click Next to accept the default settings for Step 1 of the application installation. 8. Click Next to accept the default settings for Step 2 of the application installation. The

JNDI name must be set to:
eis/XUConnectionFactory 9. Click Next to accept the default settings in Step 3. 10. In Step 4, click Finish to complete the configuration. 11. Once the installation is complete, click Save to Master Configuration. 12. Click the Save button to confirm a save to the master configuration. 13. In the left pane, click Applications and Enterprise Applications.

102

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0
14. In the Enterprise Applications page, select JRules Decision Service and click Start to

start the application. Note: By default the ruleset.xmlDocumentDriverPool.maxsize ruleset property value is set to 1. This value could cause a bottleneck if you have several clients executing a hosted transparent decision service concurrently. Increasing the value of this property could significantly increase the performance. A value of 30 could be a good candidate size. The hosted transparent decision service requires that you set the web container customer property DecodeUrlAsUTF8 to False to support a localized ruleset path, as follows:
1. Open the WebSphere Administrative Console. 2. Click Servers > Application servers > server_name > Web container settings > Web

container > Custom properties.
3. Click Add customer properties. 4. Enter DecodeUrlAsUTF8 as the name and False as the value. 5. Click Apply and Save.

Be aware that this setting impacts all applications deployed on the server. For more information on checking that the hosted transparent decision service has been deployed successfully, refer to the Rule Execution Server Console online help.
Related Concepts

Rule Execution Server Deployment on Clusters
Related Tasks

Installing Rule Execution Server on WebSphere Application Server 6.0 Installing Rule Execution Server on WebSphere Application Server 6.1
Related Reference

Rule Execution Server Database Driver Issues

Installing Rule Execution Server on WebSphere Application Server 6.0
Installing Rule Execution Server on WebSphere Application Server 6.0 includes:
◆ Step 1. Changing Persistence from the default database persistence to file persistence, if

required.
◆ Step 2. Creating Database Resources.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

103

◆ Step 3. Creating a Cloudscape Schema. ◆ Step 4. Creating a Data Source and Connection Pool on WebSphere 6.0. ◆ Step 5. Deploying the XU RAR on WebSphere 6.0. ◆ Step 6. Deploying the Rule Execution Server Management EAR on WebSphere 6.0. ◆ Step 7. Changing the Class Loader Mode on WebSphere 6.0. ◆ Step 8. Activating Security on WebSphere 6.0 through the definition of a custom registry,

and mapping security roles.
◆ Step 9. Running Rule Execution Server Diagnostic to confirm connectivity. ◆ To enable optional features, refer to:

Deploying the Scenario Service Provider EAR on WebSphere 6.0. Deploying the Hosted Transparent Decision Service EAR on WebSphere 6.0.

Deploying the Rule Execution Server Console Online Help To enable online help for Rule Execution Server, deploy <InstallDir>/ executionserver/online-help/resonlinehelp.ear on your application server. The procedure for deploying EARs is described in Step 6. Deploying the Rule Execution Server Management EAR on WebSphere 6.0. Deploying Help in a Non-secure Context Running the Rule Execution Server Console from a secure http may cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this:
1. Extract the jrules-bres-management.war from the management EAR. 2. In jrules-bres-management.war, edit the file web.xml and in the context parameter ilog.rules.res.HELP_CONTEXT, specify an absolute URL (for example, http://myserver/resonlinehelp). 3. Save the file and repackage the WAR into the EAR.

You may need to restart WebSphere and the Rule Execution Server Console for the online help to function correctly. Step 1. Changing Persistence By default, persistence is set to datasource. To help you change the persistence type, an Ant script is provided to create a new instance of the management and monitoring model and the Execution Unit (XU) using a specific persistence mode. The ressetup.xml file is located in: 104
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0
<InstallDir>/executionserver/bin

The Ant task element attributes are as follows:

Table 7 Ant Task Element Attributes for the ressetup.xml File Element Attributes xuinput xuoutput managementinput managementoutput Description Path to input the XU .rar. Path to output the XU .rar Path to input the management .ear Path to output the management .ear Required one of the pairs input/ output is required

The Ant task element properties are as follows:

Table 8 Ant Task Element Properties for the ressetup.xml File Element Property persistence.type Description The persistence type. The possible values are: ◆ file (for a file persistence in J2SE)

Required no

datasource (for a database persistence in J2EE) jdbc (for a database persistence in J2SE)

persistence.jdbc.user

Login to use with the database connection for J2SE. no no

persistence.jdbc.crypted Password will be encrypted in the XU configuration .password.enabled file. persistence.jdbc. password persistence.jdbc.driver

A password to use with the database connection for no J2SE. A driver implementation class to establish a connection with the database. no no no

persistence.datasource. The JNDI name of the datasource. jndi persistence.file.directory Where the path to the top directory containing rulesets is.

The following example creates a new XU (.rar) and a new management stack (EAR) that are configured to use file persistence:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

105

<import file="${executionserver.home}/lib/classpath-executionserver.xml"/> <taskdef resource="res-tasks.properties" > <classpath refid="executionserver.setup.classpath"/> </taskdef> <res-setup xuinput="../applicationservers/websphere6/jrules-bres-xu-WAS6.rar" xuoutput="myxu.rar" managementInput="../applicationservers/websphere6/jrules-bresmanagement-WAS6.ear" managementOutput="mymgmt.ear" > <property name="persistence.type" value="file" /> <property name="persistence.datasource.jndi" value="java:/jdbc/ mydatasource" /> </res-setup>

Step 2. Creating Database Resources Before you can use Rule Execution Server with database persistence you must create a dedicated schema in the database (containing tables, views, and so on). SQL scripts are provided for this task and are located in:
<InstallDir>/executionserver/databases

A readme file in this directory provides additional information on the scripts provided. The schema_derby.sql script creates a schema named BRES, so you may need to reconfigure your datasource so that it connects to the Derby database as user BRES. For the Oracle database, in addition to tables and indexes, a sequence and a trigger are also created. The SQL scripts schema_oracle.sql and schema_oracle_plsql.sql are provided for this task. The scripts should be run in the following sequence:
1. schema_oracle.sql 2. schema_oracle_plsql.sql

When using an Oracle database, you should run all scripts in the SQL Plus client. Any tool that can handle SQL can be used to import and run the SQL scripts. The tools provided for each database include:
◆ cview – Cloudscape ◆ ij command line processor – Derby ◆ command center or db2 command line processor – IBM DB2 ◆ mysql command line processor – MySQL ◆ sqlplus command line processor – Oracle ◆ PointBase console – Pointbase ◆ Query Tool – SQL Server ◆ isql command line processor – Sybase.

106

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0 To access the database, the database user must have a user ID and a password. The database user must have complete privileges on the tables and view of the schema (create, insert, delete). They must also have create index privileges. On Oracle, the database user must also have create trigger and create sequence privileges. A client should be installed for the database that you use. Please refer to the documentation of these tools for more information. Note: There is no optimization in the scripts. For better performance, you can modify the parameters that create the resources to fit your database configuration and data.

Step 3. Creating a Cloudscape Schema A sample Cloudscape schema is used in describing the installation of Rule Execution Server. To create a schema in Cloudscape:
1. Launch Cloudview (Cview) using cview.bat. 2. In Cview, select File > New > Database. 3. Enter a Name for the database and click OK. 4. Open the schema in a text editor:
<InstallDir>/executionserver/databases/cloudscape/schema_cloudscape.sql

5. In Cview, copy and paste the contents of the schema file into the window under the tab

Database.
6. Deselect Stop on Error and click execute (

).

7. In the left frame open Database_Name > Tables and check that the tables have been

created.
8. In Cview select File > Exit.

Step 4. Creating a Data Source and Connection Pool on WebSphere 6.0 The data source is based on the database schema created, following the guidelines in Step 2. Creating Database Resources. Creating a JDBC Provider To create a JDBC provider:
1. Log in to the WebSphere Console. 2. In the left pane click Resources and JDBC Providers.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

107

3. The default scope of the provider used by Rule Execution Server is Server. In the right

pane select Server and click Apply. Some default providers should appear if you use default configuration.
4. Click the New button to create a new JDBC provider:

In Step 1 select the database type. In Step 2 select the provider type. In Step 3, in the pull-down menu, select the implementation type. Choose an implementation which supports XA features.
5. Click Next. 6. Check that the class path to the JAR of your driver and the implementation class are

correct. Default values are usually sufficient. Click Apply. Note: Some drivers (such as Oracle OCI drivers) need to access additional libraries at runtime (.dll or.so files). As a consequence, you will have to set up your working environment in order to access these libraries (PATH, LD_LIBRARY_PATH, and so on). You may have to restart your server in order to take these changes into account. The Additional Properties panel appears at the side of the page. This will allow you to create the data source. Creating a Data Source and Connection Pool To create a data source and a connection pool:
1. Click Resources and JDBC Providers. 2. The JDBC provider you want to create the data source for and click Data Sources in

Additional Properties.
3. Click New to create a new data source. 4. Enter resdatasource as the Name of the data source, jdbc/bresdatasource for the

JNDI name, and the Database name which depends on the database type (see Table 9). For Cloudscape this is normally the path to the directory where the files of the database are stored. For DB2 this is the name of the database. Note: The name of the data source is not important here but the JNDI name is. Be sure to set it to jdbc/bresdatasource, otherwise the Rule Execution Server will not be able to use the data source.
5. De-select Use this Data Source in container managed persistence (CMP).

108

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0
6. Select a data store helper class that is suitable to your database. The default provided is

normally sufficient.
7. Click Apply. A connection pool is automatically created and associated with the data

source and the Additional Properties panel is activated.
8. Click Custom Properties in Additional Properties.

Depending on the database you want to connect to, you have different properties to define. Table 9 presents the minimum set of properties required to define the supported databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.
Table 9 Database Driver Properties Database DB2 Universal JDBC Driver Properties

databaseName – Actual database name if the driverType is set to 4, or a locally cataloged database name if the driverType is set to 2 driverType – Possible values are 2 or 4

The following properties are required only if the driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – Locally cataloged database name) driverType – Only value is 2 databaseName – For example, Sample

DB2 Universal JDBC XA Driver DB2 legacy CLI-based Type 2 Cloudscape JDBC Driver

◆ ◆

Parameter: ◆ databaseName – Path to the directory where the files of the database are stored (for example, c:\dir\subdir\mydb) Optional parameters: ◆ createDatabase – Default value for the databaseName parameter. Usually points to a directory that does not exist. If you want to use this value, set this parameter to the value create.
◆ ◆

user – Name of the user. password – The user password.

In the default script provided the user password is PBPUBLIC.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

109

Table 9 Database Driver Properties Database Cloudscape Network Server using JDBC driver Properties

databaseName – Actual name of the database, not the path to the database directory driverType – Only value is 4 serverName – TCP/IP address or host name portNumber – TCP/IP port number retrieveMessagesfromServerOnGetMessage – Required by WebSphere, not by the database server. Default value is false. Set it to true to enable SQLException.getMessage() URL – For example, jdbc:oracle:oci:@sample Database Name: path to the location of the database files.

◆ ◆ ◆ ◆

Oracle JDBC Driver Derby

For more information, refer to the Derby documentation. 9. If you want to protect the password you can use an alias instead of the custom properties.

Specify it in the Component-managed Authentication Alias of the datasource. To create the alias use the J2EE Connector Architecture (J2C) authentication data link to set the name and password.
10. Click New to add the Name user and Value (for example, PBPUBLIC) to define the user

to connect to the database. Click OK.
11. To create a password repeat step 7 and specify password for Name and PBPUBLIC (for

example) for Value. Click OK.
12. At the top of the page click Save and Save again to confirm the change to JDBC

providers. Connecting to the Database To test the connection to your database:
1. Open Resources > JDBC providers > Cloudscape JDBC Provider > Data sources >

resdatasource.
2. Click Test Connection.

If the test fails, check that the information you provided (user, password, and so on) is correct. Step 5. Deploying the XU RAR on WebSphere 6.0 To deploy the XU RAR on WebSphere Application Server:

110

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0
1. Open the WebSphere Console. 2. In the left pane, click Resources and Resource Adapters. 3. In the right pane, set the scope to the node and click Apply. 4. Click Install RAR. 5. In the right pane, select Local path and Browse to:
<InstallDir>/executionserver/applicationservers/websphere6/jrules-bres-xuWAS6.rar

Click Next.
6. In the right pane, configure the RAR or accept the default (an empty form) and click OK. 7. You are prompted to Save changes to the Master Configuration. Click Save again to

confirm the change.
8. In the left pane, click Resources and Resource Adapters and verify that WebSphere

Relational Resource Adapter is in the list.
9. Click XU then under Additional Properties, click J2C connection factories. 10. Click New. 11. Enter the following values:

Name xu_cf JNDI name eis/XUConnectionFactory
12. Click OK. 13. At the top of the page click Save and Save again to confirm the change.

Step 6. Deploying the Rule Execution Server Management EAR on WebSphere 6.0 To deploy the EAR on WebSphere Application Server:
1. Open the WebSphere Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane, select Local file system and Browse to:
<InstallDir>/executionserver/applicationservers/websphere6/jrules-bresmanagement-WAS6.ear

Click Next.
4. Select the checkbox Generate Default Bindings and click Next.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

111

5. Click Continue to accept the security warning. 6. In Step 1 click Next to accept the default settings. 7. In Step 2 select ILOG Rule Execution Server Console and click Next. 8. In Step 2 select RES console webapp and click Next. 9. In Step 3 for the javax.resource.cci.ConnectionFactory, set multiple existing resource

JNDI names:
a. Scroll down to the table and select ILOG Rule Execution Server Console. b. Scroll up and select the eis/XUConnectionFactory resource JNDI name c. Click Apply. 10. In Step 3 for the javax.sql.DataSource, set multiple existing resource JNDI names: a. Scroll down to the table and select ILOG Rule Execution Server Console. b. Scroll up and select the jdbc/bresdatasource resource JNDI name c. Click Apply. d. Click Next to complete Step 3. 11. In Step 4 select ILOG Rule Execution Server Console and click Next. 12. In Step 5 click Next for no security.

For more information on how to activate security, see Step 8. Activating Security on WebSphere 6.0.
13. In Step 6 click Finish to accept the default settings and start the installation.

The installation starts. When complete the message Application ILOG Rule Execution Server installed successfully is displayed. Save changes to the master configuration.
14. In the left pane, click Applications and Enterprise Applications. 15. In the Enterprise Applications page select ILOG Rule Execution Server Console and

click Start to start the application. Step 7. Changing the Class Loader Mode on WebSphere 6.0 Set the class loader mode to Parent Last for the Rule Execution Server EAR to avoid problems in generating reports, as follows:
1. Log in to the WebSphere Console. 2. Select Application > Enterprise Applications and click ILOG Rule Execution Server

Console. 112
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0
3. In the section Class Loading and File Update Detection, for Class loader mode select

Parent Last.
4. In the section Related Items, click on Web modules and then on jrules-bresmanagement-WAS6.ear.

5. In the section Class loader mode, select Parent Last. Click OK. 6. Click Save to apply changes to the master configuration and when prompted, Save again

to confirm the changes. Step 8. Activating Security on WebSphere 6.0 WebSphere Application Server Version 6.0 provides security infrastructure and mechanisms to protect sensitive J2EE resources and administrative resources and to address enterprise end-to-end security requirements on authentication, resource access control, data integrity, confidentiality, privacy, and secure interoperability. The security layers in WebSphere Application Server are shown in the following:

WebSphere Application Server supports the J2EE model for creating, assembling, securing, and deploying applications. By default, the Rule Execution Server Console does not require security in WebSphere. However, to activate access control for Rule Execution Server in WebSphere Application Server 6.0, perform the following steps.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

113

Defining a Custom Registry WebSphere uses various kinds of user registries (OS, LDAP, or Custom). This section explains how to configure a user registry. WebSphere provides a custom registry sample named FileRegistrySample. This sample enables the definition of the username/passwords/groups in text files without encryption. The relationship between the various roles/groups/users in the proposed custom definition is as follows:

To define a custom registry:
1. Log on to the WebSphere Console. To define the path of the files, you need to define

two Custom Properties.
2. Click Security and Global security. Under User registries click Custom to open the

Custom user registry page:

114

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0

As the Server user ID and Server user password, enter websphere.
3. Under Additional Properties click Custom properties. This page is used to add the

group and user properties. Click New.
4. The usersFile property defines the path to the file that contains the user definition.

Set the Name to usersFile and enter the Value ${USER_INSTALL_ROOT}/jrules/ users.props. Click OK.
5. Click New and define the groupsFile property, which defines the path to the file that

contains the group definition.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

115

For Name specify groupsFile and enter the Value ${USER_INSTALL_ROOT}/ jrules/groups.props. Click OK.
6. According to your USER_INSTALL_ROOT variable (WAS_HOME, by default), create a directory named bres and then create two files named users.props and groups.props in ${USER_INSTALL_ROOT}/bres.

The property files must define the following:
a. A websphere/wasadmin user for the WebSphere Console authentication. b. A bres/bresgroup for the Rule Execution Server Console authentication.

The users.props file must contain the users definition:
# Format: # name:passwd:uid:gids:display name # where name = userId/userName of the user # passwd = password of the user # uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user # websphere:websphere:100:0:Websphere Administrator bres:bres:2:1:BRE Server Administrator

The groups.props file must contain the groups definition:
# Format: # name:gid:users:display name # where name = groupId of the group # gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group # wasadmin:0:websphere:Administrative Group

116

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0
bresgroup:1:bres:BRE Server Admin Group

7. At the top of the page click Save. Click the Save button to confirm a save to the master

configuration. Enabling Global Security After the configuration of the custom user registry, you can enable the server security. To enable security settings, modify the Global Security as follows:
1. Click Security and Global Security. 2. Check Enabled. Enforce Java 2 Security is selected automatically. 3. For Active User Registry select Custom user registry. 4. Click Apply. At the top of the page click Save. Click the Save button to confirm a save

to the master configuration.
5. Restart your server. 6. Refresh the WebSphere Administrative Console. You will be required to log on using a User ID/Password. By default this is websphere/websphere.

Mapping the bresgroup to the Monitor Role To access the MBeans of the Rule Execution Server model, an application must have sufficient security credentials, restricted to the Monitor role in the WebSphere authentication system. Rule Execution Server users can be given access to the MBeans of the model by configuring a mapping between the bresgroup declared in the custom registry and the Monitor role, as follows:
1. In the WebSphere Console open System administration > Console settings > Console

groups.
2. Click Add. Enter the group name bresgroup and for Role(s) select Monitor.

Click Apply.
3. Click OK. At the top of the page click Save. Click the Save button to confirm a save to

the master configuration. Mapping Security Roles to Users/Groups When the global security is enabled you can define the security mapping for the Rule Execution Server Console.
1. Open Applications > Enterprise Applications > RES console > Additional

Properties > Map Security roles to users/groups.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

117

2. To define how the bres_admin role is mapped in the application server security, select the bres_admin role to open the following:

3. Click Lookup users and Search to display the following:

4. Select the bres item. To do this click on it under Available and use >> to move it to the

Selected column.
5. Click OK to return to the Mapping users to roles page. 6. Select the bres_admin role. 7. Click Lookup groups and click Search to display the following:

118

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0

8. Select the bresgroup item. To do this click on it under Available and use >> to move it

to the Selected column.
9. Click OK to return to the Mapping Users to Roles page. 10. Check the All authenticated? checkbox.

Click OK.
11. At the top of the page click Save. Click the Save button to confirm a save to the master

configuration. To apply these settings to the Rule Execution Server Console, you must restart the application from the list of the installed applications in the WebSphere Console.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

119

Security Policies for the Rule Execution Server Console When the global security of WebSphere is activated, the MBean server cannot be accessed from the deployed application. These security policies are overridden for the Rule Execution Server Console because it needs to record and manage a set of MBeans. Rule Execution Server is packaged with a specific policy file that overrides the server policies. This file is packaged in an EAR file was.policy in the META-INF directory. Step 9. Running Rule Execution Server Diagnostic Verify that the Rule Execution Server has been successfully installed by launching the Rule Execution Server Diagnostic:
1. Open the Rule Execution Server Console by typing bres at the root URL on the host

machine:
http://localhost:9080/bres

If your browser is not running on the same host as the application server, you can replace localhost with <host>.
2. Sign in to the Rule Execution Server Console (the default user ID and password is bres/ bres). 3. In the Rule Execution Server Console click the Diagnostics tab. 4. Click Run Diagnostics. You should see a report similar to the following:

120

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0

Important: To let a scalable number of users access resources through the Java components, JCA assigns the task of implementing connection pooling to application server vendors. On WebSphere Application Server, the pool size is not instantiated beforehand and therefore prevents the server diagnostic from validating a Rule Execution Server before the first execution of a rule engine. The diagnostic remains useful to validate a configuration, especially in a cluster, to check invoked XUs registered with the management model. If the diagnostic is performed before any XUs have been invoked, the test is passed and a message is displayed verifying that no XU(s) have been initialized.

Deploying the Scenario Service Provider EAR on WebSphere 6.0 The scenario service provider EAR must be deployed on the same server as the XU. To deploy the EAR:
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

121

1. Use the WebSphere Console to deploy: <InstallDir>/executionserver/applicationservers/websphere6/jrulesssp-WAS6.ear 2. The SSP application can be configured in the web.xml of the Rule Execution Server

Console using the parameter name:
ilog.rules.res.SSP_CONTEXT

Configuring the Scenario Service Provider The following is an example ANT task to change the configuration of the SSP archive. To update the scenario service provider archive, you must use the new library of jrulesbres-setup.jar, located in <InstallDir>/executionserver/lib/ .
<taskdef resource="bres-tasks.properties" > <classpath> <pathelement location="<InstallDir>/executionserver/lib/jrules-bressetup.jar"/> <pathelement location="<InstallDir>/executionserver/lib/jrulesengine.jar"/> </classpath> </taskdef> <property name="ssp.in" value="<InstallDir>/executionserver/applicationservers/vendor/jrules-sspvendor.ear"/> <property name="ssp.out" value="${basedir}/jrules-ssp-My.ear"/> <target name="setup"> <ssp-setup sspInput="${ssp.in}" sspOutput="${ssp.out}" verbose="true"> <xom> <fileset dir="./data"> <include name="loan.jar"/> </fileset> </xom> <configuration log4jFile="./data/log4j.properties" handler="execution.trace.Handler"/> <j2seExecution persistenceMode="file" persistenceProperties="ilog.rules.bres.xu.ruleset.fs.IlrFileRulesetInformationP rovider.repositoryDirPath=c:/res-data-v6" traceLevel="FINE" traceAutoflush="true" plugins="{pluginClass=ilog.rules.bres.ras.plugin.IlrExecutionTracePlugin}, {pluginClass=ilog.rules.res.decisionservice.plugin.IlrWsdlGeneratorPlugin}"/> </ssp-setup> </target>

Where jrules-ssp-vendor.ear and jrules-ssp-My.ear are the filenames of the application server .EAR files.

122

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.0 Checking the Availability of Scenario Service Provider You can check on the availability of the Scenario Service Provider (SSP) as follows:
◆ Enter the URL http://<host>:<port>/ssp. A log on page will appear if SSP is

available.
◆ Through the Rule Execution Server Console. If you use the Test Ruleset feature and SSP

is not available, you will get the error message:
Host and port appear to be responsive but the service does not exist: /ssp/unsecured/XS ◆ Through the Rule Scenario Manager Console, by selecting Admin > SSP Servers.

Deploying the Hosted Transparent Decision Service EAR on WebSphere 6.0 The hosted transparent decision service must be deployed on the same node as the XU. To deploy the hosted transparent decision service EAR on WebSphere Application Server 6.0:
1. Open the Web Sphere Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane, select Local file system and Browse to: <InstallDir>\executionserver\applicationservers\websphere6\jrules -bres-ootbds-WAS6.ear 4. Click Next. 5. Select the checkbox Generate Default Bindings and click Next. 6. Click Continue to accept the security warning. 7. Save to Master Configuration. 8. Click Save to confirm the change. 9. In the left pane, click Applications and Enterprise Applications. 10. In the Enterprise Applications page select JRules Decision Service and click Start to

start the application. Note: By default the ruleset.xmlDocumentDriverPool.maxsize ruleset property value is set to 1. This value could cause a bottleneck if you have several clients executing a hosted transparent decision service concurrently. Increasing the value of this property could significantly increase the performance. A value of 30 could be a good candidate size.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

123

The hosted transparent decision service requires that you set the web container customer property DecodeUrlAsUTF8 to False to support a localized ruleset path, as follows:
1. Open the WebSphere Administrative Console. 2. Click Servers > Application servers > server_name > Web container settings > Web

container.
3. Under Additional Properties, click Custom Properties. 4. Click Add customer properties and enter DecodeUrlAsUTF8 as the name and False

as the value.
5. Click Apply and Save.

Be aware that this setting impacts all applications deployed on the server. For more information on checking that the hosted transparent decision service has been deployed successfully, refer to the Rule Execution Server Console online help. WebSphere 6.0 in Cluster Mode When WebSphere Application Server 6.0 is used in cluster mode, the data source needs to be defined at node level in the cluster (as opposed to cluster level).
Related Concepts

Rule Execution Server Deployment on Clusters
Related Tasks

Installing Rule Execution Server on WebSphere Application Server 5.1 Installing Rule Execution Server on WebSphere Application Server 6.1
Related Reference

Rule Execution Server Database Driver Issues

Installing Rule Execution Server on WebSphere Application Server 6.1
Installing Rule Execution Server on WebSphere Application Server 6.1 includes:
◆ Step 1. Creating Database Resources. ◆ Step 2. Creating a Derby Schema. ◆ Step 3. Changing Persistence on WebSphere 6.1 from the default database persistence to

file persistence, if required.
◆ Step 4. Creating a Data Source and Connection Pool on WebSphere 6.1.

124

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1
◆ Step 5. Deploying the XU RAR on WebSphere 6.1. ◆ Step 6. Deploying the Rule Execution Server Management EAR on WebSphere 6.1. ◆ Step 7. Deploying the Rule Execution Server Console Online Help. ◆ Step 8. Activating Security on WebSphere 6.1 through the definition of a custom registry,

and mapping security roles.
◆ Step 9. Running Rule Execution Server Diagnostic to confirm connectivity. ◆ To enable optional features, refer to:

Deploying the Scenario Service Provider EAR on WebSphere 6.1. Deploying the Hosted Transparent Decision Service EAR on WebSphere 6.1.

WebSphere Application Server 6.1 in Cluster Mode When WebSphere Application Server 6.1 is used in cluster mode, the data source needs to be defined at node level in the cluster (as opposed to cluster level). Step 1. Creating Database Resources Before you can use Rule Execution Server with database persistence you must create a dedicated schema in the database (containing tables, views, and so on). SQL scripts are provided for this task and are located in:
<InstallDir>/executionserver/databases

A readme file in this directory provides additional information on the scripts provided. The schema_derby.sql script creates a schema named BRES, so you may need to reconfigure your datasource so that it connects to the Derby database as user BRES. For the Oracle database, in addition to tables and indexes, a sequence and a trigger are also created. The SQL scripts schema_oracle.sql and schema_oracle_plsql.sql are provided for this task. The scripts should be run in the following sequence:
1. schema_oracle.sql 2. schema_oracle_plsql.sql

When using an Oracle database, you should run all scripts in the SQL Plus client. Any tool that can handle SQL can be used to import and run the SQL scripts. The tools provided for each database include:
◆ cview – Cloudscape ◆ ij command line processor – Derby ◆ command center or db2 command line processor – IBM DB2 ◆ mysql command line processor – MySQL ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

125

◆ sqlplus command line processor – Oracle ◆ PointBase console – Pointbase ◆ Query Tool – SQL Server ◆ isql command line processor – Sybase.

To access the database, the database user must have a user ID and a password. The database user must have complete privileges on the tables and view of the schema (create, insert, delete). They must also have create index privileges. On Oracle, the database user must also have create trigger and create sequence privileges. A client should be installed for the database that you use. Please refer to the documentation of these tools for more information. Note: There is no optimization in the scripts. For better performance, you can modify the parameters that create the resources to fit your database configuration and data.

Step 2. Creating a Derby Schema A sample Derby schema is used in describing the installation of Rule Execution Server. It is assumed that the WebSphere installation home directory is C:/Program Files/IBM/ WebSphere/AppServer and the embedded version of Derby is used. Create a schema in Derby as follows (note that the application server must not be running):
1. Launch <WasInstallDir>/derby/bin/embedded/ij.bat or ij.sh. 2. Connect to the database. For example, to connect to the new database resdb, use the

command:
ij> connect 'jdbc:derby: <was_installation_dir>/derby/databases/ resdb;create=true'; 3. Run the script that creates the database schema: ij> run '<InstallDir>/executionserver/databases/derby/ schema_derby.sql';

If the script is being run for the first time, some errors related to the drop statements may occur.
4. Close the ij utility: ij> quit; 5. Start the application server.

126

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1

Step 3. Changing Persistence on WebSphere 6.1 By default, persistence is set to datasource. To help you change the persistence type, an Ant script is provided to create a new instance of the management and monitoring model and the Execution Unit (XU) using a specific persistence mode. The ressetup.xml file is located in:
<InstallDir>/executionserver/bin

The Ant task element attributes are as follows:

Table 10 Ant Task Element Attributes for the ressetup.xml File Element Attributes xuinput xuoutput managementinput managementoutput Description Path to input the XU .rar. Path to output the XU .rar Path to input the management .ear Path to output the management .ear Required one of the pairs input/ output is required

The Ant task element properties are as follows:

Table 11 Ant Task Element Properties for the ressetup.xml File Element Property persistence.type Description The persistence type. The possible values are: ◆ file (for a file persistence in J2SE)

Required no

datasource (for a database persistence in J2EE) jdbc (for a database persistence in J2SE)

persistence.jdbc.user

Login to use with the database connection for J2SE. no no

persistence.jdbc.crypted Password will be encrypted in the XU configuration .password.enabled file. persistence.jdbc. password persistence.jdbc.driver

A password to use with the database connection for no J2SE. A driver implementation class to establish a connection with the database. no

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

127

Table 11 Ant Task Element Properties for the ressetup.xml File Element Property Description Required no no

persistence.datasource. The JNDI name of the datasource. jndi persistence.file.directory Where the path to the top directory containing rulesets is.

The following example creates a new XU (.rar) and a new management stack (EAR) that are configured to use file persistence:
<import file="${executionserver.home}/lib/classpath-executionserver.xml"/> <taskdef resource="res-tasks.properties" > <classpath refid="executionserver.setup.classpath"/> </taskdef> <res-setup xuinput="../applicationservers/websphere6/jrules-bres-xu-WAS6.rar" xuoutput="myxu.rar" managementInput="../applicationservers/websphere6/jrules-bresmanagement-WAS6.ear" managementOutput="mymgmt.ear" > <property name="persistence.type" value="file" /> <property name="persistence.datasource.jndi" value="java:/jdbc/ mydatasource" /> </res-setup>

Step 4. Creating a Data Source and Connection Pool on WebSphere 6.1 The data source is based on the database schema created, following the guidelines in Step 1. Creating Database Resources. Creating a JDBC Provider To create a JDBC provider:
1. Log in to the Integrated Solutions Console. 2. In the left pane open Resources > JDBC and click JDBC Providers. 3. In the right panel in Scope select the Node and Server and click New. 4. In Step 1 select the database type, provider type, and an implementation type that

supports XA features. For example, Derby, Derby JDBC Provider, and XA data source. Click Next.
5. Step 2 is skipped and a summary is provided in Step 3, as follows:

128

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1

Check that the class path to the JAR of your driver and the implementation class are correct. Default values are usually sufficient.
6. Click Finish and Save to save the changes to the master configuration.

Note: Some drivers (such as Oracle OCI drivers) need to access additional libraries at runtime (.dll or.so files). As a consequence, you will have to set up your working environment in order to access these libraries (PATH, LD_LIBRARY_PATH, and so on). You may have to restart your server in order to take these changes into account.
7.

Creating a Data Source and Connection Pool To create a data source and a connection pool:
1. In the Integrated Solutions Console open Resources > JDBC and Data sources. 2. In the right panel in Scope select the Node and Server and click New. 3. In Step 1, enter resdatasource as the Data source name, jdbc/bresdatasource

for the JNDI name and click Next. Note: The name of the data source is not important here but the JNDI name is. Be sure to set it to jdbc/bresdatasource, otherwise Rule Execution Server will not be able to use the data source.
4. In Step 2 select the JDBC provider you created in the previous section and click Next.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

129

5. In Step 3, enter the specific database properties for the data source. For example, this is the path you used to create resdb in Step 2. Creating a Derby Schema. De-select Use

this data source in container managed persistence (CMP). Click Next.
6. In Step 4, a summary of the data source is provided. Click Finish and Save to save the

changes to the master configuration. Creating J2C Authentication Data
1. In the Integrated Solutions Console open Resources > JDBC and Data sources. 2. Click resdatasource. 3. Under Related Items, click JAAS - J2C authentication data. 4. Click New and set the fields as follows:

Alias: ResDerbyUser User ID: bres Password: bres Click Apply and Save directly to the master configuration.
5. Open Resources > JDBC and Data sources and click resdatasource. 6. In the section Component-managed authentication alias, select the DerbyUser alias. 7. In the section Container-managed authentication, select DerbyUser for the

Container-managed authentication alias.
8. Click Apply and Save directly to the master configuration.

Setting Custom Properties Depending on the database you want to connect to, you have different properties to define. Table 12 presents the minimum set of properties required to define the supported databases.

130

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1 If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.
Table 12 Database Driver Properties Database DB2 Universal JDBC Driver Properties

databaseName – Actual database name if driverType is set to 4, or a locally cataloged database name if driverType is set to 2 driverType – Possible values are 2 or 4

The following properties are required only if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – Locally cataloged database name driverType – Only value is 2 databaseName – For example, Sample URL – For example, jdbc:oracle:oci:@sample Database Name: path to the location of the database files.

DB2 Universal JDBC XA Driver DB2 legacy CLI-based Type 2 Oracle JDBC Driver Derby

◆ ◆

For more information, refer to the Derby documentation.

To set custom properties:
1. In the Integrated Solutions Console open Resources > JDBC and click Data sources. 2. Click the data source you want to customize. 3. Under Additional Properties, click Custom properties. 4. Change an existing property or create a new one by clicking New. 5. Click OK and Save to save the changes to the master configuration.

Connecting to the Database To test the connection to your database:
1. In the Integrated Solutions Console open Resources > JDBC and click Data sources. 2. Select the data source you want to test and click Test connection.

Step 5. Deploying the XU RAR on WebSphere 6.1 To deploy the XU RAR on WebSphere Application Server:
1. Open the Integrated Solutions Console. ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

131

2. In the left panel, open Resources > Resource Adapters and click Resource adapters. 3. In the right panel, select the Node and Server and click Install RAR. 4. In the right panel, select Local path and Browse to:
<InstallDir>/executionserver/applicationservers/websphere6/jrules-bres-xuWAS6.rar

Click Next.
5. In the right panel, configure the RAR or accept the default settings and click OK and

Save directly to the master configuration.
6. In the Resource adapters window, set Scope to All scopes and click XU. 7. Under Additional Properties, click J2C connection factories and New. 8. Enter the following values:

Name xu_cf JNDI name eis/XUConnectionFactory
9. Click OK and Save to save the changes to the master configuration.

Step 6. Deploying the Rule Execution Server Management EAR on WebSphere 6.1 To deploy the EAR on WebSphere Application Server:
1. Open the Integrated Solutions Console. 2. In the left panel, open Applications and click Install New Application.

132

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1
3. In the right panel, select Local file system and Browse to:
<InstallDir>/executionserver/applicationservers/websphere6/jrules-bresmanagement-WAS6.ear

4. Select the checkbox Show me all installation options and parameters. Click Next. 5. Select the checkbox Generate Default Bindings and click Next. 6. Click Continue to accept the security warning. 7. In Step 1 click Next to accept the default settings. 8. In Step 2 select ILOG Rule Execution Server Console and click Next. 9. In Step 3 click Next to accept the default settings. 10. In Step 4 select ILOG Rule Execution Server Console and click Next. 11. In Step 5 select ILOG Rule Execution Server Console and click Next.

You will activate security in Step 8. Activating Security on WebSphere 6.1.
12. In Step 6 select ILOG Rule Execution Server Console and click Next to accept the

default settings.
13. In Step 7 and Step 8 click Next. 14. Step 9 provides a summary. Click Finish. When the installation has completed click

Save directly to the master configuration. Defining the Class Loading Sequence
1. In the left panel open Applications > Enterprise Applications. Click ILOG Rule

Execution Server.
2. Click Class loading and update detection. 3. For Polling interval for updated files, specify 0. 4. Select the checkbox Classes loaded with application class loader first. 5. Click OK. 6. Click Manage Modules. 7. Click ILOG Rule Execution Server Console. 8. Under General Properties, for Class loader order select Classes loaded with

application class loader first.
9. Click OK and Save directly to the master configuration. 10. In the left pane, open Applications > Enterprise Applications.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

133

11. In the Enterprise Applications page select ILOG Rule Execution Server and click

Start to start the application. Step 7. Deploying the Rule Execution Server Console Online Help To deploy the online help for the Rule Execution Server Console:
1. Open the Integrated Solutions Console. 2. In the left pane, open Applications and click Install New Application. 3. In the right pane, select Local file system and Browse to: <InstallDir>/executionserver/online-help/resonlinehelp.ear 4. Select the checkbox Show me all installation options and parameters. Click Next. 5. Select the checkbox Generate Default Bindings and click Next. 6. Click Continue to accept the security warning. 7. In Step 1 through Step 7 click Next to accept the default settings. 8. Step 8 provides a summary. Click Finish. When the installation has completed click

Save directly to the master configuration.
9. In the left pane, open Applications > Enterprise Applications. 10. In the Enterprise Applications page select Rule Execution Server Console Online

Help and click Start to start the applications. Deploying Help in a Non-secure Context Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this:
1. Extract the jrules-bres-management.war from the management EAR. 2. In jrules-bres-management.war, edit the file web.xml and in the context parameter ilog.rules.res.HELP_CONTEXT, specify an absolute URL (for example, http://myserver/resonlinehelp). 3. Save the file and repackage the WAR into the EAR.

You may need to restart WebSphere and the Rule Execution Server Console for the online help to function correctly. Step 8. Activating Security on WebSphere 6.1 WebSphere Application Server Version 6.1 provides security infrastructure and mechanisms to protect sensitive J2EE resources and administrative resources and to address enterprise 134
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1 end-to-end security requirements on authentication, resource access control, data integrity, confidentiality, privacy, and secure interoperability. The security layers in WebSphere Application Server are shown in the following:

WebSphere Application Server supports the J2EE model for creating, assembling, securing, and deploying applications. By default, the Rule Execution Server Console does not require security in WebSphere. However, to activate access control for Rule Execution Server in WebSphere 6.1, perform the following steps. Defining a Custom Registry WebSphere uses various kinds of user registries (OS, LDAP, or Custom). This section explains how to configure a user registry. WebSphere provides a custom registry sample named FileRegistrySample. This sample enables the definition of the username/passwords/groups in text files without encryption. The relationship between the various roles/groups/users in the proposed custom definition is as follows:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

135

To define a custom registry:
1. Log on to the Integrated Solutions Console. To define the path of the files, you need to

define two custom properties.
2. In the left panel open Security > Secure administration, applications, and

infrastructure. Enable administrative and application security and click Security Configuration Wizard.
3. In Step 1, specify the level of protection and click Next. 4. In Step 2 select Standalone custom registry and click Next. 5. According to your USER_INSTALL_ROOT variable (WAS_HOME/profiles/ PROFILENAME, by default), create a directory named res and two files named users.props and groups.props in the directory ${USER_INSTALL_ROOT}/res.

The property files must define: A websphere/wasadmin user for WebSphere Console authentication. A bres/bresgroup for the Rule Execution Server Console authentication. The users.props file must contain the following users definition:
# # # # # # # Format: name:passwd:uid:gids:display name where name = userId/userName of the user passwd = password of the user uid = uniqueId of the user gid = groupIds of the groups that the user belongs to display name = a (optional) display name for the user

136

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1
# websphere:websphere:100:0:Websphere Administrator bres:bres:2:1:BRE Server Administrator

The groups.props file must contain the following groups definition:
# Format: # name:gid:users:display name # where name = groupId of the group # gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group # wasadmin:0:websphere:Administrative Group bresgroup:1:bres:BRE Server Admin Group

6. In Step 3, the Primary administrative user name should be websphere. For Name and Value specify usersFile and groupsFile and their corresponding Value, or path (${USER_INSTALL_ROOT}/jrules/users.props and ${USER_INSTALL_ROOT}/ jrules/groups.props, respectively).

Click Next.
7. In Step 4, review the security configuration summary and click Finish. 8. At the top of the page click Save. Click the Save button to confirm a save to the master

configuration.
9. Click Save. You will need to restart the server to apply the settings.

Mapping the bresgroup to the Monitor Role To access the MBeans of the Rule Execution Server model, an application must have sufficient security credentials, restricted to the Monitor role in the WebSphere authentication system. Rule Execution Server users can be given access to the MBeans of the model by configuring a mapping between the bresgroup declared in the custom registry and the Monitor role, as follows:
1. In the Integrated Solutions Console open Users and Groups > Administrative Group

Roles.
2. Click Add. Enter the group name bresgroup and for Role(s) select Monitor.

Click Apply.
3. Click the Save directly to the master configuration.

Mapping Security Roles to Users/Groups When the global security is enabled you can define the security mapping for the Rule Execution Server Console.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

137

1. Open Applications > Enterprise Applications > ILOG Rule Execution Server >

Security role to users/group mapping to open the following:

2. To define how the bres_admin role is mapped in the application server security, select the bres_admin role and click Lookup users and Search to display the following:

138

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1

3. Select the bres item. To do this click on it under Available and use >> to move it to the

Selected column.
4. Click OK to return to the Security role to user/group mapping page. 5. Select the bres_admin role. 6. Click Lookup groups and click Search to display the following:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

139

7. Select the bresgroup item. To do this click on it under Available and use >> to move it

to the Selected column.
8. Click OK to return to the Mapping Users to Roles page. 9. Check the All authenticated? checkbox.

140

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1

Click OK.
10. At the top of the page click Save directly to the master configuration.

To apply these settings to the Rule Execution Server Console, you must stop and restart the application from the list of the installed applications in the Integrated Solutions Console through Applications > Enterprise Applications.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

141

Security Policies for the Rule Execution Server Console When the global security of WebSphere is activated, the MBean server cannot be accessed from the deployed application. These security policies must be overridden for the Rule Execution Server Console because it needs to record and manage a set of MBeans. Rule Execution Server is packaged with a specific policy file that overrides the server policies. This file is packaged in an EAR file was.policy in the META-INF directory. Step 9. Running Rule Execution Server Diagnostic Verify that Rule Execution Server has been successfully installed by launching the Rule Execution Server diagnostic:
1. Open the Rule Execution Server Console by typing bres at the root URL on the host

machine:
http://localhost:9081/bres

If your browser is not running on the same host as the application server, you can replace localhost with <host>.
2. Sign in to the Rule Execution Server Console (the default user ID and password is bres/ bres). 3. In the Rule Execution Server Console click the Diagnostics tab. 4. Click Run Diagnostics. You should see a report similar to the following:

142

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1

Important: To let a scalable number of users access resources through the Java components, JCA assigns the task of implementing connection pooling to application server vendors. On WebSphere Application Server, the pool size is not instantiated beforehand and therefore prevents the server diagnostic from validating a Rule Execution Server before the first execution of a rule engine. The diagnostic remains useful to validate a configuration, especially in a cluster, and to check invoked XUs registered with the management model. If the diagnostic is performed before any XUs have been invoked, the test is passed and a message is displayed verifying that no XU(s) have been initialized.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

143

Deploying the Scenario Service Provider EAR on WebSphere 6.1 The scenario service provider EAR must be deployed on the same server as the XU. To deploy the EAR:
1. Open the Integrated Solutions Console. 2. In the left pane, open Applications and click Install New Application. 3. In the right pane, select Local file system and Browse to:
<InstallDir>/executionserver/applicationservers/websphere6/jrules-sspWAS6.ear

4. Select the checkbox Show me all installation options and parameters. Specify a Context root of ssp. Click Next. 5. Select the checkbox Generate Default Bindings and click Next. 6. Click Continue to accept the security warning. 7. In Step 1 through Step 7 click Next to accept the default settings. 8. In Step 8 if you have activated security select bres_admin and click Lookup groups. 9. Click Search. 10. Select the bresgroup item. To do this click on it under Available and use >> to move it

to the Selected column.
11. Click OK to return to the Mapping Users to Roles page. Click Next. 12. Click Finish. After the installation has completed click Save directly to the master

configuration.
13. In the left panel open Applications > Enterprise Applications. Click SSP. 14. Click Class loading and update detection. 15. For Polling interval for updated files, specify 0. Select the checkbox Classes loaded

with application class loader first.
16. Click OK. 17. Click Manage Modules. 18. Click ssp. 19. Under General Properties, for Class loader order select Classes loaded with

application class loader first.
20. Click OK.

144

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1
21. Click OK and Save directly to the master configuration. 22. In the left pane, open Applications > Enterprise Applications. 23. In the Enterprise Applications page select jrules-ssp-WAS6 and click Start to start the

application. The SPP application can be configured in the web.xml of the Rule Execution Server Console using the parameter name:
ilog.rules.res.SSP_CONTEXT

Configuring the Scenario Service Provider The following is an example ANT task to change the configuration of the SSP archive. To update the scenario service provider archive, you must use the new library of jrulesbres-setup.jar, located in <InstallDir>/executionserver/lib/ .
<taskdef resource="bres-tasks.properties" > <classpath> <pathelement location="<InstallDir>/executionserver/lib/jrules-bressetup.jar"/> <pathelement location="<InstallDir>/executionserver/lib/jrulesengine.jar"/> </classpath> </taskdef> <property name="ssp.in" value="<InstallDir>/executionserver/applicationservers/vendor/jrules-sspvendor.ear"/> <property name="ssp.out" value="${basedir}/jrules-ssp-My.ear"/> <target name="setup"> <ssp-setup sspInput="${ssp.in}" sspOutput="${ssp.out}" verbose="true"> <xom> <fileset dir="./data"> <include name="loan.jar"/> </fileset> </xom> <configuration log4jFile="./data/log4j.properties" handler="execution.trace.Handler"/> <j2seExecution persistenceMode="file" persistenceProperties="ilog.rules.bres.xu.ruleset.fs.IlrFileRulesetInformationP rovider.repositoryDirPath=c:/res-data-v6" traceLevel="FINE" traceAutoflush="true" plugins="{pluginClass=ilog.rules.bres.ras.plugin.IlrExecutionTracePlugin}, {pluginClass=ilog.rules.res.decisionservice.plugin.IlrWsdlGeneratorPlugin}"/> </ssp-setup> </target>

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

145

Where jrules-ssp-vendor.ear and jrules-ssp-My.ear are the filenames of the application server .EAR files. Checking the Availability of Scenario Service Provider You can check on the availability of the Scenario Service Provider (SSP) as follows:
◆ Enter the URL http://<host>:<port>/ssp. A log on page will appear if SSP is

available.
◆ Through the Rule Execution Server Console. If you use the Test Ruleset feature and SSP

is not available, you will get the error message:
Host and port appear to be responsive but the service does not exist: /ssp/unsecured/XS ◆ Through the Rule Scenario Manager Console, by selecting Admin > SSP Servers.

Deploying the Hosted Transparent Decision Service EAR on WebSphere 6.1 The hosted transparent decision service must be deployed on the same node as the XU. To deploy the hosted transparent decision service EAR on WebSphere Application Server 6.1:
1. Open the Integrated Solutions Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane, select Local file system and Browse to:
<InstallDir>/executionserver/applicationservers/websphere6/jrules-bresootbds-WAS6.ear

4. Select the checkbox Show me all installation options and parameters. 5. Click Next. 6. Select the checkbox Generate Default Bindings and click Next. 7. Click Continue to accept the security warning. 8. For Step 1 to Step 7 click Next to accept the default settings. 9. Step 8 provides a summary. Click Finish. 10. Once the installation has completed click Save directly to the master configuration. 11. In the left panel open Applications > Enterprise Applications. Click the JRules

Decision Service.
12. Click Class loading and update detection. 13. For Polling interval for updated files, specify 0.

146

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Execution Server on WebSphere Application Server 6.1
14. Select the checkbox Classes loaded with application class loader first. 15. Click OK. 16. Click Manage Modules. 17. Click DecisionService. 18. Under General Properties for Class loader order select Classes loaded with

application class loader first.
19. Click OK. 20. Click OK and Save directly to the master configuration. 21. In the left panel, open Applications > Enterprise Applications. 22. In the Enterprise Applications page select JRules Decision Service and click Start to

start the application. Note: By default the ruleset.xmlDocumentDriverPool.maxsize ruleset property value is set to 1. This value could cause a bottleneck if you have several clients executing a hosted transparent decision service concurrently. Increasing the value of this property could significantly increase the performance. A value of 30 could be a good candidate size. The hosted transparent decision service requires that you set the web container customer property DecodeUrlAsUTF8 to False to support a localized ruleset path, as follows:
1. Open the Integrated Solutions Console. 2. Click Servers > Application servers and the server name. 3. Under Container Settings click Web container settings. 4. Click Web container. Under Additional Properties click Custom Properties. 5. Click New and enter DecodeUrlAsUTF8 as the Name and False as the Value. 6. Click Apply and Save directly to the master configuration.

Be aware that this setting impacts all applications deployed on the server. For more information on checking that the hosted transparent decision service has been deployed successfully, refer to the Rule Execution Server Console online help.
Related Concepts

Rule Execution Server Deployment on Clusters
Related Tasks

Installing Rule Execution Server on WebSphere Application Server 5.1

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

147

Installing Rule Execution Server on WebSphere Application Server 6.0
Related Reference

Rule Execution Server Database Driver Issues

Rule Execution Server Database Driver Issues
The known issues include:
◆ Cloudscape XA Features ◆ Null Default Resource Provider Error ◆ ORACLE XA Features ◆ JDBC Not Bound

Cloudscape XA Features The driver version must be at least 5.1.6.12. This version can be retrieved with the latest Fix Pack for WebSphere. Null Default Resource Provider Error If you receive this message, check in the bres-console.log file for the original SQL error. In WebSphere if the SQL message is SQL operations are not allowed with no global transaction by default for XA drivers, set the JDBC connection pool property SupportsLocalTransaction to true if your XA driver supports performing SQL operations with no global transaction. Activate this option in WebSphere as follows:
1. In the WebSphere Administrative Console, select Services > JDBC > Connection

Pools.
2. Choose your connection pool. 3. In the tab Configuration, choose the tab Connections. 4. Display the Advanced Options by clicking Show. 5. At the bottom of the page, check Supports Local Transaction. 6. Restart your server.

148

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Rule Execution Server Deployment on Clusters

ORACLE XA Features If you need to use XA features with an Oracle 9i database, you have to configure your database and the server JVM. To do so, you have to run the two scripts initjvm.sql and initxa.sql that are located in the directory:
ORACLE_HOME/javavm/install

For more information, please contact your DBA or your local ORACLE support. JDBC Not Bound This error message is raised when an error occurs during the creation of the data source. Refer to the traces to locate the original cause. In the vast majority of cases one of the following is likely:
◆ A directory does not exist or cannot be read or written to (Derby). ◆ There is a missing schema or table. ◆ There are missing privileges to access the database resource.

Rule Execution Server Deployment on Clusters
Within the J2EE framework, clusters provide mission-critical services to ensure minimal downtime and maximum scalability. A cluster is a group of application servers that transparently run your J2EE application as if it were a single entity. Cluster implementations on J2EE application servers come with their own set of terminology and each of the following terms are important to understand how your cluster will perform:
◆ Cluster and component failover services. ◆ HTTP session failover. ◆ Single points of failure in a cluster topology.

Rule Execution Server supports: BEA clusters, IBM clusters, JBoss clusters, and clusters on Oracle 10g Release 3 (10.1.3).
Related Concepts

Cluster Configuration Cluster Topology

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

149

Cluster Configuration On a cluster configuration, an XU is deployed on each node—there is one XU for each node of a cluster. Application servers administration tools handle cluster deployment. An XU instance can only be used by a local (same node) client. The client and the XU communicate via direct Java method calls, so the XU does not need serialization.

Related Concepts

Cluster Topology

150

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Rule Execution Server Deployment on Clusters

Cluster Topology A cluster using Rule Execution Server involves a collaboration between the Rule Execution Server MBeans. The topology of the cluster has significant influence on the management of the notification mechanism when a resource is changed. The following figure shows a basic scenario of a distributed notification mechanism in a cluster. This type of mechanism is likely to be used several times by the management model to interact with the various Execution Unit (XU) instances in a cluster. An XU MBean of type IlrXU is deployed with the XU to collaborate with the Rule Execution Server JMX infrastructure.

The following sequence applies:
1. A management client sets a resource on a ruleset MBean. 2. The ruleset makes a query to the MBean Server to retrieve all the XU instances in the

cluster (this operation requires a specific implementation for each application server).
3. A notification is sent to each instance. Related Concepts

Cluster Configuration IBM WebSphere Clusters When deploying the different Rule Execution Server components on a WebSphere application server it is important to deploy the management module on a single server in the

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

151

WebSphere cell. Only a single management module is necessary to manage all Execution Units (XU) on each cluster. It is important to define a logical subset of servers:
◆ A standalone server of the cell outside the cluster needs be dedicated to the deployment

of the Rule Execution Server management module. There is no need to have a failover mechanism.
◆ A cluster of servers dedicated to the deployment of the XU. You can only install the XU (.rar file) at the node level, and you should declare the resource adapter at the node or

the server level so that every server in the cluster contains this definition.
◆ The data source needs to be defined at the node level.

This configuration will guarantee that a single management module is instantiated in the WebSphere cell.

The notification mechanism in WebSphere uses a simpler pattern compared to BEA WebLogic because the Rule Execution Server MBeans take advantage of the distributed MBean mechanism provided by WebSphere. When an MBean is registered in a server in WebSphere, it is automatically visible to the Deployment Manager MBean Server.

152

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Rule Execution Server Deployment on Clusters To notify each XU of changes in the management model, it is simply a matter of querying the Deployment Manager MBean Server and notifying each XU retrieved by the query.

Related Concepts

Cluster Configuration Cluster Topology
Related Reference

Multiple deployment manager cells: http://publib.boulder.ibm.com/ infocenter/wsphelp/index.jsp?topic=/com.ibm.websphere.nd.doc/ info/ae/ae/cins_mudomain.html Tips for WebSphere v5 Network Deployment Administrators: http://
websphere.sys-con.com/read/45408.htm http://publib.boulder.ibm.com/infocenter/wsphelp/ index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/ cins_mudomain.html

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

153

154

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Servers

This section provides instructions on installing the Rule Scenario Manager JRules module on WebSphere Application Servers.
In this Section

Installing Rule Scenario Manager on WebSphere Application Server 5.1 Installing Rule Scenario Manager on WebSphere Application Server 6.0 Installing Rule Scenario Manager on WebSphere Application Server 6.1 ILOG provides a specific integration extension for the IBM WebSphere Process Server (WPS) platform: http://www.ilog.com/solutions/business/bpm/ibmwps.cfm

Installing Rule Scenario Manager on WebSphere Application Server 5.1
Installing Rule Scenario Manager on WebSphere Application Server 5.1 requires the prior deployment of Rule Execution Server (see Installing Rule Execution Server on WebSphere Application Server 5.1). The installation of Rule Scenario Manager on WebSphere Application Server 5.1 involves the following steps:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

155

◆ Step 1. Creating a Data Source and Connection Pool. ◆ Step 2. Deploying Rule Scenario Manager EARs on WebSphere 5.1. ◆ Step 3. Changing the Class Loader Mode on WebSphere 5.1. ◆ Step 4. Activating Security through the definition of a custom registry, and mapping

security roles.
◆ Step 5. Changing the Configuration of the Rule Scenario Manager Console.

By default, persistence is set at the database level. For information on configuring the persistence mode of Rule Execution Server, see Installing Rule Execution Server on WebSphere Application Server 5.1. Using an Oracle 9i or 10g Database If you intend to use an Oracle 9i or 10g database:
1. Unzip the file jrules-rsm-WAS5.ear. 2. Extract and unzip the file jrules-rsm.war. 3. Extract the file: \WEB-INF\classes\resources\config\jpox.ds.properties

and add the following property:
javax.jdo.mapping.Schema=XXX

where XXX is the name, in upper case, of the schema/user to use by default for all classes persisted using this PMF. JPOX will prefix all table names with this schema name if the RDBMS supports specification of schema names in DDL.
4. Re-zip the files into the WAR, and the WAR into the EAR. 5. Deploy the EAR, as described in Step 2. Deploying Rule Scenario Manager EARs on

WebSphere 5.1. Step 1. Creating a Data Source and Connection Pool To create a JDBC provider:
1. Log on to the WebSphere Administrative Console. 2. In the left pane click Resources and JDBC Providers. 3. The default scope of the provider used by Rule Scenario Manager is Server. In the right

pane select Server and click Apply. Some default providers should appear if you use the default configuration. 156
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 5.1
4. Click the New button to create a new JDBC provider. It is not mandatory to choose an

implementation which supports XA features, unless you use the same database as the Rule Execution Server.
5. For JDBC Providers choose the database type and click OK. In General Properties,

check that the class path to the JAR of your driver and the implementation class are correct. Default values are usually sufficient. Click OK. Note: Some drivers (such as Oracle OCI drivers) need to access additional libraries at runtime (.dll or .so files). As a consequence, you will have to set up your working environment in order to access these libraries (PATH, LD_LIBRARY_PATH, and so on). You may have to restart your server in order to take these changes into account. Creating a Data Source and Connection Pool To create a data source and a connection pool:
1. Open Resources > JDBC Providers. Click the JDBC provider you want to define the

data source and connection pool for and under Additional Properties, click Data Sources.
2. Click New to create a new data source. 3. Enter rsmdatasource as the Name of the data source, jdbc/rsmdatasource for the

JNDI Name. Note: The name of the data source is not important here but the JNDI name is. Be sure to set it to jdbc/rsmdatasource, otherwise Rule Scenario Manager will not be able to use the data source.
4. Click Apply. A connection pool is automatically created and associated with the data

source.
5. Click Custom Properties in Additional Properties.

Depending on the database you want to connect to, you have different properties to define. Table 13 presents the minimum set of properties required to define the supported

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

157

databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.
Table 13 Database Driver Properties Database DB2 Universal JDBC Driver Properties

databaseName – Actual database name if driverType is set to 4, or a locally cataloged database name if driverType is set to 2 driverType – Possible values are 2 or 4

The following properties are required only if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – Locally cataloged database name driverType – Only value is 2 databaseName – For example, Sample URL – For example, jdbc:oracle:oci:@sample

DB2 Universal JDBC XA Driver DB2 legacy CLI-based Type 2 Oracle JDBC Driver

◆ ◆

6. If you have applied IBM patch PK13771, continue to Step 7. Otherwise, click Apply and

Save at the top of the page to confirm a save to the master configuration.
7. At the bottom of the page, under Related Items click J2C Authentication Data

Entries.
8. Click New. 9. Define an Alias name. For example, DbUser. 10. Define the User ID and Password used to access the database.

Click OK.
11. In the rsmdatasource page, for Component-managed Authentication Alias select the alias you created (DbUser). 12. Click Apply and Save at the top of the page to confirm a save to the master

configuration. Connecting to the Database To test the connection to your database:
1. Click JDBC Providers in the left frame. 2. Click the name of your provider. 3. Under Additional Properties click Data Sources.

158

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 5.1
4. Click the name of your data source. 5. Click the Test Connection button.

If the test fails, check that the information you provided (user, password, and so on) is correct. For more information on connection pools and data sources, please refer to the documentation of IBM WebSphere. Step 2. Deploying Rule Scenario Manager EARs on WebSphere 5.1 To deploy the EARs on WebSphere Application Server:
1. Open the WebSphere Administrative Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane select Local path and Browse to: <InstallDir>/scenariomanager/applicationservers/websphere5/ jrules-rsm-WAS5.ear 4. Click Next. 5. Select Generate Default Bindings and click Next to accept the default settings for the

application bindings. Click Continue to accept the security warning.
6. Click Next to accept the default settings for Step 1 of the application installation. 7. For Step 2 use the following settings:

Click Next.
8. Click Next to complete Step 3. 9. Click Next to accept the default settings in Step 4.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

159

10. In Step 5 click Next for no security. For information on activating security, see Step 4.

Activating Security.
11. In Step 6, click Finish to complete the configuration. 12. Repeat the above steps to deploy the RSM online help: <InstallDir>/scenariomanager/online-help/rsmonlinehelp.ear 13. Once the installation is complete, click Save to Master Configuration. 14. Click the Save button to confirm a save to the master configuration. 15. In the left pane, click Applications and Enterprise Applications. 16. In the Enterprise Applications page select RSM and click Start to start the application.

Manually Deploying Help in a Non-secure Context Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this:
1. Extract the file web.xml from your RSM Console EAR. 2. Edit the file web.xml and in the context parameter ilog.rules.rsm.HELP_CONTEXT, specify an absolute URL (for example, http://myserver/rsmonlinehelp). 3. Save the file and repackage it into the EAR.

You may need to restart WebSphere and the Rule Scenario Manager for the online help to function correctly. You can use the rsm-console-setup ANT task described in Step 5. Changing the Configuration of the Rule Scenario Manager Console to deploy the help. Step 3. Changing the Class Loader Mode on WebSphere 5.1 Set the class loader mode to Parent Last for the Rule Scenario Manager EAR and WAR to avoid problems in generating reports, as follows:
1. Log in to the WebSphere Administrative Console. 2. Select Application > Enterprise Applications and click RSM. 3. In the section Classloader Mode, select Parent Last.

Click Apply.
4. Scroll down to the section Related Items.

Click on Web Modules and then on jrules-rsm.war.

160

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 5.1
5. In the section Classloader Mode, select PARENT_LAST. Click OK. 6. Click Save to apply changes to the master configuration and when prompted, Save again

to confirm the changes. Step 4. Activating Security WebSphere Application Server Version 5.1 provides security infrastructure and mechanisms to protect sensitive J2EE resources and administrative resources and to address enterprise end-to-end security requirements on authentication, resource access control, data integrity, confidentiality, privacy, and secure interoperability. The security layers in WebSphere Application Server are shown in the following:

WebSphere Application Server supports the J2EE model for creating, assembling, securing, and deploying applications. By default, the Rule Scenario Manager Console does not require security in WebSphere. However, to activate access control for Rule Scenario Manager in WebSphere 5.1, follow the steps in the next section. Defining a Custom Registry WebSphere uses various kinds of user registries (OS, LDAP, or Custom). This section explains how to configure a user registry. WebSphere provides a custom registry sample named FileRegistrySample. This sample enables the definition of the username/passwords/groups in text files without encryption. The relationship between the various roles/groups/users in the proposed custom definition is as follows:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

161

To define a custom registry:
1. To define the path of the files, you need to define two custom properties.

In the WebSphere Administrative Console, click Security. Under User Registries click Custom to open the following:

As the Server User ID and Server User Password, enter websphere.
2. Under Additional Properties click Custom Properties. 3. Click New. Define the usersFile property with the path to the file that contains the

user definition.

162

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 5.1

Set the Name to usersFile and Value to ${USER_INSTALL_ROOT}/jrules/ users.props. Click OK.
4. Click New. Define the groupsFile property with the path to the file that contains the

group definition.

Set Name to groupsFile and enter the Value ${USER_INSTALL_ROOT}/jrules/ groups.props. Click OK.
5. Click Save at the top of the page and the Save button to update the master repository

with your changes.
6. According to your USER_INSTALL_ROOT variable (WAS_HOME, by default), create a directory named rsm and then create two files named users.props and groups.props in ${USER_INSTALL_ROOT}/jrules.

The property files must define the following:
a. A websphere/wasadmin user for the WebSphere Administrative Console

authentication.
b. A rsm/rsmgroup for the Rule Scenario Manager Console authentication.

The users.props file must contain the users definition:
# # # # Format: name:passwd:uid:gids:display name where name = userId/userName of the user passwd = password of the user

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

163

# uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user # websphere:websphere:100:0:Websphere Administrator rsm:rsm:2:1:Rule Scenario Manager User

The groups.props file must contain the groups definition:
# Format: # name:gid:users:display name # where name = groupId of the group # gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group # wasadmin:0:websphere:Administrative Group rsmgroup:1:rsm:Rule Scenario Manager User Group

Enabling Global Security After the configuration of the custom user registry, you can enable the server security. To enable security settings:
1. Click Security and Global Security. 2. Check Enabled. Note that Enforce Java 2 Security is selected automatically. 3. For Active user registry select Custom. 4. Click Apply and Save.

Note: You may be prompted to enter the Server User ID and Server User Password. By default this is websphere/websphere. Click Apply and Save.
5. Restart your server for the changes to take effect. You will be required to log on using a User ID/Password. By default this is websphere/websphere.

Mapping the rsmgroup to the Operator Role To access the MBeans of the Scenario Service Provider model, an application must have sufficient security credentials, restricted to the Administrator role in the WebSphere authentication system. This is managed by the Rule Execution Server, and is described in Installing Rule Execution Server on WebSphere Application Server 5.1. It is sufficient for Rule Scenario Manager users to configure a mapping between the
rsmgroup declared in the custom registry and the Operator role, as follows: 1. In the WebSphere Administrative Console open System Administration > Console

Groups and click Add.
2. Specify the group rsmgroup.

164

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 5.1
3. In Role(s) select Operator.

4. Click Apply. 5. Click OK and restart the server.

Mapping Security Roles to Users/Groups When the global security is enabled you can define the security mapping for the Rule Scenario Manager Console through Applications > Enterprise Applications > RSM > Additional Properties > Map Security roles to users/groups. To define how the rsm_user role is mapped in the application server security:
1. Select the rsm_user role.

2. Click Lookup users. The following is displayed:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

165

3. Click Search. 4. Select the rsm item. 5. Click OK to return to the Mapping Users to Roles page. 6. Select the rsm_user role. 7. Click Lookup groups. The following is displayed:

166

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 5.1

8. Click Search. 9. Select the rsmgroup item. 10. Click OK to return to the Mapping Users to Roles page. 11. Check the All Authenticated? checkbox.

12. Click OK.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

167

13. To apply these settings to the Rule Scenario Manager Console, you must restart the

application from the list of the installed applications in the WebSphere Administrative Console. Security Policies for the Rule Scenario Manager Console When the global security of WebSphere is activated, the MBean server cannot be accessed from the deployed application. These security policies must be overridden for the Rule Scenario Manager Console because it needs to record and manage a set of MBeans. Rule Scenario Manager is packaged with a specific policy file that overrides the server policies. This file is supplied for the Console and packaged in the jrules-rsm-WAS5.ear file; the file is called was.policy located in the meta-inf directory. Opening the Rule Scenario Manager Console Verify that the Rule Scenario Manager Console has been successfully installed by launching it in a browser. Type rsm at the root URL on the host machine:
http://localhost:9080/rsm

If your browser is not running on the same host as the application server, you can replace localhost with <host> or the TCP/IP address. According to the application server security assignment, enter the login name and password of a Rule Scenario Manager user and click Sign in. The rsm_user role must be assigned a user with a password. The default username/password for Rule Scenario Manager is rsm/ rsm. Step 5. Changing the Configuration of the Rule Scenario Manager Console The following is an example ANT task to change the configuration of the Rule Scenario Manager Console. The default name of the ANT task is rsm-console-setup. To update the configuration of the Rule Scenario Manager Console and deploy the help, you must use the new library of jrules-rsm-setup.jar, located in <InstallDir>/ scenariomanager/lib/ .
<taskdef resource="rsm-tasks.properties" > <classpath> <pathelement location="<InstallDir>/scenariomanager/lib/jrules-rsmsetup.jar"/> </classpath> </taskdef> <property name="rsm.console.in" value="<InstallDir>/scenariomanager/ applicationservers/vendor/jrules-ssp-vendor.ear"/> <property name="rsm.console.out" value="${basedir}/jrules-rsm-My.ear"/> <target name="setup"> <rsm-console-setup rsmConsoleInput="${rsm.console.in}" rsmConsoleOutput="${rsm.console.out}"

168

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.0
verbose="true"> <extensions descFile="./data/extensions.xml"> <fileset dir="./data"> <include name="myPackage.jar"/> </fileset> </extensions> <configuration emptyXmlGridFile="./data/emptyXmlGridTemplate.xml" traceFilterFile="./data/tracefilter.properties" log4jFile="./data/log4j.properties" jpoxFile="./data/jpox.properties" jdoDataMaxSize="6400" rsmOnlinehelp="/rsmonlinehelpamoi" doublePrecision="1E-3" //default is IE-2 stringCaseSensitivity="PRECISION_STR_CASE_SENSITIVE" //default is PRECISION_STR_NO_CASE_SENSITIVE datePrecision="YMD" //other values are YMDMHMS (default) | YMDHH emptyGridServiceAvailable="false" //default is true downloadFormat="BOTH"//other values are EXCEL (default) | XML samApplication="myApplicationName" autoSaveReport="false" //default is true birtAvailable="false" //default is true/> <templates excelGridFile="./data/rsmEmptyGridTemplate.xls" rsmReportFile="./data/rsmReportTemplate.xls" scenarioRptdesignFile="./data/Scenario.rptdesign" suiteRptdesignFile="./data/Suite.rptdesign" simulationRptdesignFile="./data/Simulation.rptdesign"/> </rsm-console-setup> </target>

Where jrules-ssp-vendor.ear and jrules-ssp-My.ear are the filenames of the application server .EAR files.

Installing Rule Scenario Manager on WebSphere Application Server 6.0
Installing Rule Scenario Manager on WebSphere Application Server 6.0 requires the prior deployment of Rule Execution Server, see the Installing Rule Execution Server on WebSphere Application Server 6.0. The installation of Rule Scenario Manager on WebSphere Application Server 6.0 involves the following steps:
◆ Step 1. Creating a Data Source and Connection Pool on WebSphere 6.0. ◆ Step 2. Deploying Rule Scenario Manager EARs on WebSphere 6.0. ◆ Step 3. Changing the Class Loader Mode on WebSphere 6.0. ◆ Step 4. Activating Security through the definition of a custom registry, and mapping

security roles.
◆ Step 5. Changing the Configuration of the Rule Scenario Manager Console. ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

169

For information on configuring the persistence mode of the Rule Execution Server, see Installing Rule Execution Server on WebSphere Application Server 6.0. Using an Oracle 9i or 10g Database If you intend to use an Oracle 9i or 10g database:
1. Unzip the file jrules-rsm-WAS6.ear. 2. Extract and unzip the file jrules-rsm.war. 3. Extract the file: \WEB-INF\classes\resources\config\jpox.ds.properties

and add the following property:
javax.jdo.mapping.Schema=XXX

where XXX is the name, in upper case, of the schema/user to use by default for all classes persisted using this PMF. JPOX will prefix all table names with this schema name if the RDBMS supports specification of schema names in DDL.
4. Re-zip the files into the WAR, and the WAR into the EAR.

Deploy the EAR, as described in Step 2. Deploying Rule Scenario Manager EARs on WebSphere 6.0. Step 1. Creating a Data Source and Connection Pool on WebSphere 6.0 To create a JDBC provider:
1. Log in to the WebSphere Administrative Console. 2. In the left pane click Resources and JDBC Providers. 3. The default scope of the provider used by Rule Scenario Manager is Server. In the right

pane select Server and click Apply. Some default providers should appear if you use default configuration.
4. Click the New button to create a new JDBC provider:

In Step 1 choose the database type. In Step 2 choose the JDBC provider. In Step 3, in the pull-down menu, choose the implementation type. Choose an implementation which supports XA features if you intend to use the same database as the Rule Execution Server.
5. Click Next.

170

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.0
6. Check that the class path to the JAR of your driver and the implementation class are

correct. Default values are usually sufficient.
7. Click Apply.

Note: Some drivers (such as Oracle OCI drivers) need to access additional libraries at runtime (.dll or .so files). As a consequence, you will have to set up your working environment in order to access these libraries (PATH, LD_LIBRARY_PATH, and so on). You may have to restart your server in order to take these changes into account. The Additional Properties panel must appear on the bottom of the page. This will allow you to create the data source. To create a data source and a connection pool:
1. Click Data Sources in Additional Properties. 2. Click New to create a new data source. 3. Enter rsmdatasource as the name of the data source, jdbc/rsmdatasource for the

JNDI name, and the database name, which depends on the database type, see Table 14. For DB2 this is the name of the database. Note: The name of the data source is not important here but the JNDI name is. Be sure to set it to jdbc/rsmdatasource, otherwise Rule Scenario Manager will not be able to use the data source.
4. Deselect Use this Data Source in container managed persistence (CMP). 5. Click Apply. A connection pool is automatically created and associated with the data

source and the Additional Properties panel appears.
6. Click Custom Properties in Additional Properties.

Depending on the database you want to connect to, you have different properties to define. Table 14 presents the minimum set of properties required to define the supported databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

171

Table 14 Database Driver Properties Database DB2 Universal JDBC Driver Properties

databaseName – Actual database name if driverType is set to 4, or a locally cataloged database name if driverType is set to 2 driverType – Possible values are 2 or 4

The following properties are required only if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – Locally cataloged database name driverType – Only value is 2 databaseName – For example, Sample URL – For example, jdbc:oracle:oci:@sample Database Name: path to the location of the database files.

DB2 Universal JDBC XA Driver DB2 legacy CLI-based Type 2 Oracle JDBC Driver Derby

◆ ◆

For more information, refer to the Derby documentation. 7. Click New to add the Name user and Value (for example, PBPUBLIC) to define the user

to connect to the database. Click OK.
8. To create a password repeat step 7 and specify password for Name and PBPUBLIC (for

example) for Value. Click OK.
9. At the top of the page click Save and Save again to confirm the change to JDBC

providers. Connecting to the Database To test the connection to your database:
1. Open Resources > JDBC providers > DB2 JDBC Provider > Data

sources > rsmdatasource.
2. Click Test Connection.

If the test fails, check that the information you provided (user, password, and so on) is correct. Step 2. Deploying Rule Scenario Manager EARs on WebSphere 6.0 To deploy the EAR on WebSphere Application Server:

172

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.0
1. Open the WebSphere Console. 2. In the left pane, click Applications and Install New Application. 3. In the right pane, select Local file system and Browse to: <InstallDir>/scenariomanager/applicationservers/websphere6/ jrules-rsm-WAS6.ear

Click Next.
4. Select the checkbox Generate Default Bindings and click Next. Click Continue to

accept the security warning.
5. In Step 1 click Next to accept the default settings. 6. In Step 2 select RSM and click Next. 7. In Step 3 for javax.sql.DataSource select jdbc/rsmdatasource.

Select RSM console webapp (twice) and click Next to complete Step 3.
8. In Step 4 select RSM and click Next. 9. In Step 5 click Next for no security. For information on activating security, see Step 4.

Activating Security.
10. Click Next to accept the default settings in Step 6. 11. In the summary click Finish to complete the installation. 12. Repeat the above steps to deploy the RSM online help: <InstallDir>/scenariomanager/online-help/rsmonlinehelp.ear 13. Once the Application RSM console has installed successfully, click Save to Master

Configuration.
14. Click Save to confirm the change. 15. In the left pane, click Applications and Enterprise Applications. 16. In the Enterprise Applications page select RSM and click Start to start the application.

Manually Deploying Help in a Non-secure Context Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this:
1. Extract the file web.xml from your RSM Console EAR. 2. Edit the file web.xml and in the context parameter ilog.rules.rsm.HELP_CONTEXT, specify an absolute URL (for example, http://myserver/rsmonlinehelp). ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

173

3. Save the file and repackage it into the EAR.

You may need to restart WebSphere and the Rule Scenario Manager for the online help to function correctly. You can use the rsm-console-setup ANT task described in Step 5. Changing the Configuration of the Rule Scenario Manager Console to deploy the help. Step 3. Changing the Class Loader Mode on WebSphere 6.0 Set the class loader mode to Parent Last for the Rule Scenario Manager EAR and WAR to avoid problems in generating reports, as follows:
1. Log in to the WebSphere Console. 2. Select Application > Enterprise Applications and click RSM. 3. In the section Class Loading and File Update Detection, for Class loader mode select

Parent Last. Click Apply.
4. In the section Related Items, click on Web modules and then on jrules-rsm.war. 5. In the section Class loader mode, select Parent Last. Click OK. 6. Click Save to apply changes to the master configuration and when prompted, Save again

to confirm the changes. Step 4. Activating Security WebSphere Application Server Version 6.0 provides security infrastructure and mechanisms to protect sensitive J2EE resources and administrative resources and to address enterprise end-to-end security requirements on authentication, resource access control, data integrity, confidentiality, privacy, and secure interoperability. The security layers in WebSphere Application Server are shown in the following:

174

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.0

WebSphere Application Server supports the J2EE model for creating, assembling, securing, and deploying applications. By default, the Rule Scenario Manager Console does not require security in WebSphere. However, to activate access control for Rule Scenario Manager in WebSphere 6.0, perform the following. Defining a Custom Registry WebSphere uses various kinds of user registries (OS, LDAP, or custom). This section explains how to configure a user registry. WebSphere provides a custom registry sample named FileRegistrySample. This sample enables the definition of the username/passwords/groups in text files without encryption. The relationship between the various roles/groups/users in the proposed custom definition is as follows:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

175

To define a custom registry:
1. Log on to the WebSphere Console. To define the path of the files, you need to define

two Custom Properties.
2. Click Security and Global security. Under User registries click Custom to open the

Custom user registry page:

As the Server user ID and Server user password, enter websphere.
3. Under Additional Properties click Custom properties. This page is used to add the

group and user properties. Click New.
4. The usersFile property defines the path to the file that contains the user definition.

Set the Name to usersFile and enter the Value ${USER_INSTALL_ROOT}/jrules/ users.props. Click OK.
5. Click New and define the groupsFile property, which defines the path to the file that

contains the group definition.

176

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.0

For Name specify groupsFile and enter the Value ${USER_INSTALL_ROOT}/ jrules/groups.props. Click OK.
6. According to your USER_INSTALL_ROOT variable (WAS_HOME, by default), create a directory named rsm and then create two files named users.props and groups.props in ${USER_INSTALL_ROOT}/jrules.

The property files must define the following:
a. A websphere/wasadmin user for the WebSphere Console authentication. b. A rsm/rsmgroup for the Rule Scenario Manager Console authentication.

The users.props file must contain the users definition:
# Format: # name:passwd:uid:gids:display name # where name = userId/userName of the user # passwd = password of the user # uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user # websphere:websphere:100:0:Websphere Administrator rsm:rsm:2:1:Rule Scenario Manager User

The groups.props file must contain the groups definition:
# Format: # name:gid:users:display name # where name = groupId of the group # gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group # wasadmin:0:websphere:Administrative Group rsmgroup:1:rsm:Rule Scenario Manager User Group

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

177

7. At the top of the page click Save. Click the Save button to confirm a save to the master

configuration. Enabling Global Security After the configuration of the custom user registry, you can enable the server security. To enable security settings, modify the Global Security as follows:
1. Click Security and Global Security. 2. Check Enabled. Enforce Java 2 Security is selected automatically. 3. For Active User Registry select Custom user registry. 4. Click Apply. At the top of the page click Save. Click the Save button to confirm a save

to the master configuration.
5. Restart your server. 6. Refresh the WebSphere Administrative Console. You will be required to log on using a User ID/Password. By default this is websphere/websphere.

Mapping the rsmgroup to the Operator Role To access the MBeans of the Scenario Service Provider model, an application must have sufficient security credentials, restricted to the Administrator role in the WebSphere authentication system. This is managed by the Rule Execution Server, and is described in Installing Rule Execution Server on WebSphere Application Server 6.0. It is sufficient for Rule Scenario Manager users to configure a mapping between the
rsmgroup declared in the custom registry and the Operator role, as follows: 1. In the WebSphere Console open System administration > Console settings > Console

groups.
2. Click Add. Enter the group name rsmgroup and for Role(s) select Operator.

178

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.0

Click Apply.
3. Click OK. At the top of the page click Save. Click the Save button to confirm a save to

the master configuration. Mapping Security Roles to Users/Groups When the global security is enabled you can define the security mapping for the Rule Scenario Manager Console.
1. Open Applications > Enterprise Applications > RSM > Additional

Properties > Map Security roles to users/groups.
2. To define how the rsm_user role is mapped in the application server security, select the rsm_user role to open the following:

3. Click Lookup users and Search to display the following:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

179

4. Select the rsm item. 5. Click OK to return to the Mapping users to roles page. 6. Select the rsm_user role. 7. Click Lookup groups and click Search to display the following:

180

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.0
8. Select the rsmgroup item. 9. Click OK to return to the Mapping Users to Roles page. 10. Check the All authenticated? checkbox.

Click OK.
11. At the top of the page click Save. Click the Save button to confirm a save to the master

configuration. To apply these settings to the Rule Scenario Manager Console, you must restart the application from the list of the installed applications in the WebSphere Console. Security Policies for the Rule Scenario Manager Console When the global security of WebSphere is activated, the MBean server cannot be accessed from the deployed application. These security policies must be overridden for the Rule Scenario Manager Console because it needs to record and manage a set of MBeans. Rule Scenario Manager is packaged with a specific policy file that overrides the server policies. This file is supplied for the Console and packaged in jrules-rsm-WAS6.ear. The file is called was.policy and is found in the meta-inf directory. Opening the Rule Scenario Manager Console Verify that the Rule Scenario Manager Console has been successfully installed by launching it in a browser. Type rsm at the root URL on the host machine:
http://localhost:9080/rsm

If your browser is not running on the same host as the application server, you can replace localhost with <host> or the TCP/IP address. According to the application server security assignment, enter the login name and password of a Rule Scenario Manager user and click Sign in. The rsm_user role must be assigned a user with a password. The default username/password for Rule Scenario Manager is rsm/ rsm.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

181

Step 5. Changing the Configuration of the Rule Scenario Manager Console The following is an example ANT task to change the configuration of the Rule Scenario Manager Console. The default name of the ANT task is rsm-console-setup. To update the configuration of the Rule Scenario Manager Console and deploy the help, you must use the new library of jrules-rsm-setup.jar, located in <InstallDir>/ scenariomanager/lib/ .
<taskdef resource="rsm-tasks.properties" > <classpath> <pathelement location="<InstallDir>/scenariomanager/lib/jrules-rsmsetup.jar"/> </classpath> </taskdef> <property name="rsm.console.in" value="<InstallDir>/scenariomanager/ applicationservers/vendor/jrules-ssp-vendor.ear"/> <property name="rsm.console.out" value="${basedir}/jrules-rsm-My.ear"/> <target name="setup"> <rsm-console-setup rsmConsoleInput="${rsm.console.in}" rsmConsoleOutput="${rsm.console.out}" verbose="true"> <extensions descFile="./data/extensions.xml"> <fileset dir="./data"> <include name="myPackage.jar"/> </fileset> </extensions> <configuration emptyXmlGridFile="./data/emptyXmlGridTemplate.xml" traceFilterFile="./data/tracefilter.properties" log4jFile="./data/log4j.properties" jpoxFile="./data/jpox.properties" jdoDataMaxSize="6400" rsmOnlinehelp="/rsmonlinehelpamoi" doublePrecision="1E-3" //default is IE-2 stringCaseSensitivity="PRECISION_STR_CASE_SENSITIVE" //default is PRECISION_STR_NO_CASE_SENSITIVE datePrecision="YMD" //other values are YMDMHMS (default) | YMDHH emptyGridServiceAvailable="false" //default is true downloadFormat="BOTH"//other values are EXCEL (default) | XML samApplication="myApplicationName" autoSaveReport="false" //default is true birtAvailable="false" //default is true/> <templates excelGridFile="./data/rsmEmptyGridTemplate.xls" rsmReportFile="./data/rsmReportTemplate.xls" scenarioRptdesignFile="./data/Scenario.rptdesign" suiteRptdesignFile="./data/Suite.rptdesign" simulationRptdesignFile="./data/Simulation.rptdesign"/> </rsm-console-setup> </target>

Where jrules-ssp-vendor.ear and jrules-ssp-My.ear are the filenames of the application server .EAR files.

182

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.1

Installing Rule Scenario Manager on WebSphere Application Server 6.1
Installing Rule Scenario Manager on WebSphere Application Server 6.1 requires the prior deployment of Rule Execution Server, see Installing Rule Execution Server on WebSphere Application Server 6.1. Installing Rule Scenario Manager on WebSphere Application Server 6.1 includes:
◆ Step 1. Creating a Data Source and Connection Pool on WebSphere 6.1. ◆ Step 2. Deploying the Rule Scenario Manager EARs on WebSphere 6.1. ◆ Step 3. Deploying the Rule Scenario Manager Online Help. ◆ Step 4. Activating Security on WebSphere 6.1 through the definition of a custom registry,

and mapping security roles.
◆ Step 5. Changing the Configuration of the Rule Scenario Manager Console.

Using an Oracle 9i or 10g Database If you intend to use an Oracle 9i or 10g database:
1. Unzip the file jrules-rsm-WAS6.ear. 2. Extract and unzip the file jrules-rsm.war. 3. Extract the file: \WEB-INF\classes\resources\config\jpox.ds.properties

and add the following property:
javax.jdo.mapping.Schema=XXX

where XXX is the name, in upper case, of the schema/user to use by default for all classes persisted using this PMF. JPOX will prefix all table names with this schema name if the RDBMS supports specification of schema names in DDL.
4. Re-zip the files into the WAR, and the WAR into the EAR. 5. Deploy the EAR, as described in Step 6. Deploying the Rule Execution Server

Management EAR on WebSphere 6.1. Step 1. Creating a Data Source and Connection Pool on WebSphere 6.1 Create a data source and a connection pool as follows. Creating a JDBC Provider To create a JDBC provider:
ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

183

1. Log in to the Integrated Solutions Console. 2. In the left panel open Resources > JDBC and click JDBC Providers. 3. In the right panel in Scope select the Node and Server and click New. 4. In Step 1 select the database type, provider type, and an implementation type that

supports XA features. For example, Derby, Derby JDBC Provider, and XA data source. Click Next.
5. A summary is provided in Step 3, as follows:

Check that the class path to the JAR of your driver and the implementation class are correct. Default values are usually sufficient.
6. Click Finish and Save directly to the master configuration.

Note: Some drivers (such as Oracle OCI drivers) need to access additional libraries at runtime (.dll or.so files). As a consequence, you will have to set up your working environment in order to access these libraries (PATH, LD_LIBRARY_PATH, and so on). You may have to restart your server in order to take these changes into account. Creating a Data Source To create a data source:
1. In the Integrated Solutions Console open Resources > JDBC and Data sources. 2. In the right panel in Scope select the Node and Server and click New.

184

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.1
3. In Step 1, enter rsmsdatasource as the Data source name, jdbc/rsmdatasource

for the JNDI name and click Next. Note: The name of the data source is not important here but the JNDI name is. Be sure to set it to jdbc/rsmdatasource, otherwise Rule Scenario Manager will not be able to use the data source.
4. In Step 2 select the JDBC provider you created in the previous section or an existing

provider and click Next.
5. In Step 3, enter the specific database properties for the data source. For Derby, this is the

path used to create the database (see Table 15 for more information). De-select Use this data source in container managed persistence (CMP). Click Next.
6. In Step 4, a summary of the data source is provided.

Click Finish and Save directly to the master configuration. Creating J2C Authentication Data
1. In the Integrated Solutions Console open Resources > JDBC and Data sources. 2. Click rsmdatasource. 3. Under Related Items, click JAAS - J2C authentication data. ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

185

4. Click New and set the fields as follows:

Alias: RsmDerbyUser User ID: rsm Password: rsm Click Apply.
5. Open Resources > JDBC and Data sources and click rsmdatasource. 6. In the section Component-managed authentication alias, select the RsmDerbyUser

alias.
7. In the section Container-managed authentication, select RsmDerbyUser for the

Container-managed authentication alias.
8. Click Apply and Save to the master configuration.

Setting Custom Properties Depending on the database you want to connect to, you have different properties to define. Table 15 presents the minimum set of properties required to define the supported databases. If the driver you use is not listed, please check the documentation of WebSphere Application Server for more information.
Table 15 Database Driver Properties Database DB2 Universal JDBC Driver Properties

databaseName – Actual database name if driverType is set to 4, or a locally cataloged database name if driverType is set to 2 driverType – Possible values are 2 or 4

The following properties are required only if driverType is 4: ◆ serverName – TCP/IP address or host name

portNumber – TCP/IP port number databaseName – Locally cataloged database name driverType – Only value is 2 databaseName – For example, Sample URL – For example, jdbc:oracle:oci:@sample Database Name: path to the location of the database files.

DB2 Universal JDBC XA Driver DB2 legacy CLI-based Type 2 Oracle JDBC Driver Derby

◆ ◆

For more information, refer to the Derby documentation.

To set custom properties:

186

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.1
1. In the Integrated Solutions Console open Resources > JDBC and click Data sources. 2. Click the data source you want to customize. 3. Under Additional Properties, click Custom properties. 4. Change an existing property or create a new one by clicking New. 5. Click OK and Save directly to the master configuration.

Connecting to the Database To test the connection to your database:
1. In the Integrated Solutions Console open Resources > JDBC and click Data sources. 2. Select the data source you want to test and click Test connection.

If the test fails, you will need to correct the problem before continuing. For more information on connection pools and data sources, please refer to the documentation of IBM WebSphere. Step 2. Deploying the Rule Scenario Manager EARs on WebSphere 6.1 To deploy the Rule Scenario Manager EARs on WebSphere Application Server:
1. Open the Integrated Solutions Console. 2. In the left pane, open Applications and click Install New Application. 3. In the right pane, select Local file system and Browse to: <InstallDir>/scenariomanager/applicationservers/websphere6/ jrules-rsm-WAS6.ear 4. Select the checkbox Show me all installation options and parameters. Click Next. 5. Select the checkbox Generate Default Bindings and click Next. Click Continue to

accept the security warning.
6. In Step 1 click Next to accept the default settings. 7. In Step 2 select RSM and click Next. 8. In Step 3 click Next to accept the default settings. 9. In Step 4 select RSM and click Next. 10. In Step 5 click Next. 11. In Step 6 click Next to accept the default settings. 12. In Step 7 and Step 8 click next.

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

187

13. In Step 9 click Next for no security.

See Step 4. Activating Security on WebSphere 6.1 for more information.
14. Step 10 provides a summary. Click Finish. After the installation has completed click

Save directly to the master configuration. Defining the Class Loading Sequence
1. In the left panel of the Integrated Solutions Console, open Applications > Enterprise

Applications. Click RSM.
2. Click Class loading and update detection. 3. For Polling interval for updated files, specify 0. 4. Select the checkbox Classes loaded with application class loader first. 5. Click OK. 6. Click Manage Modules and RSM. 7. Under General Properties for Class loader order select Classes loaded with

application class loader first.
8. Click OK. 9. Click Save directly to master configuration. 10. In the left pane, open Applications > Enterprise Applications. 11. In the Enterprise Applications page select RSM and click Start to start the application.

Step 3. Deploying the Rule Scenario Manager Online Help To deploy the online help for the Rule Scenario Manager Console:
1. Open the Integrated Solutions Console. 2. In the left pane, open Applications and click Install New Application. 3. In the right pane, select Local file system and Browse to: <InstallDir>/scenariomanager/online-help/rsmonlinehelp.ear 4. Select the checkbox Show me all installation options and parameters. Click Next. 5. Select the checkbox Generate Default Bindings and click Next. 6. Click Continue to accept the security warning. 7. In Step 1 through Step 7 click Next to accept the default settings.

188

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.1
8. Step 8 provides a summary. Click Finish. When the installation has completed click

Save directly to the master configuration.
9. In the left pane, open Applications > Enterprise Applications. 10. In the Enterprise Applications page select Rule Scenario Manager Online Help and

click Start to start the application. Manually Deploying Help in a Non-secure Context Deploying the online help on the same server as the Web application could cause a security warning on Internet Explorer. You can work around this problem by deploying the online help in a non-secure context. To do this:
1. Extract the file web.xml from your RSM Console EAR. 2. Edit the file web.xml and in the context parameter ilog.rules.rsm.HELP_CONTEXT, specify an absolute URL (for example, http://myserver/rsmonlinehelp). 3. Save the file and repackage it into the EAR.

You may need to restart WebSphere and the Rule Scenario Manager for the online help to function correctly. You can use the rsm-console-setup ANT task described in Step 5. Changing the Configuration of the Rule Scenario Manager Console to deploy the help. Step 4. Activating Security on WebSphere 6.1 WebSphere Application Server Version 6.1 provides security infrastructure and mechanisms to protect sensitive J2EE resources and administrative resources and to address enterprise end-to-end security requirements on authentication, resource access control, data integrity, confidentiality, privacy, and secure interoperability. The security layers in WebSphere Application Server are shown in the following:

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

189

WebSphere Application Server supports the J2EE model for creating, assembling, securing, and deploying applications. By default, the Rule Scenario Manager Console does not require security in WebSphere. However, to activate access control for Rule Scenario Manager in WebSphere 6.1, perform the following steps. Defining a Custom Registry WebSphere uses various kinds of user registries (OS, LDAP, or Custom). This section explains how to configure a user registry. WebSphere provides a custom registry sample named FileRegistrySample. This sample enables the definition of the username/passwords/groups in text files without encryption. The relationship between the various roles/groups/users in the proposed custom definition is as follows:

190

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.1

To define a custom registry:
1. Log on to the Integrated Solutions Console. To define the path of the files, you need to

define two custom properties.
2. In the left panel open Security > Secure administration, applications, and

infrastructure. Enable administrative and application security and click Security Configuration Wizard.
3. In Step 1, specify the level of protection and click Next. 4. In Step 2 select Standalone custom registry and click Next. 5. According to your USER_INSTALL_ROOT variable, create a directory named rsm and two files named users.props and groups.props in the directory ${USER_INSTALL_ROOT}/jrules.

The property files must define: A websphere/wasadmin user for WebSphere Console authentication. A rsm/rsmgroup for the Rule Scenario Manager Console authentication. The users.props file must contain the following users definition:
# Format: # name:passwd:uid:gids:display name # where name = userId/userName of the user # passwd = password of the user # uid = uniqueId of the user # gid = groupIds of the groups that the user belongs to # display name = a (optional) display name for the user # websphere:websphere:100:0:Websphere Administrator

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

191

rsm:rsm:2:1:Rule Scenario Manager User

The groups.props file must contain the following groups definition:
# Format: # name:gid:users:display name # where name = groupId of the group # gid = uniqueId of the group # users = list of all the userIds that the group contains # display name = a (optional) display name for the group # wasadmin:0:websphere:Administrative Group rsmgroup:1:rsm:Rule Scenario Manager User Group

6. In Step 3, the Primary administrative user name should be websphere. For Name and Value specify usersFile and groupsFile and their corresponding Value, or path (${USER_INSTALL_ROOT}/jrules/users.props and ${USER_INSTALL_ROOT}/ jrules/groups.props, respectively).

Click Next.
7. In Step 4, review the security configuration summary and click Finish. 8. Click Save directly to the master configuration.

You will need to restart the server to apply the settings. Mapping the rsmgroup to the Operator Role To access the MBeans of the Scenario Service Provide model, an application must have sufficient security credentials, restricted to the Administrator role in the WebSphere authentication system. This is managed by the Rule Execution Server, and is described in Installing Rule Execution Server on WebSphere Application Server 6.1. It is sufficient for Rule Scenario Manager users to configure a mapping between the rsmgroup declared in the custom registry and the Operator role, as follows:
1. In the Integrated Solutions Console open Users and Groups > Administrative Group

Roles.
2. Click Add. Enter the group name rsmgroup and for Role(s) select Operator.

Click Apply.
3. Click Save directly to the master configuration.

Mapping Security Roles to Users/Groups When the global security is enabled you can define the security mapping for Rule Scenario Manager.
1. Open Applications > Enterprise Applications > RSM > Security role to user/group

mapping to open the following:

192

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.1

2. To define how the rsm_user role is mapped in the application server security, select the rsm_user role and click Lookup users and Search to display the following:

3. Select the rsm item. To do this click on it under Available and use >> to move it to the

Selected column.
4. Click OK to return to the Security role to user/group mapping page. 5. Select the rsm_user role. 6. Click Lookup groups and click Search to display the following: ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

193

7. Select the rsmgroup item. To do this click on it under Available and use >> to move it

to the Selected column.
8. Click OK to return to the Security role to user/group mapping page. 9. Check the All authenticated? checkbox.

Click OK.
10. Click Save directly to the master configuration.

194

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

Installing Rule Scenario Manager on WebSphere Application Server 6.1 To apply these settings to the Rule Scenario Manager Console, you must stop and restart the application RSM in the Enterprise Applications page. Security Policies for the Rule Scenario Manager Console When the global security of WebSphere is activated, the MBean server cannot be accessed from the deployed application. These security policies must be overridden for the Rule Scenario Manager Console because it needs to record and manage a set of MBeans. Rule Scenario Manager is packaged with a specific policy file that overrides the server policies. This file is packaged in an EAR file was.policy in the META-INF directory. Opening the Rule Scenario Manager Console Verify that the Rule Scenario Manager Console has been successfully installed by launching it in a browser. Type rsm at the root URL on the host machine:
http://localhost:9081/rsm

If your browser is not running on the same host as the application server, you can replace localhost with <host> or the TCP/IP address. According to the application server security assignment, enter the login name and password of a Rule Scenario Manager user and click Sign in. The rsm_user role must be assigned a user with a password. The default username/password for Rule Scenario Manager is rsm/ rsm. Step 5. Changing the Configuration of the Rule Scenario Manager Console The following is an example ANT task to change the configuration of the Rule Scenario Manager Console. The default name of the ANT task is rsm-console-setup. To update the configuration of the Rule Scenario Manager Console and deploy the help, you must use the new library of jrules-rsm-setup.jar, located in <InstallDir>/ scenariomanager/lib/ .
<taskdef resource="rsm-tasks.properties" > <classpath> <pathelement location="<InstallDir>/scenariomanager/lib/jrules-rsmsetup.jar"/> </classpath> </taskdef> <property name="rsm.console.in" value="<InstallDir>/scenariomanager/ applicationservers/vendor/jrules-ssp-vendor.ear"/> <property name="rsm.console.out" value="${basedir}/jrules-rsm-My.ear"/> <target name="setup"> <rsm-console-setup rsmConsoleInput="${rsm.console.in}" rsmConsoleOutput="${rsm.console.out}" verbose="true"> <extensions descFile="./data/extensions.xml"> <fileset dir="./data">

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES

195

<include name="myPackage.jar"/> </fileset> </extensions> <configuration emptyXmlGridFile="./data/emptyXmlGridTemplate.xml" traceFilterFile="./data/tracefilter.properties" log4jFile="./data/log4j.properties" jpoxFile="./data/jpox.properties" jdoDataMaxSize="6400" rsmOnlinehelp="/rsmonlinehelpamoi" doublePrecision="1E-3" //default is IE-2 stringCaseSensitivity="PRECISION_STR_CASE_SENSITIVE" //default is PRECISION_STR_NO_CASE_SENSITIVE datePrecision="YMD" //other values are YMDMHMS (default) | YMDHH emptyGridServiceAvailable="false" //default is true downloadFormat="BOTH"//other values are EXCEL (default) | XML samApplication="myApplicationName" autoSaveReport="false" //default is true birtAvailable="false" //default is true/> <templates excelGridFile="./data/rsmEmptyGridTemplate.xls" rsmReportFile="./data/rsmReportTemplate.xls" scenarioRptdesignFile="./data/Scenario.rptdesign" suiteRptdesignFile="./data/Suite.rptdesign" simulationRptdesignFile="./data/Simulation.rptdesign"/> </rsm-console-setup> </target>

Where jrules-ssp-vendor.ear and jrules-ssp-My.ear are the filenames of the application server .EAR files.

196

ILOG JRULES 6.6 — INSTALLING THE JRULES MODULES