SourceForge.net Logo

openCRX Admin Guide

Version 2.0

logo_openCRX

www.opencrx.org





















07-Mar-2008 @ 04:01:11 PM



Table of Contents

1 About this Book 7

1.1 Who this book is for 7

1.2 What do you need to understand this book 7

1.3 Tips, Warnings, etc. 7

2 Prerequisites 8

3 Security 9

3.1 Introduction 9

3.1.1 Basic Concepts and Conventions 9

3.1.2 Permissions / Access Control 12

3.2 Default Settings 14

3.3 Activating Security 16

3.4 Security Settings of New Objects 16

3.5 Checking Permissions 17

3.6 Login Procedure 18

3.6.1 Tomcat / Application Server Login 18

3.6.2 Segment Login 18

3.6.3 Disabling Login 18

3.7 Resetting Security 19

4 Managing Users 20

4.1 Creating Users 20

4.1.1 Create Users as Segment Administrator 21

4.1.2 Import Subjects and Application Login Principals 22

4.1.3 Import Users 23

4.2 Disable/Deactivate Users 24

4.2.1 Disable Users at the level Tomcat /Application Server 24

4.2.2 Disable Users at the level openCRX 24

5 Deployment Scenarios 25

5.1 Typical Deployment Scenarios 25

5.2 Multi Entity Deployment Scenarios 26

5.2.1 Multiple Data Segments in a single DB 26

5.2.2 Multiple DBs 27

5.3 openCRX Custom Applications 27

6 Workflow Controller 28

6.1 Workflow Controller Configuration 30

6.1.1 Startup Configuration in web.xml 30

6.1.2 ServerURL 31

6.1.3 Handler pingrate and autostart 31

6.2 Servlet IndexerServlet 32

6.3 Servlet SubscriptionHandler 32

6.4 Servlet WorkflowHandler 33

6.5 Trouble Shooting Servlets 34

7 Subscribe / Notify Services 35

7.1 Example Subscription – Account Modifications 37

7.2 Example Subscription with Filtering 38

7.3 Trouble Shooting Notification Services 39

8 E-mail Services 40

8.1 Install and Configure Mail Resource and E-Mail Services 41

8.1.1 Installation of JavaMail and JAF 41

8.1.2 Mail Resource for openCRX on Apache Tomcat 41

8.1.2.1 Add resource definition to opencrx-core-CRX.xml 41

8.1.2.2 Mail Resource in web.xml 42

8.1.3 Mail Resource for openCRX on JBoss 43

8.1.3.1 Create mail-service.xml 43

8.1.3.2 Mail Resource in web.xml and jboss-web.xml 44

8.2 Outbound E-mail 45

8.2.1 Outbound E-mail Configuration 45

8.2.2 Export E-mails 47

8.2.3 Send E-mails directly from openCRX 48

8.2.4 Send E-mails as Attachments to your Mail Client 49

8.3 Inbound E-mail 50

8.3.1 Import E-mails 50

8.4 Trouble Shooting E-mail Services 50

9 Groupware Services 51

9.1 Directory Service / LDAP 51

9.1.1 Configuring the openCRX LDAP Port 52

9.1.2 LDAP Configuration of Thunderbird 52

9.1.3 LDAP Configuration of MS Outlook 53

9.2 Calendaring 54

9.2.1 Calendar as a Set of Activities 54

9.2.2 Calendar Selectors 54

9.2.3 openCRX Activities mapped to Calendar Events 55

9.2.4 Calendaring / Free Busy 57

9.2.4.1 Free Busy Configuration of Thunderbird 57

9.2.4.2 Free Busy Configuration of MS Outlook 57

9.2.5 Calendaring / iCalendar (ICS) 58

9.2.5.1 ICS Configuration of Thunderbird/Lightning and Sunbird 58

9.2.5.2 ICS Configuration of MS Outlook 59

9.2.6 Calendaring / CalDAV 59

9.2.6.1 CalDAV Configuration of Thunderbird/Lightning and Sunbird 60

9.2.6.2 CalDAV Configuration of MS Outlook 60

9.2.6.3 CalDAV Configuration of Chandler Desktop 61

9.2.7 Calendaring / Timeline 62

9.3 Mailstore / IMAP 63

9.3.1 Configuring the openCRX IMAP Port 64

9.3.2 Configuring the IMAP Maildir Cache 64

9.3.2.1 Maildir Configuration with Apache Tomcat 64

9.3.2.2 Maildir Configuration with JBoss 64

9.3.3 IMAP Configuration of Thunderbird 65

9.3.4 IMAP Configuration of MS Outlook 66

9.4 Collaboration / Wiki 67

10 Data Import/Export 68

10.1 Importing Data into openCRX 68

10.2 Importing XML Files 68

10.2.1 Importing vCard Files ( openCRX Contacts) 71

10.2.2 Importing E-Mails 71

10.2.3 Other Options 71

10.3 Exporting Data from openCRX 72

10.3.1 Exporting XML Files 72

10.3.2 Exporting openCRX Contacts ( vCard Files) 73

10.3.3 Exporting openCRX Contacts ( Outlook Contacts) 73

10.3.4 Exporting openCRX Meetings ( iCalendar Files) 74

10.3.5 Exporting E-Mails 74

10.3.6 Other Options 74

11 Customizing openCRX 75

11.1 Managing Locales 75

11.2 Managing Packages 76

11.3 Role-based UI 77

11.3.1 Model Permissions 77

11.3.2 Custom Layout JSPs 77

12 Integration with Office Suites 78

12.1 MS Office 78

12.1.1 MS Word 78

12.1.2 MS Excel 78

12.1.3 MS Outlook 78

12.2 Open Office 78

12.2.1 OpenOffice Writer 78

12.2.2 OpenOffice Calc 78

12.3 Mozilla Thunderbird / Sunbird 78

13 Next Steps 79



List of Figures

Figure 1: Security Realms, Principals and Subjects after Initial Setup 10

Figure 2: Segment Administration 11

Figure 3: Role Drop Down with list of available Segment Login Principals 11

Figure 4: openCRX UML Model – Class Diagram SecureObject 12

Figure 5: System attributes of an openCRX object as shown in the GUI 13

Figure 6: Table OOCKE1_SEGMENT after default installation (QuickStart) 15

Figure 7: Table OOCKE1_SEGMENT after modification 15

Figure 8: Result of Check Permissions 17

Figure 9: Role Drop Down with list of available Segment Login Principals 18

Figure 10: Operation Actions > Import Login Principals (admin-Root) 22

Figure 11: Operation Actions > Import Users (admin-Standard) 23

Figure 12: Disabling of Segment Login Principal guest by admin-Standard 24

Figure 13: 3-Tier with Apache Tomcat / LWC 25

Figure 14: 3-Tier with J2EE-compliant Application Server 25

Figure 15: 4-Tier with Clustered Application and DB Servers 25

Figure 16: Multiple Data Segments in a single DB 26

Figure 17: Dedicated DB for each Entity 27

Figure 18: Accessing the openCRX Workflow Controller 28

Figure 19: openCRX 2.0 Workflow Controller 28

Figure 20: Default Configuration of WorkflowController 29

Figure 21: openCRX Administration – WorkflowController 30

Figure 22: Workflow Controller Configuration – serverURL 31

Figure 23: Workflow Controller Configuration – pingrate and autostart 31

Figure 24: Default Workflow Processes created by WorkflowHandler 33

Figure 25: Event and Notification Service 35

Figure 26: Standard Topics included in the openCRX distribution 36

Figure 27: Create a new Subscription 37

Figure 28: Create a Subscription with Filters 38

Figure 29: Flow of e-mail messages between openCRX, MTA and mail client 40

Figure 30: Create a new E-Mail Account – step 1 45

Figure 31: Create a new E-Mail Account – step 2 45

Figure 32: Create a new E-Mail Account – step 3 46

Figure 33: E-mail subject prefix and Web access URL 46

Figure 34: Example of outbound E-mail Action Log Entries 47

Figure 35: Send E-Mail from openCRX – Overview 48

Figure 36: Send E-Mail from openCRX with Actions > Follow Up 48

Figure 37: Send E-Mail as Attachment from openCRX – Overview 49

Figure 38: Export E-Mail from openCRX with Actions > Follow Up 49

Figure 39: Thunderbird LDAP Configuration 52

Figure 40: MS Outlook LDAP Configuration 53

Figure 41: An openCRX activity's iCal representation 55

Figure 42: An openCRX activity in the standard GUI 56

Figure 43: An openCRX activity filtered to a user's homepage 56

Figure 44: Timeline visualizes time-based events 62

Figure 45: Thunderbird IMAP Configuration 65

Figure 46: Thunderbird IMAP Configuration 66

Figure 47: XML import from 3rd party system – overview 69

Figure 48: Interactive import of XML Files 69

Figure 49: Interactive import of XML Files 70

Figure 50: Operation vCard Import 71

Figure 51: Exporting SalesOrder as XML File 72

Figure 52: XML Exporter provides XML data file and code tables as ZIP file 72

Figure 53: Export Contact as vCard 73

Figure 54: Export Contact to MS Outlook 73

Figure 55: Exporting Meeting / Sales Visit as iCalendar File 74



List of Listings

Listing 1: File Format Subjects and Application Login Principals 22

Listing 2: Example File Subjects and Application Login Principals 22

Listing 3: File Format Users 23

Listing 4: Example File Users 23

Listing 5: web.xml – auto startup of the Workflow Controller 30

Listing 6: Servlets managed by Workflow Controller log to server.log 34

Listing 7: File opencrx-core-CRX.xml 42

Listing 8: Uncomment mail resource definition in web.xml 42

Listing 9: Importing certificate into keystore cacerts 42

Listing 10: File mail-service.xml 43

Listing 11: Uncomment mail resource definition in web.xml 44

Listing 12: Uncomment mail resource definition in jboss-web.xml 44

Listing 13: Importing certificate into keystore cacerts 44

Listing 14: Importing Certificate 50

Listing 15: Set org.opencrx.maildir for Apache Tomcat 64

Listing 16: Set org.opencrx.maildir for Apache Tomcat 64

Listing 17: Locales in web.xml 75

Listing 18: Activating/Deactivating Locales in web.xml 75

Listing 19: Locales in web.xml 76

Listing 20: Activating/Deactivating Locales in web.xml 76



1 About this Book

This book describes various configuration settings and tasks an openCRX administrator should know about.

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

1.1 Who this book is for

The intended audience are openCRX administrators.

1.2 What do you need to understand this book

This book describes some of the settings and configurations an openCRX administrator can use to control the behavior of openCRX.

1.3 Tips, Warnings, etc.

We make use the following pictograms:

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

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

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

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



2 Prerequisites

This guide assumes that you have access to a properly installed instance of openCRX 2.0 (for installation instructions, please refer to the guides available from http://www.opencrx.org/documents.htm).

3 Security

In this chapter we will present a high-level overview of openCRX security and discuss a few select issues.

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 risk of you being locked out is real and the resources required to fix broken security settings can not be overestimated!

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 at least the basics of openCRX security BEFORE you make any changes.

3.1 Introduction

3.1.1 Basic Concepts and Conventions

  • Each “real user” is represented by a Subject (e.g. “Guest”). Subjects are managed by the openCRX Root administrator (admin-Root).

  • Each subject has an Application Login Principal (also called login id). Application login principals are managed by the openCRX Root administrator (admin-Root).

  • Each application login principal is assigned to a subject (e.g. principal “guest” is assigned to subject “Guest”) and allows a “real user” to login.

  • A “real user” can have one or more additional segment login principals. The 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” who 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. Each “real user” also has a Principal Group, e.g. “guest.Group”.

  • Each segment has a corresponding realm to manage Principals:

    • 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> (e.g. principals for the segment Standard are stored in the realm Standard).

    • Each segment has a segment administrator principal (admin-<segment name>) (e.g. admin-Standard for the segment Standard).

The following figure shows the situation after the initial setup of openCRX (assuming you worked through the QuickStart guide):

Figure 1: Security Realms, Principals and Subjects after Initial Setup

Summarizing the above:

  • there is a realm for each segment (e.g. if you followed the QuickStart guide there is a realm Standard corresponding to the segment Standard)

  • the realm Default acts as login realm, i.e. it contains all principals who are allowed to login to the openCRX application; PrincipalGroups in this realm are only used to configure Granted Roles by inheritance (in addition to configuring them directly in the appropriate grid).

  • 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 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 like Head of Sales or CFO).

Available segment login principals are listed in the so-called Role Drop Down:

Figure 3: Role Drop Down with list of available Segment Login Principals

3.1.2 Permissions / Access Control

The openCRX security framework makes a distinction between Ownership Permissions (i.e. permissions granted on a particular object are based on object ownership) and Model Permissions (i.e. permissions are granted on a particular model element). As Model Permissions are not yet implemented we only talk about Ownership Permissions in this guide.

Ownership permissions are used to control browse/delete/update access to openCRX objects by Users and UserGroups (Ownership access control). Every openCRX object is a SecureObject. The following figure shows an extract from the UML model (if you are interested in all the details and the formally correct and complete specifications you should refer to the latest openCRX UML models):

Figure 4: openCRX UML Model – Class Diagram SecureObject

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)

If you see N/A in a field instead of a more meaningful value the object cannot be retrieved (N/A stands for Not Available); maybe the object was deleted or the provider is not accessible/available.

The most important security attributes of an object X are discussed below:

  • Owning User: this user "owns" object X; the Owning User can always browse/delete/update object X (unless the access level is set to 0 [no access]).

  • Owning Groups: these groups might enjoy privileged treatment for browsing/deleting/updating object X depending on the relevant access level settings.

  • Access Granted by Parent: this attribute is set by configuration and refers to the parent object that grants access to object X.

  • Browse Access Level: this setting determines which users/user groups are granted browse access to direct composite objects of object X [i.e. can view/inspect direct composite objects (including all their attributes) of object X].

    It is a common misconception that browse access level of an object X controls browse access to this object X – please read the above definition carefully!

  • Delete Access Level: this setting determines which users/user groups are granted delete access to object X and all its composite objects (recursively!) [i.e. can delete object X and all its composite objects (recursively!)].

  • Update Access Level: this setting determines which users / user groups are granted update access to object X [i.e. can change object X; this includes adding composite objects to object X].



Figure 5: System attributes of an openCRX object as shown in the GUI

The following access levels are available to control which users / user groups are granted permission to browse/delete/update a particular object X:

Access Level

Meaning

0 – N/A

no access

1 – private

access is granted if the user is owning user of object X

2 – basic

access is granted if at least one of the following conditions is true:

(a) the user is owning user of object X

(b) the user is member of any of the owning groups of object X

(c) any of the owning groups of object X is a subgroup** of any group the user is member of

3 – deep

access is granted if at least one of the following conditions is true:

(a) the user is owning user of object X

(b) the user is member of any of the owning groups of object X

(c) any of the owning groups of object X is a subgroup** of any group the user is member of

(d) any of the owning groups of object X is a subgroup** of any supergroup* of any group the user is member of

4 – global

all users are granted access

* Owning group Gsuper is a supergroup of an owning group G if every user who is member of G is also member of Gsuper

** Owning group Gsub is a subgroup of an owning group G if every user who is member of Gsub is also member of G



3.2 Default Settings

Default access level settings for non-Root segments (e.g. segment Standard) after a clean install are as follows:

Browse Access Level:

4 – global

Update Access Level:

3 – deep

Delete Access Level:

1 – private



Figure 6: Table OOCKE1_SEGMENT after default installation (QuickStart)

Due to the setting access_level_browse = 4 (global) any user with access to a particular segment is allowed to browse top level objects (i.e. browse all accounts, browse all activities, browse all documents, etc.).

These default settings are suitable for test environments and deployments in smaller companies/teams with a liberal access policy; for most real-world applications, however, it is more appropriate to set access_level_browse = 3 (deep) for non-Root segments. You can do this by changing the values in the column access_level_browse from 4 to 3 (table kernel_Segment). After this change, the table kernel_Segment will look as shown in the following figure:

Figure 7: Table OOCKE1_SEGMENT after modification



Segment security settings are loaded during the initialization of the openCRX servlet. Hence, if you change settings you must redeploy openCRX for the new settings to become active.









3.3 Activating Security

The openCRX security provider manages all security data and provides access control services for all requests through the openCRX API. Hence, you can rely on openCRX access control even if you write you own clients or adapters for openCRX.

Security (including Access Control) is not just an add-on, rather it is an integral part of openCRX; openCRX Access Control is always activated.

The only “hardening” you might want to do is the one described in the previous chapter: set browse access level to 3 for non-Root segments.

3.4 Security Settings of New Objects

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

Browse Access Level:

3 – deep

Update Access Level:

2 – basic

Delete Access Level:

2 – basic

Access Granted by Parent

in general: Parent object as modeled

exceptions: there are some select exceptions, but they are all pre-configured

Owning User:

User who is creating the object

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 (except Users, see below).


Please note that the User Group Users (e.g. Standard\\Users) is not added to the list of Owning Groups of newly created objects unless the creating user's Primary User Group is equal to Users.

Please note that a User'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 Creator or assigned Activity Group and not based on the settings of the user who executes the operation.



3.5 Checking Permissions

You can check security permissions on any SecureObject with the operation Check Permissions. Provide the principal name as a parameter. The following figure shows the result of the operation on a Contact:

Figure 8: Result of Check Permissions

The meaning of the above result is as follows:

Has read permission:

principal can browse this object

principal cannot browse this object

Has update permission:

principal can modify/update this object

principal cannot modify/update this object

Has delete permission:

principal can delete this object

principal cannot delete this object

Membership for read:

principal has read permission if the intersection of the resulting list of groups and the list of owning groups of the respective SecureObject is not empty

Membership for update:

principal has modify/update permission if the intersection of the resulting list of groups and the list of owning groups of the respective SecureObject is not empty

Membership for delete:

principal has delete permission if the intersection of the resulting list of groups and the list of owning groups of the respective SecureObject is not empty



3.6 Login Procedure

The openCRX login procedure consists of 2 levels:

3.6.1 Tomcat / Application Server Login

The Tomcat / application server login procedure depends on various parameters:

  • Tomcat / Application server (e.g. JBoss, BEA WLS, IBM WebSphere, etc.)

  • configuration of Tomcat / application server

    • file-based realm (e.g. users.properties for JBoss)

    • DB-based realm (e.g. DatabaseLoginModule for JBoss)

    • LDAP-based realm

    • company-specific / custom-tailored realms

Please note that even though openCRX might be involved in managing some of the above-mentioned realms (e.g. DB-based realm) the Tomcat / application server login is not really under control of openCRX. Many login problems are related to incomplete/faulty configuration settings.

3.6.2 Segment Login

Access to segments is managed/controlled by the ObjectInspectorServlet. The included DefaultRoleMapper identifies all Segment Login Principals of a given Subject and grants access to the respective segments through the Role Drop Down:

Figure 9: Role Drop Down with list of available Segment Login Principals

It is possible to deploy user-specific implementations of the DefaultRoleMapper so that you can adapt the segment login procedure to your requirements.

3.6.3 Disabling Login

Please refer to the chapter “Disable/Deactivate Users”.

3.7 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 (and that includes the security settings of that object!). For example, the only way to recover from setting Update Access Level to 0 – 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 might be forced to reset all security settings to a well-defined state. Not an easy task – and it typically involves a lot of manual work.



Educate your users about openCRX security. You might also consider disabling some of the more powerful operations and/or security attributes in the default GUI.

4 Managing Users



Read through the chapter Basic Concepts and Conventions (Security) before reading this chapter. It is quite helpful to have a good understanding of the terms Subject, Application Login Principal, Segment Login Principal, User, etc. before you start reading here.

4.1 Creating Users

Even though you can create users with a variety of methods, “behind the scenes” the following steps are always required to create a new openCRX user:

Who

Steps

Root administrator
admin-Root

  • create a new Subject

    • set the qualifier to the desired login id

  • create a new Principal in realm Default
    (--> Application Login Principal)

    • set the qualifier to the desired login id

    • link this Principal to the Subject created in the previous step

    • make Principal member of the appropriate Principal Group(s), e.g. Users

Segment administrator
admin-<SegmentName>

  • create a new Contact

  • create a new User

    • link this User to the Contact created in the previous step

    • the Segment Login Principal is created automatically

Depending on how you create a new user, some of the above steps might be taken care of by a wizard. If you want to have full control over the user creation process, however, then you can certainly create new users following the above instructions step by step.

Have a look at Figure 1: Security Realms, Principals and Subjects after Initial Setup and Figure 2: Segment Administration to see how this all fits together.

4.1.1 Create Users as Segment Administrator

The Segment administrator can create new users with the following steps:

  • login as Segment administrator (e.g. admin-Standard)

  • create a contact for the new user

  • navigate to User Homepages and execute the operation Create User:

  • upon execution a new principal and a new subject are automatically created if they do not exist yet (please note that both the subject name and principal name are set to the value of the parameter “Principal name”)

  • remain logged in as Segment administrator and navigate to the newly created Homepage of the new user

  • execute the operation Edit > User Settings and adjust the settings:

  • now the new user should be able to login

4.1.2 Import Subjects and Application Login Principals

Creating large numbers of subjects/principals by hand can be quite a tedious job. If you prepare a text file containing the appropriate information in the file format as outlined below, the Root administrator (admin-Root) can use the operation Actions > Import Login Principals to create Subjects and Application Login Principals automatically.

Figure 10: Operation Actions > Import Login Principals (admin-Root)

Listing 1: File Format Subjects and Application Login Principals

Subject;<subject name>;<subject description>

Principal;<principal name>;<principal description>;<subject name>;<groups>





Listing 2: Example File Subjects and Application Login Principals

Subject;joe;Doe, Joe
Subject;mark;Ferguson, Mark
Subject;peter;Lagerfeld, Peter

Principal;joe;Doe, Joe;joe;Users,Administrators
Principal;mark;Ferguson, Mark;mark;Users
Principal;peter;Lagerfeld, Peter;peter;Users







4.1.3 Import Users

Similarly to importing Subjects and Application Login Principals from a file you can also import Users from a file. If you prepare a text file containing the appropriate information in the file format as outlined below, the Segment administrator (admin-<SegmentName>) can use the operation Actions > Import Users to create Users automatically.

Figure 11: Operation Actions > Import Users (admin-Standard)

Listing 3: File Format Users

User;<principal>;<account alias>;<account full name>;<primary group>;<password>[;group [, group] ]



Please note that <password> is a clear-text value. The optional parameter group can be used to make the Segment Login Principal member of the respective Principal Groups of that segment.

Listing 4: Example File Users

User;joe;JD;Doe, Joe;Users;2%jOd.IT
User;mark;Fergi;Ferguson, Mark;Users;maFe&.3-
User;peter;Pete;Lagerfeld, Peter;Users;PlF*;ReGaL



Contacts are not created automatically; existing Contacts are first search by <account alias>. If no matching account alias is found, Contacts are search by <account full name>. If still no matching account is found, the UserHome is not created.

Users are only imported/created if the referenced Principals exist.





4.2 Disable/Deactivate Users

There are various ways of disabling/deactivating users. To fully understand your options it is helpful if you are familiar with the openCRX Login Procedure.

4.2.1 Disable Users at the level Tomcat /Application Server

Depending on the configuration of your application server you can disable users at that level. For example, if you rely on file-based realms, you can simply remove users from the file tomcat-users.xml (with Tomcat) or users.properties (with JBoss) to prevent access to openCRX. If you block access at the level Tomcat / application Server such users are locked out from accessing any application and any openCRX segment. However, as the Tomcat/ application Server Login procedure is not entirely controlled by openCRX you might have to consult the documentation of your respective application server or ask your application server administrator for details.

4.2.2 Disable Users at the level openCRX

The segment administrator (e.g. admin-Standard) can prevent a user from accessing a particular openCRX segment by either disabling the respective Segment Login Principal or by deleting it altogether. Disabling is the preferred option to prevent access temporarily. If a user has multiple Segment Login Principals you must disable all of them to prevent access to the openCRX application.

Figure 12: Disabling of Segment Login Principal guest by admin-Standard



You should not delete a particular Subject as long as it is referenced by any Principal. Otherwise you'll end up with “dangling” Subject references.



5 Deployment Scenarios

openCRX supports a multitude of deployment scenarios.

5.1 Typical Deployment Scenarios

The following table lists some of the pros and cons of the most common openCRX deployment scenarios. Please note that the list is by no means complete:

3-Tier with Tomcat/LWC

Figure 13: 3-Tier with Apache Tomcat / LWC

  • Tomcat engine extended by openMDX LightweightContainer (LWC) so that EARs with EJBs and WARs can be deployed

  • simple setup and manage­ment (Server Installer)

  • limited scalability and avail­ability (no clustering), but highest performing 3-Tier deployment with full transaction service



3-Tier with AppServer

Figure 14: 3-Tier with J2EE-compliant Application Server

  • J2EE-compliant Application Server (JBoss is supported out of the box)

  • simple setup and manage­ment (one application server)

  • limited scalability and avail­ability (no clustering)

  • Transaction Service



4-Tier with Clusters

Figure 15: 4-Tier with Clustered Application and DB Servers

  • demanding setup (four and more application servers)

  • multiple security zones for highest security (Internet, DMZ, Intranet)

  • maximum availability

  • fully fault tolerant

  • unlimited scalability

  • Transaction Service



5.2 Multi Entity Deployment Scenarios

The open source MDA platform openMDX supports a multitude of deployment scenarios and persistency configurations. The most common multi entity deployment scenarios are discussed in the following sections.

5.2.1 Multiple Data Segments in a single DB

The setup “Multiple Data Segments in a single DB” provides adequate security for many use cases and is relatively easy to manage. As all the data is stored in a single database, however, security configuration mistakes (e.g. principals linked to the wrong subject, etc.) might lead to situations where a user is granted access to the data of a particular company/client that should not be accessible (please note that human error is the root cause here, not a malfunction of openCRX). Furthermore, this setup is not recommended if users can get direct access to the database, e.g. with third party reporting tools as those tools typically bypass the openCRX API.

Figure 16: Multiple Data Segments in a single DB

5.2.2 Multiple DBs

The highest level of security is provided by setting up a dedicated database for each entity so that data sets of the various entities are physically separated:

Figure 17: Dedicated DB for each Entity

5.3 openCRX Custom Applications

<documentation pending>

6 Workflow Controller

With the Workflow Controller the openCRX Root administrator (admin-Root) can enable/disable various servlets (configured in web.xml) included in the openCRX distribution. This chapter gives an overview over the currently available servlets and explains how to start/stop them.

You can access the Workflow Controller by navigating to the URL

http://127.0.0.1:8080/opencrx-core-CRX/WorkflowController

or starting the Workflow Controller Wizard as shown in the figure below:

Figure 18: Accessing the openCRX Workflow Controller

You should connect to the Workflow Controller with http. If you use SSL-secured connections to start/stop servlets you must ensure that your server's certificate is available in cacerts.

The following figure shows the Workflow Controller of openCRX 2.0:

Figure 19: openCRX 2.0 Workflow Controller

Please note that access is granted to the openCRX Root administrator (admin-Root) only. Hence, if you see the openCRX login screen instead of the Workflow Controller you must first login as Root administrator. Also, ensure that openCRX is properly initialized before you connect to the Workflow Controller.

The first time the Workflow Controller is started it will create a default configuration:



Figure 20: Default Configuration of WorkflowController

If you ever need to recreate this default configuration, you can do so with the following steps:

  • stop the WorkflowController

  • delete the Configuration with the name WorkflowController

  • start the WorkflowController



You can manually start (stop) servlets that are managed by the Workflow Controller by clicking on “Turn On” (“Turn Off”). Please note that you can control servlets on a segment by segment basis. For example, if you created a segment “MySegment” in addition to the segment “Standard” you can start/stop servlets of the segment “MySegment” without interfering with the servlets of the segment “Standard”.

6.1 Workflow Controller Configuration

In addition to configuring the Startup option of the Workflow Controller you can also configure various options related to the servlets managed by the Workflow Controller. The configuration of the Workflow Controller is accessible to the openCRX Root administrator (admin-Root) by navigating to Administration and then clicking on the icon of the WorkflowController:

Figure 21: openCRX Administration – WorkflowController





6.1.1 Startup Configuration in web.xml

You can start the Workflow Controller manually by navigating to the URL

http://127.0.0.1:8080/opencrx-core-CRX/WorkflowController

or starting the Workflow Controller Wizard. However, it is also possible to start the Workflow Controller automatically by activating the corresponding option in the file web.xml:

Listing 5: web.xml – auto startup of the Workflow Controller

<!-- WorkflowController -->
<servlet id="WorkflowController">
<servlet-name>WorkflowController</servlet-name>
<servlet-class>org.opencrx.kernel.workflow.servlet.WorkflowControllerServlet</servlet-class>
...
<!-- activate if WorkflowController should be initialized at startup-->
<load-on-startup>10</load-on-startup>
</servlet>



With the value of load-on-startup (10 above) you can control the order of starting up servlets in case there is more than one.

6.1.2 ServerURL

Adapt the value of serverURL to your environment (e.g. http://127.0.0.1:8080/opencrx-core-CRX):

Figure 22: Workflow Controller Configuration – serverURL

6.1.3 Handler pingrate and autostart

Use pingrate to define the interval (in minutes) between successive calls of the respective handler and autostart (true/false) to start the respective handler automatically:

Figure 23: Workflow Controller Configuration – pingrate and autostart

6.2 Servlet IndexerServlet

The openCRX IndexerServlet updates index entries (used for keyword/index based search introduced with openCRX v2) by indexing all objects which do not have an IndexEntry newer than the modification date of the object. The IndexerServlet creates an index by invoking the operation updateIndex() on the object to be indexed.

As indexing can put some heavy load on your database server you might consider turning off (or at least lowering the frequency of calling) the IndexerServlet during busy hours.



6.3 Servlet SubscriptionHandler

The openCRX SubscriptionHandler is the backbone of the openCRX Subscribe / Notify Services. The Subscription Handler does not require any configuration by the openCRX administrator other than setting the pingrate and autostart options, i.e. it is designed to work “out of the box”.

Turning on the SubscriptionHandler of a particular segment is required if you want that segment to provide Alerts and E-mail Notifications to its Users. The polling frequency can be set by the Root administrator (see Figure 23: Workflow Controller Configuration – pingrate and autostart).

The SubscriptionHandler checks openCRX audit entries on a regular basis and – if matching Subscriptions exist – executes the Workflow Process referenced by the Subscription using Userhome.executeWorkflow().



Userhome.executeWorkflow() – implemented by the openCRX plugin – creates an entry in Userhome.wfProcessInstance (accessible through the grid Workflow Process Instances). Synchronous workflows are executed immediately, asynchronous workflows are left alone (the Servlet WorkflowHandler is specialized in dealing with asynchronous workflows – see below for details).


6.4 Servlet WorkflowHandler

The openCRX WorkflowHandler is responsible for executing WfProcessInstances based on asynchronous WfProcesses like:

  • org.opencrx.mail.workflow.ExportMailWorkflow

  • org.opencrx.mail.workflow.SendMailNotificationWorkflow

  • org.opencrx.mail.workflow.SendMailWorkflow

The execution frequency can be set by the Root administrator (see Figure 23: Workflow Controller Configuration – pingrate and autostart). Please note that the WorkflowHandler is required for outbound E-Mail Services.

The WorkflowHandler executes Workflow Process Instances that have not been executed yet.

The first time the WorkflowHandler is started it will create various default Workflow Processes:

Figure 24: Default Workflow Processes created by WorkflowHandler

If you ever need to recreate these default Workflow Processes, you can do so with the following steps:

  • stop the Servlet WorkflowHandler

  • delete the Workflow Processes that were originally created by the WorkflowHandler (or at least the ones that still exist)

  • start the Servlet WorkflowHandler

All WfProcesses with undefined/unknown runtime length should be defined as asynchronous. This is particularly true for WfProcesses that might block. The default setup ensures that blocking WfProcesses cannot block openCRX.



6.5 Trouble Shooting Servlets

All the openCRX servlets controlled by the Workflow Controller log their actions to the server log file (e.g. D:\jboss-4.2.1.GA\server\default\log\server.log on JBoss). The following log file extract shows, for example, that the three Servlets IndexerServlet, SubscriptionHandler, and WorkflowHandler seem to be working fine:

Listing 6: Servlets managed by Workflow Controller log to server.log

20:25:18,388 INFO [STDOUT] Tue Mar 04 20:25:18 CET 2008: Indexer CRX/Standard
20:27:18,400 INFO [STDOUT] Tue Mar 04 20:27:18 CET 2008: SubscriptionHandler CRX/Standard
20:27:18,400 INFO [STDOUT] Tue Mar 04 20:27:18 CET 2008: WorkflowHandler CRX/Standard

openCRX Exceptions (like NullPointers, etc.), however, are still logged to the application log file as configured during the installation (see QuickStart guide).

It is always worth checking whether the Workflow Handlers actually are active; they must be started by the Root administrator. You can find out by connecting to the Workflow Controller (see Figure 19: openCRX 2.0 Workflow Controller).



After restarting the application server all servlets managed by the WorkflowController are turned off, i.e. the Root Administrator must explicitly turn them on again (if desired) unless the respective servlet's autostart option is set to true in the WorkflowController's configuration and the WorkflowController's Startup option is set to true in the file web.xml. The servlets do not automatically resume the state they were in before the application server was shut down.

7 Subscribe / Notify Services

openCRX features a powerful event subscription and notification service:

Figure 25: Event and Notification Service

Once a topic is created, openCRX users can subscribe to it. Users manage their subscriptions individually on their UserHomes (with the Wizard UserSettings or by editing their subscriptions manually). If a topic has subscribed users and a monitored event occurs then the predefined actions are performed. If the action is set to – for example – creating an alert for subscribed users, then each subscribed user will receive an alert on the UserHome.

Please note that event and notification services depend on the Servlet SubscriptionHandler, i.e. you must turn on the openCRX Subscription Handler for the respective segment with the Workflow Controller, otherwise Topic Actions are not executed, i.e. no Alerts and E mail Notifications.

Furthermore, as outbound E-Mail Services depend on the WorkflowHandler, you must activate the Workflow Handler to receive E-Mail Notifications.

The openCRX distribution includes quite a few default topics (see Figure 26: Standard Topics included in the openCRX distribution) to get you started:

  • Topic Account modification alert sends an alert to the UserHome of subscribed users whenever an account is modified.

  • Topic Activity follow-up modification alert sends an alert to the UserHome of subscribed users whenever a Follow Up of an Activity is modified.

  • Topic Mail notification for new alerts sends an e-mail notification to subscribed users – assuming outbound e-mail services are configured correctly – whenever an Alert is created/modified.

Please note that newly created Segments do neither contain Workflow Processes nor Topics (i.e. the respective grids are empty). Both Workflow Processes and Topics are created by the Subscription Handler of the respective segment when it is started for the first time.



Figure 26: Standard Topics included in the openCRX distribution

Users can easily custom-tailor their subscriptions with filters and by selecting event types like Object Creation, Object Replacement, and Object Removal.

7.1 Example Subscription – Account Modifications

In this example we will create a subscription to the standard Topic Account Modifications for the user “guest”.

  • Login as guest, and execute the operation Edit > User Settings to start the respective wizard. Check both “Is Active” and “Creation” as shown below:

Figure 27: Create a new Subscription

  • Click Apply to store your settings.



Please note that the Root administrator must start the Subscription Handler – otherwise you will not get any Alerts/Notifications.



7.2 Example Subscription with Filtering

In combination with openCRX security the subscription filter feature enables you to provide highly specific subscriptions. Imagine the following situation: there are 2 Activity Trackers DivisionA:ProjectX and DivisionA:ProjectY and some of your users are interested in receiving notifications related to activities of ProjectX only, some users want to receive notifications related to activities of ProjectY only, and some users want to receive notifications from both projects. Such a situation could be handled as follows:

  • create a PrincipalGroups DivisionA.ProjectX and DivisionA.ProjectY

  • assign PrincipalGroup DivisionA.ProjectX to ActivityTracker DivisionA:ProjectX; like this new activities assigned to this Tracker will also be assigned the PrincipalGroup DivisionA.ProjectX

  • assign PrincipalGroup DivisionA.ProjectY to ActivityTracker DivisionA:ProjectY; like this new activities assigned to this Tracker will also be assigned the PrincipalGroup DivisionA.ProjectY

  • an Activity Modification subscription of a user wanting notifications related to ProjectX and ProjectY would look as follows:

Figure 28: Create a Subscription with Filters

Enter the name of the attribute (owner in our example) into the name field and then enter the value(s) to match into the value field (in our case Standard:DivisionA.ProjectX and Standard:DivisionA.ProjectY)



Multiple values of a named filter are combined with OR.

Multiple named filters are combined with AND.

7.3 Trouble Shooting Notification Services

The following table lists some of the common issues and how to fix them:

Problem

Solution

The grids Workf