![]() |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Version
Table of Contents 1.2 What do you need to understand this book 8 3.1.1 Basic Concepts and Conventions 10 3.1.2 Permissions / Access Control 13 3.1.3 The SQL approach to understanding security 15 3.4 Security Settings of New Objects 18 3.6.1 Apache Tomcat / Application Server Login 20 4.1.1 Create Users as Segment Administrator 23 4.1.2 Import Subjects and Application Login Principals 26 4.2 Disable/Deactivate Users 28 4.2.1 Disable Users at the level Tomcat /Application Server 28 4.2.2 Disable Users at the level openCRX 28 5.1 Typical Deployment Scenarios 29 5.2 Multi Entity Deployment Scenarios 31 5.2.1 Multiple Data Segments in a single DB 31 5.3 openCRX Custom Applications 32 6.1 Workflow Controller Configuration 35 6.1.1 Startup Configuration in web.xml 35 6.1.3 Handler pingrate and autostart 36 6.3 Servlet SubscriptionHandler 37 6.4 Servlet WorkflowHandler 38 6.5 Trouble Shooting Servlets 39 7 Subscribe / Notify Services 40 7.1 Example Subscription – Account Modifications 42 7.2 Example Subscription – Activity Assignment Changes 42 7.3 Example Subscription with Filtering 43 7.5 Trouble Shooting Notification Services 44 8.1 Install and Configure Mail Resource and E-Mail Services 46 8.1.1 Installation of JavaMail and JAF 46 8.1.2 Mail Resource for openCRX on Apache Tomcat 46 8.1.2.1 Add resource definition to openejb.xml 46 8.1.2.2 Mail Resource in web.xml 47 8.2.1 Outbound E-mail Configuration 48 8.2.3 Send E-mails directly from openCRX 51 8.2.4 Send E-mails as Attachments to your Mail Client 52 8.2.5 Send E-mails to Fax-/SMS-Gateways 53 8.4 Trouble Shooting E-mail Services 54 9.1 Directory Service / LDAP (not available anymore) 55 9.1.1 Configuring the openCRX LDAP Port 56 9.1.2 LDAP Configuration of Thunderbird 56 9.1.3 LDAP Configuration of MS Outlook 57 9.2.1.1 Connecting MS Outlook to the openCRX vcard servlet 59 9.2.1.2 Connecting Thunderbird to the openCRX vcard servlet 59 9.3.1 Calendar as a Set of Activities 60 9.3.3 openCRX Activities mapped to Calendar Events 63 9.3.4 Calendaring / Free Busy 65 9.3.4.1 Free Busy Configuration of Thunderbird 65 9.3.4.2 Free Busy Configuration of MS Outlook 65 9.3.5 Calendaring / iCalendar (ICS) 66 9.3.5.1 ICS Configuration of Thunderbird/Lightning and Sunbird 67 9.3.5.2 ICS Configuration of MS Outlook 67 9.3.5.3 ICS Configuration of Zimbra 68 9.3.5.4 ICS Configuration of iPhone 68 9.3.5.6 iCalender Guard Event 70 9.3.6.2 CalDAV Configuration of Thunderbird/Lightning and Sunbird 73 9.3.6.3 CalDAV Configuration of MS Outlook 73 9.3.6.4 CalDAV Configuration of iPhone 74 9.3.7 Calendaring / Timeline 76 9.4.1 Configuring the openCRX IMAP Port 79 9.4.2 Configuring the IMAP Maildir Cache 79 9.4.2.1 Maildir Configuration with Apache Tomcat 79 9.4.3 IMAP Configuration of Thunderbird 80 9.4.4 IMAP Configuration of MS Outlook 81 10 openCRX is a REST Service (Web Service) 83 11.1 Importing Data into openCRX 84 11.2.1 Importing Excel Files ( openCRX Accounts) 87 11.2.2 Importing vCard Files ( openCRX Contacts) 90 11.3 Exporting Data from openCRX 91 11.3.2 Exporting Data to MS Excel / Open Office Calc Files 93 11.3.3 Exporting openCRX Contacts ( vCard Files) 94 11.3.4 Exporting openCRX Meetings ( iCalendar Files) 95 12.2.1 Enabling/Disabling Root Menu Entries 99 13 Integration with Office Application 101 13.1 MS Word, OpenOffice Writer, etc. 101 13.2 MS Excel, Open Office Calc, etc. 102 13.3 MS Outlook, Thunderbird/Lightning, Sunbird, etc. 102 14.3 Large Scale Reporting 104
List of Figures Figure 1: Security Realms, Principals and Subjects after Initial Setup 11 Figure 2: Segment Administration 12 Figure 3: Role Drop Down with list of available Segment Login Principals 12 Figure 4: openCRX UML Model – Class Diagram SecureObject 13 Figure 5: System attributes of an openCRX object as shown in the GUI 14 Figure 6: Table OOCKE1_SEGMENT after default installation 17 Figure 7: Table OOCKE1_SEGMENT after modification 17 Figure 8: Result of Check Permissions 19 Figure 9: Role Drop Down with list of available Segment Login Principals 20 Figure 10: New user guest – step 1 23 Figure 11: New user guest – step 2 23 Figure 12: New user guest – step 3 23 Figure 13: New user guest – step 4 24 Figure 14: New user guest – step 4 24 Figure 15: New user guest – step 5 24 Figure 16: New user guest – step 6 25 Figure 17: Operation Actions > Import Login Principals (admin-Root) 26 Figure 18: Operation Actions > Import Users (admin-Standard) 27 Figure 19: Disabling of Segment Login Principal guest by admin-Standard 28 Figure 20: 3-Tier with Apache Tomcat / OpenEJB 29 Figure 21: 4-Tier with multiple Tomcat / OpenEJB instances 29 Figure 22: 3-Tier with J2EE-compliant Application Server 29 Figure 23: 4-Tier with Clustered Application and DB Servers 30 Figure 24: Multiple Data Segments in a single DB 31 Figure 25: Dedicated DB for each Entity 32 Figure 26: Accessing the openCRX Workflow Controller 33 Figure 27: openCRX 2.5.2 Workflow Controller 33 Figure 28: Default Configuration of WorkflowController 34 Figure 29: openCRX Administration – WorkflowController 35 Figure 30: Workflow Controller Configuration – serverURL 36 Figure 31: Workflow Controller Configuration – pingrate and autostart 36 Figure 32: Default Workflow Processes created by WorkflowHandler 38 Figure 33: Event and Notification Service 40 Figure 34: Standard Topics included in the openCRX distribution 41 Figure 35: Create a new Subscription 42 Figure 36: Create a Subscription with Filters 43 Figure 37: Flow of e-mail messages between openCRX, MTA and mail client 45 Figure 38: Create a new E-Mail Account – step 1 48 Figure 39: Create a new E-Mail Account – step 2 48 Figure 40: Create a new E-Mail Account – step 3 49 Figure 41: E-mail subject prefix and Web access URL 49 Figure 42: Example of outbound E-mail Action Log Entries 50 Figure 43: Send E-Mail from openCRX – Overview 51 Figure 44: Send E-Mail from openCRX with Actions > Follow Up 51 Figure 45: Send E-Mail as Attachment from openCRX – Overview 52 Figure 46: Export E-Mail from openCRX with Actions > Follow Up 52 Figure 47: Thunderbird LDAP Configuration 56 Figure 48: MS Outlook LDAP Configuration 57 Figure 49: openCRX Activity Groups / openCRX Activity Filters 60 Figure 50: An openCRX activity's iCal representation 63 Figure 51: An openCRX activity in the standard GUI 63 Figure 52: An openCRX activity filtered to a user's homepage 64 Figure 53: iCalendar conversion between VEVENT and VTODO 70 Figure 54: Timeline visualizes time-based events 76 Figure 55: E-Mail Address UNASSIGNED 78 Figure 56: Thunderbird IMAP Configuration 80 Figure 57: MS Outlook IMAP Configuration 81 Figure 58: XML import from 3rd party system – overview 85 Figure 59: Interactive import of XML Files 85 Figure 60: Interactive import of XML Files 86 Figure 61: Import Accounts from Excel Sheet – Sample Excel Sheet 87 Figure 62: Import Accounts from Excel Sheet – Import Report 89 Figure 63: Operation vCard Import 90 Figure 64: Exporting SalesOrder as XML File 92 Figure 65: XML Exporter provides XML data file and code tables as ZIP file 92 Figure 66: Exporting SalesOrder as Spreadsheet File 93 Figure 67: Exported Spreadsheet File 93 Figure 68: Manually Export Contact as vCard 94 Figure 69: Export individual Contact as vCard with Wizard 94 Figure 70: Export multiple Contact as vCards with Wizard 94 Figure 71: Exporting Meeting / Sales Visit as iCalendar File 95 Figure 72: Export individual Activity as iCal with Wizard 95 Figure 73: Launch Wizard User Settings 99 Figure 74: Wizard User Settings – enable/disable Root Menu Entries 99 Figure 75: RTF Document generated by merging live data with template 101 Figure 76: Contacts Export Dialog 102
List of Listings Listing 1: File Format Subjects and Application Login Principals 26 Listing 2: Example File Subjects and Application Login Principals 26 Listing 3: File Format Users 27 Listing 4: Example File Users 27 Listing 5: web.xml – auto startup of the Workflow Controller 35 Listing 6: Servlets managed by Workflow Controller log to server.log 39 Listing 7: File openejb.xml 47 Listing 8: Uncomment mail resource definition in web.xml 47 Listing 9: Importing certificate into keystore cacerts 47 Listing 10: Importing Certificate 54 Listing 11: Set org.opencrx.maildir for Apache Tomcat 79 Listing 12: Locales in web.xml 97 Listing 13: Activating/Deactivating Locales in web.xml 97 Listing 14: Packages in web.xml 98 Listing 15: Activating/Deactivating Packages in web.xml 98
1 About this BookThis book describes various configuration settings and tasks that make an openCRX administrator's life easier. 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 forThe intended audience are openCRX administrators. 1.2 What do you need to understand this bookThis 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:
2 PrerequisitesThis guide assumes that you have access to a
properly installed instance of openCRX You can either follow the openCRX Server Installer documentation (http://www.opencrx.org/server.htm) or you can do a manual installation of openCRX following the installation guide for Tomat 6. 3 SecurityIn this chapter we will present a high-level overview of openCRX security and discuss a few important issues.
3.1 Introduction3.1.1 Basic Concepts and Conventions
The following figure shows the situation after the initial setup of openCRX (assuming you installed openCRX Server or followed the installation guide for Tomat 6): Figure 1: Security Realms, Principals and Subjects after Initial Setup Summarizing the above:
The segment administrator (e.g. admin-Standard) creates principals and User home pages with the operation createUser():
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 ControlThe openCRX security framework makes a clear distinction between Ownership Permissions (permissions granted on a particular object) and Model Permissions (permissions granted on a particular model element). As the latter are not implemented (yet) 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 (i.e. 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
The most important security attributes of an object X are discussed below:
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:
3.1.3 The SQL approach to understanding securityIf you are familiar with SQL, the following approach to understanding security might be helpful. Let's put ourselves into the role of the AccessControl Plugin; accessing an object (read mode) results in a SELECT statement as follows: SELECT * FROM T WHERE owner IN (p1, p2, ....)
3.2 Activating SecuritySecurity (including Access Control) is not just a fancy add-on, rather it is an integral part of openCRX; openCRX Access Control is always activated. 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.
3.3 Default SettingsDefault access level settings for non-Root segments (e.g. segment Standard) after a clean install are as follows:
Figure 6: Table OOCKE1_SEGMENT after default installation 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. any user can browse all accounts, all activities, all documents, etc.). These default settings are suitable for test environments and deployments in smaller companies/teams with a generous 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 OOCKE1_SEGMENT). After this change, the table OOCKE1_SEGMENT will look as shown in the following figure: Figure 7: Table OOCKE1_SEGMENT after modification
3.4 Security Settings of New ObjectsNew objects are by default created with the following security settings:
3.5 Checking PermissionsYou can check security permissions on any SecureObject with the operation Security > Check Permissions. Provide the principal name as a parameter. The following figure shows the result of the operation on a user's homeage: Figure 8: Result of Check Permissions The meaning of the above result is as follows:
3.6 Login ProcedureThe openCRX login procedure consists of 2 levels: 3.6.1 Apache Tomcat / Application Server LoginThe Apache Tomcat / application server login procedure depends on various parameters:
Please note that even though openCRX might be involved in managing some of the above-mentioned realms (e.g. DB-based realm) the login procedure is not really under control of openCRX. Many login problems are really related to incomplete/faulty configuration settings of the servlet container.
3.6.2 Segment LoginAccess 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 LoginPlease refer to the chapter “Disable/Deactivate Users”. 3.7 Resetting Security
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
4.1 Creating UsersEven 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:
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 AdministratorThe Segment administrator can create new users with the following steps:
Figure 10: New user guest – step 1
Figure 11: New user guest – step 2
Figure 12: New user guest – step 3
Figure 13: New user guest – step 4
Figure 14: New user guest – step 4
Figure 15: New user guest – step 5
Figure 16: New user guest – step 6
4.1.2 Import Subjects and Application Login PrincipalsCreating 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 17: Operation Actions > Import Login Principals (admin-Root) Listing 1: File Format Subjects and Application Login Principals Subject;<subject
name>;<subject description>
Listing 2: Example File Subjects and Application Login Principals Subject;joe;Doe,
Joe
4.1.3 Import UsersSimilarly 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 18: 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 a “-” value (a dash without the quotes) means empty in the context of a user file. Example: if you don't want to explicitly define a primary group, you can just put a dash and the importer will create the default primary group <principal>.Group for the respective user. Listing 4: Example File Users User;joe;JD;Doe,
Joe;Users;2%jOd.IT;MGMT,SALES
4.2 Disable/Deactivate UsersThere 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 ServerDepending 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 Apache 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 openCRXThe 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 19: Disabling of Segment Login Principal guest by admin-Standard
5 Deployment ScenariosopenCRX supports a multitude of deployment scenarios. 5.1 Typical Deployment ScenariosThe 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:
5.2 Multi Entity Deployment ScenariosThe 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 DBThe 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 real 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 24: Multiple Data Segments in a single DB Detailed instructions on how you can create and configure new segments are provided in the installation guide for Tomat 6. 5.2.2 Multiple DBsThe 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 25: Dedicated DB for each Entity 5.3 openCRX Custom ApplicationsInformation about openCRX custom projects is available from the openCRX wiki, e.g. https://sourceforge.net/apps/trac/opencrx/wiki/Sdk24.CustomProject. 6 Workflow ControllerWith 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 26: Accessing the openCRX Workflow Controller
The following
figure shows the Workflow Controller of openCRX
Figure 27:
openCRX
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 “OtherSegment” in addition to the segment “Standard” you can start/stop servlets of the segment “OtherSegment” without interfering with the servlets of the segment “Standard”. 6.1 Workflow Controller ConfigurationIn 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 available to the openCRX Root administrator (admin-Root) by navigating to Administration and then clicking on the icon of the WorkflowController: Figure 29: openCRX Administration – WorkflowController
6.1.1 Startup Configuration in web.xmlYou 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 -->
6.1.2 ServerURLAdapt the value of serverURL to your environment (e.g. http://127.0.0.1:8080/opencrx-core-CRX): Figure 30: Workflow Controller Configuration – serverURL 6.1.3 Handler pingrate and autostartUse 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 31: Workflow Controller Configuration – pingrate and autostart 6.2 Servlet IndexerServletThe 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.
6.3 Servlet SubscriptionHandlerThe 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 31: 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 WorkflowHandlerThe openCRX WorkflowHandler is responsible for executing WfProcessInstances based on asynchronous WfProcesses like:
The execution frequency can be set by the Root administrator (see Figure 31: Workflow Controller Configuration – pingrate and autostart).
The WorkflowHandler executes Workflow Process Instances that have not been executed yet.
6.5 Trouble Shooting ServletsAll the openCRX servlets controlled by the Workflow Controller log their actions to the server log file (e.g. TOMCAT_HOME\log\catalina.<date>.log). 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 openCRX Exceptions (like NullPointers, etc.), however, are still logged to the application log file as configured during the installation. 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 27: openCRX 2.5.2 Workflow Controller).
7 Subscribe / Notify ServicesopenCRX features a powerful event subscription and notification service: Figure 33: 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.
The openCRX distribution includes quite a few default topics (see Figure 34: Standard Topics included in the openCRX distribution) to get you started:
Figure 34: 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 ModificationsIn this example we will create a subscription to the standard Topic Account Modifications for the user “guest”.
Figure 35: Create a new Subscription
7.2 Example Subscription – Activity Assignment ChangesWith the following steps you can create a subscription to activity assignment changes:
To locate the identity of a user's homepage, you can navigate to the respective homepage and inspect the tab [System]. The pattern is as follows: xri://@openmdx*org.opencrx.kernel.home1/provider/<providerName>/segment/<SegmentName>/userHome/<principal>
7.3 Example Subscription with FilteringIn 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, whereas some users want to receive notifications related to activities of ProjectY only. A third group of users wants to receive notifications from both projects. Such a situation could be handled as follows:
Figure 36: 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)
7.4 RSS FeedsNew alerts are also available as RSS feeds. Users can subscribe to their news feed directly from their homepage: 7.5 Trouble Shooting Notification ServicesThe following table lists some of the common issues and how to fix them:
8 E-mail ServicesPlease note that we have no intention to duplicate mail server (MTA) or mail client functionality in openCRX as there are lots of excellent products available (Open Source and commercial). It is our goal, however, that openCRX integrates with all the major products that adhere to the major standards and support standard protocols like SMTP, POP3, IMAP, etc. This ensures that you can continue to use your favorite mail server (qmail, postfix, etc.) and your favorite mail client (Thunderbird, Outlook, etc.).
The following figure shows the flow of mail
messages between openCRX, mail server, and mail client as it is
supported with openCRX
Figure 37: Flow of e-mail messages between openCRX, MTA and mail client In this chapter we will first guide you through the required installation and configuration steps before we discuss various important use cases. 8.1 Install and Configure Mail Resource and E-Mail ServicesThe following chapters explain how to install JavaMail and how to configure the Java mail service and various in- and outbound E mail services.
8.1.1 Installation of JavaMail and JAFDetailed installation instructions are provided at the JavaMail home: http://java.sun.com/products/javamail/FAQ.html And here is the short version:
The following instructions are dependent on your deployment scenario as the steps for creating mail resources vary from application server to application server. We provide instructions for Apache Tomcat. 8.1.2 Mail Resource for openCRX on Apache Tomcat8.1.2.1 Add resource definition to openejb.xmlOpen the file TOMCAT_HOME\conf\openejb.xml and add (or modify) the mail resource definition. In the sample file below you must at least adapt the highlighted strings to your own environment: Listing 7: File openejb.xml ...
Additional information about configuration options of JavaMail is available from the JavaMail home: http://java.sun.com/products/javamail/FAQ.html 8.1.2.2 Mail Resource in web.xmlIn the file web.xml in the directory <Tomcat Install Dir>\apps\opencrx-core-CRX\opencrx-core-CRX\WEB-INF you must uncomment the following section: Listing 8: Uncomment mail resource definition in web.xml
... Restart Tomcat for these changes to become active.
8.2 Outbound E-mail8.2.1 Outbound E-mail ConfigurationopenCRX users can configure e-mail accounts on their homepage indicating where they would like to receive e-mail notifications (e.g. generated by subscriptions):
Figure 38: Create a new E-Mail Account – step 1
Figure 39: Create a new E-Mail Account – step 2
The various fields have the following meanings:
Figure 40: Create a new E-Mail Account – step 3
Figure 41: E-mail subject prefix and Web access URL
The meaning of the two fields is as follows: You can easily test your e-mail settings if you create a subscription for Account Modifications (see Example Subscription – Account Modifications) and then work through the following steps:
Figure 42: Example of outbound E-mail Action Log Entries
8.2.2 Export E-mailsPlease refer to chapter 9.4 Mailstore / IMAP. 8.2.3 Send E-mails directly from openCRXAny openCRX E-Mail Activity can be sent as e-mail directly from openCRX: Figure 43: Send E-Mail from openCRX – Overview The idea behind this functionality is less that you will use openCRX as a mail client, rather the SendMailWorkflow is an important element of the openCRX campaign management functionality. E-Mail Activities of type “E-Mails” are controlled by the Activity Process E-mail Process. Send E-Mail Activities to all recipients by executing the operation Actions > Follow Up and then selecting the Transition Send as mail as shown below: Figure 44: Send E-Mail from openCRX with Actions > Follow Up
8.2.4 Send E-mails as Attachments to your Mail ClientAny openCRX E-Mail Activity can be sent to your mail client as an attachment. The idea behind this functionality is that you might want to put some finishing touches on an e-mail before you actually send it from your mail client: Figure 45: Send E-Mail as Attachment from openCRX – Overview E-Mail Activities of type “E-Mails” are managed by the standard Activity Process E mail Process, i.e. they can be exported to the user's default mail account by executing the operation Actions > Follow Up and then selecting the Transition Export as mail attachment: Figure 46: Export E-Mail from openCRX with Actions > Follow Up
8.2.5 Send E-mails to Fax-/SMS-GatewaysThe SendMailWorkflow supports mail gateways if you set the attribute gateway of the respective e-mail activity. The gateway address is used for addresses which are not of type EmailAddress. For example, in the case of a phone number, the address is converted to an e-mail address as follows:
Example: if the domain address of an e-mail activity is set to the email address noreply@fax-gateway.opencrx.org, the the phone number +41 (44) 111-2233 is converted to the email address _41441112233@fax-gateway.opencrx.org. This conversion feature allows you to mix e-mail addresses and phone numbers in member lists of address groups. Depending on the recipient's type of addresss the SendMailWorkflow will either send an e-mail to the listed e mail address as is (e-mail address) or first convert the recipient's phone number to an e-mail address so that the resulting e-mail can be handled by your fax-/sms-gateway.
8.3 Inbound E-mailPlease refer to chapter 9.4 Mailstore / IMAP. 8.3.1 Import E-mailsPlease refer to chapter 9.4 Mailstore / IMAP. 8.4 Trouble Shooting E-mail ServicesThe following table lists some of the common issues and how to fix them:
9 Groupware ServicesopenCRX features the following groupware services:
|
|
|
|
|
|
|
|
|
|
|
|
|
The openCRX LDAP port is by default set
to 1389 (to avoid conflicts with other LDAP daemons listening on the
LDAP standard port 389). You can change this configuration in the
file config.ldif
located
in
opencrx-groupware-CRX.ear\opencrx-ldap-CRX.war\WEB-INF\config\
Look
for the entry ds-cfg-listen-port.
If you build your own EARs you can change
the openCRX LDAP port in your project's file build.properties
(ldap.listenPort) or directly in your build.xml.
The following steps are required to configure Thunderbird 2
for LDAP:
start
Thunderbird and select the menu Tools
> Options
select
Composition and select the
tab Addressing
check
Directory Server and click
on the button Edit Directories
Figure 47: Thunderbird LDAP Configuration
in the
dialog window LDAP Directory Servers click on the button Add
populate
the Directory Server Properties dialog as follows (assuming
the openCRX Server is at localhost,
connecting with Username guest):
|
|
|
|
|
|
|
|
|
|
click OK
to accept
The following steps are required to
configure MS Outlook 2007 for LDAP:
start Outlook and select the
menu Tools > Account Settings
click on the tab Address
Books
populate the Add/Change E-mail
Account dialog as follows (assuming the openCRX Server is at
localhost, connecting with
Username guest):
|
|
|
|
|
|
|
|
click
on the button More Settings
and select the tab Connection
enter
a display name (of your choice) and verify that port is set to 1389
select
the tab Search
in
the field group Search Base click on Custom and populate as
follows:
Figure
48: MS Outlook LDAP Configuration
click
OK,
Next,
Finish,
and Close
to conclude the configurationion
The openCRX vcard servlet does for accounts what the openCRX ical servlet does for activities: it makes them available to third-party clients who access the openCRX server with the http protocol.
openCRX can map sets of accounts to a vcard file (a sequence of vcards). The resulting vcard file can be imported and/or processed by vcard-enabled clients like Outlook, Thunderbird, etc. At this time, account filters are the only supported account selectors. Account filters support reading and updating, but not creating of accounts (R=read, U=update):
Set of Accounts |
RUC |
vCard Selector |
Account Filter |
RU |
accounts?id=<provider>/<segment>/filter/<account filter name>&type=vcf |
VCF Selector Examples:
accounts?id=CRX/Standard/filter/All+Accounts&type=vcf
accounts?id=CRX/Standard/filter/Accounts+with+missing+or+broken+vCard&type=vcf
|
Use the openCRX Wizard “Calendar / vCard Connection Helper” to generate valid VCF Selectors. You can start the wizard from your homepage:
Choose the options “vCard” and “Account Filter” and then select the desired account filter: |
Detailed instructions on how to connect MS Outlook are available from http://www.opencrx.org/opencrx/2.4/Outlook_ICS_VCF_adapter.htm
A Thunderbird add-on is available that enables you to map address books to openCRX account selectors:
openCRX supports a wide range of types of activities, including Tasks, Meetings, E Mails, Phone Calls, etc. Even though all activities are kept in a single location (think of a box containing activities), openCRX offers a multitude of mechanisms to structure, filter, and group activities:
activities can be assigned to activity groups, which enables you to group them by Tracker, Category, and Milestone
activities can be filtered with predefined filters (e.g. activities filtered to a user's homepage, activities filtered by resource) and user-defined ActivityFilters (either at a global level or at the level of an activity group)
To fully understand the power of this approach, consider a large project X (e.g. building a power plant) with millions of activities. With openCRX, a project is typically mapped to an activity tracker (e.g. all activities of project X are assigned to the activity tracker Project X). As a large project is often times structured, i.e. broken down into subprojects, milestones, etc., let us assume that the respective subset of activities related to Project X is assigned to an activity group Milestone 2. With openCRX, it's a single click and you can browse all the activities assigned to Milestone 2, or you can view all these activities in a calendar application like Sunbird or MS Outlook:
Figure 49: openCRX Activity Groups / openCRX Activity Filters
It goes without saying that different users have different needs. It is also quite natural that the needs change over time. With openCRX, it is easy to deliver as there are virtually unlimited possibilities to slice and dice the universe of activities. For example, instead of pulling a set of activities based on their assignment to activity groups, there are many use cases where one would like to define a filter to define a subset of activities. On the one hand, openCRX features lots of default filters, on the other hand, there are powerful tools to define custom filters virtually any way you like. For example: an auditor might be interested in all activities involving a particular subcontractor, another user could be interested in browsing through all the meetings related to Project X. Hence, in the context of calendaring it helps if you think of a calendar as a set of activities, nothing more and nothing less.
openCRX can map each of the above-mentioned set of activities to a calendar. Depending on the mapping, the resulting calendar can be presented in various formats, e.g. ICS calendar, Free Busy calendar, XML file, Timeline, etc. Some typical ICS calendar selectors are listed below (R=read, U=update, C=create):
Set of Activities |
RUC |
ICS Calendar Selector |
Tracker |
RUC |
activities?id=<provider>/<segment>/tracker/<name>&type=ics |
... Filtered |
RUC |
activities?id=<provider>/<segment>/tracker/<name>/filter/<filter name>&type=ics |
Category |
RUC |
activities?id=<provider>/<segment>/category/<name>&type=ics |
... Filtered |
RUC |
activities?id=<provider>/<segment>/category/<name>/filter/<filter name>&type=ics |
Milestone |
RUC |
activities?id=<provider>/<segment>/milestone/<name>&type=ics |
... Filtered |
RUC |
activities?id=<provider>/<segment>/milestone/<name>/filter/<filter name>&type=ics |
Global Filter |
RU |
activities?id=<provider>/<segment>/globalfilter/<activity filter name>&type=ics |
Homepage |
RU |
activities?id=<provider>/<segment>/userhome/<home qualifier>&type=ics |
Resource |
RU |
activities?id=<provider>/<segment>/resource/<resource name>&type=ics |
Birthdays |
R |
bdays?id=<provider>/<segment>/filter/<account filter name>&type=ics |
|
Use the openCRX Wizard “Calendar / vCard Connection Helper” from your Homepage to generate valid Calendar Selectors:
Choose the option “Calendar” and then make your selections:
|
CalDAV calendar selectors look as follows (R=read, U=update, C=create):
Set of Activities |
RUC |
CalDAV Calendar Selector |
Tracker |
RUC |
<provider>/<segment>/tracker/<name> |
... Filtered |
RUC |
<provider>/<segment>/tracker/<name>/filter/<filter name> |
Category |
RUC |
<provider>/<segment>/category/<name> |
... Filtered |
RUC |
<provider>/<segment>/category/<name>/filter/<filter name> |
Milestone |
RUC |
<provider>/<segment>/milestone/<name> |
... Filtered |
RUC |
<provider>/<segment>/milestone/<name>/filter/<filter name> |
Global Filter |
RU |
<provider>/<segment>/globalfilter/<activity filter name> |
Homepage |
RU |
<provider>/<segment>/userhome/<home qualifier> |
Resource |
RU |
<provider>/<segment>/resource/<resource name> |
|
Use the openCRX Wizard “Calendar / vCard Connection Helper” from your Homepage to generate valid Calendar Selectors:
Choose the option “Calendar” and then make your selections (set Type to CalDAV for CalDAV calendar selectors):
|
The wizard can also build URLs for CalDAV calendar collections:
Set of Calendars |
RUC |
CalDAV Calendar Collection Selector |
Collection |
RUC |
<provider>/<segment>/user/<principal name>/profile/<profile name> |
Example: http://demo.opencrx.org/opencrx-caldav-CRX/CRX/Standard/user/guest/profile/MyCals
openCRX activities correspond to calendar events (or tasks). An event's iCal representation is stored in the corresponding activity's iCal attribute:
Figure 50: An openCRX activity's iCal representation
In the openCRX standard GUI the same activity is presented as follows:
Figure 51: An openCRX activity in the standard GUI
As the above activity is assigned to “guest” it is automatically filtered to the homepage of the user guest:
Figure 52: An openCRX activity filtered to a user's homepage
For the purpose of this guide this activity is also assigned to the tracker “shared”. In various of this guide's examples we will make use of these facts by using the Calendar Selectors activities?id=CRX/Standard/userhome/guest and activities?id=CRX/Standard/tracker/shared.
Free Busy is part of the iCalendar standard (RFC 2445) for calendar data exchange (see also Wikipedia). Many calendar clients rely on this information for group scheduling. openCRX can derive free busy information on-the-fly from the respective activities; as most clients do not support authentication the default configuration of the openCRX ical servlet does not require authentication to retrieve Free Busy information. However, the principal guest must exist (but you can disable the login):
Free Busy URL (without authentication, requires openCRX principal guest):
http://<crxServer>:<Port>/opencrx-ical-<Provider>/freebusy
?id=<Provider>/<Segment>/<Calendar
Selector>
Example:
http://localhost:8080/opencrx-ical-CRX/freebusy?id=CRX/Standard/tracker/main
Please note that free busy information is provided by the openCRX server in a read-only fashion (i.e. free busy clients cannot update such information).
|
If you prefer authentication for Free Busy clients you can add the url-pattern /freebusy to the web-resource-collection (in the file web.xml of the ical servlet). |
Thunderbird 2.0 supports free busy if the following add-ons are installed:
Lightning (at least v0.9)
SOGo Connector Thunderbird Extension (at least v0.95)
Once the SOGo Connector is installed, Contact Cards of the Thunderbird Address Book will feature a tab CalDAV. This is where you can enter the URL:
See http://support.microsoft.com/kb/291621. Please note that Outlook does not support SSL with free busy.
iCalendar is implemented/supported by a large number of products (see RFC 2445 or Wikipedia for information about the iCalendar standard, sometimes referred to as “iCal”). openCRX can derive iCalendar information on-the-fly from the respective activities. iCal clients must authenticate to read and/or write iCalendar data.
ICS URL (with authentication):
http://<crxServer>:<Port>/opencrx-ical-<Provider>/activities
?id=<Provider>/<Segment>/<Calendar
Selector>&type=ics
Example:
http://localhost:8080/opencrx-ical-CRX/activities?id=CRX/Standard/tracker/main&type=ics
|
See chapter 9.3.2 Calendar Selectors for information on how to construct calendaring URLs. |
|
Please note that calendars without “C” (create) in the table provided in chapter 9.3.2 Calendar Selectors do not support creation of new events/tasks with external ICS clients. The reason being that without a well-defined ActivityCreator associated with the respective calendar selector it is not possible to create an activity and assign it to the appropriate activity groups. |
While the mapping of most of openCRX's activity attributes to iCal attributes is obvious, the following hints might still be helpful:
VEVENT:
Activity.disabled==true --> STATUS:CANCELLED
Activity.percentComplete==0 --> STATUS:TENTATIVE
percentComplete>0 --> STATUS:CONFIRMED
VTODO:
Activity.disabled==true --> STATUS:CANCELLED
Activity.percentComplete==0 --> STATUS:NEEDS-ACTION
Activity.percentComplete>0 --> STATUS:IN-PROCESS
Activity.percentComplete==100 --> STATUS:COMPLETED
Please note that Activity.percentComplete cannot be changed upon import of a vCard as openCRX activities are managed by activity processes. Hence, changing the status of an activity outside of openCRX does not change the status of this activity in openCRX (even if it is reimported).
Thunderbird 2.0 with the Lightning add-on (at least version 0.9) is a fully-fledged calendar client and offers virtually the same calendaring functionality as the stand-alone calendar client Sunbird (at least version 0.9). Creating a remote calendar (hosted on your openCRX server) is rather straightforward:
start Thunderbird/Lightning or Sunbird
select the menu File > New Calendar
in the dialog window Create New Calendar you select On the Network
then you select iCalendar (ICS)
enter an ICS URL into the field Location;
example:
the user guest would connect to this openCRX homepage with the URL
http://127.0.0.1:8080/opencrx-ical-CRX/activities?id=CRX/Standard/userhome/guest&type=ics
See chapter 9.3.2 Calendar Selectors for information on ICS
URLs
give your calendar a name and pick a color of your choice
That's it. You
are connected to openCRX:
Version 0.9 of Thunderbird/Lightning and Sunbird requires a life connection to openCRX (i.e. no support for offline viewing/editing) unless you enable the experimental Cache of Ligthning/Sunbird.
Out of the box Redmond's flagship MS Outlook 2007 does not offer you much choice with ICS calendars. You are stuck with one of the following 2 options:
Published Calendars
are local
calendars published to a remote location, but there is no sync with
that remote calendar (i.e. changes to the remote calendar will
never automatically make it back into your Outlook)
Internet Calendar Subscription
These
calendars are striclty read-only in Outlook, i.e. not very
useful...
Not to leave you out in the rain, we put together a bunch of VBA scripts that teach your Outlook a few new tricks. The scripts and detailed instructions for both MS Outlook 2003 and MS Outlook 2007 are available from http://www.opencrx.org/opencrx/2.4/Outlook_ICS_VCF_adapter.htm
Zimbra (v5.0.14 GA Release) does not offer you much choice with remote ICS calendars. It is possible to subscribe to a remote calendar, but in read-only mode; furthermore, only a minimal set of iCal attributes is actually visible in the Zimbra calendar. Nevertheless, here is how to subscribe:
connect to your Zimbra server and login
click on the tab [Calendar]
click the button [New Calendar] and then
populate the dialog as follows:
|
Please note that the ICS URL in the field URL must also include your openCRX user name and password because Zimbra does not really manage your remote credentials. |
With iPhone OS3.0 you can connect to any remote ICS calendar (read-only) as follows:
on your iPhone home screen, tap the icon Settings
tap on Mail, Contacts, Calendars
tap on Add Account...
tap on Other
tap on Add Subscribed Calendar
enter or paste the ICS URL into the field Server
tap [Next] to verify the account information
|
If you get a message “Cannot Connect Using SSL” tap [No] to move on to the next screen where you can enter the connection details. |
verify/complete your subscription information as follows:
Name |
Value / Description |
|
Server |
verify the ICS URL |
|
Description |
any text you like |
|
Username |
your openCRX user name |
|
Password |
your openCRX password |
|
Use SSL |
if you use SSL, set to [ON], |
|
Remove Alarms |
as you prefer |
tap [Next]
if you use SSL in combination with a self-signed certificate, you will get a message Unable to Verify Certificate --> tap Accept
if everything works out, you can tap Save to store the settings and your calendar will be available in the Calendar App from the iPhone's home screen
The openCRX ICS Adapter does not support deleting events (because deleting objects is typically not an acceptable operation in an enterprise environment). openCRX does support disabling of objects, however. If there is a need to disable events directly from your ICS Client, here is how to do it:
Assuming you have a remote calendar CAL with the URL <U> defined in your ICS client, define a new remote calendar CAL-trash with the URL <U>&disabled=true (i.e. append the string “&disabled=true” to the URL); the name of the calendar is not important, we just call it “CAL-trash” to indicate that it contains disabled activities.
example:
existing calendar CAL
(showing only events that are not disabled) with the
URL
http://127.0.0.1:8080/opencrx-ical-CRX/activities?id=CRX/Standard/userhome/guest&type=ics
the URL of the calendar CAL-trash
showing events that are disabled
is
http://127.0.0.1:8080/opencrx-ical-CRX/activities?id=CRX/Standard/userhome/guest&type=ics&disabled=true
to delete an event of your calendar CAL, move the event from the calendar CAL to the calendar CAL-trash
If you retrieve an iCalender from the openCRX ICS Adapter, the very first event is a so-called Guard Event:
the Guard Event is always the first event delivered by the ICS Adapter
the attribute SUMMARY corresponds to the Calendar-ID
the attribute DTSTART is set to 19000101T000000Z
The openCRX ICS Adapter supports the creation of new events/tasks as long as a calendar's Guard Event is posted to the adapter together with the new event/task. The openCRX ICS Adapter also verifies the UID of the Guard Event.
Many calendar applications differentiate between events (entries in a calendar with well-defined start and end date) and tasks or to-dos (entries in a task list with a well-defined due date). openCRX also supports this distinction. openCRX can even convert activities from VEVENT to VTODO and vice versa without loss of information. To convert an openCRX activity from one type to the other, simply edit the activity and change the iCal type in the respective drop down as shown below:
Figure 53: iCalendar conversion between VEVENT and VTODO
CalDAV is implemented/supported by a growing number of products (see http://caldav.calconnect.org/ or Wikipedia for information about the CalDAV standard). openCRX is a fully-fledged CalDAV server; the functionality is implemented by a native CalDAV servlet. CalDAV clients must authenticate to read and/or write CalDAV data.
CalDAV URL for individual calendar:
http://<crxServer>:<Port>/opencrx-caldav-<Provider>/<Provider>/<Segment>/<Calendar Selector>
Example:
http://localhost:8080/opencrx-caldav-CRX/CRX/Standard/tracker/main
CalDAV URL for CalDAV calendar collection:
http://<crxServer>:<Port>/opencrx-caldav-<Provider>/<Provider>/<Segment>/user/<principal name>/profile/<Calendar Profile>
Example:
http://localhost:8080/opencrx-caldav-CRX/CRX/Standard/user/guest/profile/MyCals
|
See chapter 9.3.2 Calendar Selectors for information on how to construct calendaring URLs. The easiest way to construct CalDAV URLs is to use the openCRX Wizard “Calendar / vCard Connection Helper” from your Homepage. |
|
Please note that calendars without “C” (create) in the table provided in chapter 9.3.2 Calendar Selectors do not support creation of new events/tasks with external CalDAV clients. The reason being that without a well-defined ActivityCreator associated with the respective calendar selector it is not possible to create an activity and assign it to the appropriate activity groups. In the case of calendar collections/profiles, it depends on the feed whether the respective calendar supports activity creation or not. If openCRX can determine a well-defined ActivityCreator, activity creation is supported, otherwise not. |
Some CalDAV clients (e.g. Apple's iPhone) support CalDAV collections. With openCRX you can define CalDAV collections as follows:
navigate to a user's homepage
click on the
tab [Calendar Profiles] and select New
> Calendar Profile:
enter at least a name for your new collection, e.g. MyCals, and then click [Save]
navigate to this new calendar profile and then add the desired feed(s), e.g. an Activity Tracker or an Activity Filter, as follows:
select New > Activity Group
Calendar Feed as shown below:
select an activity group and enter at least a name for this feed
and mark it as active:
click [Save]
optionally, add more feeds (you can also add additional feeds later)
Thunderbird 2.0 with the Lightning add-on (at least version 0.9) is a fully-fledged calendar client and offers virtually the same calendaring functionality as the stand-alone calendar client Sunbird (at least version 0.9). Creating a remote calendar (hosted on your openCRX server) is rather straightforward:
start Thunderbird/Lightning or Sunbird
select the menu File > New Calendar
in the dialog window Create New Calendar you select On the Network
then you select CalDAV
enter a CalDAV URL into the field Location;
example:
the user guest would connect to this openCRX homepage with the URL
http://127.0.0.1:8080/opencrx-caldav-CRX/CRX/Standard/userhome/guest
See chapter 9.3.2 Calendar Selectors for information on CalDAV
URLs
give your calendar a name and pick a color of your choice
that's it – you are connected to openCRX
Outlook does not support CalDAV. There are third-party extensions you might want to try. Some of them are listed at http://wiki.davical.org/w/CalDAV_Clients/Outlook.
See also http://www.opencrx.org/opencrx/2.4/Outlook_ICS_VCF_adapter.htm
With iPhone OS3.0+ you can connect to any openCRX calendar collection as follows:
connect to openCRX navigate to the calendar collection you want to connect your iPhone
start the
wizard Calendar / vCard
Connection Helper:
this wizard
“calculates” the CalDAV URL required to connect:
copy the above URL (you'll need to paste it later)
on your iPhone home screen, tap the icon Settings
|
|
|
If you get a message “Cannot Connect Using SSL” tap [No] to move on to the next screen where you can enter the connection details. |
verify/complete your subscription information as follows:
Name |
Value / Description |
|
Server |
verify the server name |
|
User Name |
your openCRX user name |
|
Password |
your openCRX password |
|
Description |
any text you like |
|
Use SSL |
if you use SSL, set to [ON], |
|
Port |
port number (Tomcat) |
|
Account URL |
the CalDAV URL |
if you use SSL in combination with a self-signed certificate, you will get a message Unable to Verify Certificate --> tap Accept
if everything works out, you can tap Save to store the settings and your calendar will be available in the Calendar App from the iPhone's home screen
|
Unfortunately, iPhone OS3.0+ does not support Tasks over CalDAV, i.e. you will only see openCRX Activities of type VEVENT in your iPhone calendar. |
The CalDAV protocol supports deletion of events/tasks. openCRX honors such requests, although the respective activity is disabled and not deleted. If you absolutely want to delete an activity you can do so with the standard GUI.
Timeline is an extremely interesting DHTML-based AJAX widget for visualizing time-based events. It is like Google Maps for time-based information. A live example is available at http://www.simile-widgets.org/timeline/
Figure 54: Timeline visualizes time-based events
CrxObjects with sets of activities typically feature the wizard Timeline. Simply call that wizard to construct a timeline to visualize activities right in your browser:
Instead of offering platform specific plugins for a multitude of mail clients like MS Outlook, MS Outlook Express, Thunderbird, Evolution, Eudora, Elm, etc. openCRX features a platform neutral IMAP adapter (get more information about IMAP or read what Wikipedia is saying about IMAP). The advantages of such a standardized IMAP adapter are:
works with any IMAP client (including your favorite one)
no clumsy installation of plugins, i.e. you can get this to work on your company's laptop regardless of how “hardened” and locked down the system is
supports single message import and bulk import
imports headers, body, and attachments
automatically creates references to sender and recipient(s) if the respective e mail addresses are present in openCRX
In a nutshell this means that you can use any IMAP client to connect to openCRX and view openCRX EMailActivities. openCRX activity groups are mapped to IMAP folders. The folders contain openCRX EMailActivities.
Viewing/exporting of EmailActivities is always possible, creating/updating of EmailActivities requires that an E-Mail Activity Creator is defined for the respective Activity Group, and deleting of EmailActivities is not supported.
|
If you move an e-mail message from a non-openCRX IMAP folder to an openCRX IMAP folder and the target folder does not have a valid E-Mail Activity Creator defined, openCRX will not be able to create an EMailActivitiy in that folder. Due to the move operation the message is deleted from the source folder and your e mail message is lost. Hence, it is good practice to copy (and not move) e-mails to openCRX IMAP folders. Only after verifying that the EMailActivitiy was actually created by openCRX in the target folder should you delete (if necessary) the message from the source folder. |
|
E-mail addresses should be unique! If you import e-mails into openCRX with the IMAP Adapter, openCRX tries to match sender and recipients based on e-mail addresses. For obvious reasons, this will produce unexpected (if not undesired) results if e-mail addresses in openCRX are not unique. You can test your openCRX database for duplicate e-mail addresses with the following query: SELECT email_address, count(*) |
|
E-mail address UNASSIGNED. If the openCRX IMAP Adapter is not able to link a sender/recipient address to an existing e-mail address in openCRX, the adapter can assign such senders/recipients to an account of your choice. Simply add an e-mail address UNASSIGNED to the desired account as shown below: Figure 55: E-Mail Address UNASSIGNED
In order to detect missing e-mail addresses (and then enter them and reassign the respective e-mail activities) you can simply work through the activities assigned to the account with the above e-mail address. |
The following information is required to connect an IMAP client to openCRX:
Host |
IP address or host name of openCRX
Server |
Port |
1143 (note that the IMAP standard port is 143) |
User name |
<login principal name>@<Segment> |
Password |
principal's openCRX password |
|
The openCRX IMAP adapter does not support SSL, i.e. you should use this feature on secured networks only (Intranet, VPN, ...). |
The openCRX IMAP port is by default set to 1143
(to avoid conflicts with other IMAP daemons listening on the IMAP
standard port 143). You can change this configuration in the file
web.xml
located in the directory
opencrx-core-CRX\opencrx-imap-CRXWEB-INF\
Look for the the param-name port.
If you build your own EARs you can change the openCRX LDAP port in your project's file build.properties (imap.listenPort) or directly in your build.xml.
For increased performance the openCRX IMAP Adapter works with a cache. The location of this cache, the so-called Maildir, can be set as a JAVA_OPTS.
|
You can reset the cache by deleting it. The openCRX IMAP Adapter will recreate the cache automatically. Hence, you might want to delete the cache when restarting Apache Tomcat. |
Add the following line to your JAVA_OPTS in your Tomcat start batch file (e.g. tomcat.bat, run.bat, run.sh, etc.):
Listing 11: Set org.opencrx.maildir for Apache Tomcat
...
set JAVA_OPTS=%JAVA_OPTS%
-Dorg.opencrx.maildir="%CATALINA_HOME%\maildir"
...
The following information is required to configure an IMAP account:
Email account |
<login principal name>@<Segment> |
Password |
openCRX password of the respective principal |
Your name |
<login principal name>@<Segment> |
Email Address |
your e-mail address |
Type of server |
IMAP |
Incoming Server |
name or IP address of your openCRX server |
Port |
1143 |
Incoming User Name |
<login principal name>@<Segment> |
Figure 56: Thunderbird IMAP Configuration
|
If you move an e-mail message from a non-openCRX IMAP folder to an openCRX IMAP folder and the target folder does not have a valid E-Mail Activity Creator defined, openCRX will not be able to create an EMailActivitiy in that folder. Due to the move operation the message is deleted from the source folder in your IMAP client and your e-mail message will be lost. Hence, it is good practice to copy (and not move) e-mails to openCRX IMAP folders. Only after verifying that the EMailActivitiy was actually created by openCRX in the target folder should you delete (if necessary) the message from the source folder. |
The following steps are required to configure MS Outlook 2007 for LDAP:
Email account |
<login principal name>@<Segment> |
Password |
openCRX password of the respective principal |
Your Name |
<login principal name>@<Segment> |
E-mail Address |
your e-mail address |
Account type |
IMAP |
Incoming mail server |
name or IP address of your openCRX server |
Incoming Port |
1143 |
Incoming User Name |
<login principal name>@<Segment> |
Figure 57: MS Outlook IMAP Configuration
|
If you move an e-mail message from a non-openCRX IMAP folder to an openCRX IMAP folder and the target folder does not have a valid E-Mail Activity Creator defined, openCRX will not be able to create an EMailActivitiy in that folder. Due to the move operation the message is deleted from the source folder of your IMAP client and your e-mail message will be lost. Hence, it is good practice to copy (and not move) e-mails to openCRX IMAP folders. Only after verifying that the EMailActivitiy was actually created by openCRX in the target folder should you delete (if necessary) the message from the source folder. |
The openCRX REST servlet allows easy 3rd party integration with openCRX. The full functionality of the openCRX API can be accessed via REST requests, i.e. you can use openCRX as a REST Service.
See http://code.google.com/p/rest-client/ for a REST client.
Sample REST requests are available
from
http://www.opencrx.org/opencrx/2.3/new.htm#REST
You might also want to look at the following Wiki
page:
https://sourceforge.net/apps/trac/opencrx/wiki/Sdk24.Rest
There are many ways of importing data (from other systems into openCRX) and exporting data (from openCRX to other systems). Generally speaking, there is no best way of doing imports/exports because depending on how much weight you put on the pros and cons of the various methods you may come to a different conclusion. Some issues to consider are:
one-time import/export vs. multiple imports/exports
file-based/batched vs. connection-based/real-time
allow manual process steps vs. fully automated
...
In this chapter we will cover some of the basic options you can choose from, but there are obviously other (and sometimes better) options to consider.
|
While it may be tempting to connect to the openCRX database for “quick and dirty” imports/exports, you should really consider using the openCRX API. On the one hand, importers/exporters accessing the database directly are bypassing openCRX security (this is actually more of a warning than a tip...). On the other hand, the openCRX database schema is subject to change (whereas the API is stable). |
The task of importing data is handled by importers. In principle, you can import almost anything into openCRX, it’s really only a matter of writing an appropriate importer.
|
You must ensure that (legal) values are assigned to all mandatory (i.e. non-optional) attributes of openCRX objects created/updated during the import; in particular, all code attributes are mandatory! |
The Open Source distribution of openCRX includes importers for vCard (see Importing vCard Files)and iCalendar files (see Error: Reference source not found) in addition to the XML importer.
You can import virtually any data into openCRX as long as you provide it in the form of schema-compliant XML files. The openCRX schema files can be found in the file opencrx-kernel.jar (unzip and look for xmi subdirectories). Alternatively, you can export example objects as XML files and look at the produced XML files (although the generated XML file also contains all the derived and optional attributes; hence, you will have to prune the generated XML file before you can use it as a template).
Some of the configuration information and data provided with openCRX are also provided in the form of XML files and imported during system setup (e.g. units of measurement are loaded from opencrx-core-CRX\opencrx-core-CRX\WEB-INF\config\data\ Root\101_uoms.xml).
An XML import from a third party system might typically involve the following steps:
Figure 58: XML import from 3rd party system – overview
You can import schema-compliant XML files with the following methods:
Interactive / on-demand
Navigate to your user home and execute the operation File > Import:
Figure 59: Interactive import of XML Files
Click on the button
and navigate to XML file to be imported. Next you click OK to to
start the import. Please note that this method is very suitable for
small XML files and on-the-fly imports. If you are dealing
with larger XML files, however, you should consider the bulk import
described below.
Bulk Import
Use the bulk import for large XML files or if you need to import multiple XML files in an automated fashion. Put your XML file(s) into the following directory (you might have to expand the EAR file to do so):
opencrx-core-CRX\opencrx-core-CRX\WEB-INF\config\data\<SegmentName>
where <SegmentName> can be Root, Standard, or whatever your Segment is named.
Next you login as openCRX Root administrator (admin-Root) and execute the operation View > Reload. Click Yes to start the operation.
Figure 60: Interactive import of XML Files
|
Once the import is started you can close the browser, i.e. there is no need to keep the session alive until the import is completed. Some information regarding the progress of the import is written to the console. |
|
In case you have data dependencies between/among your XML files (e.g. some files contain Contact data while others contain address data which is composite to Contact data) you should make sure that parent data are imported before child data gets imported. This should be relatively easy to achieve as XML files are imported in alphabetical order. |
You can directly import Excel Sheets that contain field names in the first row and then data in the rows 2, 3, .... An example sheet is shown below:
Figure 61: Import Accounts from Excel Sheet – Sample Excel Sheet
The following field attributes are supported:
Field Name |
openCRX Attribute / Description |
DTYPE |
(optionally) provide the type of openCRX account; acceptable values are: CONTACT, LEGALENTITY, GROUP, and UNSPECIFIEDACCOUNT |
TITLE |
Contact.salutationCode |
FIRSTNAME |
Contact.firstName |
MIDDLENAME |
Contact.middleName |
LASTNAME |
Contact.lastName |
ALIASNAME |
Contact.aliasName |
NICKNAME |
Contact.nickName |
SUFFIX |
Contact.suffix |
COMPANY |
depending on the type of imported Account, the value
is mapped to one of the following attributes: |
JOBTITLE |
Contact.jobTitle |
DEPARTMENT |
Contact.department |
BIRTHDAY |
Contact.birthdate
the following formats are recognized: |
HOMEPHONE |
Account.PhoneNumber.fullNumber (with usage = home) |
HOMEPHONE2 |
Account.PhoneNumber.fullNumber (with usage = other) |
HOMEFAX |
Account.PhoneNumber.fullNumber (with usage = fax home) |
HOMEADDRESSLINE |
Account.PostalAddress.postalAddressLine (usage = home) |
HOMESTREET |
Account.PostalAddress.postalStreet (usage = home) |
HOMECITY |
Account.PostalAddress.postalCity (usage = home) |
HOMEPOSTALCODE |
Account.PostalAddress.postalCode (usage = home) |
HOMESTATE |
Account.PostalAddress.postalState (usage = home) |
HOMECOUNTRY or |
Account.PostalAddress.postalCountry (usage = home) |
BUSINESSPHONE |
Account.PhoneNumber.fullNumber (with usage = business) |
BUSINESSPHONE2 |
Account.PhoneNumber.fullNumber (with usage = other) |
BUSINESSFAX |
Account.PhoneNumber.fullNumber (with usage = fax business) |
BUSINESSADDRESSLINE |
Account.PostalAddress.postalAddressLine (usage = business) |
BUSINESSSTREET |
Account.PostalAddress.postalStreet (usage = business) |
BUSINESSCITY |
Account.PostalAddress.postalCity (usage = business) |
BUSINESSPOSTALCODE |
Account.PostalAddress.postalCode (usage = business) |
BUSINESSSTATE |
Account.PostalAddress.postalState (usage = business) |
BUSINESSCOUNTRY or |
Account.PostalAddress.postalCountry (usage = business) |
MOBILEPHONE |
Account.PhoneNumber.fullNumber (usage = mobile) |
EMAILADDRESS |
Account.EMailAddress.emailAddress (usage = business) |
EMAIL2ADDRESS |
Account.EMailAddress.emailAddress (usage = home) |
EMAIL3ADDRESS |
Account.EMailAddress.emailAddress (usage = other) |
WEBPAGE |
Account.WebAddress.webUrl (usage = business) |
ASSISTANTSNAME |
if matching account with full name equal to ASSISTANTSNAME is found, then the matching account is made a member of the imported account; furthermore, ASSISTANTSNAMEROLE is mapped to Member.memberRole |
MANAGERSNAME |
if matching account with full name equal to MANAGERSNAME is found, then the imported account is made a member of the matching account; furthermore, MANAGERSROLE is mapped to Member.memberRole |
NOTES |
Account.description |
CATEGORIES |
Account.category you can provide a semicolon-separated list of categories (e.g. Business;Birthday;Xmas) and the importer will add all missing items to the list of categories contained in Account.category |
|
The field names match up with those produced by MS Outlook if you export Contacts from MS Outlook to an Excel Sheet: |
The Importer produces a detailed on-screen report with clickable links and a summary report stating the total number of created/updated accounts:
Figure 62: Import Accounts from Excel Sheet – Import Report
|
Before you launch an import of thousands of accounts, verify the structure of your Excel sheet with a few lines/accounts only. |
vCard is file format standard for personal data interchange, specifically electronic business cards (additional information is for example available from http://en.wikipedia.org/wiki/VCard).
These are the steps to import a vCard file:
click on the provider Accounts and navigate to an existing Contact (or create a new one)
select the operation File > Import vCard to unhide the import dialog:
Figure 63: Operation vCard Import
select the appropriate language
click the Browse button and navigate to the vCard file you want to import
click the OK button to start the import operation
Please refer to the Chapter 8 E-mail Services, in particular chapter 8.3.1 Import E-mails.
There are various other options to consider. You could for example develop a custom-tailored JSP Wizard to import data on demand or on a regular basis (e.g. controlled by the openCRX WorkflowController).
Sometimes it is more appropriate to develop a specific openCRX client to handle imports, and in a typical enterprise class environment you will probably consider developing adapters to connect/integrate openCRX with 3rd party systems on a real-time basis.
The task of exporting data is handled by exporters. The Open Source distribution of openCRX includes exporters for vCard and iCalendar files in addition to the XML exporter.
This allows you to export contacts and meetings/sales visits or any other object from openCRX. vCard and iCalendar files can be imported by a large variety of other applications, including Microsoft Outlook. This chapter shows how to export data.
Navigate to the object to be exported as XML file and execute the operation File > Export Advanced as shown below:
Figure 64: Exporting SalesOrder as XML File
In order to better control which additional objects (composites, referenced objects, ...) the XLM exporter should export together with the object loaded in the Inspector, you can (optionally) provide a reference filter (optionally with a navigation level). By default, only the current object will be exported. If you provide – for example when exporting a sales order – customer;address as a reference filter, the customer and all referenced addresses will be exported together with the main object. If you export a contact and provide the reference filter member[1] you will get direct members of this contact.
If the export is successful the exporter will terminate with status OK and you will be provided with a link to the file Export.zip containing the raw data:
Figure 65: XML Exporter provides XML data file and code tables as ZIP file
The openCRX ICS Adapter can also export iCalendars in XML format:
ICS URL (to get XML file with authentication):
http://<crxServer>:<Port>/opencrx-ical-<Provider>/activities
?id=<Provider>/<Segment>/<Calendar
Selector>&type=xml
Example:
http://localhost:8080/opencrx-ical-CRX/activities?id=CRX/Standard/tracker/main&type=xml
|
See chapter 9.3.2 Calendar Selectors for information on how to construct calendaring URLs. |
Navigate to the object to be exported as spreadsheet file and execute the operation File > Export Advanced as shown below:
Figure 66: Exporting SalesOrder as Spreadsheet File
In order to better control which additional objects (composites, referenced objects, ...) the XLM exporter should export together with the object loaded in the Inspector, you can (optionally) provide a reference filter. By default, only the current object will be exported. If you provide – for example – :*/:* as a reference filter, all composites up to 2 levels deep will be exported together with the main object (this should be sufficient for most use cases). You can also provide a reference filter to dereference and export referenced objects like the customer or the salesRep of a sales order.
If the export is successful the exporter will terminate with status OK and you will be provided with a link to the file Export.xls containing the raw data:
Figure 67: Exported Spreadsheet File
Based on such spreadsheet files end-users can easily create reports or do some ad-hoc data analysis without the need to know anything about Java or writing JSPs. The standard distribution of openCRX includes various example reports based on this technology.
These are the steps to manually export a contact to a vCard file:
navigate to the contact you want to export
click on the tab Account
select the contents of the field vCard and copy it to an empty text file
save the text file with any name and extension “vcf”, e.g. contact.vcf:
Figure 68: Manually Export Contact as vCard
There is also a wizard vCard.jsp available which allows you to export individual accounts or batches of accounts as vCards.
Navigate to an Account and select File > Save as vCard to start the export:
Figure 69: Export individual Contact as vCard with Wizard
In order to export multiple accounts as vCards, create an Account Filter that selects the desired accounts and then navigate to this Account Filter. Select File > Save Filtered Accounts as vCard:
Figure 70: Export multiple Contact as vCards with Wizard
These are the steps to export an individual activity (e.g. a meeting or a sales visit) to an iCalendar file:
navigate to the meeting (or sales visit) you want to export
click on the tab Details
select the contents of the field iCal and copy it to an empty text file
save the text file with any name and extension “ics”, e.g. meeting.ics:
Figure 71: Exporting Meeting / Sales Visit as iCalendar File
There is also a wizard iCal.jsp available which allows you to export individual activities or batches of activities as iCals.
Navigate to an Activity and select File > Save as iCal to start the export:
Figure 72: Export individual Activity as iCal with Wizard
In order to export multiple activities as iCals, navigate to an Activity Group (Activity Tracker, Category, Milestone), to an Activity Filter (or to any other object that features a list of assigned activities like Userhome, Account) and then select File > Save Filtered Activities as iCal (Save Assigned Activities as iCal).
Please refer to the Chapter 8 E-mail Services, in particular chapter 8.2.2 Export E-mails.
There are various other options to consider. You could for example develop a custom-tailored JSP Wizard to export data on demand or on a regular basis (e.g. controlled by the openCRX WorkflowController).
Sometimes it is more appropriate to develop a specific openCRX client to handle exports, and in a typical enterprise class environment you will probably consider developing adapters to connect/integrate openCRX with 3rd party systems on a real-time basis.
If you have a REST client available, then exporting via REST is also a very viable option.
Please refer to the guides available at http://www.opencrx.org/documents.htm for detailed information regarding UI customization and localization.
The default installation of openCRX activates all locales that are included in the Open Source distribution. The openCRX administrator may wish to deactivate certain locales from the locale list. This chapter shows how you can achieve this.
The locale list is contained in the file
opencrx-core-CRX\opencrx-core-CRX\WEB-INF\web.xml
Look for the section <!-- locales --> to find a list of available locales:
Listing 12: Locales in web.xml
<!-- locales
-->
<init-param>
<param-name>locale[0]</param-name>
<param-value>en_US</param-value>
</init-param>
<init-param>
<param-name>locale[1]</param-name>
<param-value>de_CH</param-value>
</init-param>
<init-param>
<param-name>locale[2]</param-name>
<param-value>es_MX</param-value>
</init-param>
...
You can deactivate locales by simply commenting them out. The following example shows how to deactivate the locale de_CH.
Listing 13: Activating/Deactivating Locales in web.xml
<!-- locales
-->
<init-param>
<param-name>locale[0]</param-name>
<param-value>en_US</param-value>
</init-param>
<!--
<init-param>
<param-name>locale[1]</param-name>
<param-value>de_CH</param-value>
</init-param>
-->
<init-param>
...
|
Please note that you must not deactivate the base locale (that is the locale with the id 0, typically en_US) as the base locale contains a lot of customizing information not present in other locales. |
The default installation of openCRX activates all packages that are included in the Open Source distribution. The openCRX administrator may wish to deactivate certain packages if they are not used. This chapter shows how you can achieve this.
The package list is contained in the file
opencrx-core-CRX\opencrx-core-CRX\WEB-INF\web.xml
Look for the section <!-- Admin --> to find a list of available packages:
Listing 14: Packages in web.xml
<!-- Admin
-->
<init-param>
<param-name>rootObject[0]</param-name>
<param-value>xri:@openmdx:org.opencrx.kernel.admin1/provider/CRX/segment/${SEGMENT}</param-value>
</init-param>
<!--
Home -->
<init-param>
<param-name>rootObject[1]</param-name>
<param-value>xri:@openmdx:org.opencrx.kernel.home1/provider/CRX/segment/${SEGMENT}/userHome/${USER}</param-value>
</init-param>
<!--
Accounts -->
<init-param>
<param-name>rootObject[2]</param-name>
<param-value>xri:@openmdx:org.opencrx.kernel.account1/provider/CRX/segment/${SEGMENT}</param-value>
</init-param>
...
You can deactivate packages by simply commenting them out. The following example shows how to deactivate the package depot1:
Listing 15: Activating/Deactivating Packages in web.xml
...
</init-param>
<!-- Depots -->
<!--
<init-param>
<param-name>rootObject[6]</param-name>
<param-value>xri:@openmdx:org.opencrx.kernel.depot1/provider/CRX/segment/${SEGMENT}</param-value>
</init-param>
-->
<!--
Documents -->
<init-param>
<param-name>rootObject[6]</param-name>
<param-value>xri:@openmdx:org.opencrx.kernel.document1/provider/CRX/segment/${SEGMENT}</param-value>
</init-param>
<!--
Buildings -->
...
|
Please note that you must renumber all the packages listed after the package you deactivated so that the package numbering does not have any gaps (i.e. package numbering starts at 0 and it must be consecutive). |
|
It is also possible to change the order of the active packages by renumbering them. However, you must still ensure both that the numbering starts at 0 and that the numbering is consecutive. |
Individual user can enable/disable root menu entries with the wizard User Settings (available on a user's Homage):
Figure 73: Launch Wizard User Settings
Once the wizard has loaded, uncheck entries you don't need:
Figure 74: Wizard User Settings – enable/disable Root Menu Entries
|
Please note that entries corresponding to packages disabled by the openCRX administrator cannot be enabled with this wizard. Packages disabled in web.xml are not available at all! |
|
Depending on the width of your screen you can adjust the number of items shown as tabs in the top-level navigation in the same wizard (fewer items for narrow screens, more items for wider screens). |
Requires Model Permissions (which are not implemented yet). The same goal can easily be achieved with multiple web applications, however.
Model permissions are not implemented yet.
openCRX is distributed with 2 default layout JSPs located in the directory opencrx-core-CRX\opencrx-core-CRX\WEB-INF\config\layout\en_US:
show-Default.jsp
This layout JSP renders all pages that show information (typically an Inspector containing information about the current object and all the grids containing associated information). This layout JSP is generic (it is provided by openMDX/portal) and it can handle any object.
edit-Default.jsp
Similarly, this layout JSP renders all pages that are used to edit objects.
If you have a need for specialized screens for a particular object in edit and/or show mode, you can write your own layout JSP and deploy it to the above-mentioned directory. The file name of your custom layout JSP determines which objects (or rather: objects of which class) will be handled by your custom layout JSP.
Example:
Let's assume you want to replace the default edit screen for openCRX Contacts (i.e. class org.opencrx.kernel.account1.Contact) with a custom layout JSP. Name your file
edit-org.opencrx.kernel.account1.Contact.jsp
and deploy it to the directory ...\WEB-INF\config\layout\en_US. After restarting Tomcat or your application server your new layout JSP will be active.
|
If you develop localized JSPs you can create new directories for the respective locales and then deploy your localized JSPs there. The fallback algorithms are comparable to those in ui customization. |
openCRX provides various technologies that enable you to easily integrate common office suites like Open Office or Microsoft Office.
openCRX supports the JSP-wizard-based generation of RTF documents. You can generate RTF documents from scratch or merge data with existing RTF templates. The RTF documents are generated on the fly and can be opened with any RTF-compatible word processor including OpenOffice Writer and MS Word.
You can test this feature on our demo server (or on your own installation if you installed the openCRX Server) with the following steps:
connect and login as user guest
navigate to any
contact and execute the operation
Tools > Mail Merge
--> RTF Document
the wizard will provide a list of suitable templates and then generate the RTF document on the fly
Figure 75: RTF Document generated by merging live data with template
If you installed the openCRX SDK you will find the templates and the JSP wizard in the following locations:
<SDK_Install_Dir>\opencrx-2.5.1\core\src\data\org.opencrx\documents
<SDK_Install_Dir>\opencrx-2.5.1\core\src\data\org.opencrx\wizards\en_US\MailMerge.jsp
With this approach it is quite easy to generate all kinds of documents, including letters, invoices, purchase orders, etc.
openCRX supports both a raw spreadsheet export of data and the JSP-wizard-based generation of XLS documents. You can generate XLS documents from scratch or merge data with existing XLS templates. The XLS documents are generated on the fly and can be opened with any XLS-compatible spreadsheet program including OpenOffice Calc and MS Excel.
You can test this feature on our demo server (or on your own installation if you installed the openCRX Server) with the following steps:
connect and login as user guest
navigate to Accounts
execute the
operation Reports > Contacts Report as shown
below
Figure 76: Contacts Export Dialog
the Spreadsheet is generated on the fly and can be downloaded from the openCRX server by clicking on the link provided in the operation result
You might also want to look at the information provided in the chapters
11.3.2 Exporting Data to MS Excel / Open Office Calc Files
14.1 Standard Reports
See chapter 9 Groupware Services.
openCRX provides various technologies that enable you to create reports of a wide variety, anything from simple ad-hoc reports to large scale bulk reports.
Included in the openCRX standard distribution are the following reports:
Account List (available on Account Filters)
Account Member List (available on Groups)
Activity List (available on Activity Groups and Filters)
Activity List with Follow-Ups (available on Activity Groups and Filters)
Contract List (available on Contract Filters)
Contract List with Positions (available on Contract Filters)
You can install these standard reports into any openCRX Segment with the wizard Segment Setup. The reports are based on spreadsheet templates. If you installed the openCRX SDK you will find the templates in the following location:
<SDK_Install_Dir>\opencrx-2.5.1\core\src\data\org.opencrx\documents\
|
The templates contain VBA macros to “beautify” the reports. These macros will probably not work in Open Office Calc... |
You can test – for example – the Report Account List with the following steps:
connect and login as user guest
navigate to Accounts > Account Filters and select All Accounts
select the Menu
File > Export
click the button [OK] to generate Export.xls
open Export.xls with Excel (enable Macros) to get an alphabeticallly sorted list of accounts complete with e-mail address and phone numbers
See chapter 11.3.2 Exporting Data to MS Excel / Open Office Calc Files.
Standard office suite know how (and maybe a bit of macro programming) should get you a long way. Once you're ready to “institutionalize” a report you can prepare a template and an openCRX Export Profile. Consult the templates and the Export Profiles provided by the opeCRX distribution for examples.
If your task is to produce a large number of reports (e.g. monthly reporting for all your clients) or reports based on large amounts of data, spreadsheet-based reporting is probably not the way to go. Maybe you want to generate reports in a format other than XLS. On the one hand, openCRX already includes libraries to generate reports and documents in various formats, on the other hand you can easily add additional libraries to openCRX.
Format |
Library / Additional Information |
XLS |
Apache POI / http://poi.apache.org/ |
|
iText / http://www.lowagie.com/iText/ |
RTF |
Simple RTF Writer / http://www.it-s-easy.com/downloads.htm |
Obviously, there are many more possibilities, like for example exporting data in XML format and then doing some kind of fancy transformation. One such example is available from http://www.koalix.org/
In terms of how to generate your reports, there are also various options available depending on your preferences:
JSP-Based Reporting
This approach
is typically recommended if you need on-demand reporting and the
generation of the report does not put an undue burden on the
server. The following screen shot shows an example HTML-report:
Java Program
Large-scale batch reporting can be done with
a Java Program (basically an openCRX client programmed in Java that
prepares the desired reports).
BI-Reporting Suite
If you plan to
use a BI-Reporting Suite (e.g. Crystal
Reports, Pentaho,
BIRT,
etc.), you should keep in mind that directly accessing the
openCRX database is not a very good idea. We strongly recommend
you either retrieve data through the openCRX API (e.g. with REST)
or set up a dedicated reporting DB (the process to populate such a
reporting DB should retrieve data from the openCRX DB through the
openCRX API). The reason for not accessing the openCRX database
directly is the following one: while the openCRX API is stable, the
OO-to-relational mapping is not and hence the schema of the openCRX
DB is subject to change over time. Hence, if you access the openCRX
DB directly you will have to adapt your reports if the DB schema
changes, a potentially expensive proposition. Furthermore, whenever
you access the openCRX DB directly there is no access control...
The SNMP agent for the Sun JVM can be enabled as described at http://java.sun.com/j2se/1.5.0/docs/guide/management/SNMP.html and http://www.ilikespam.com/blog/monitoring-the-jvm-with-snmp.
Put snmp.acl in TOMCAT_LWC_HOME/bin and give read access to the file for the owner only.
#The communities public and private
are allowed access from the local host.
acl = {
{
communities = public, private
access =
read-only
managers = localhost
}
}
# Traps are sent to localhost only
trap = {
{
trap-community = public
hosts =
localhost
}
}
Add the following options to tomcat.sh -Dcom.sun.management.snmp.port=8161 -Dcom.sun.management.snmp.acl.file=TOMCAT_LWC_HOME/bin/snmp.acl
After startup the variables can be retrieved
with
snmpwalk
-c public -v2c localhost:8161
.1.3.6.1.4.1.42.2.145.3.163.1.1.4.1.
See
http://support.ipmonitor.com/mibs/JVM-MANAGEMENT-MIB/oids.aspx
for a list of all OIDs supported by the JVM.
A simple cron-based monitoring environment can invoke snmpwalk periodically and send mail if a monitored parameter violates a predefined constraint. Use gkrellm with the snmp extension (see http://triq.net/gkrellm_snmp.html) or OpenNMS (see http://www.opennms.org/) for more advanced monitoring solutions.
This approach only works for the Sun JVM. JRockit does not seem to support the options -Dcom.sun.management.snmp.*
You can connect Tomcat w/ openCRX with OpenLDAP as follows:
replace the JDBC Realm entry in the file opencrx-core-CRX\opencrx-core-CRX\META-INF\context.xml with the following entry:
<Realm
className="org.apache.catalina.realm.JNDIRealm"
debug="99"
connectionName="cn=Manager,dc=opencrx,dc=org"
connectionPassword="secret"
connectionURL="ldap://localhost:389"
userPassword="userPassword"
userPattern="cn={0},ou=people,dc=opencrx,dc=org"
roleBase="ou=groups,dc=opencrx,dc=org"
roleName="cn"
roleSearch="(uniqueMember={0})"
/>
Users must be entered into your LDAP server as follows (userPattern):
# Users
dn: cn=guest,ou=people,dc=opencrx,dc=org
objectClass:
organizationalPerson
sn: guest
cn: guest
userPassword:
opencrx
dn:
cn=admin-Root,ou=people,dc=opencrx,dc=org
objectClass:
organizationalPerson
sn: admin-Root
cn:
admin-Root
userPassword: opencrx
dn:
cn=admin-Standard,ou=people,dc=opencrx,dc=org
objectClass:
organizationalPerson
sn: admin-Standard
cn:
admin-Standard
userPassword: opencrx
Groups must be entered into your LDAP server as follows (roleBase, roleName, and roleSearch):
# Groups
dn: ou=groups,dc=opencrx,dc=org
objectClass:
organizationalUnit
ou: groups
dn:
cn=OpenCrxRoot,ou=groups,dc=opencrx,dc=org
objectClass:
groupOfUniqueNames
cn: OpenCrxRoot
uniqueMember:
cn=admin-Root,ou=people,dc=opencrx,dc=org
dn:
cn=OpenCrxAdministrator,ou=groups,dc=opencrx,dc=org
objectClass:
groupOfUniqueNames
cn: OpenCrxAdministrator
uniqueMember:
cn=admin-Standard,ou=people,dc=opencrx,dc=org
dn:
cn=OpenCrxUser,ou=groups,dc=opencrx,dc=org
objectClass:
groupOfUniqueNames
cn: OpenCrxUser
uniqueMember:
cn=guest,ou=people,dc=opencrx,dc=org
You might want to have a look at some of the additional documentation published at http://www.opencrx.org/documents.htm.
License
The contents of this file are
subject to a BSD license (the "License"); you may not use
this file except in compliance with the License. You may obtain a
copy of the License at http://
Copyright 2009 ©
CRIXP Corp. All rights reserved.