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.6.5
Application Server see here for information about deploying openCRX on Tomcat	openCRX FAQ	[ ] Bea Weblogic [ ] IBM WebSphere [ ] JBoss ...
Database Management System	openCRX FAQ	[ ] Oracle [ ] DB/2 [ ] MS SQL [ ] PostgreSQL [ ] MySQL [ ] MaxDB ...

2.2 Installing JDK

Install the JDK.

Don't forget to set environment variables JAVA_HOME and JRE_15 (or JRE_14, depending on the JDK version).

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.

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 MySQL, MaxDB, PostgreSQL, MS SQL, 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.

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), 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. 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

...
16:49:23,783 INFO [ChannelSocket] JK: ajp13 listening on /0.0.0.0:8009
16:49:23,799 INFO [JkMain] Jk running ID=0 time=0/79 config=null
16:49:23,799 INFO [Server] JBoss (MX MicroKernel) [4.0.3SP1 (build: CVSTag=JBoss_4_0_3_SP1 date=200510231054)] Started in 21s:750ms

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:28:08,719 INFO [Server] JBoss (MX MicroKernel) [4.0.3SP1 (build: CVSTag=JBoss_4_0_3_SP1 date=200510231054)] Started in 21s:922ms
10:29:02,141 INFO [STDOUT] Sun Mar 12 10:29:02 CET 2006: Login: requestURL=http://localhost:8080/opencrx-core-CRX/Login.jsp; isRequestedSessionIdFromCookie=true
10:29:02,141 INFO [STDOUT] Sun Mar 12 10:29:02 CET 2006: Login: locale=null
10:30:54,563 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/en_US
10:30:54,907 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/de_CH
10:30:55,172 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/es_MX
10:30:55,438 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/zh_CN
10:30:55,688 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/sv_SE
10:30:56,016 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/tr_TR
10:30:56,454 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/fr_FR
10:30:57,063 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/it_IT
10:30:57,422 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/ru_RU
10:30:57,782 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/pl_PL
10:30:58,094 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/pt_BR
10:30:58,672 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/cs_CZ
10:30:59,657 INFO [STDOUT] Loading 67 ui files for locale en_US
10:31:00,547 INFO [STDOUT] Loading 67 ui files for locale de_CH
10:31:02,079 INFO [STDOUT] Loading 67 ui files for locale es_MX
10:31:02,797 INFO [STDOUT] Loading 67 ui files for locale zh_CN
10:31:03,485 INFO [STDOUT] Loading 67 ui files for locale sv_SE
10:31:04,219 INFO [STDOUT] Loading 67 ui files for locale tr_TR
10:31:04,891 INFO [STDOUT] Loading 0 ui files for locale null
10:31:04,891 INFO [STDOUT] Loading 67 ui files for locale fr_FR
10:31:05,563 INFO [STDOUT] Loading 67 ui files for locale it_IT
10:31:06,235 INFO [STDOUT] Loading 0 ui files for locale null
10:31:06,235 INFO [STDOUT] Loading 0 ui files for locale null
10:31:06,235 INFO [STDOUT] Loading 67 ui files for locale ru_RU
10:31:06,985 INFO [STDOUT] Loading 67 ui files for locale pl_PL
10:31:07,657 INFO [STDOUT] Loading 0 ui files for locale null
10:31:07,672 INFO [STDOUT] Loading 67 ui files for locale pt_BR
10:31:08,360 INFO [STDOUT] Loading 67 ui files for locale cs_CZ
10:31:10,750 INFO [STDOUT] Storing 2569 ui elements
10:31:17,297 INFO [STDOUT] Loading texts
10:31:17,297 INFO [STDOUT] Loading /WEB-INF/config/texts/en_US/texts.properties
10:31:17,329 INFO [STDOUT] Loading /WEB-INF/config/texts/en_US/opencrx.texts.properties
10:31:17,375 INFO [STDOUT] Loading /WEB-INF/config/texts/de_CH/opencrx.texts.properties
10:31:17,375 INFO [STDOUT] Loading /WEB-INF/config/texts/de_CH/texts.properties
...
...
10:31:17,875 INFO [STDOUT] Loading data
10:31:17,875 INFO [STDOUT] Loading /WEB-INF/config/bootstrap/Root/100_security_policy.xml
10:31:17,954 INFO [STDOUT] Storing 5 objects
10:31:26,422 INFO [STDOUT] Creating org::openmdx::security::authorization1/provider/CRX/segment/Root
10:31:26,641 INFO [STDOUT] Creating org::openmdx::security::
                    authorization1/provider/CRX/segment/Root/policy/Default
10:31:26,860 INFO [STDOUT] Creating org::openmdx::security::
                    authorization1/provider/CRX/segment/Root/policy/Default/role/OpenCrxAdministrator
10:31:27,000 INFO [STDOUT] Creating org::openmdx::security::
                    authorization1/provider/CRX/segment/Root/policy/Default/role/OpenCrxUser
10:31:27,079 INFO [STDOUT] Creating org::openmdx::security::
                    authorization1/provider/CRX/segment/Root/policy/Default/role/OpenCrxRoot
10:31:27,125 INFO [STDOUT] Loading /WEB-INF/config/bootstrap/Root/101_security_subjects.xml
10:31:28,922 INFO [STDOUT] Storing 2 objects
10:31:28,938 INFO [STDOUT] Creating org::opencrx::security::identity1/provider/CRX/segment/Root
10:31:29,172 INFO [STDOUT] Creating org::opencrx::security::
                    identity1/provider/CRX/segment/Root/subject/admin-Root
10:31:29,344 INFO [STDOUT] Loading /WEB-INF/config/bootstrap/Root/102_security_realms.xml
10:31:29,391 INFO [STDOUT] Storing 10 objects
10:31:29,469 INFO [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root
10:31:29,532 INFO [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Default
10:31:29,641 INFO [STDOUT] Creating org::openmdx::security::
                    realm1/provider/CRX/segment/Root/realm/Default/principal/admin-Root
10:31:29,735 INFO [STDOUT] Creating org::openmdx::security::
                    realm1/provider/CRX/segment/Root/realm/Default/principal/Administrators
10:31:29,829 INFO [STDOUT] Creating org::openmdx::security::
                    realm1/provider/CRX/segment/Root/realm/Default/principal/Users
10:31:29,922 INFO [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Root
10:31:30,016 INFO [STDOUT] Creating org::openmdx::security::
                    realm1/provider/CRX/segment/Root/realm/Root/principal/Administrators
10:31:30,157 INFO [STDOUT] Creating org::openmdx::security::
                    realm1/provider/CRX/segment/Root/realm/Root/principal/Users
10:31:30,407 INFO [STDOUT] Creating org::openmdx::security::
                    realm1/provider/CRX/segment/Root/realm/Root/principal/admin-Root.User
10:31:30,547 INFO [STDOUT] Creating org::openmdx::security::
                    realm1/provider/CRX/segment/Root/realm/Root/principal/admin-Root
10:31:30,625 INFO [STDOUT] Loading /WEB-INF/config/bootstrap/Root/200_code_segment.xml
10:31:32,954 INFO [STDOUT] Storing 1 objects
10:31:35,985 INFO [STDOUT] Creating org::opencrx::kernel::code1/provider/CRX/segment/Root
10:31:36,485 INFO [STDOUT] Loading /WEB-INF/config/bootstrap/Root/300_admin_segment.xml
10:31:38,141 INFO [STDOUT] Storing 1 objects
10:31:38,172 INFO [STDOUT] Creating org::opencrx::kernel::admin1/provider/CRX/segment/Root
10:31:38,500 INFO [STDOUT] Loading /WEB-INF/config/bootstrap/Standard/dummy.xml
10:31:41,110 INFO [STDOUT] Storing 0 objects
10:31:41,110 INFO [STDOUT] Done
10:31:41,110 INFO [STDOUT] Inspecting /WEB-INF/config/filters/
10:31:41,219 INFO [STDOUT] Loading /WEB-INF/config/filters/
10:31:44,141 INFO [STDOUT] Loaded filters #4112
10:31:44,500 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/en_US
10:31:44,735 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/de_CH
10:31:44,891 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/es_MX
10:31:45,047 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/zh_CN
10:31:45,219 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/sv_SE
10:31:45,360 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/tr_TR
10:31:45,454 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/fr_FR
10:31:45,625 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/it_IT
10:31:45,782 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/ru_RU
10:31:45,938 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/pl_PL
10:31:46,094 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/pt_BR
10:31:46,235 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/cs_CZ
10:31:46,485 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. Only the segment Standard (note the capital “S”) is configured by default.

The segment Standard is preconfigured in the file web.xml. To add a segment with a different name you must edit web.xml and add an entry with the corresponding segmentName (see example below on how to configure a segment ABC). Please note that segments must be numbered consecutively without gaps starting at zero, i.e. 0, 1, 2, 3, 4, ...

Listing 5: Configuration of segment ABC in web.xml

...
<init-param>
  <param-name>segmentName[0]</param-name>
  <param-value>Standard</param-value>
</init-param>
<init-param>
  <param-name>segmentName[1]</param-name>
  <param-value>ABC</param-value>
</init-param>
...

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 6: Console Output – Importing Codes and Data

...
11:10:20,348 INFO [STDOUT] Loading codes
11:10:20,504 INFO [STDOUT] Loading /WEB-INF/config/code/Root/en_US/accesslevel.xml
11:10:20,566 INFO [STDOUT] Loading /WEB-INF/config/code/Root/en_US/accountcategory.xml
11:10:20,566 INFO [STDOUT] Loading /WEB-INF/config/code/Root/en_US/accountstate.xml
...
...
11:10:21,941 INFO [STDOUT] Loading /WEB-INF/config/code/Root/de_CH/accesslevel.xml
11:10:21,957 INFO [STDOUT] Loading /WEB-INF/config/code/Root/de_CH/accountcategory.xml
11:10:21,988 INFO [STDOUT] Loading /WEB-INF/config/code/Root/de_CH/accountstate.xml
...
...
11:10:41,098 INFO [STDOUT] Loading /WEB-INF/config/code/Root/cs_CZ/usageproductbaseprice.xml
11:10:41,113 INFO [STDOUT] Loading /WEB-INF/config/code/Root/cs_CZ/utcoffset.xml
11:10:41,145 INFO [STDOUT] Storing 1491 code entries
11:14:52,535 INFO [STDOUT] Done
11:14:53,473 INFO [STDOUT] Loading data
11:14:53,504 INFO [STDOUT] Loading /WEB-INF/config/data/Standard/bug-and-feature-process.xml
11:14:59,582 INFO [STDOUT] Storing 10 objects
11:15:00,113 INFO [STDOUT] Loading /WEB-INF/config/data/Standard/workflows.xml
11:15:00,145 INFO [STDOUT] Storing 15 objects
11:15:00,629 INFO [STDOUT] Loading /WEB-INF/config/data/Root/uom_SI_and_Paper.xml
11:15:04,082 INFO [STDOUT] Storing 42 objects
11:15:09,160 INFO [STDOUT] Done
11:18:20,723 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/en_US
11:18:21,191 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/de_CH
11:18:21,410 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/es_MX
11:18:21,598 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/zh_CN
11:18:21,988 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/sv_SE
11:18:22,270 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/tr_TR
11:18:22,457 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/fr_FR
11:18:22,723 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/it_IT
11:18:22,941 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/ru_RU
11:18:23,223 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/pl_PL
11:18:23,504 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/pt_BR
11:18:24,285 INFO [STDOUT] Inspecting /WEB-INF/config/ui/Root/cs_CZ
11:18:24,535 INFO [STDOUT] Inspecting /WEB-INF/config/filters/

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.

3.4 Create a new User guest

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 10: 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 11: 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 in the grid Subjects:

Figure 12: 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 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 13: 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 14: Realm Default

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

Figure 15: Create a new Principal

You need to link this Principal with the previously created Subject. Click on the looking glass icon of the field Subject to open the Lookup Inspector in a new browser window. Select the Subject guest by clicking in the appropriate check box:

Figure 16: Select Subject guest in the Lookup Inspector

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 17: 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 18: 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). Click on the looking glass in the tab Member of Principal Groups to open the Lookup Inspector:

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

The Lookup Inspector lists all the principals and principal groups of the respective realm; principal group entries have a check box:

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

Select the Principal Group Users by clicking the appropriate check box as shown in the figure above. This will automatically close the Lookup Inspector.

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

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

Back in the tab Member of Principal Groups you click the button [+] to add the Principal to the Principal Group Users selected in the previous step:

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

You cannot just type Users into the input box – you must use the Lookup Inspector to select the appropriate Principal Group.

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 4

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 shown below:

Figure 24: View > Recalculate and Refresh activates/updates charts

As administrator you first have to create a new Contact in 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 25: 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 unless you know exactly what you are doing):

Figure 26: 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 to fetch values for Contact and Primary user group (note that you must use the Lookup Inspector to fetch values for the parameters Contact and Primary user group, i.e. you cannot just type some text into these fields), and then type a password (e.g. guest) into the fields Initial password and Password again:

Figure 27: 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 28: Result of operation Create User

The grid User Homes contains now 2 entries: admin-Standard and 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.

Congratulations! You have successfully created a new user guest. The new user should now be able to login. You can try this out with the following steps:

logoff
login again with Username guest and Password guest

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

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.