|
|
Version
Table of Contents
1.2 What do you need to understand this book 7
3.1.1 Basic Concepts and Conventions 9
3.1.2 Permissions / Access Control 12
3.4 Security Settings of New Objects 16
3.5.1 Application Server Login 17
4.1.1 Create Users Manually 20
4.1.2 Import Subjects and Application Login Principals 21
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.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.3 Multiple Applications 26
5.3 openCRX Custom Applications 26
6.1 Workflow Controller Configuration 29
6.1.1 Startup Configuration in web.xml 29
6.1.3 Handler pingrate and autostart 30
6.2 Servlet SubscriptionHandler 31
6.3 Servlet WorkflowHandler 32
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.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.6 Trouble Shooting E-mail Services 57
9.1 Importing Data into openCRX 59
9.2.1 Importing vCard Files ( openCRX Contacts) 62
9.2.2 Importing iCalendar Files ( openCRX Meetings) 62
9.3 Exporting Data from openCRX 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
10.3.2 Multiple Applications 69
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: |
|
|
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
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 |
|
|
Segment administrator |
|
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 |
|
|
|
4-Tier with AppServer |
Figure 13: 4-Tier with Application Server |
|
|
|
4-Tier with Clustered AppServers |
Figure 14: 4-Tier with Clustered Application Servers |
|
|
|
4-Tier with Servlet Engine |
Figure 15: 4-Tier with Servlet Engine |
|
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
Figure 19: openCRX
|
|
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. |
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 |
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.
|
|
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. |
|
|
I started the Subscription Handler but I never receive any Alerts / Notifications |
|
|
I receive Alerts on my Subscriptions but no Notification E mails |
|
to see all rows without filtering (maybe you defined a default
filter in the past?)
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
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