openCRX Quick Start

Version 1.7.1

www.opencrx.org

The contents of this file are subject to a BSD license (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License here

List of Figures
2-1. Secure communication between openCRX server and multiple mail servers
3-1. Data in the openCRX database can be partitioned into data segments.
3-2. Initial login as admin-Root
3-3. Initial screen after login as admin-Root
3-4. Realm "Default" is created automatically
3-5. admin-Root sets Access Levels of Codes
3-6. admin-Root sets Access Levels of Uoms
3-7. Create a new Segment
3-8. Verify creation of new principals admin-Standard and loader-Standard
3-9. Login as admin-Standard
3-10. Homepage of admin-standard (charts initialized)
3-11. Verify Users and User Groups
3-12. Create a new User by clicking on the button [Principal]
3-13. Enter Prinicpal name (=Login name) into the field "Qualifier"
3-14. Add Principal to Principal Group - Step 1
3-15. Add Principal to Principal Group - Step 2
3-16. Add Principal to Principal Group - Step 3
3-17. Add Principal to Principal Group - Step 4
3-18. As admin-Standard, create a Contact for the new user "guest"
3-19. Operation [Create User]
3-20. As root, verify creation of new user "guest"
3-21. The new user "guest" can login in the standard GUI
4-1. Provider List
5-1. Locale List
7-1. Operation vCard import
7-2. Result of the vCard import operation
7-3. Operation iCalendar import
7-4. Result of the iCalendar import operation
7-5. Operation Import on UserHome
8-1. Operation vCard export
8-2. Result of the vCard export operation
8-3. Operation iCalendar export
8-4. Result of the iCalendar export operation
8-5. Operation Export XML
9-1. Overview Event Subscription / Notification
9-2. Topics included in the openCRX distribution
9-3. Create a new subscription
9-4. Lookup Inspector for Topics
9-5. Subscription "New Account"
9-6. UserHome with the newly created subscription "New Account"
10-1. Create a new E-mail Account
10-2. E-mail Account Object
10-3. Grid Tab [E-mail]
10-4. E-mail Options
10-5. Create a Default Mail Server E-mail Account
11-1. Ready to launch MS Word

List of Examples
3-1. openCRX.users.properties with user=password syntax.
3-2. openCRX.roles.properties with user.Roles=role1,role2 syntax.
3-3. initializing the openCRX Root servlet
4-1. web.xml with the provider declaration for Forecasts
4-2. web.xml with the Forecasts provider commented out
5-1. web.xml with the locale declarations
5-2. web.xml with one of the locale declarations commented out
11-1. Sample VBA code (sample-letter.doc)
11-2. additionalElementDefinition for MS Word Sample Letter

Chapter 1. About this Book

This book describes what you need to get started with openCRX and how you configure openCRX.

Who this book is for

The intended audience are openCRX administrators and advanced users.

What do you need to understand this book

This book describes how to install openCRX and how to configure openCRX. If you intend to install openCRX it is a plus if you are comfortable with application servers and database servers (even though the explanations in this guide are rather detailed).

Chapter 2. Prerequisites

In a first step you must decide which database and which application server you are going to use.

As far as the database is concerned, the openCRX FAQ might give you some guidance in making your choice (please note that the Open Source distribution of openCRX includes all the required configuration/deployment files for MySQL, MaxDB, PostgreSQL, MS SQL, and Oracle.

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 Open Source distribution of openCRX includes all the required configuration/deployment files for JBoss (which is also Open Source and free), BEA Weblogic, and IBM WebSphere.

Having made your choices regarding database and application server you should get the appropriate openCRX Installation Guides from here. Following those guides you should then install the openCRX database and the application server.

If you follow our application server installation guides you will also install openMDX, the leading Open Source MDA platform.

The remainder of this document assumes that you decided for MySQL and JBoss and hence you should have a working installation of

the MySQL database (following the openCRX Installation Guide for MySQL) and
the JBoss application server (following the openCRX Installation Guide for JBoss)

Enabling Outgoing E-mail (SMTP Adapter)

If if you want to enable outgoing e-mail by activating the openCRX SMTP Adapter, please refer to the /core/README file contained in the opencrx-core distribution (e.g. opencrx-1.7.0-core.CRX.jre-1.4.zip). Enabling outgoing e-mail is optional (and only required if you want openCRX to send e-mail notifications).

Figure 2-1. Secure communication between openCRX server and multiple mail servers

The openCRX SMTP Adapter works best in combination with a corporate mail server (depending on the volume of outgoing e-mail you might even consider a dedicated e-mail server) with decent response times. Every user can define his preferred mail server or rely on the Default Mail Server defined by the segment administrator. The openCRX SMTP Adapter is TLS enabled, i.e. if the mail server supports TLS then the communication between the openCRX server and the mail server will be encrypted. Configuration of e-mail options at the user level is explained in chapter Outbound E-mail Service.

Chapter 3. Create 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 he would have edited the files openCRX.users.properties and openCRX.roles.properties in the directory ./jboss-4.0.1/server/default/conf as follows and then restarted the application server:

Example 3-1. openCRX.users.properties with user=password syntax.

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

Example 3-2. openCRX.roles.properties with user.Roles=role1,role2 syntax.

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

Before a user can login to openCRX you must first create a new login at the application server level. Of course you can automate this process. E.g. on JBoss you can replace the file-based org.jboss.security.auth.spi.UsersRolesLoginModule login module with the database login module org.jboss.security.auth.spi.DatabaseServerLoginModule and configure it to access the openCRX security tables security_Principal and security_Credential. Please refer to the JBoss installation guide if you want to make use of the database login module.

Overview

Before we get started with setting up openCRX it is helpful to you know that - by default - there are three types of users playing quite different roles in the context of openCRX:

Root (default login is admin-Root)
- Performs the initial openCRX setup. This initializes the database and loads basic openCRX working data (e.g. code tables). This is a one-time task.
- Creates new segments. openCRX is multi-entity enabled. Each entity's data is stored in its own data segment. The segmentation of data is a basic and important concept of openCRX. It allows to setup private areas for different user groups, e.g. branches of a company or different small business companies. A user can have multiple logins, whereas a login allows access to exactly one segment. E.g. a user demo can have the logins demo-companyA and demo-companyB which are managed by root in the table security_Principal. If the user logs in as demo-companyA he/she has access to the segment companyA, i.e. he/she can only see data created by users of companyA. This is shown in Figure 3-1. A small to medium setup has typically 1 data segment only, named Standard.
Administrator (default login is admin-<SegmentName>). Each data segment has its own administrator. E.g. the administrator for the segment companyA has the login admin-companyA, the administrator for the segment Standard has the login admin-Standard. The administrator is responsible for all administrative tasks related to a particular data segment, e.g. creating users.
User: A user is a standard openCRX user which manages accounts, products, leads, activities, etc. Each user is assigned to a segment and is member of one or more user groups.

Depending on your configuration/use of openCRX there may be "technical users" like - for example - loader-Standard, which is used to import data. You do not have to configure anything to create these technical users.

Figure 3-1. Data in the openCRX database can be partitioned into data segments.

enlarge

All users who access openCRX by the same web application (e.g. opencrx-core-CRX) also share the same customization files (user interface, code tables, basic data). The openCRX/Core README explains how to setup multiple and differently customized web applications.

The following sections explain:

Initial Setup of openCRX
Creation of a new data Segment
Create a User

Initial Setup

After deploying openCRX to the application server and creating the logins you are now ready for the initial setup.

Connect to the openCRX Root login page (e.g. http://localhost:8080/opencrx-core-CRX-Root/Login). Login as admin-Root as shown in Figure 3-2.

Figure 3-2. Initial login as admin-Root

The servlet loads the initial data, e.g. default security policies, subjects and principals, units of measurement, code tables, etc. The output is shown on the application server console as shown below:

Example 3-3. initializing the openCRX Root servlet

11:26:31,488 INFO  [STDOUT] Thu Aug 11 09:00:37 CEST 2005: Login: requestURL=http://...
11:26:31,492 INFO  [STDOUT] Thu Aug 11 09:00:37 CEST 2005: Login: locale=null
11:26:31,528 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/en_US
11:26:32,510 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/de_CH
11:26:33,431 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/es_MX
11:26:34,422 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/zh_CN
11:26:35,384 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/sv_SE
11:26:36,305 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/tr_TR
11:26:37,146 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fa_IR
11:26:37,917 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fr_FR
11:26:39,049 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/nl_NL
11:26:39,850 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/ru_RU
11:26:40,751 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pl_PL
11:26:41,833 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pt_BR
11:26:44,657 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/cs_CZ
11:26:45,528 INFO  [STDOUT] Loading 64 ui files for locale en_US
11:26:46,319 INFO  [STDOUT] Loading 64 ui files for locale de_CH
11:26:47,381 INFO  [STDOUT] Loading 64 ui files for locale es_MX
11:26:48,472 INFO  [STDOUT] Loading 64 ui files for locale zh_CN
11:26:49,584 INFO  [STDOUT] Loading 64 ui files for locale sv_SE
11:26:50,606 INFO  [STDOUT] Loading 64 ui files for locale tr_TR
11:26:51,707 INFO  [STDOUT] Loading 64 ui files for locale fa_IR
11:26:52,679 INFO  [STDOUT] Loading 64 ui files for locale fr_FR
11:26:53,750 INFO  [STDOUT] Loading 0 ui files for locale null
11:26:53,750 INFO  [STDOUT] Loading 64 ui files for locale nl_NL
11:26:54,721 INFO  [STDOUT] Loading 0 ui files for locale null
11:26:54,731 INFO  [STDOUT] Loading 64 ui files for locale ru_RU
11:26:55,723 INFO  [STDOUT] Loading 64 ui files for locale pl_PL
11:26:56,855 INFO  [STDOUT] Loading 0 ui files for locale null
11:26:56,855 INFO  [STDOUT] Loading 64 ui files for locale pt_BR
11:26:57,896 INFO  [STDOUT] Loading 64 ui files for locale cs_CZ
11:26:59,048 INFO  [STDOUT] Storing 2325 ui elements
11:27:10,374 INFO  [STDOUT] loading texts
11:27:10,394 INFO  [STDOUT] loading /WEB-INF/config/texts/en_US/texts.properties
11:27:10,404 INFO  [STDOUT] loading /WEB-INF/config/texts/en_US/opencrx.texts.properties
11:27:10,414 INFO  [STDOUT] loading /WEB-INF/config/texts/de_CH/opencrx.texts.properties
11:27:10,414 INFO  [STDOUT] loading /WEB-INF/config/texts/de_CH/texts.properties
11:27:10,414 INFO  [STDOUT] loading /WEB-INF/config/texts/es_MX/opencrx.texts.properties
11:27:10,424 INFO  [STDOUT] loading /WEB-INF/config/texts/es_MX/texts.properties
11:27:10,434 INFO  [STDOUT] loading /WEB-INF/config/texts/zh_CN/opencrx.texts.properties
11:27:10,444 INFO  [STDOUT] loading /WEB-INF/config/texts/zh_CN/texts.properties
11:27:10,464 INFO  [STDOUT] loading /WEB-INF/config/texts/sv_SE/opencrx.texts.properties
11:27:10,474 INFO  [STDOUT] loading /WEB-INF/config/texts/sv_SE/texts.properties
11:27:10,484 INFO  [STDOUT] loading /WEB-INF/config/texts/tr_TR/opencrx.texts.properties
11:27:10,484 INFO  [STDOUT] loading /WEB-INF/config/texts/tr_TR/texts.properties
11:27:10,484 INFO  [STDOUT] loading /WEB-INF/config/texts/fa_IR/opencrx.texts.properties
11:27:10,484 INFO  [STDOUT] loading /WEB-INF/config/texts/fa_IR/texts.properties
11:27:10,494 INFO  [STDOUT] loading /WEB-INF/config/texts/fr_FR/opencrx.texts.properties
11:27:10,504 INFO  [STDOUT] loading /WEB-INF/config/texts/fr_FR/texts.properties
11:27:10,514 INFO  [STDOUT] loading /WEB-INF/config/texts/nl_NL/opencrx.texts.properties
11:27:10,524 INFO  [STDOUT] loading /WEB-INF/config/texts/nl_NL/texts.properties
11:27:10,534 INFO  [STDOUT] loading /WEB-INF/config/texts/ru_RU/texts.properties
11:27:10,544 INFO  [STDOUT] loading /WEB-INF/config/texts/ru_RU/opencrx.texts.properties
11:27:10,554 INFO  [STDOUT] loading /WEB-INF/config/texts/pl_PL/opencrx.texts.properties
11:27:10,564 INFO  [STDOUT] loading /WEB-INF/config/texts/pl_PL/texts.properties
11:27:10,564 INFO  [STDOUT] loading /WEB-INF/config/texts/pt_BR/opencrx.texts.properties
11:27:10,564 INFO  [STDOUT] loading /WEB-INF/config/texts/pt_BR/texts.properties
11:27:10,574 INFO  [STDOUT] loading /WEB-INF/config/texts/cs_CZ/opencrx.texts.properties
11:27:10,584 INFO  [STDOUT] loading /WEB-INF/config/texts/cs_CZ/texts.properties
11:27:10,604 INFO  [STDOUT] loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
11:27:10,624 INFO  [STDOUT] de_CH not found. Fallback to en_US
...
11:27:10,734 INFO  [STDOUT] loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
11:27:10,744 INFO  [STDOUT] loading data
11:27:10,755 INFO  [STDOUT] loading /WEB-INF/config/bootstrap/100_security_policy.xml
11:27:10,825 INFO  [STDOUT] storing 5 objects
11:27:10,965 INFO  [STDOUT] loading /WEB-INF/config/bootstrap/101_security_subjects.xml
11:27:15,331 INFO  [STDOUT] storing 5 objects
11:27:15,672 INFO  [STDOUT] loading /WEB-INF/config/bootstrap/102_security_realms.xml
11:27:15,782 INFO  [STDOUT] storing 6 objects
11:27:15,952 INFO  [STDOUT] loading /WEB-INF/config/bootstrap/200_code_segment.xml
11:27:19,247 INFO  [STDOUT] storing 1 objects
11:27:19,597 INFO  [STDOUT] replacing org::opencrx::kernel::code1/provider/CRX/segment/Root
11:27:19,657 INFO  [STDOUT] loading /WEB-INF/config/bootstrap/300_admin_segment.xml
11:27:23,853 INFO  [STDOUT] storing 1 objects
11:27:23,863 INFO  [STDOUT] done
11:27:23,863 INFO  [STDOUT] loading codes
11:27:23,963 INFO  [STDOUT] loading /WEB-INF/config/code/en_US/accesslevel.xml
11:27:23,984 INFO  [STDOUT] loading /WEB-INF/config/code/en_US/accountcategory.xml
...
11:27:41,469 INFO  [STDOUT] loading /WEB-INF/config/code/cs_CZ/usageproductbaseprice.xml
11:27:41,499 INFO  [STDOUT] loading /WEB-INF/config/code/cs_CZ/utcoffset.xml
11:27:41,529 INFO  [STDOUT] storing 1573 code entries
11:28:20,525 INFO  [STDOUT] done
11:28:20,525 INFO  [STDOUT] Inspecting /WEB-INF/config/filters/
11:28:21,146 INFO  [STDOUT] loading /WEB-INF/config/filters/
11:28:28,436 INFO  [STDOUT] filter loaded for references 3113
11:28:28,436 INFO  [STDOUT] loading data
11:28:28,436 INFO  [STDOUT] loading /WEB-INF/config/data/uom_SI_and_Paper.xml
11:28:30,389 INFO  [STDOUT] storing 39 objects
11:28:32,762 INFO  [STDOUT] done
11:28:33,103 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/en_US
11:28:33,534 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/de_CH
11:28:33,914 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/es_MX
11:28:34,375 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/zh_CN
11:28:34,705 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/sv_SE
11:28:35,076 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/tr_TR
11:28:35,346 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fa_IR
11:28:35,546 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fr_FR
11:28:35,947 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/nl_NL
11:28:36,217 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/ru_RU
11:28:36,438 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pl_PL
11:28:36,898 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pt_BR
11:28:37,229 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/cs_CZ
11:28:38,200 INFO  [STDOUT] Inspecting /WEB-INF/config/filters/

After the successful startup of the root servlet you see the start screen as shown in Figure 3-3. You should see the root objects openCRX Administration, Codes, UOMs, Security Realms, Security Policies and Security Users / Groups.

Figure 3-3. Initial screen after login as admin-Root

If you started with an empty database (or imported new codes) you MUST SHUT DOWN the servlet or your app server, restart it, and then login again as admin-Root.

You can now navigate through the Codes, UOMs, etc. You should see the data which was initially loaded by the servlet. Verify now whether the principal admin-Root has been created correctly: click Security Realms > select the Default realm. You then see a tab containing the principal admin-Root and the principal groups Administrators, Roots, and Users as shown in Figure 3-4.

Figure 3-4. Realm "Default" is created automatically

Next you must set the access levels of all the codes to global (Browse), basic (Update), and basic (Delete). Open the code provider by clicking on Codes. Select the menu Security > Set Access Level to unhide the parameter panel and then set the parameters of this operation as shown in Figure 3-5.

Figure 3-5. admin-Root sets Access Levels of Codes

Click the button [OK] to start the operation (please note that this operation can take several minutes on a slower machine.).

Finally, you must set the access levels of all the units of measurment to global (Browse), basic (Update), and basic (Delete). Open the UOM provider by clicking on UOMs. Select the menu Security > Set Access Level to unhide the parameter panel and then set the parameters of this operation as shown in Figure 3-6.

Figure 3-6. admin-Root sets Access Levels of Uoms

Click the button [OK] to start the operation. Congratulations! You have successfully completed the initial setup of openCRX.

Creation of a new data Segment

Connect to the Root GUI and 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 Realm name to Default and the Segment name to Standard. Set the password to *. This creates a segment with name Standard. This is shown in Figure 3-7.

Figure 3-7. Create a new Segment

After creating the segment, click on the menu Security Realms and navigate to the realm Default. Verify whether the principals admin-Standard and loader-Standard were created as shown in Figure 3-8.

Figure 3-8. Verify creation of new principals admin-Standard and loader-Standard

Next you have to open a new browser window and start the Standard GUI by entering the URL http://localhost:8080/opencrx-core-CRX/Login. Login as admin-Standard as shown in Figure 3-9.

Figure 3-9. Login as admin-Standard

Before you can login as admin-Standard you must add the login to your application server's user list. E.g. with JBoss you must add the user to the file openCRX.users.properties:

After the first successful login as administrator you have to log out and log in again. This properly initializes the GUI.

Initially, the administrator homepage does not contain any charts. You can activate the charts by executing the operation View > Recalculate and Refresh (but do not forget to log out and log in again if it is the first time you logged in as administrator; otherwise the Recalculate and Refresh operation will fail!). Now the administrator homepage should look as shown in Figure 3-10.

Figure 3-10. Homepage of admin-standard (charts initialized)

Verify in Security Users / Groups whether the following entries exist as shown in Figure 3-11:

Standard\\Administrators
Standard\\Unassigned
Standard\\Unspecified
Standard\\Users
Standard\\admin-Standard
Standard\\loader-Standard

These default users and groups were created by the operation Create Administrator you previously executed as Root.

Figure 3-11. Verify Users and User Groups

Congratulations! You have successfully created the new segment Standard.

Create a User

The creation of a new user is performed in two steps:

as Root: create a new principal
as segment Administrator: create a new user

Open a new browser window, start the Root GUI by entering the URL http://localhost:8080/opencrx-core-CRX-Root/Login and then login as admin-Root. Create a new principal by navigating to Security Realms > Default and then selecting the creator menu New > Principal as shown in Figure 3-12.

Figure 3-12. Create a new User by clicking on the button [Principal]

You only have to set the field qualifier at the bottom of the new principal form. Enter the principal name (login name) of the user, e.g. guest as shown in Figure 3-13. The other fields can be left blank. They are set automatically by the operation Create User which is performed by the segment administrator in the next step.

Figure 3-13. Enter Prinicpal name (=Login name) into the field "Qualifier"

Before you can login as guest you must add the login to the application server's user list. E.g. with JBoss you must add the login to the file openCRX.users.properties.

Next you must add the newly created principal to the appropriate principal group. Navigate to the newly created principal (i.e. load it into the inspector) and click on the looking glass in the tab Member of Principal Groups to open the Lookup Inspector:

Figure 3-14. Add Principal to Principal Group - Step 1

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

Figure 3-15. Add Principal to Principal Group - Step 2

Click the check box next to the principal group you want to add the newly created principal to (normal users should be added to the principal group Users, segment administrators should be added to the principal group Administrators). This will automatically close the Lookup Inspector again.

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 selected in the previous step.

Figure 3-16. Add Principal to Principal Group - Step 3

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

Figure 3-17. Add Principal to Principal Group - Step 4

Now you have to go back to the Standard GUI (the servlet where you are logged in as admin-Standard). As administrator you first have to create a new contact in Accounts for the new user guest. Enter at least the last name as shown in Figure 3-18.

Figure 3-18. As admin-Standard, create a Contact for the new user "guest"

Click the button [Save] to store the contact.

Then 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 in Figure 3-19.

Figure 3-19. Operation [Create User]

Set the fields user id and principal name to the login name of the new user, e.g. guest. Set the field realm to Default. Set the field contact to the contact you have created previously (use the lookup inspector which appears if you click the looking glass icon) and set the primary user group to Standard\\Users (also use the lookup Inspector to do this). The password fields can be set to the value *.

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.

Click the button [OK] to create the new user. The operation creates a new homepage and links the Principal with the newly created user. You can verify the result of the operation by opening User Homepages segment which shows the newly created homepage.

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.

As root you can also verify whether the creation of the new user was successful. In the Root GUI Click Security Realms and navigate to the realm Default where you select the principal guest. The fields user and primary user group should be set as shown in Figure 3-20.

Figure 3-20. As root, verify creation of new user "guest"

Congratulations! You have successfully created a new user guest. The new user should now be able to login in the standard GUI.

Once the new user opens a browser window and connects to the standard GUI by entering the URL http://localhost:8080/opencrx-core-CRX/Login he will be able to login as guest as shown in Figure 3-21.

Figure 3-21. The new user "guest" can login in the standard GUI

The new user login must be added to the application server's user list, e.g. with JBoss to the file openCRX.users.properties:

After the first successful login as guest you have to log out and log in again. This properly initializes the GUI.

Chapter 4. Managing the Provider List

The default installation of openCRX activates all providers that are included in the Open Source distribution. The openCRX administrator may wish to remove certain providers from the provider list. This chapter shows how you can achieve this.

Let us assume that the openCRX administrator decided to hide the provider Forecasts.

Figure 4-1. Provider List

The provider list is contained in the file web.xml which is contained in the file opencrx-core-CRX.war (contained in opencrx-core-CRX-web.ear, both files are archive files that can be opened with a ZIP utility) deployed to your application server. The following discussion assumes that you use the JBoss application server.

In the case of the JBoss application server you should find the file opencrx-core-CRX-web.ear in the directory ./jboss-4.0.1/server/default/deploy. To make changes to files contained in the file opencrx-core-CRX-web.ear you can basically decide between the following two approaches (remember to stop the application server BEFORE you make any changes!):

(1) expand/unzip the EAR, (2) extract the file to be changed from the WAR, (3) change the file, (4) add the changed file back to the WAR, and then (5) pack/zip the EAR back together; this process is obviously pretty cumbersome if you intend to make frequent changes
you can first extract all the files contained in the EAR file to a directory with the same name as the EAR file, e.g. opencrx-core-CRX-web.ear; you can then extract all the files contained in the WAR file to a directory with the same name as the WAR file, e.g. opencrx-core-CRX.war (to avoid naming conflicts you do this by extracting the files to a temporary directory, delete the WAR file, and then rename the temporary directory to opencrx-core-CRX.war); now you can change files without unzipping/zipping

Let us now proceed. First you need to stop your application server. Then you locate the file web.xml in the directory .\jboss-4.0.1\server\default\deploy\opencrx-core-CRX-web.ear\opencrx-core-CRX.war\WEB-INF. Open it with an editor and locate the following few lines:

Example 4-1. web.xml with the provider declaration for Forecasts

<!-- Forecasts -->
<init-param>
  <param-name>rootObject[9]</param-name>
  <param-value>xri:@openmdx:org.opencrx.kernel.forecast1/provider/CRX/segment/${SEGMENT}</param-value>
</init-param>
<init-param>
  <param-name>rootObjectClass[9]</param-name>
  <param-value>org:opencrx:kernel:forecast1:Segment</param-value>
</init-param>

To hide this provider you can either delete the above lines or comment them out as shown in the following example:

Example 4-2. web.xml with the Forecasts provider commented out

<!-- Forecasts -->
<!--
<init-param>
  <param-name>rootObject[9]</param-name>
  <param-value>xri:@openmdx:org.opencrx.kernel.forecast1/provider/CRX/segment/${SEGMENT}</param-value>
</init-param>
<init-param>
  <param-name>rootObjectClass[9]</param-name>
  <param-value>org:opencrx:kernel:forecast1:Segment</param-value>
</init-param>
-->

Providers must be numbered with consecutive numbers (i.e. you must not skip numbers!). If you for example decided to hide the Forecasts provider then you must adapt the numbers of the following providers (Workflows, User Homepages, Security/Identity) accordingly.

Save the changed file and restart your application server. The provider list of openCRX will not show "Forecasts" anymore.

To unhide/reactivate this provider, simply uncomment the declarations in the file web.xml.

With some application servers it is necessary to delete temporary directories and working directories before starting the application server again to make sure that the configuration changes are properly processed.

Chapter 5. Managing Locales

The default installation of openCRX activates all locales that are included in the Open Source distribution. The openCRX administrator may wish to deactivate certain locales from the locale list. This chapter shows how you can achieve this.

Let us assume that the openCRX administrator decided to deactivate locale ru_RU (Russian).

Figure 5-1. Locale List

The locale list is contained in the file web.xml which is contained in the file opencrx-core-CRX.war (contained in opencrx-core-CRX-web.ear, both files are archive files that can be opened with a ZIP utility) deployed to your application server. The following discussion assumes that you use the JBoss application server.

(1) expand/unzip the EAR, (2) extract the file to be changed from the WAR, (3) change the file, (4) add the changed file back to the WAR, and then (5) pack/zip the EAR back together; this process is obviously pretty cumbersome if you intend to make frequent changes
you can first extract all the files contained in the EAR file to a directory with the same name as the EAR file, e.g. opencrx-core-CRX-web.ear; you can then extract all the files contained in the WAR file to a directory with the same name as the WAR file, e.g. opencrx-core-CRX.war (to avoid naming conflicts you do this by extracting the files to a temporary directory, delete the WAR file, and then rename the temporary directory to opencrx-core-CRX.war); now you can change files without unzipping/zipping

Example 5-1. web.xml with the locale declarations

.
<init-param>
  <param-name>locale[9]</param-name>
  <param-value>nl_NL</param-value>
</init-param>
<init-param>
  <param-name>locale[11]</param-name>
  <param-value>ru_RU</param-value>
</init-param>
<init-param>
  <param-name>locale[12]</param-name>
  <param-value>pl_PL</param-value>
</init-param>
.

To deactivate locale ru_RU you can simply comment out the relevant portion of the declaration as shown in the following example:

Example 5-2. web.xml with one of the locale declarations commented out

.
<init-param>
  <param-name>locale[9]</param-name>
  <param-value>nl_NL</param-value>
</init-param>
<!--
<init-param>
  <param-name>locale[11]</param-name>
  <param-value>ru_RU</param-value>
</init-param>
--><init-param>
  <param-name>locale[12]</param-name>
  <param-value>pl_PL</param-value>
</init-param>
.

Save the changed file and restart your application server. The locale list of openCRX will not include the locale "ru_RU" anymore.

Please note that the login page is a special case as the login page does not know anything about available locales. If you want to remove locale "ru_RU" from the login page as well, you need to edit the file Login.jsp which is contained in the file opencrx-core-CRX.war (contained in opencrx-core-CRX-web.ear, both files are archive files that can be opened with a ZIP utility). It is no big issue, however, if you do not update Login.jsp after deactivating a locale in web.xml - if somebody tries to login with a locale that is deactivated, the default locale (en_US) will be used to start the session.

To unhide/reactivate a previously deactivated locale, simply uncomment the respective declaration in the file web.xml.

Please refer to the openCRX Language Localization Guide for more details on how to localize openCRX according to your needs.

Chapter 6. Security

We do not recommend learning about security with mission critical data. Backup your data BEFORE you make changes if you are not certain what the consequences are! The default settings should work for virtually all users; the probability of getting yourself into trouble by changing default settings should not be underestimated. Read and understand the openCRX Security Guide BEFORE you make any changes.

Starting with openCRX v1.4.0 access control is activated. Please refer to the openCRX Security Guide for a detailed explanation of role-based security as it is implemented by openCRX. In this chapter we discuss a few select issues only, including disaster recovery if you locked yourself out and/or screwed up the security settings in a major way.

Security Setting of New Objects

New objects are by default created with the following security settings:

Owning User: User who is creating the object
Browse Access Level: 3 - deep
Update Access Level: 2 - basic
Delete Level: 2 - basic
Owning Groups: Primary User Group of the user who is creating the object and (meaning as well as) Owning Group(s) of the parent object of the new object

Please note that the User Group Users (e.g. Standard\\Users) is not added to the list of Owning Groups of newly created top-level objects (i.e. objects attached to a segment, even if Users is an Owning Group of the segment)

Please note that a users's primary user group is set by the segment administrator with the operation [Create User]. To change an existing user's primary group, the segment administrator simply executes the operation [Create User] again with a new parameter for primary user group.

In the context of activity management there are various operations that set/change the Owning Groups of objects based on the settings of an assigned Activity Tracker and not based on the settings of the user who executes the operation.

If you see N/P in a field instead of a more meaningful value you probably do not have browse access to the respective object (N/P stands for No Permission).

Resetting Security

If you get the setting of Update Access Level wrong you may not be able to change the respective object from the GUI anymore. For example, the only way to recover from setting Update Access Level to N/A for a particular object is to edit the data directly in the database!

If you (or one of your users) managed to screw up the security settings in a major way you may be forced to reset all security settings to a well-defined state. Included in the openCRX distribution are example scripts set-access-level.sql for all supported DBs. Please refer to the openCRX Security Guide for a detailed explanation of security BEFORE you execute any scripts. Consider running the complete script set-access-level.sql as a last resort only! In many cases it you will probably get away with fixing the security settings of a particular object on the DB.

Chapter 7. Importing Data

The task of importing data is handled by importers. In principle, you can import almost anything into openCRX, it's really only a matter of writing an importer. The Open Source distribution of openCRX includes importers for vCard and iCalendar files in addition to the XML importer. This allows you to import data from a large variety of other programs, including Microsoft Outlook. This chapter shows how to import data.

Importing vCard Files

These are the steps to import a vCard file:

click on the provider Accounts
click on the operations button [Import] to unhide the import dialog
select the appropriate language
click the Browse button and navigate to the vCard file you want to import
click to button [OK] to start the import operation

Figure 7-1. Operation vCard import

The result of the import operation also contains a link to the created/updated contact (only if the import was successful).

Figure 7-2. Result of the vCard import operation

Importing iCalendar Files

These are the steps to import an iCalendar file:

click on the provider Activities
click on the operations button [Import] to unhide the import dialog
select the appropriate language
click the Browse button and navigate to the iCalendar file you want to import
click to button [OK] to start the import operation

Figure 7-3. Operation iCalendar import

The result of the import operation also contains a link to the created/updated meeting (only if the import was successful).

Figure 7-4. Result of the iCalendar import operation

Importing XML Files

These are the steps to import an XML file:

click on the provider My Homepage
click on the operations button [Import] to unhide the import dialog
select the appropriate language
click the Browse button and navigate to the XML file you want to import
click to button [OK] to start the import operation

Figure 7-5. Operation Import on UserHome

Please note that only schema-compliant XML files can be imported.

Chapter 8. Exporting Data

The task of exporting data is handled by exporters. In principle, you can export any object from openCRX, it's really only a matter of writing an exporter. The Open Source distribution of openCRX includes exporters for vCard and iCalendar files in addition to XML files. This allows you to export contacts and meetings/sales visits or any other object from openCRX. vCard and iCalendar files can be imported by a large variety of other applications, including Microsoft Outlook. This chapter shows how to export data.

Exporting vCard Files

These are the steps to export a contact to a vCard file:

click on the provider Accounts and navigate to the contact you want to export
click on the operations button [Export as vCard] to unhide the export dialog
select the appropriate language
click to button [OK] to start the export operation

Figure 8-1. Operation vCard export

If the export operation was successful the result will contain a link to the vCard file. Click on that link to download the vCard file from the openCRX server.

Figure 8-2. Result of the vCard export operation

Exporting iCalendar Files

These are the steps to export a meeting (or a sales visit) to an iCalendar file:

click on the provider Activities and navigate to the meeting (or sales visit) you want to export
click on the operations button [Export as iCalendar] to unhide the export dialog
select the appropriate language
click to button [OK] to start the export operation

Figure 8-3. Operation iCalendar export

If the export operation was successful the result will contain a link to the iCalendar file. Click on that link to download the iCalendar file from the openCRX server.

Figure 8-4. Result of the iCalendar export operation

Exporting XML Files

All objects can be exported as XML files. These are the steps to export (for example) a meeting (or a sales visit) to an XML file:

click on the provider Activities and navigate to the meeting (or sales visit) you want to export
click on the expand button [>] and then on the operations button [Export XML] to unhide the export dialog
optional: enter the desired level of dereferencing into the field Criteria - if you leave this field empty a default value of "1" is used (this is usually sufficient)
click to button [OK] to start the export operation

Figure 8-5. Operation Export XML

The XML file is automatically zipped. You can download this file and save it.

Chapter 9. The Event Subscription / Notification Service

openCRX features a powerful event subscription and notification service (see Figure 9-1 for an overview):

Figure 9-1. Overview Event Subscription / Notification

enlarge

Administrators can create Topics containing information like a "topic path pattern" and "action to perform". Tthe openCRX distribution includes quite a few default topics (see Figure 9-2) to get you started, e.g.

Account Modification sends an alert to the UserHome of subscribed users if any account is modified
Alert Modification sends an e-mail alert to subscribed users if any of the alerts on their UserHome is modified
Lead Modification sends an alert to the UserHome of subscribed users if any lead is modified
.

Once a topic is created openCRX users can subscribe to it. Users manage their subscriptions individually on their UserHomes. If a topic has subscribed users and a monitored event occurs then the predefined action is performed. If the action is set to - for example - creating an alert for subscribed users, then each subscribed user will receive an alert on his UserHome.

Figure 9-2. Topics included in the openCRX distribution

enlarge

Example Subscription - New Accounts

In this example we will create a subscription to the standard topic Account Modifications Topic so that we will receive an alert on our UserHome whenever a new account is created. Login to openCRX (or navigate to your UserHome if you are already logged in). Click on the Grid tab Subscriptions to see all your current subscriptions:

Figure 9-3. Create a new subscription

Click on the creator menu New > Subscription to create a new subscription.

Enter a name and a description of the subscription to be created and check the box Active. Click on the edit icon of the field Event type and then select the option [1] Object Creation; this will ensure that we will get alerts for new accounts only (if you leave the field Event type empty you will get alerts for all event types, i.e. Object Creation, Object Modification, and Object Removal). Then you click the lookup icon next to the field Topic to start the lookup inspector where you select the topic entry Account Modifications Topic:

Figure 9-4. Lookup Inspector for Topics

Your new subscription should now look as follows:

Figure 9-5. Subscription "New Account"

To complete the process you click the button [Save].

Back on your UserHome you should now see an entry for your newly created subscription:

Figure 9-6. UserHome with the newly created subscription "New Account"

You can test your new subscription with the following steps:

create a new account (e.g. a new contact)
navigate to your homepage and check whether you actually received an alert related to the newly created account

In many cases you can make use of the operations Add Subscription, Remove Subscription, Add Subscription for Parent, and Remove Subscription for Parent located in the operations menu Tools. If your segment administrator has created the respective Topics these operations are a quick way to create/delete subscriptions. Try this out by navigating to a contact and executing the operation Tools > Add Subscription for Parent - this will add the subscription Account Modifications Topic to your list of subscriptions.

Chapter 10. Outbound E-mail Service

openCRX users can configure an E-mail account on their UserHome indicating where they would like to receive e-mail notifications (e.g. generated by a subscription to the topic "Alert Modifications Topic"). Click on My Homepage and select the Grid Tab [E-Mail]. Next you click on the creator menu New > E-Mail Account to create a new E-mail Account:

Figure 10-1. Create a new E-mail Account

Now you can define your E-mail Account for outbound e-mail service (SMTP):

Figure 10-2. E-mail Account Object

E-mail address: enter your e-mail address (i.e. the address where you would like to receive e-mail notifications)
Reply address: enter a reply address (is also used for the From field)
Default: check if this is your default e-mail address (notifications will only be sent to your default e-mail address)
(Outgoing) Mail server (SMTP): openCRX will connect to this SMTP server to submit e-mail notifications
(Outgoing) Mail server port: the default port for SMTP is 25, but you can change the port if your mail server is listening on a different port
(Outgoing) User name: enter the user name to be used for authentication purposes (only used if Authentication required is checked)
(Outgoing) Password: enter the password to be used for authentication purposes (only used if Authentication required is checked)
(Outgoing) Authentication required: if checked, openCRX will authenticate with User name and Password to get access to the mail server
(Outgoing) SSL/TLS: check this option if the outgoing mail server supports TLS and you want to encrypt the communication between openCRX and the mail server

Click the button [Save] to complete the creation of your E-mail Account.

Back on My Homepage you should see an entry in the Grid Tab [E-Mail] reflecting your new E-mail Account:

Figure 10-3. Grid Tab [E-mail]

If you edit your Homepage you can set additional E-mail options which are valid system-wide for your openCRX account:

Figure 10-4. E-mail Options

E-mail subject prefix: enter a string that might help you identifying or filtering e-mails from your openCRX server (optional, i.e. you can also leave this empty) - the entered string is prepended to the subject line of generated e-mails
Web access URL: enter the URL of the openCRX instance at hand; if entered correctly, generated e-mails will contain URLs that allow you to connect to your openCRX server with a single click

Click the button [Save] to update your Homepage..

You can test your new subscription with the following steps:

create a new account (e.g. a new contact)
navigate to your homepage and check whether you actually received an alert related to the newly created account
next click on the Grid Tab [Workflow Process Instances] on your homepage (unhide it by clicking on [>] if it is not visible)
there should be an entry org.opencrx.kernel.workflow.SendMail (you might have to sort the column Started on to located the recent entries)
click on the icon of the respective grid entry to inspect the corresponding Workflow Process Entry object
the grid Action Log Entries contains either the message body of the e-mail that was sent or an error message if the workflow failed (please note that it is not unusual to see a "timeout" error message even if you actually received an e-mail; the reason is an e-mail server with high latency - try sending out notifications through an e-mail server that is responsive).

If the mail server is not very responsive you might get warnings about failed deliveries from openCRX to the mail server even though respective e-mails are actually delivered to you. One of the solutions to this problem is the use of a more responsive mail server.

Default Mail Server

As a segment administrator you can define a default mail server. This allows users of your segment to send outbound e-mails (e.g. notification e-mails) through this default mail server without configuring their own mail server. Your segment users do not need to know any access information nor do they need any login credentials. Here are the steps to configure a default mail server for your segment:

connect to the standard GUI and login as segment administrator (e.g. admin-Standard)
click on My Homepage and select the Grid Tab [E-Mail]. Next you click on the creator menu New > E-Mail Account to create a new E-mail Account
provide all the relevant information (including credentials required to send e-mail - your credentials are safe as they are not accessible by other segment users)
replace the generated qualifier with the string SYSTEM as shown in Figure 10-5 and then click the button [Save] to create this new e-mail account

Figure 10-5. Create a Default Mail Server E-mail Account

Tell your segment users that they do not need to provide any information regarding Outgoing Mail Server (SMTP) (i.e. they can leave the respective fields empty). Furthermore, segment users must uncheck the option Default on their e-mail account settings to indicate that e-mails should be sent through the default mail server as configured by the segment administrator (but segment users must still provide a valid e-mail address and a reply address).

Chapter 11. Integration of MS Word

The basic approach we take to merge openCRX data with your MS Word templates is as follows (a detailed example is available on the openCRX website): create XML export of the object at hand (including referenced objects and all the required code tables), load a document based on a prepared template with MS Word and then pass the XML files to that document where VBA code will merge the data into the document. The following steps are required to configure this feature (it is expected that the Administrator takes care of this, i.e. we do not expect end users to go through the following steps.):

create a template with placeholders of the sort <<tagName>>; you can either start with a template included in the openCRX distribution (templates are located in opencrx-core-CRX-web.ear\opencrx-core-CRX.war\documents), download the MS Word Template "sample-letter" that already contains lots of VBA helper functions or you can start from scratch and write your own library

adapt the VBA code specific to the template (i.e. you need to make sure that all your placeholders are replaced with openCRX data when the code is executed)

Example 11-1. Sample VBA code (sample-letter.doc)

   contact = getObj(xmlclean, "org.opencrx.kernel.account1.Contact")
   localeIdx = 0
   Call ReplaceField("salutationCode$ShortText", getCodeValueText(xmlclean, "salutationCode", Val(getTagValue(contact, "salutationCode")), localeIdx, False), False)
   Call ReplaceField("lastName", getTagValue(contact, "lastName"), False)
   'primary mailing address
   ReDim usagefilter(0, 1)
   usagefilter(0, 0) = "usage"
   usagefilter(0, 1) = "300" 'primary
   mailingAddress = getObjList(getContent(xmlclean, "org.opencrx.kernel.account1.Contact"), "address", usagefilter, "postalStreet")
   Call ReplaceField("postalAddressLine", getTagMultiValueAsString(getTagValue(mailingAddress(0), "postalAddressLine"), itemTag), False)
   Call ReplaceField("postalStreet", getTagMultiValueAsString(getTagValue(mailingAddress(0), "postalStreet"), itemTag), False)
   Call ReplaceField("postalCity", getTagValue(mailingAddress(0), "postalCity"), False)
   Call ReplaceField("postalState", getTagValue(mailingAddress(0), "postalState"), False)
   Call ReplaceField("postalCode", getTagValue(mailingAddress(0), "postalCode"), False)
   Call ReplaceField("postalCountry$ShortText", getCodeValueText(xmlclean, "country", Val(getTagValue(mailingAddress(0), "postalCountry")), localeIdx, False), False)
   phoneNumber = getObjList(getContent(xmlclean, "org.opencrx.kernel.account1.Contact"), "address", usagefilter, "phoneNumberFull")
   Call ReplaceField("primaryPhone", getTagValue(phoneNumber(0), "phoneNumberFull"), False)

store your template in a place where it can be read by all those users who need to create documents based on it (e.g. on your WebDAV server, on your file server, or directly on the openCRX server, e.g. in the directory opencrx-core-CRX-web.ear\opencrx-core-CRX.war\documents like the sample templates)

add an <additionalElementDefinition> block to the XML exporter section of the ui configuration file common.xml and set the template attribute so that it points to your template

Example 11-2. additionalElementDefinition for MS Word Sample Letter

   <org.openmdx.ui1.ElementDefinition name="org:opencrx:kernel:base:XmlExporter:Pane:Op:Tab:exportXml">
    <_object>
     <active>true</active>
     <toolTip>
      <_item>Export XML</_item>
     </toolTip>
     <label>
      <_item>Export XML</_item>
     </label>
     <iconKey>org:opencrx:kernel:Export</iconKey>
     <order>
      <_item>0</_item>
      <_item>0</_item>
      <_item>5</_item>
     </order>
    </_object>
    <_content>

   <additionalElementDefinition>
      <org.openmdx.ui1.AdditionalElementDefinition id="ExportContactToWord">
       <_object>
        <active>true</active>
        <toolTip>
         <_item>Export to Word</_item>
        </toolTip>
        <label>
         <_item>Word Sample Letter</_item>
        </label>
        <iconKey>org:opencrx:kernel:Export</iconKey>
        <order>
         <_item>0</_item>
         <_item>0</_item>
         <_item>6</_item>
        </order>
        <forClass>
         <_item>org:opencrx:kernel:account1:Contact</_item>
        </forClass>
        <memberDefinitionElementName>
         <_item>item</_item>
        </memberDefinitionElementName>
        <memberDefinitionMimeType>
         <_item>application/x-openmdx-xml-for-word-export;template=documents/sample-letter.doc;macro=xmlMerge;visible=true</_item>
        </memberDefinitionMimeType>
       </_object>
      </org.openmdx.ui1.AdditionalElementDefinition>
     </additionalElementDefinition>
    </_content>
   </org.openmdx.ui1.ElementDefinition>

after restarting your application server you can create merged Word documents with a single click

Figure 11-1. Ready to launch MS Word

It is probably helpful if you look at the sample that is provided with the distribution (details are published on the openCRX website).

Chapter 12. Next Steps

Appendix A. Appendix

Bibliography

[01] openCRX - the leading open source CRM solution, opencrx.org.

@ http://www.opencrx.org

[02] openMDX - The leading open source MDA platform, openmdx.org.

@ http://www.openmdx.org