Home
Demo
Documentation
Downloads
FAQ
Project
Support
Tour
Team

Community
Forums
openCRX Partners
 
Features
Roadmap
License

 



SourceForge.net Logo

openCRX Quick Start

Version 1.8.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

Table of Contents
1. About this Book
Who this book is for
What do you need to understand this book
2. Prerequisites
Enabling Outgoing E-mail (SMTP Adapter)
3. Create Logins
Overview
Initial Setup
Creation of a new data Segment
Create a User
4. Running the Workflow Execution Client
SendMail Workflow (JavaMail)
5. Managing the Provider List
6. Managing Locales
7. Security
Security Setting of New Objects
Resetting Security
8. Importing Data
Importing vCard Files
Importing iCalendar Files
Importing XML Files
9. Exporting Data
Exporting vCard Files
Exporting iCalendar Files
Exporting XML Files
10. The Event Subscription / Notification Service
Example Subscription - New Accounts
11. Outbound E-mail Service
Default Mail Server
12. Integration of MS Word
13. Next Steps
A. Appendix
Bibliography
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 in Realm 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 Subject
3-13. Enter Subject name (=Login name) into the field "Qualifier"
3-14. Newly created Subject "guest"
3-15. Create a new Principal
3-16. Link new Principal with Subject guest
3-17. Add Principal to Principal Group - Step 1
3-18. Add Principal to Principal Group - Step 2
3-19. Add Principal to Principal Group - Step 3
3-20. Add Principal to Principal Group - Step 4
3-21. As admin-Standard, create a Contact for the new user "guest"
3-22. Operation [Create User]
3-23. As root, verify creation of new user "guest.User" in Realm Standard
3-24. The new user "guest" can login in the standard GUI
5-1. Provider List
6-1. Locale List
7-1. Subjects, Realms, and Principals
7-2. Segment Administration
7-3. Role Drop Down with list of available Principals
8-1. Operation vCard import
8-2. Result of the vCard import operation
8-3. Operation iCalendar import
8-4. Result of the iCalendar import operation
8-5. Operation Import on UserHome
9-1. Operation vCard export
9-2. Result of the vCard export operation
9-3. Operation iCalendar export
9-4. Result of the iCalendar export operation
9-5. Operation Export XML
10-1. Overview Event Subscription / Notification
10-2. Topics included in the openCRX distribution
10-3. Create a new subscription
10-4. Lookup Inspector for Topics
10-5. Subscription "New Account"
10-6. UserHome with the newly created subscription "New Account"
11-1. Create a new E-mail Account
11-2. E-mail Account Object
11-3. Grid Tab [E-mail]
11-4. E-mail Options
11-5. Create a Default Mail Server E-mail Account
12-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
5-1. web.xml with the provider declaration for Forecasts
5-2. web.xml with the Forecasts provider commented out
6-1. web.xml with the locale declarations
6-2. web.xml with one of the locale declarations commented out
12-1. Sample VBA code (sample-letter.doc)
12-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 to 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 should read the file core/README included in the distribution. The README contains important information – for example on how you can build the Runtime Binaries from the distribution.

Read the file core/README included in the distribution.

Next, 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 Running the Workflow Execution Client and SendMail Workflow (JavaMail). 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 this requires creating/editing the files openCRX.users.properties and openCRX.roles.properties in the directory ./jboss-4.0.2/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. 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 who 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

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

14:10:36,006 INFO  [Server] JBoss (MX MicroKernel) [4.0.2 (build: CVSTag=JBoss_4_0_2 date=200505022023)] Started in 1m:10s:892ms
14:12:16,390 INFO  [STDOUT] Tue Oct 04 14:12:16 CEST 2005: Login: requestURL=http://demo.opencrx.org/opencrx-core-CRX-Root/Login.jsp; isRequestedSessionIdFromCookie=false
14:12:16,390 INFO  [STDOUT] Tue Oct 04 14:12:16 CEST 2005: Login: locale=null
14:16:14,813 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/en_US
14:16:15,774 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/de_CH
14:16:16,556 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/es_MX
14:16:19,820 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/zh_CN
14:16:20,732 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/sv_SE
14:16:21,583 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/tr_TR
14:16:22,374 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fa_IR
14:16:23,115 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fr_FR
14:16:23,856 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/it_IT
14:16:24,757 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/nl_NL
14:16:25,388 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/ru_RU
14:16:26,209 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pl_PL
14:16:26,971 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pt_BR
14:16:27,722 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/cs_CZ
14:16:28,603 INFO  [STDOUT] Loading 65 ui files for locale en_US
14:16:30,215 INFO  [STDOUT] Loading 65 ui files for locale de_CH
14:16:31,818 INFO  [STDOUT] Loading 65 ui files for locale es_MX
14:16:33,320 INFO  [STDOUT] Loading 65 ui files for locale zh_CN
14:16:34,792 INFO  [STDOUT] Loading 65 ui files for locale sv_SE
14:16:36,134 INFO  [STDOUT] Loading 65 ui files for locale tr_TR
14:16:37,586 INFO  [STDOUT] Loading 65 ui files for locale fa_IR
14:16:38,918 INFO  [STDOUT] Loading 65 ui files for locale fr_FR
14:16:40,350 INFO  [STDOUT] Loading 66 ui files for locale it_IT
14:16:41,792 INFO  [STDOUT] Loading 65 ui files for locale nl_NL
14:16:43,134 INFO  [STDOUT] Loading 0 ui files for locale null
14:16:43,144 INFO  [STDOUT] Loading 65 ui files for locale ru_RU
14:16:44,616 INFO  [STDOUT] Loading 65 ui files for locale pl_PL
14:16:46,108 INFO  [STDOUT] Loading 0 ui files for locale null
14:16:46,118 INFO  [STDOUT] Loading 65 ui files for locale pt_BR
14:16:47,500 INFO  [STDOUT] Loading 65 ui files for locale cs_CZ
14:16:52,147 INFO  [STDOUT] Storing 2411 ui elements
14:17:06,297 INFO  [STDOUT] Loading texts
14:17:06,297 INFO  [STDOUT] Loading /WEB-INF/config/texts/en_US/texts.properties
14:17:06,317 INFO  [STDOUT] Loading /WEB-INF/config/texts/en_US/opencrx.texts.properties
14:17:06,337 INFO  [STDOUT] Loading /WEB-INF/config/texts/de_CH/opencrx.texts.properties
14:17:06,347 INFO  [STDOUT] Loading /WEB-INF/config/texts/de_CH/texts.properties
14:17:06,357 INFO  [STDOUT] Loading /WEB-INF/config/texts/es_MX/opencrx.texts.properties
14:17:06,377 INFO  [STDOUT] Loading /WEB-INF/config/texts/es_MX/texts.properties
14:17:06,387 INFO  [STDOUT] Loading /WEB-INF/config/texts/zh_CN/opencrx.texts.properties
14:17:06,407 INFO  [STDOUT] Loading /WEB-INF/config/texts/zh_CN/texts.properties
14:17:06,427 INFO  [STDOUT] Loading /WEB-INF/config/texts/sv_SE/opencrx.texts.properties
14:17:06,427 INFO  [STDOUT] Loading /WEB-INF/config/texts/sv_SE/texts.properties
14:17:06,437 INFO  [STDOUT] Loading /WEB-INF/config/texts/tr_TR/opencrx.texts.properties
14:17:06,447 INFO  [STDOUT] Loading /WEB-INF/config/texts/tr_TR/texts.properties
14:17:06,457 INFO  [STDOUT] Loading /WEB-INF/config/texts/fa_IR/opencrx.texts.properties
14:17:06,467 INFO  [STDOUT] Loading /WEB-INF/config/texts/fa_IR/texts.properties
14:17:06,477 INFO  [STDOUT] Loading /WEB-INF/config/texts/fr_FR/opencrx.texts.properties
14:17:06,487 INFO  [STDOUT] Loading /WEB-INF/config/texts/fr_FR/texts.properties
14:17:06,517 INFO  [STDOUT] Loading /WEB-INF/config/texts/it_IT/opencrx.texts.properties
14:17:06,527 INFO  [STDOUT] Loading /WEB-INF/config/texts/it_IT/texts.properties
14:17:06,537 INFO  [STDOUT] Loading /WEB-INF/config/texts/nl_NL/opencrx.texts.properties
14:17:06,547 INFO  [STDOUT] Loading /WEB-INF/config/texts/nl_NL/texts.properties
14:17:06,567 INFO  [STDOUT] Loading /WEB-INF/config/texts/ru_RU/texts.properties
14:17:06,577 INFO  [STDOUT] Loading /WEB-INF/config/texts/ru_RU/opencrx.texts.properties
14:17:06,598 INFO  [STDOUT] Loading /WEB-INF/config/texts/pl_PL/opencrx.texts.properties
14:17:06,598 INFO  [STDOUT] Loading /WEB-INF/config/texts/pl_PL/texts.properties
14:17:06,608 INFO  [STDOUT] Loading /WEB-INF/config/texts/pt_BR/opencrx.texts.properties
14:17:06,618 INFO  [STDOUT] Loading /WEB-INF/config/texts/pt_BR/texts.properties
14:17:06,628 INFO  [STDOUT] Loading /WEB-INF/config/texts/cs_CZ/opencrx.texts.properties
14:17:06,638 INFO  [STDOUT] Loading /WEB-INF/config/texts/cs_CZ/texts.properties
14:17:06,688 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,728 INFO  [STDOUT] de_CH not found. Fallback to en_US
14:17:06,738 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,748 INFO  [STDOUT] es_MX not found. Fallback to en_US
14:17:06,758 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,778 INFO  [STDOUT] zh_CN not found. Fallback to en_US
14:17:06,778 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,798 INFO  [STDOUT] sv_SE not found. Fallback to en_US
14:17:06,808 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,818 INFO  [STDOUT] tr_TR not found. Fallback to en_US
14:17:06,828 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,838 INFO  [STDOUT] fa_IR not found. Fallback to en_US
14:17:06,848 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,858 INFO  [STDOUT] fr_FR not found. Fallback to en_US
14:17:06,868 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,888 INFO  [STDOUT] it_IT not found. Fallback to en_US
14:17:06,888 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,908 INFO  [STDOUT] nl_NL not found. Fallback to en_US
14:17:06,908 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,928 INFO  [STDOUT] ru_RU not found. Fallback to en_US
14:17:06,938 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,948 INFO  [STDOUT] pl_PL not found. Fallback to en_US
14:17:06,958 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,968 INFO  [STDOUT] pt_BR not found. Fallback to en_US
14:17:06,978 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:06,988 INFO  [STDOUT] cs_CZ not found. Fallback to en_US
14:17:06,998 INFO  [STDOUT] Loading /WEB-INF/config/report/en_US/org.opencrx.kernel.activity1.Segment-ActivityTrackers.rptdesign
14:17:07,018 INFO  [STDOUT] Loading data
14:17:07,028 INFO  [STDOUT] Loading /WEB-INF/config/bootstrap/100_security_policy.xml
14:17:07,108 INFO  [STDOUT] Storing 5 objects
14:17:23,091 INFO  [STDOUT] Creating org::openmdx::security::authorization1/provider/CRX/segment/Root
14:17:23,282 INFO  [STDOUT] Creating org::openmdx::security::authorization1/provider/CRX/segment/Root/policy/Default
14:17:23,352 INFO  [STDOUT] Creating org::openmdx::security::authorization1/provider/CRX/segment/Root/policy/Default/role/OpenCrxAdministrator
14:17:23,442 INFO  [STDOUT] Creating org::openmdx::security::authorization1/provider/CRX/segment/Root/policy/Default/role/OpenCrxUser
14:17:23,492 INFO  [STDOUT] Creating org::openmdx::security::authorization1/provider/CRX/segment/Root/policy/Default/role/OpenCrxRoot
14:17:23,512 INFO  [STDOUT] Loading /WEB-INF/config/bootstrap/101_security_subjects.xml
14:17:26,536 INFO  [STDOUT] Storing 2 objects
14:17:26,566 INFO  [STDOUT] Creating org::opencrx::security::identity1/provider/CRX/segment/Root
14:17:26,636 INFO  [STDOUT] Creating org::opencrx::security::identity1/provider/CRX/segment/Root/subject/admin-Root
14:17:26,676 INFO  [STDOUT] Loading /WEB-INF/config/bootstrap/102_security_realms.xml
14:17:26,757 INFO  [STDOUT] Storing 10 objects
14:17:26,777 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root
14:17:26,827 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Default
14:17:26,887 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Default/principal/admin-Root
14:17:27,057 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Default/principal/Administrators
14:17:27,157 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Default/principal/Users
14:17:27,377 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Root
14:17:27,417 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Root/principal/Administrators
14:17:27,518 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Root/principal/Users
14:17:27,588 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Root/principal/admin-Root.User
14:17:27,678 INFO  [STDOUT] Creating org::openmdx::security::realm1/provider/CRX/segment/Root/realm/Root/principal/admin-Root
14:17:27,758 INFO  [STDOUT] Loading /WEB-INF/config/bootstrap/200_code_segment.xml
14:17:30,542 INFO  [STDOUT] Storing 1 objects
14:17:34,087 INFO  [STDOUT] Creating org::opencrx::kernel::code1/provider/CRX/segment/Root
14:17:34,207 INFO  [STDOUT] Loading /WEB-INF/config/bootstrap/300_admin_segment.xml
14:17:37,332 INFO  [STDOUT] Storing 1 objects
14:17:37,372 INFO  [STDOUT] Creating org::opencrx::kernel::admin1/provider/CRX/segment/Root
14:17:37,452 INFO  [STDOUT] Done
14:17:37,462 INFO  [STDOUT] Loading codes
14:17:37,482 INFO  [STDOUT] Loading /WEB-INF/config/code/en_US/accesslevel.xml
14:17:37,522 INFO  [STDOUT] Loading /WEB-INF/config/code/en_US/accountcategory.xml
...
14:18:07,315 INFO  [STDOUT] Loading /WEB-INF/config/code/cs_CZ/utcoffset.xml
14:18:07,355 INFO  [STDOUT] Storing 1586 code entries
14:20:39,734 INFO  [STDOUT] Done
14:20:39,754 INFO  [STDOUT] Inspecting /WEB-INF/config/filters/
14:20:39,834 INFO  [STDOUT] Loading /WEB-INF/config/filters/
14:20:45,372 INFO  [STDOUT] Loaded filters #3624
14:20:45,382 INFO  [STDOUT] Loading data
14:20:45,392 INFO  [STDOUT] Loading /WEB-INF/config/data/uom_SI_and_Paper.xml
14:20:48,146 INFO  [STDOUT] Storing 39 objects
14:20:50,950 INFO  [STDOUT] Done
14:20:51,811 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/en_US
14:20:52,042 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/de_CH
14:20:52,232 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/es_MX
14:20:52,412 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/zh_CN
14:20:52,603 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/sv_SE
14:20:52,763 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/tr_TR
14:20:52,943 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fa_IR
14:20:53,073 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/fr_FR
14:20:53,243 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/it_IT
14:20:53,454 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/nl_NL
14:20:53,594 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/ru_RU
14:20:53,794 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pl_PL
14:20:53,984 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/pt_BR
14:20:54,145 INFO  [STDOUT] Inspecting /WEB-INF/config/ui/cs_CZ
14:20:54,365 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 double check the spelling of the name of your DB (e.g. crx-crx vs. crx-CRX), verify user name and password, verify the permissions of the user, etc.

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 Subjects (and the special providers History and Favorites).

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, and Users as shown in Figure 3-4.

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

The initialization sequence also created the realm Root with the 4 Principals Administrators, Users, admin-Root, and admin-Root.User.

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 Segment name to Standard. Leave the field Admin principal name empty and 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

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). Please note that segments must be numbered consecutively without holes starting at zero, i.e. 0, 1, 2, 3, 4, ...

Example. Segment configuration in web.xml (adding Segment ABC) 


<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>

After creating the segment, click on the menu Security Realms and navigate to the realm Standard. Verify whether the following principals were created as shown in Figure 3-8: Administrators, Unassigned, Unspecified, Users, admin-Standard, admin-Standard.User.

Figure 3-8. Verify creation of new principals in Realm 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 Realm whether the following entries exist as shown in Figure 3-11:

  • Administrators

  • Unassigned

  • Unspecified

  • Users

  • admin-Standard

  • admin-Standard.User

These default principals 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

New users are created with the following steps:

  • as Root (admin-Root): create a new subject

  • as Root (admin-Root): create a new principal in realm Default and link this principal to the subject created in the previous step

  • as Root (admin-Root): make principal member of group Users

  • as segment Administrator (admin-Standard): 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 subject by navigating to Security Subjects and then selecting the creator menu New > Subject as shown in Figure 3-12.

Figure 3-12. Create a new Subject

The user name (login id) of the new user must be entered into the field Qualifier at the bottom of the form!

Enter the subject name (which will be the user/login id) of the user into the field Qualifier (e.g. guest as shown in Figure 3-13). It is recommended that you also set the field Description.

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

After clicking on the button [Save] the new Subject is created:

Figure 3-14. Newly created Subject "guest"

Next, you need to create a new Principal by clicking on the provider Security Realms and then selecting Realm Default. Select the creator menu New > Principal as shown in Figure 3-15.

Figure 3-15. Create a new Principal

The user name (login id) of the new user must be entered into the field Qualifier at the bottom of the form!

Enter the Principal name (which will be the user/login id) of the user into the field Qualifier (e.g. guest as shown in Figure 3-16). Next 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. This will take you back to the Principal form as shown in Figure 3-16.

Figure 3-16. Link new Principal with Subject guest

After clicking on the button [Save] the new Principal is created.

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-17. 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-18. 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-19. Add Principal to Principal Group - Step 3

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

Figure 3-20. 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-21.

Figure 3-21. 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-22 (note that you need to 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).

Figure 3-22. Operation [Create User]

Set the field Principal name to the login name of the new user, e.g. guest. 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 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 Standard. In addition to the Principal guest you should also see the User guest.User.

Figure 3-23. As root, verify creation of new user "guest.User" in Realm Standard

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-24.

Figure 3-24. 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. Running the Workflow Execution Client

openCRX comes with a workflow execution client (WfExecutionClient) which executes pending workflows (SendAlert, SendMail, etc.). Workflows are executed outside of the openCRX application so that even large numbers of pending workflows do not interfere and slow down the openCRX server (NOTE: The workflow executor will be implemented as message driven bean (MDB) in the future).

The WfExecutionClient performs the following tasks:

  • 'Listen' to object modifications and check for matching subscriptions. The WfExecutionClient periodically checks the AuditEntry table for new object creation, modification and removal events.

  • Create a workflow process for each matching subscription.

  • Invoke the openCRX server to execute synchronous workflows (e.g. SendAlert).

  • Execute asynchronous workflows (e.g. SendMail) in the context of the WfExecutionClient.

The following steps are required to run the WfExecutionClient:

  • Setup openCRX for ant as described in step 4/ of the README. Preferably you install and setup openCRX in a dedicated directory, e.g. opencrx-1.8.1-clients-CRX.

  • Install an openCRX server instance as described in the application server installation guides available here.

  • Configure the connection URLs, username and password in the client resource adapter files:

    • core\src\ear\opencrx-core-WfExecutionClient.ear\server.rar\META-INF\ra.xml

    Adapt the values for the fields UserName, Password, ConnectionURL to your environment. admin-Standard is typically OK as username for the Segment Standard.

  • Adapt the logger configuration located in ../core/etc/log/SysLog.log.properties. LogFilePath must point to an existing directory.

  • Run the client with

    ant -Dclient.provider.name="CRX" -Dclient.segment.name="Standard" WfExecutionClient

    Specify a provider (e.g. CRX) and segment name (e.g. Standard) matching the openCRX server. If you get exceptions then either the ra.xml configuration does not match your environment or you don't have a running openCRX instance. Also check the log file configuration in the previous step.

SendMail Workflow (JavaMail)

SendMail is a workflow which enables openCRX to send e-mail notifications to users. The following steps (in addition to running the workflow execution client) are required to activate the SendMail workflow:

  • install JavaMail for the Java VM in use as described at J2EE JavaMail

  • copy opencrx-sendmail.jar to JAVA_HOME/jre/lib/ext

Chapter 5. 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 5-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.2/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.2\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 5-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 5-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, Realm) 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 6. 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 6-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.

In the case of the JBoss application server you should find the file opencrx-core-CRX-web.ear in the directory ./jboss-4.0.2/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.2\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 6-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 6-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.

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.

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 7. 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 will present a high-level overview and we will 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.

Starting with openCRX v1.8.0 various security concept enhancements are activated. Some of the basic concepts are:

  • Each ,real' user is represented by a subject, e.g. ,Guest'.

  • Each subject has a login id (application login principal), e.g. ,guest'. Each (application login) principal is assigned to a subject (e.g. the principal ,guest' is assigned to subject ,Guest') and allows a ,real user' to login to openCRX. Subjects and application login principals are managed by the openCRX Root administrator (admin-Root).

  • A ,real user' can have one or more additional segment login principals. A segment login principal has typically the same name as the application login principal (e.g. ,guest') and grants a ,real user' login access to a segment. Segment login principals are managed by the openCRX segment administrators (e.g. admin-Standard for the Segment Standard).

  • Each ,real user' which has access to a segment (i.e. has a segment login principal) has (in addition to the segment login principal) a segment user principal, e.g. ,guest.User'. The segment user principal is required to assign objects to an owning user.

  • Principals are stored in realms. Each segment has a corresponding realm:

    • The application login principals are stored in the realm ,Default'.

    • The segment login principals for segment ,<segment name>' are stored in the realm ,<segment name>'.

    • Each segment has a segment administrator principal (admin-<segment name>).

  • Each segment login principal has a home page in the corresponding segment (qualifier of principal and home page must match!).

  • Each segment login principal is correlated with a contact. This correlation is e.g. required to find all activities and contracts assigned to the logged in principal.

All security data is managed by the openCRX security provider. The following figure should give you an idea of how it all fits together:

Figure 7-1. Subjects, Realms, and Principals

Hence, summarizing the above:

  • there is a Realm for each segment (e.g. if you followed this guide there is a Realm Standard because you created a segment Standard)

  • the Realm Default acts as login realm, i.e. it contains all principals who are allowed to login to the application server

  • there is a subject for each 'real user' and all principals of a user are assigned to the same subject; this allows openCRX to find all principals of a user (--> role selection drop down)

The segment administrator (e.g. admin-Standard) creates Principals and User Homepages with the operation createUser() :

  • Each segment login principal has a home page in the corresponding segment (qualifier of principal and home page must match!).

  • Each segment login principal is correlated with a contact. This correlation is e.g. required to find all activities and contracts assigned to the logged in principal.

Figure 7-2. Segment Administration

While each 'real user' (typically) has 1 application login principal only, 'real users' may have multiple segment login principals (e.g. because a 'real user' is allowed to access multiple segments or because a 'real user' is allowed to access a particular segment in different roles [e.g. Head of Sales and and CFO] - all available segment login principals are listed in the so-called Role Drop Down:

Figure 7-3. Role Drop Down with list of available Principals

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 8. 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

  • select the operation File | Import vCard 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 8-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 8-2. Result of the vCard import operation

Importing iCalendar Files

These are the steps to import an iCalendar file:

  • click on the provider Activities

  • select the operation File | Import iCal 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 8-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 8-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

  • select the operation File | 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 8-5. Operation Import on UserHome

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

Chapter 9. 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

  • select the operation File | Export as vCard to unhide the export dialog

  • select the appropriate language

  • click to button [OK] to start the export operation

Figure 9-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 9-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

  • select the operation File | Export as iCal. to unhide the export dialog

  • select the appropriate language

  • click to button [OK] to start the export operation

Figure 9-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 9-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 contact to an XML file:

  • click on the provider Accounts and navigate to the contact you want to export

  • select the operation File | Export XML. to unhide the export dialog

  • optional: enter the desired reference filter(s) into the field Reference filter - if you leave this field empty only the object currently loaded in the Inspector will be exported; with the reference filter :* the currently inspected object including all its composites will be exported, with the reference filter address the contact including all its addresses will be exported.

  • click to button [OK] to start the export operation

Figure 9-5. Operation Export XML

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

Chapter 10. The Event Subscription / Notification Service

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

Figure 10-1. Overview Event Subscription / Notification

enlarge

Please note that the event subscription and notification services depends on a properly configured and running WfExecutionClient (see Running the Workflow Execution Client)

The openCRX distribution includes quite a few default topics (see Figure 10-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 10-2. Topics included in the openCRX distribution

If required, Administrators can create Topics containing information like a "topic path pattern" and "actions to perform".

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 10-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:

Figure 10-4. Lookup Inspector for Topics

Your new subscription should now look as follows:

Figure 10-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 10-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 to your list of subscriptions.

Chapter 11. 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 11-1. Create a new E-mail Account

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

Figure 11-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 11-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 11-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 11-5 and then click the button [Save] to create this new e-mail account

Figure 11-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 12. 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 12-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 12-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 12-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 13. 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
http://www.crixp.com/ http://www.openmdx.org/