SourceForge.net Logo

openCRX Admin Guide

Version 1.10.0

logo_openCRX

www.opencrx.org





















28-Feb-2007 @ 09:44:12 AM



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 Login Procedure 17

3.5.1 Application Server Login 17

3.5.2 Segment Login 17

3.5.3 Disabling Login 17

3.6 Resetting Security 18

4 Managing Users 19

4.1 Creating Users 19

4.1.1 Create Users Manually 20

4.1.2 Import Subjects and Application Login Principals 21

4.1.3 Import Users 22

4.2 Disable/Deactivate Users 23

4.2.1 Disabling Users at the level Application Server 23

4.2.2 Disabling Users at the level openCRX 23

5 Deployment Scenarios 24

5.1 Typical Deployment Scenarios 24

5.2 Multi Entity Deployment Scenarios 25

5.2.1 Multiple Data Segments in a single DB 25

5.2.2 Multiple DBs 26

5.2.3 Multiple Applications 26

5.3 openCRX Custom Applications 26

6 Workflow Controller 27

6.1 Workflow Controller Configuration 29

6.1.1 Startup Configuration in web.xml 29

6.1.2 ServerURL 30

6.1.3 Handler pingrate and autostart 30

6.2 Servlet SubscriptionHandler 31

6.3 Servlet WorkflowHandler 32

6.4 MailImporterServlet 33

6.5 Trouble Shooting Servlets 34

7 Subscribe / Notify Services 35

7.1 Example Subscription – Activity Modifications 37

7.2 Example Subscription with Filtering 39

7.3 Trouble Shooting Notification Services 40

8 E-mail Services 41

8.1 Import E-mails from a Mail Client into openCRX 42

8.2 Use openCRX as an E-mail Archive/Audit Tool 43

8.3 Send E-mail directly from openCRX 44

8.4 Export E-mails from openCRX to your Mail Client 45

8.5 Install and Configure Mail Resource and E-Mail Services 47

8.5.1 Installation of JavaMail and JAF 47

8.5.2 Create mail-service.xml 47

8.5.3 Mail Resource in web.xml and jboss-web.xml 49

8.5.4 Outbound E-mail 50

8.5.5 Inbound E-mail 53

8.5.6 Trouble Shooting E-mail Services 57

9 Data Import/Export 59

9.1 Importing Data into openCRX 59

9.2 Importing XML Files 59

9.2.1 Importing vCard Files ( openCRX Contacts) 62

9.2.2 Importing iCalendar Files ( openCRX Meetings) 62

9.2.3 Other Options 63

9.3 Exporting Data from openCRX 63

9.3.1 Exporting XML Files 63

9.3.2 Exporting openCRX Contacts ( vCard Files) 64

9.3.3 Exporting openCRX Contacts ( Outlook Contacts) 65

9.3.4 Exporting openCRX Meetings ( iCalendar Files) 66

9.3.5 Other Options 66

10 Customizing openCRX 67

10.1 Managing Locales 67

10.2 Managing Packages 68

10.3 Role-based UI 69

10.3.1 Model Permissions 69

10.3.2 Multiple Applications 69

10.3.3 Custom Layout JSPs 69

11 Integration with Office Suites 70

11.1 MS Office 70

11.1.1 MS Word 70

11.1.2 MS Excel 70

11.1.3 MS Outlook 70

11.2 Open Office 70

11.2.1 OpenOffice Writer 70

11.2.2 OpenOffice Calc 70

12 Next Steps 71



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 kernel_Segment after default installation (QuickStart) 15

Figure 7: Table kernel_Segment after modification 15

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

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

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

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

Figure 12: 3-Tier with Application Server 24

Figure 13: 4-Tier with Application Server 24

Figure 14: 4-Tier with Clustered Application Servers 24

Figure 15: 4-Tier with Servlet Engine 24

Figure 16: Multiple Data Segments in a single DB 25

Figure 17: Dedicated DB for each Entity 26

Figure 18: Accessing the openCRX Workflow Controller 27

Figure 19: openCRX 1.10.0 Workflow Controller 27

Figure 20: Default Configuration of WorkflowController 28

Figure 21: openCRX Administration – WorkflowController 29

Figure 22: Workflow Controller Configuration – serverURL 30

Figure 23: Workflow Controller Configuration – pingrate and autostart 30

Figure 24: Default Workflow Processes created by WorkflowHandler 32

Figure 25: openCRX MailImporterServlet 33

Figure 26: MailImporterServlet – Configuration 33

Figure 27: Event and Notification Service 35

Figure 28: Standard Topics included in the openCRX distribution 36

Figure 29: Create a new Subscription – step 1 37

Figure 30: Create a new Subscription – step 2 37

Figure 31: Create a new Subscription – step 3 38

Figure 32: Create a new Subscription – step 4 38

Figure 33: Create a Subscription with Filters 39

Figure 34: Flow of messages between openCRX, mail server and mail client 41

Figure 35: Import E-Mails from Mail Client 42

Figure 36: E-Mail Audit – import all inbound/outbound e-mail messages 43

Figure 37: Send E-Mail from openCRX – Overview 44

Figure 38: Send E-Mail from openCRX with Actions > Follow Up 44

Figure 39: Export E-Mail from openCRX – Overview 45

Figure 40: Export E-Mail from openCRX with Actions > Follow Up 45

Figure 41: Envelope E-mail with exported E-Mail Activity as attachment 46

Figure 42: MS Outlook – Resend This Message to edit/send e-mail 46

Figure 43: MS Outlook – Send message 47

Figure 44: Create a new E-Mail Account – step 1 50

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

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

Figure 47: E-mail subject prefix and Web access URL 51

Figure 48: Example of outbound E-mail Action Log Entries 52

Figure 49: Envelope E-Mail with attached E-Mail to be imported 53

Figure 50: Activity Tracker E-Mail is created automatically 54

Figure 51: Activity Tracker E-Mail with newly imported e-mail 54

Figure 52: Newly imported e-mail 55

Figure 53: Activity Creator Default E-mail Creator 56

Figure 54: XML import from 3rd party system – overview 60

Figure 55: Interactive import of XML Files 60

Figure 56: Interactive import of XML Files 61

Figure 57: Operation vCard Import 62

Figure 58: Exporting Contact as XML File 63

Figure 59: XML Exporter provides XML data file and code tables as ZIP file 64

Figure 60: Export Contact as vCard 64

Figure 61: Export Contact to MS Outlook 65

Figure 62: MS Outlook Contact created from openCRX Contact 65

Figure 63: Exporting Meeting / Sales Visit as iCalendar File 66



List of Listings

Listing 1: File Format Subjects and Application Login Principals 21

Listing 2: Example File Subjects and Application Login Principals 21

Listing 3: File Format Users 22

Listing 4: Example File Users 22

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

Listing 6: Iterate all auditees and check for new audit entries 31

Listing 7: Mark Audit Entries as visited by Subscription Handler 31

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

Listing 9: File mail-service.xml 48

Listing 10: Uncomment mail resource definition in web.xml 49

Listing 11: Uncomment mail resource definition in jboss-web.xml 49

Listing 12: Importing certificate into keystore cacerts 49

Listing 13: Debug Output of MailImporterServlet 53

Listing 14: Importing Certificate 57

Listing 15: Locales in web.xml 67

Listing 16: Activating/Deactivating Locales in web.xml 67

Listing 17: Locales in web.xml 68

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



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 1.10.0 (please refer to the QuickStart guide available from http://www.opencrx.org/documents.htm for installation instructions).

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

  • 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 the latter is 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 was introduced with openCRX v1.4.0. 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 kernel_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 (e.g. browse all accounts, browse all activities).

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 kernel_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 Login Procedure

The openCRX login procedure consists of 2 levels:

3.5.1 Application Server Login

The application server login procedure depends on various parameters:

  • application server (e.g. JBoss, BEA WLS, IBM WebSphere, etc.)

  • configuration of 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 application server login is not really under control of openCRX. Many login problems are related to incomplete/faulty application server configuration settings.

3.5.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 8: 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.5.3 Disabling Login

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

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



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

The following steps are 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

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 Manually

The openCRX QuickStart guide (http://www.opencrx.org/documents.htm) contains a very detailed step-by-step example of how to manually create a new openCRX user.

In addition to the procedure described in the openCRX QuickStart guide where a new Subject and a new Principal are created manually, there is also fast procedure if subject name and principal name are identical:

  • 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 created automatically if they do not exist yet



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 9: 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 10: 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 Disabling Users at the level 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 with JBoss you can simply remove users from the file users.properties to prevent access to openCRX. If you block access at the level Application Server such users are locked out from accessing any application and any openCRX segment. However, as the Application Server Login procedure is not entirely controlled by openCRX you must consult the documentation of your respective AppServer or your AppServer Admin for details.

4.2.2 Disabling 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 11: 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

5.1 Typical Deployment Scenarios

The following table lists some of the pros and cons of the 4 most common deployment scenarios:

3-Tier with AppServer

Figure 12: 3-Tier with Application Server

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

  • limited security (not recom­mended for Internet deploy­ment)

  • limited scalability and avail­ability (no clustering)

  • Transaction Service

4-Tier with AppServer

Figure 13: 4-Tier with Application Server

  • simple setup (two application servers)

  • allows to setup Internet, DMZ, Intranet security zones

  • limited scalability and avail­ability (no clustering)

  • Transaction Service

4-Tier with Clustered AppServers

Figure 14: 4-Tier with Clustered Application Servers

  • complex setup (four and more application servers)

  • allows to setup Internet, DMZ, Intranet security zones

  • full scalability and availability

  • Transaction Service

4-Tier with Servlet Engine

Figure 15: 4-Tier with Servlet Engine

  • complex setup (four and more application servers)

  • allows to setup Internet, DMZ, Intranet security zones

  • full scalability and availability

  • 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.) can 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.2.3 Multiple Applications

Multiple (differently) customized Web-EARs can access the same App-EAR. The build process creates the following EARs:

  • One App EAR for the provider.name specified in build.properties

  • One Web EAR for the provider.name and web.application.name in build.properties, whereas the Web EAR delegates to the App EAR.

  • With ant -Dweb.application.name=<appname> -Ddata.dir=<custom dir> additional Web EARs can be created. They Web EAR has the name <appname> containing the customizing info from <custom dir>.

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 1.10.0 (the look and feel may be different for other openCRX versions):

Figure 19: openCRX 1.10.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 the 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 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().

Listing 6: Iterate all auditees and check for new audit entries

for(
Iterator j = auditSegments.iterator();
j.hasNext();
) {
Auditee auditee = (Auditee)j.next();
AuditEntryFilter filter = basePkg.createAuditEntryFilter();
// Not visited elements are marked with VISITOR_ID:-
// Visited elements are marked with VISITOR_ID:<time stamp of visit>
filter.thereExistsVisitedBy(
FilterOperators.IS_IN,
new String[]{VISITOR_ID + ":-"}
);
try {
this.handleSubscriptions(
...
auditee.getAudit(filter)
);
}
catch(ServiceException e) {
System.out.println(new Date() + ": openCRX/SubscriptionHandler:
exception occured " + e.getMessage() + ". Continuing");
}
}
private static final String VISITOR_ID = "SubscriptionHandler";



Please note that activating the Subscription Handler on a DB with lots of (unvisited) Audit Entries (e.g. after an upgrade from openCRX v1.8.1 to openCRX v1.9.1 or later) can put some heavy load on your system until all the Notifications have been generated. You might want to use the following statement to mark all the existing entries as visited:

Listing 7: Mark Audit Entries as visited by Subscription Handler

UPDATE kernel_AuditEntry_N
set visited_by = 'SubscriptionHandler:-'
where (object_idx = 0) and (visited_by is null)

Userhome.executeWorkflow() – implemented by the openCRX plugin – creates an entry in Userhome.wfProcessInstance (accessible through the grid Workflow Process Instances) and executes synchronous workflows immediately. Beyond creating entries for asynchronous workflows, executeWorkflow() does not do anything with them (the Servlet WorkflowHandler is specialized in dealing with asynchronous workflows – see below for details).

6.3 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 current setup ensures that blocking WfProcesses cannot block openCRX.

6.4 MailImporterServlet

The MailImporterServlet provides generic E-mail Services. The servlet regularly connects to e-mail boxes and fetches messages to be imported into openCRX.

Figure 25: openCRX MailImporterServlet

The configuration of the MailImporterServlet is explained in detail in the chapter E-mail Services). The Root administrator (admin-Root) can set a few select options in the MailImporterServlet's ComponentConfiguration. The figure below shows the default configuration as it is created the first time the MailImporterServlet is started:

Figure 26: MailImporterServlet – Configuration

Polling frequency and autostart can also be set (see Figure 23: Workflow Controller Configuration – pingrate and autostart).

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.0.3SP1\server\default\log\server.log on JBoss). The following log file extract shows, for example, that both the Subscription Handler and the Workflow Handler seem to be working fine, whereas the MailImporterServlet cannot connect to the mail box (due to missing configuration):

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

2006-04-04 14:04:25,936 INFO [STDOUT] Tue Apr 04 14:04:25 CEST 2006: openCRX/SubscriptionHandler: CRX/Standard
2006-04-04 14:04:25,967 INFO [STDOUT] Tue Apr 04 14:04:25 CEST 2006: openCRX/WorkflowHandler: CRX/Standard
2006-04-04 14:04:26,451 DEBUG [org.jboss.resource.connectionmanager.IdleRemover]
run: IdleRemover notifying pools, interval: 450000
2006-04-04 14:04:27,092 INFO [STDOUT] DEBUG: setDebug: JavaMail version 1.3.3
2006-04-04 14:04:27,092 INFO [STDOUT] DEBUG POP3: connecting to host "mail.changeme.com", port 110, isSSL false
2006-04-04 14:04:52,795 INFO [STDOUT] S: EOF
2006-04-04 14:05:15,811 INFO [STDOUT] C: QUIT
2006-04-04 14:05:15,811 INFO [STDOUT] S: EOF

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 1.10.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 27: Event and Notification Service

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 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 her 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 28: Standard Topics included in the openCRX distribution) to get you started:

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

  • Topic Activity Follow Up Modifications sends an alert to the UserHome of subscribed users whenever a Follow Up of an Activity is modified.

  • Topic Alert Modifications 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 28: 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 – Activity Modifications

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

  • Login as guest, click on the grid Tab Subscriptions (on the Homepage) and then use the Creator Menu New > Subscription to create a new Subscription:

Figure 29: Create a new Subscription – step 1

  • Enter Name and 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:

Figure 30: Create a new Subscription – step 2

  • Next you click OK to accept; selecting option [1] Object Creation 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).

  • Type activity into the field Topic; the autocompleter will show a drop down from which you select Activity Modifications [Activity Name] as shown below:

Figure 31: Create a new Subscription – step 3

  • Click the button to commit the new Subscription. The grid Subscriptions should now contain an entry for the new Subscription:

Figure 32: Create a new Subscription – step 4

  • This completes the creation of this new Subscription.



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 ActivityTrackers 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 33: 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 (Standard:DivisionA.ProjectX and Standard:DivisionA.ProjectY in our case)



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 Workflow Processes and/or Topics are empty.

  • verify that the Subscription Handler of the respective segment was started at least once (Workflow Processes and Topics are created automatically by the Subscription Handler if they are not present)

  • click on the filter button to see all rows without filtering (maybe you defined a default filter in the past?)

I started the Subscription Handler but I never receive any Alerts / Notifications

  • verify that you started the correct Subscription Handler (each segment has its own Subscription Handler)

  • in case you upgraded to a new version of openCRX and forgot to delete Workflows and Topics provided by openCRX, stop the Subscription Handler, delete Workflow Processes and Topics, and then start the Subscription Handler again

  • check the openCRX log files to find out whether bad/corrupt data might be causing problems (e.g. NullPointer Exception during Workflow execution)

I receive Alerts on my Subscriptions but no Notification E mails

  • verify that JavaMail is properly installed and the mail service properly configured

  • verify your e-mail settings (see E-mail Services for details)

  • verify that the Servlet WorkflowHandler of the respective segment is turned on



8 E-mail Services

Please note that you can use your favorite e-mail client with openCRX. None of our E-mail services are platform dependent and they work with any e-mail client and with any mail server as long as they support standard protocols like SMTP, POP3, POP3S, IMAP, IMAPS, etc.

Inbound and outbound E-mail services are based on JavaMail. Installation of JavaMail is not required to run openCRX, but it is required if you want to make use of openCRX E-Mail services.

The following figure shows the flow of mail messages between openCRX, mail server, and mail client as it is supported with openCRX 1.10.0:

Figure 34: Flow of messages between openCRX, mail server and mail client

In the following few sections we will first discuss various important use cases and subsequently show how to configure openCRX in order to make use of the available functionality.

8.1 Import E-mails from a Mail Client into openCRX

Instead of offering platform specific plugins for a multitude of