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 G_super is a supergroup of an owning group Gif every user who is member of Gis also member of G_super
** Owning group G_sub is a subgroup of an owning group Gif every user who is member of G_subis 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 management (Server Installer)
limited scalability and availability (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 management (one application server)
limited scalability and availability (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

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

<servlet id="WorkflowController">
<servlet-name>WorkflowController</servlet-name>
<servlet-class>org.opencrx.kernel.workflow.servlet.WorkflowControllerServlet</servlet-class>
...

<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