Chapter 1. About this Book

openCRX is the leading open source CRM tool. openCRX is based on the openMDX [02] application framework, an open source application framework based on the OMG's model driven architecture (MDA) standards. This guarantees maximum openness, standards compliance and a state-of-the-art component-based architecture.

Chapter 2. Prerequisites

As a first step select the openCRX version you want to install. Based on the published version compatibility information you can determine the appropriate versions of openMDX and WebSphere.

• Purchase/Install WebSphere 5.x (we have tested openCRX on WebSphere 5.0 and 5.1)

• Download openMDX from here.

• Download openCRX from here.

WebSphere 5.0 comes with JRE-1.3, whereas WebSphere 5.1 with JRE-1.4. Download the appropriate version of openCRX and openMDX. E.g. for WebSphere v5.0 you must download the openCRX distribution for jre-1.3 (e.g. opencrx-1.4.0-core.CRX.jre-1.3.zip), for WebSphere 5.1 you must download the version for jre-1.4 (e.g. opencrx-1.5.0-core.CRX.jre-1.4.zip).

As a first step you must install the database as described in the database distribution. If you have successfully installed the database you are ready to continue with the WebSphere setup.

Chapter 3. Installing openCRX for WebSphere

In a first step you must install WebSphere. You should be able to start and stop WebSphere and launch the WebSphere Administrative Console as shown in Figure 3-1.

The openCRX installation requires the following steps:

• Configure properties for the Java Virtual Machine required by openCRX and openMDX.

• Create and configure the datasource to access the openCRX database.

• Enable WebSphere security.

• Deploy the openCRX application enterprise archives.

• Start and test openCRX

Chapter 4. Installing Libraries

As a first step you must install the openMDX and the database libraries and make them available to WebSphere. You can do this by navigating to Environment > Manage WebSphere Variables.

• openMDX. Add a new variable by clicking new and add the entry with name OPENMDX_HOME and value ${WAS_INSTALL_ROOT}/openmdx/lib as shown in Figure 4-1

• Database. For most databases there already exist corresponding environment variables. However, the value must be adapted to your environment. E.g. the Jdbc driver for Microsoft SQL Server 2000 should have the name MSSQLSERVER_JDBC_DRIVER_PATH and e.g. the value C:\pgm\Microsoft SQL Server 2000 Driver for JDBC\lib.

So far you only have created the environment variables. You now must copy the required libraries to the directories that you have configured, e.g.

• openMDX - Step 1. Copy the libraries openmdx-kernel.jar, openmdx-base.jar and openmdx-application.jar to the directory OPENMDX_HOME, e.g. C:\pgm\WebSphere\AppServer\openmdx\lib. Create the directory if it does not exist.

• openMDX - Step 2. Copy the library openmdx-kernel.jar to the directory WebSphere\AppServer\lib\ext. The library is required by the WebSphere RMIC compiler when you deploy the EARs.

• Database. Copy the libraries msbase.jar, mssqlserver.jar, msutil.jar to the directory MSSQLSERVER_JDBC_DRIVER_PATH, e.g. C:\pgm\Microsoft SQL Server 2000 Driver for JDBC\lib.

Save the changes you have made so far.

Make sure that you copy the library openmdx-kernel.jar to the directory WebSphere\AppServer\lib\ext. Otherwise the deployment of the openCRX applications will fail.

Chapter 5. Configuring the Java Virtual Machine

Now you must add some options to the Java Virtual Machine configuration. Navigate to Application Servers > server1 > Process Definition > Java Virtual Machine as shown in Figure 5-1.

You must configure the following options:

• Classpath. All openMDX libraries must be added to the classpath. You can use the envrionment variables you have configured in the previous step. Add the entries

  • ${OPENMDX_HOME}/openmdx-kernel.jar

  • ${OPENMDX_HOME}/openmdx-base.jar

  • ${OPENMDX_HOME}/openmdx-application.jar

• Generic JVM arguments. Add the following options:

  • -Dorg.openmdx.compatibility.base.application.j2ee.domain=apps

  • -Dorg.openmdx.compatibility.base.application.j2ee.server=server1

  • -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol

  • -Dorg.openmdx.log.config.filename=C:\pgm\WebSphere\AppServer\server1.log.properties

  • -Dmail.SSLSocketFactory.class=org.opencrx.kernel.mail.SendMailSSLSocketFactory

• Create the file C:\pgm\WebSphere\AppServer\server1.log.properties using a text editor with the following content.

  Example 5-1. listing of server.log.properties.

  ApplicationId = opencrx-server1
  LogFileExtension = log
  LogFilePath = C:/pgm/WebSphere/AppServer/logs/
  LogLevel = warning
  java.LoggingMechanism = SharedDatedFileLoggingMechanism

  Adapt C:/pgm/WebSphere/AppServer to your environment!

Save the modifications you have made so far.

Before you continue you must restart (stop and start) WebSphere. The newly configured libraries and environment variables only become active after restarting WebSphere.

WebSphere 5.1 requires an additional step: the Java security policy must be extended. Open the file C:/pgm/WebSphere/AppServer/java/jre/lib/security/java.policy with a text editor and add the lines listed below:

grant codeBase "file:/C:/pgm/WebSphere/AppServer/openmdx/lib/*" {
    permission java.security.AllPermission;
};

This allows the openMDX libraries to access Java system properties.

Chapter 6. Configuring the Datasource

The openCRX application requires the configuration of a Jdbc datasource to connect to the openCRX database. You can do this a follows:

Navigate to Resources > Jdbc Providers and select the Jdbc driver which matches the database where you installed the openCRX database schema, e.g. Microsoft JDBC Driver for MSSQL Server 2000 as shown in Figure 6-1.

Verify whether the default values match the environment variables and library names which you have configured in Installing Libraries. E.g. for SQL Server 2000 the library files are msbase.jar, mssqlserver.jar, msutil.jar and the implementation class name is com.microsoft.jdbcx.sqlserver.SQLServerDataSource. Also verify the values with your Jdbc driver documentation.

As next step you must create a datasource. Select Additional Properties > DataSources and then select New. Enter the values as shown on Figure 6-3.

You must at least set the values for the following fields:

• Name. jdbc_datasource_0.

• JNDI Name. jdbc/opencrx_CRX.

• Component-managed Authentication Alias. Select a principal from the drop down which allows you to login to the database. You can add J2C Authentication Principals under Security > JAAS Configuration > J2C Authentication Data. Make sure that you enter a valid UserId and Password, otherwise WebSphere is not able to establish a connection to the openCRX database and the startup of openCRX will fail.

• Container-managed Authentication Alias. Select a principal from the drop down which allows you to login to the database. You can add J2C Authentication Principals under Security > JAAS Configuration > J2C Authentication Data. Make sure that you enter a valid UserId and Password, otherwise WebSphere is not able to establish a connection to the openCRX database.

Next you must complete the datasource configuration by setting the Additional Properties > Custom Properties as shown in Figure 6-4.

The properties are driver-specific. The Jdbc driver documentation should list the required properties. E.g. the Microsoft JDBC driver for MSSQLServer 2000 requires the following custom properties:

• databaseName. Set the value to the openCRX database name, e.g. crx-CRX.

• portNumber. 1433.

• selectMethod. cursor.

• serverName. localhost.

The datasource configuration is now complete. Save the changes you have made so far.

Chapter 7. Enabling WebSphere Security

openCRX requires that each user is properly authenticated. This allows openCRX to correlate a session to user-specific application data and to perform access control. openCRX does not support non-authenticated sessions. User authentication must be activated in WebSphere as follows:

• Select Security > Global Security and check the boxes Enabled and Enforce Java 2 Security as shown in Figure 7-1.

• Set Active User Registry to Local OS or to another registry listed in the drop down. Local OS makes the all users and groups defined by the operating systems available as WebSphere users and groups.

• After clicking OK WebSphere requires that you enter a Server User ID and Server User Password under Security > User Registries > Local OS. When security is turned on, the WebSphere process will run under this operating system user. Typical values are wasadmin, <wasadmin password>. Under Windows the user must be in the Administrator's group.

Save the changes you have made so far. Shut down and restart WebSphere.

Because security is now turned on you must provide the startServer command with the configured server user and password, e.g. startServer server1 -username wasadmin -password <wasadmin password>. Otherwise WebSphere will not start.

Chapter 8. Deploying openCRX

openCRX comes with three enterprise application archives (EAR):

• opencrx-core-CRX-App.ear. contains the openCRX server components, i.e. Enterprise Java Beans.

• opencrx-core-CRX-web.ear. contains the web application for standard openCRX users.

• opencrx-core-CRX-Root-web.ear. Contains the web application for root openCRX users.

In a first step you deploy opencrx-core-CRX-App.ear. Select Applications > Enterprise Applications and then click the Browse button to select the EAR file as shown in Figure 8-1.

You can skip all screens and leave the default values until you reach Step 1: Provide options to perform the installation as shown in Figure 8-2. Check the box Deploy EJBs. This generates the RMI stubs for all EJBs contained in the EAR.

If you do not check Deploy EJBs, WebSphere will not find the stubs in the EAR and will not be able to start openCRX.

You can skip all steps and leave the default values until you reach the final step Step 9: Summary as shown in Figure 8-3. Verify the values and then click finish.

The deployment process should pass without any errors and warnings. If the deployment process fails you have probably not copied openmdx-kernel.jar to the directory WebSphere\AppServer\lib\ext as described in Installing Libraries.

The installed application should now appear in Applications > Enterprise Applications as openCRX Core EAR. Check the application and click Start.

As next step you must install the web applications opencrx-core-CRX-web.ear and opencrx-core-CRX-Root-web.ear. The process is the same as described previously for the opencrx-core-CRX-App.ear. However, there are a few differences in Step 1 and Step 5.

In Step 1 you must select the option Pre-compile JSP as shown in Figure 8-4. The web application contains Java Server Pages which must be precompiled during deployment.

The web applications define the following security roles:

• opencrx-core-CRX-web.ear. This application is used by openCRX standard users and defines the roles OpenCrxUser and OpenCrxAdministrator. Only users who are member of OpenCrxUser or OpenCrxAdministrator are able to login to the web application.

• opencrx-core-CRX-Root-web.ear. This application is used by openCRX root users and defines the role OpenCrxRoot. Only root users who are member of OpenCrxRoot are able to login to the web application.

The roles are defined in the deployment descriptors of the application enterprise archives and must be mapped in Step 5: Map security roles to users/groups to WebSphere users and groups.

In a first step select the role, e.g. OpenCrxRoot, as shown in Figure 8-5. Then either click Lookup users or Lookup groups. Lookup users allows you to add WebSphere users to the groups OpenCrxRoot, OpenCrxAdministrator and OpenCrxUser. Lookup groups allows you to add WebSphere groups. In order that a WebSphere user is able to login to the application he/she must be member of the configured WebSphere group.

Be careful that you add to the group OpenCrxRoot only users which should have openCRX root privileges. The openCRX standard configuration assumes that you configure the user admin-Root (member of role OpenCrxRoot) for the application opencrx-core-CRX-Root-web.ear and the users admin-Standard (member of role OpenCrxAdministrator) and guest (member of role OpenCrxUser) for the application opencrx-core-CRX-web.ear.

You can click Next on all the following steps and finally click Finish. If the application does not deploy without errors you cannot use openCRX; please review/correct your installation carefully until the application can be deployed without errors..

Chapter 9. Next Steps

Before you proceed to the openCRX QuickStart guide make sure that you have deployed and started all applications as shown in Figure 9-1.

The application is initialized the first time a user calls the login page. If the startup fails you should consult the following log files:

• WebSphere startServer.log. Located in WebSphere\AppServer\logs\server1 and contains WebSphere startup information.

• WebSphere SystemErr.log. Located WebSphere\AppServer\logs\server1 in and contains the stderr output of WebSphere and deployed applications.

• WebSphere SystemOut.log. Located in WebSphere\AppServer\logs\server1 and contains the stdout output of WebSphere and deployed applications. This file contains the informational messages of the openCRX web application startup sequence.

• openCRX opencrx-server1.log. Located in WebSphere\AppServer\logs\server1 and contains the openCRX application log files.