This book describes what you need to get started with openCRX and how to configure openCRX. Please note that this is a guide to set up a runtime environment. Information on how to set up a development environment is available in the file /core/README.

openCRX is the leading enterprise-class open source CRM suite. openCRX is based on openMDX, an open source MDA framework based on the OMG's model driven architecture (MDA) standards. This guarantees total openness, standards compliance, a state-of-the-art component-based architecture, and virtually unlimited scalability.

1.1 Who this book is for

The intended audience are openCRX administrators and advanced users.

1.2 What do you need to understand this book

This book describes how to install openCRX and how to configure openCRX. Even though it is possible to install openCRX without a deeper understanding of J2EE applications, application servers, and database management systems, it is still a plus if you are comfortable with these topics.

openCRX is an enterprise-class J2EE application. Installation, administration, and maintenance of such applications is somewhat more involved than running a simple setup.exe (or make install, for that matter). So please do not expect that you will manage to install openCRX in 10 minutes as even experienced administrators can easily spend an hour or more on their first install.

1.3 Tips, Warnings, etc.

We make use the following pictograms:

Information provided as a “Tip” might be helpful for various reasons: time savings, risk reduction, etc. - it goes without saying that we advise to follow our guides meticulously

meticulous \muh-TIK-yuh-luhs\, adjective:
Extremely or excessively careful about details.

You should carefully read information marked with “Important”. Ignoring such information is typically not a good idea.

Warnings should not be ignored (risk of data loss, etc.)

2 Prerequisites

Installing openCRX is a somewhat involved process as you are required to install/configure various other components as well. In a first step, however, you need to choose an appropriate selection of software packages, namely an application server (click here for list J2EE-compliant application servers supported by openCRX), a database management system (click here for list of database management systems supported by openCRX), and a JDK.

Before you get started with the selection process, however, it is a good idea to spend some time browsing the various pages containing information about the products and reviewing the openCRX version compatibility information provided at http://www.opencrx.org/faq.htm#versioncompatibility.

2.1 Selection of Software Packages / Versions

In the end, you will have installed several software packages and it makes sense to write down the names and version numbers of these software packages – this information might be helpful in the future in case you require support or want to file a bug report:

Required Software Packages	Information	Name	Version
openCRX CRM Suite	www.opencrx.org	openCRX
openMDX MDA Platform	www.openmdx.org	openMDX
Java 2 Platform Standard Edition	BEA website IBM website java.sun.com	[ ] BEA JRockit JDK [ ] IBM JDK [ ] Sun J2SE JDK ...
Java Build Tool	ant.apache.org	Ant	[ ] 1.7.0
Application Server see here for information about deploying openCRX on Tomcat	openCRX FAQ	[ ] Bea Weblogic [ ] IBM WebSphere [ ] JBoss [ ] Sun AS ...
Database Management System	openCRX FAQ	[ ] Oracle [ ] DB/2 [ ] MS SQL [ ] PostgreSQL [ ] MySQL ...

2.2 Installing JDK

Install the JDK.

Don't forget to set environment variables JAVA_HOME and JRE_15.

2.3 Installing Ant

Install Ant. Ant is required to build the openCRX runtime binaries.

Don't forget to set environment variables ANT_HOME and ANT_OPTS.

2.4 Build the Runtime Binaries

Read the file /core/README included in the openCRX distribution. This README contains important information, including how you can build the Runtime Binaries from the distribution. The following is a short summary of the relevant steps:

Expand opencrx-1.11.0-core.jre-1.5.zip to any directory
Create directory opt in the expanded directory
Expand openmdx-1.18.2-core.jre-1.5.zip to opt
Expand openmdx-1.18.2-portal.jre-1.5.zip to opt
Expand openmdx-1.18.2-security.jre-1.5.zip to opt
Expand openmdx-1.18.2-websphere.websphere-6.zip to opt
Open shell and cd to directory ./opencrx-1.11.0/core
ant install-src
ant assemble
EARs are created in directory
./opencrx-1.11.0/jre-1.5/core/deployment-unit

2.5 Installing / Configuring Database

As far as the database is concerned, the openCRX FAQ might give you some guidance in making your choice (please note that the openCRX distribution includes all the required configuration and deployment files for PostgreSQL, MySQL, MS SQL, IBM DB/2 and Oracle). Various openCRX installation guides for database management systems are available from http://www.opencrx.org/documents.htm.

The remainder of this document assumes that you decided for MySQL and hence – after following the openCRX Installation Guide for MySQL – you should have a working installation of the MySQL database before you continue with this guide.

2.6 Installing / Configuring Application Server

As far as the application server is concerned, your best bet is probably the one you know best as long as it is J2EE-compliant (additional information regarding the choice of an application server is available in the openCRX FAQ). The openCRX distribution includes the required configuration and deployment files for JBoss (which is also Open Source and free), Sun AS (platform edition is free), BEA Weblogic, and IBM WebSphere. Installation guides are available from http://www.opencrx.org/documents.htm.

The remainder of this document assumes that you decided for JBoss and hence – after following the openCRX Installation Guide for JBoss – you should have a working installation of the JBoss application server before you continue with this guide. If you follow our application server installation guides you will also install openMDX, the leading Open Source MDA platform.

Obviously, if you ended up making different choices, you can still follow this guide. You might have to make some minor adjustments to the instructions given here and some of our screen shots might look somewhat different from what you will see on your screen.

Assuming you have JBoss up and running, the last few lines of your console output should look similar to the following ones:

Listing 1: Console Output – JBoss startup

...
17:23:05,650 INFO [EARDeployer] Started J2EE application: file:/D:/jboss-4.0.5.GA/server/default/deploy/opencrx-core-CRX-Web.ear/
17:23:05,728 INFO [Http11AprProtocol] Starting Coyote HTTP/1.1 on http-0.0.0.0-8080
17:23:05,759 INFO [Server] JBoss (MX MicroKernel) [4.0.5.GA (build: CVSTag=Branch_4_0 date=200610162339)] Started in 32s:141ms

Now you are ready to continue.

3 openCRX Setup and Configuration

Once the database is ready and openCRX properly deploys on your application server there are still a few tasks left to set up and configure openCRX. This chapter guides you through these tasks on a step-by-step basis.

3.1 Overview

Let us give you a brief overview of the tasks ahead before we get started:

Verify/Create Application Server Logins {openCRX/AppServer Admin}
First Login / Initial Setup as admin-Root {openCRX Admin}
- Create Data Segment “Standard” {openCRX Admin}
- Import Codes and Data {openCRX Admin}
- Set Access Levels of Codes {openCRX Admin}
Create a new User guest {openCRX Admin / Segment Admin}
- Create a new Subject guest {openCRX Admin}
- Create a new Principal guest in realm Default {openCRX Admin}
- Make new Principal guest member of group Users {openCRX Admin}
- Segment Administrator creates new Contact {Segment Admin}
- Segment Administrator creates new User {Segment Admin}

All right, let's get started.

3.2 Verify/Create Application Server Logins

For the following steps we assume that the openCRX administrator has configured the users admin-Root, admin-Standard and guest with the appropriate roles on the application server. In the case of JBoss this requires creating/editing the files users.properties and roles.properties as follows:

Listing 2: File users.properties with syntax user=password

admin-Root=rootSecret
admin-Standard=adminSecret
guest=guest

Listing 3: File roles.properties with syntax user.Roles=role1,role2,...

admin-Root.Roles=OpenCrxRoot
admin-Standard.Roles=OpenCrxAdministrator
guest.Roles=OpenCrxUser

It is strongly recommended that you stay with the file-based UsersRolesLoginModule for the user admin-Root. This simplifies the openCRX bootstrapping.

3.3 First Login / Initial Setup as admin-Root

Connect to the login page of openCRX. The exact URL depends on your deployment details. For a standard openCRX deployment to JBoss running on your local machine and listening at port 8080 the URL is

http://localhost:8080/opencrx-core-CRX/Login

You should see the openCRX Login page as follows:

Figure 1: openCRX Login page

3.3.1 Login as admin-Root

Enter admin-Root into the field Username and then enter rootSecret into the field Password (you may have chosen a different password, i.e. enter the password you chose during installation/configuration of the application server):

Figure 2: First login with admin-Root / rootSecret

Click the button to start the initialization process.

If you can't get past the login screen (with the correct Username and Password, of course) and the Warning “Browser must accept cookies” keeps showing up need to verify your browser settings related to cookies. If you have installed a personal firewall (e.g. ZoneAlarm) you also need to verify those cookie settings. The application server must be able to create/set a session cookie.

The openCRX servlet is initialized during this first login, i.e. don't kill the browser if it takes a while. The application console output will look similar to the following listing:

Listing 4: Console Output – Initialization of the openCRX servlet

10:09:48,756 INFO [STDOUT] Wed Dec 13 10:09:48 CET 2006: Login: requestURL=http://localhost:8080/opencrx-core-10:10:23,026 INFO [STDOUT] Inspecting /WEB-INF/config/filters

If you see lots of error messages on the console and/or your log files grow very fast (several hundred KB if not more) then it is quite likely that your DB connection is not configured correctly. Please note that there is absolutely no sense in continuing before you have fixed your DB connection. You might want to verify

the spelling of the name of your DB (e.g. crx-CRX vs. CRX_CRX)
user name (e.g. system) and password (e.g. manager)
permissions of the user, etc.

After the successful startup of the openCRX servlet you see the start screen as shown in the figure below. You should at least see the root objects Administration, Codes, Security Realm, Security Policies, and Security Subjects:

Figure 3: Start screen of admin-Root

3.3.2 Create Data Segment “Standard”

Execute the operation Actions > Create Administrator to create a new segment and selected default accounts (including an administrator's account which allows you to manage the newly created segment).

Set the field Segment name to Standard. Leave the field Admin principal name empty and set the fields Initial password and Password again to * as shown in the figure below:

Figure 4: Create a new segment named Standard

Please verify the spelling of the segment name:
Standard (with a capital “S”).

Next you click OK to execute the operation Create Administrator which creates the segment named Standard. The result of executing this operation should look as follows:

Figure 5: Result of operation Create Administrator

3.3.3 Import Codes and Data

openCRX is distributed with many code tables and several data files (e.g. unit of measurement information, standard activity management process). Code tables and data files must be imported from the provided XML files to make them available to openCRX.

Execute the operation View > Reload and then click Yes to start the import:

Figure 6: Load Code Tables and Data – Step 1

Figure 7: Load Code Tables and Data – Step 2

Please note that this operation takes some time to complete as thousands of objects are made persistent in your database during the import. The console output will look similar to the following listing:

Listing 5: Console Output – Importing Codes and Data

...
10:31:59,894 INFO [STDOUT] Loading codes
10:31:59,894 INFO [STDOUT] Loading /WEB-INF/config/code/Root/en_US/accesslevel.xml
10:31:59,925 INFO [STDOUT] Loading /WEB-INF/config/code/Root/en_US/accountcategory.xml
10:31:59,925 INFO [STDOUT] Loading /WEB-INF/config/code/Root/en_US/accountrole.xml
...
10:32:00,300 INFO [STDOUT] Loading /WEB-INF/config/code/Root/de_CH/accesslevel.xml
10:32:00,316 INFO [STDOUT] Loading /WEB-INF/config/code/Root/de_CH/accountcategory.xml
10:32:00,316 INFO [STDOUT] Loading /WEB-INF/config/code/Root/de_CH/accountrole.xml
...
13:18:02,441 INFO [STDOUT] Loading /WEB-INF/config/code/Root/es_CO/usageproductbaseprice.xml
13:18:02,457 INFO [STDOUT] Loading /WEB-INF/config/code/Root/es_CO/utcoffset.xml
13:18:02,488 INFO [STDOUT] Storing 1538 code entries
13:19:06,585 INFO [STDOUT] Done
13:19:06,648 INFO [STDOUT] Loading data
13:19:06,648 INFO [STDOUT] Loading /WEB-INF/config/data/Standard/bug-and-feature-process.xml
13:19:07,384 INFO [STDOUT] Storing 26 objects
13:19:10,093 INFO [STDOUT] Loading /WEB-INF/config/data/Standard/contracts.xml
13:19:10,908 INFO [STDOUT] Storing 1 objects
13:19:11,033 INFO [STDOUT] Loading /WEB-INF/config/data/Standard/products.xml
13:19:13,022 INFO [STDOUT] Storing 1 objects
13:19:13,319 INFO [STDOUT] Loading /WEB-INF/config/data/Root/uom_SI_and_Paper.xml
13:19:14,415 INFO [STDOUT] Storing 42 objects
13:19:15,903 INFO [STDOUT] Done

3.3.4 Set Access Levels of Codes

Navigate to the package Codes by clicking on the Root menu entry Codes. Then execute the operation Security > Set Access Level as shown below:

Figure 8: Execute Operation Set Access Level

Set the parameters as follows (see also figure below):

Browse access level: [4] global
Update access level: [2] basic
Delete access level: [2] basic
Mode: [1] recursive

Figure 9: Parameters of Operation Set Access Level

Please note that this operation also takes a fair amount of time to complete:

Figure 10: Result of the Operation Set Access Level

3.3.5 Restarting the Application Server

Please restart the application server. On Windows you can stop JBoss by typing <CTRL>-C into the command window.

After stopping JBoss and before restarting JBoss it is strongly advised that you delete the tmp and work directories:

jboss-4.2.1.GA\server\default\tmp

jboss-4.2.1.GA\server\default\work

On Windows you can start JBoss by executing run.bat located in the directory jboss-4.2.1.GA\bin

3.4 Create a new User guest

Once your application server is up and running again and openCRX properly deployed, new users are created with the following steps:

as admin-Root: create a new Subject
as admin-Root: create a new Principal in realm Default and link this principal to the subject created in the previous step
as admin-Root: make Principal member of group Users
as admin-Standard: create a new Contact
as admin-Standard: create a new User and link this User to the contact created in the previous step

The following sections will guide you through the creation of a new User guest with permission to access the previously created segment Standard.

3.4.1 Create a new Subject guest

As admin-Root, navigate to the package Security Subjects and then create a new Subject with the creator menu New > Subject as shown below:

Figure 11: Create a new Subject

Enter guest into the field Description. More importantly, change the proposed Qualifier to guest as shown in the figure below:

Figure 12: Change the Subject's Qualifier to guest

The Subject Qualifier represents the Subject's Login name.

Next you click Save to store this new Subject. You should now see 3 Subjects (including the newly created Subject guest) in the grid Subjects:

Figure 13: Grid Subjects with admin-Root, admin-Standard, and guest

3.4.2 Create a new Principal guest in realm Default

Next, you need to create a new Principal in realm Default.

Please make sure that you create the new Principal in realm Default and not in some other realm – follow instructions meticulously!

Click on the package Security Realm in the root menu and then navigate to the realm Default. You can do this – for example – by clicking on the bread crum entry Security Realms as shown in the figure below:

Figure 14: Click on bread crum entry Security Realms

Next you click on the icon of the Realm Default. Your screen should now look as follows:

Figure 15: Realm Default

Select the creator menu New > Principal as shown as shown below:

Figure 16: Create a new Principal

You need to link this Principal with the previously created Subject. Type guest into the field Subject and then select guest [guest] from the autocompleter's drop down menu as shown below:

Figure 17: Select Subject guest from the drop down menu

Please note that just typing the word guest into the Subject field is not sufficient. You must select the appropriate Subject from the drop down menu that contains all Subjects that match the string you typed into the Subject field (depending on the speed of your server you will see the drop down menu before you have finished typing – that is OK, just select the appropriate Subject from the drop down menu)

Next you enter the Principal name (which will be the user/login id) of the Principal into the field Qualifier (e.g. guest as shown in the figure below):

Figure 18: Change the Principal's Qualifier to guest

Next you click Save to store this new Principal. In the grid Principals you should now see 2 Principal Groups (Administrators, Users) and 3 Principals (admin-Root, admin-Standard, and the newly created Principal guest):

Figure 19: Grid Principals with newly created Principal guest

3.4.3 Make new Principal guest member of group Users

Next you must add the newly created Principal guest to the appropriate Principal Group. Navigate to the newly created principal (i.e. load it into the inspector by clicking on its icon).

Start typing Users into the input box of the grid Member of Principal Groups as shown below:

Figure 20: Add Principal guest to Principal Group Users – Step 1

As soon as the drop down menu of the autocompleter appears, select the entry Users [Users].

Please note that just typing the word Users is not sufficient. You must select the appropriate Principal Group from the drop down menu of the AutoCompleter.

Normal users should be added to the principal group Users, segment administrators should be added to the principal group Administrators).

Consult the openCRX Admin Guide for additional/more detailed information on principals and principal groups.

To actually add the Principal Group Users you still need to select the menu Edit > Add Object and click on it as shown below:

Figure 21: Add Principal guest to Principal Group Users – Step 2

You cannot just type Users into the input box – you must use the AutoCompleter or the Lookup Inspector to select the appropriate Principal Group before executing Add Object.

Finally, this principal group should show up in the Grid Member of Principal Groups as shown below:

Figure 22: Add Principal guest to Principal Group Users – Step 3

That's it for admin-Root. You can now log out by clicking on Logoff.

3.4.4 Segment Administrator creates new Contact

Enter admin-Standard into the field Username and then enter adminSecret into the field Password (you may have chosen a different password, i.e. enter the password you chose during installation/configuration of the application server):

Figure 23: First login with admin-Standard / adminSecret

Click the button to start the login process.

Please note that no charts are displayed when a users logs in for the first time. Activate charts by executing the operation View > Recalculate and Refresh.

As Segment administrator you first have to create a new Contact in the package Accounts for the new user guest. To do so, click on the package Accounts in the root menu and then select the creator menu New > Contact as shown in the figure below:

Figure 24: Create new Contact – Step 1

This brings up the form for new contacts. Enter guest into the field Last name (feel free to provide additional information, but don't change the Qualifier, which is generated automatically by openCRX, unless you know exactly what you are doing):

Figure 25: Create new Contact – Step 2

Next you click Save to store this new Contact. This takes you back to the Account grid.

3.4.5 Segment Administrator creates new User

Click User Homepages and select the operation Actions > Create User... which allows you to create and initialize a new user. Set the fields to the values as shown below – type guest into the field Principal name, use the Lookup Inspector or the autocompleter to fetch values for Contact and Primary user group (note that you must either fetch values with the Lookup Inspector or select entries from the autocompleter's drop down menu for the parameters Contact and Primary user group, i.e. it is not sufficient to just type some text into these fields), and then type a password (e.g. guest) into the fields Initial password and Password again:

Figure 26: Create new User

Passwords are stored in the table security_Credential. If you do not have the login module of your application server configured to access the table security_Credential then the setting of the passwords in openCRX has no effect (with JBoss, for example, you can edit the files users.properties and roles.properties to add users).

Next you click OK to execute the operation Create User which creates the User named guest. The result of executing this operation should look as follows:

Figure 27: Result of operation Create User

The grid User Homes contains now 2 entries: admin-Standard and guest.

Congratulations! You have successfully created the new user guest. The new user should now be able to login. You can verify this by disconnecting and reconnecting with Username guest and Password guest.

You can usually fix corrupt data of an existing user by creating this user's homepage again – note, however, that the respective user's personal settings are reset to default values by executing the operation Create User.

4 Next Steps

Now that you have successfully installed and configured openCRX you might want to have a look at some of the additional documentation published at http://www.opencrx.org/documents.htm.