![]() |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Version
Table of Contents 1.2 What do you need to understand this book 10 3.1.1 Basic Concepts and Conventions 12 3.1.2 Permissions / Access Control 15 3.1.3 The SQL approach to understanding security 17 3.4 Security Settings of New Objects 20 3.6.1 Apache Tomcat / Application Server Login 22 4.1.1 Create Users as Segment Administrator 25 4.1.2 Import Subjects and Application Login Principals 28 4.2 Disable/Deactivate Users 30 4.2.1 Disable Users at the level Tomcat /Application Server 30 4.2.2 Disable Users at the level openCRX 30 5.1 Typical Deployment Scenarios 31 5.2 Multi Entity Deployment Scenarios 33 5.2.1 Multiple Data Segments in a single DB 33 5.3 openCRX Custom Applications 34 6 Workflow Controller and Servlets 35 6.1 Workflow Controller Configuration 37 6.1.1 Startup Configuration in web.xml 37 6.1.3 Handler pingrate and autostart 38 6.3 Servlet SubscriptionHandler 39 6.4 Servlet DocumentScannerServlet 40 6.5 Servlet WorkflowHandler 41 6.6 Trouble Shooting Servlets 42 7 Subscribe / Notify Services 43 7.1 Example Subscription – Account Modifications 45 7.2 Example Subscription – Activity Assignment Changes 45 7.3 Example Subscription with Filtering 46 7.5 Trouble Shooting Notification Services 47 8.1 Install and Configure Mail Resource and E-Mail Services 49 8.1.1 Installation of JavaMail 49 8.1.2 Mail Resource for openCRX on Apache Tomcat 49 8.1.2.1 Add resource definition(s) to openejb.xml 49 8.1.2.2 Mail Resource in web.xml 51 8.2.1 Outbound E-mail Configuration 53 8.2.2 Outgoing E-mail's FROM value 55 8.2.4 Send E-mails directly from openCRX 56 8.2.5 Send E-mails as Attachments to your Mail Client 57 8.2.6 Send E-mails to Fax-/SMS-Gateways 58 8.3.1 Inbound E-mail with IMAP Adapter 59 8.3.2 Inbound E-mail with Wizard Upload E-Mail 62 8.3.3 Inbound E-mail with MailImporterServlet 63 8.4 Use openCRX as an E-mail Archive/Audit Tool 68 8.5 Trouble Shooting E-mail Services 69 9.1 Directory Service / LDAP 70 9.1.1 Configuring the openCRX LDAP Port 71 9.1.2 Enabling SSL Support for LDAP 71 9.1.3 LDAP Configuration of Thunderbird 72 9.1.4 LDAP Configuration of MS Outlook 73 9.2.1.1 Connecting MS Outlook to the openCRX vcard servlet 75 9.2.1.2 Connecting Thunderbird to the openCRX vcard servlet 75 9.3.1 Calendar as a Set of Activities 76 9.3.2 Calendar Selectors (ICS and CalDAV) 77 9.3.3 Mapping of Activities to Calendar Events and Tasks 80 9.3.3.1 Conversions between VEVENT and VTODO 81 9.3.4 Calendaring / Free Busy 82 9.3.4.1 Free Busy Configuration of Thunderbird/Lightning 82 9.3.4.2 Free Busy Configuration of MS Outlook 84 9.3.4.3 Free Busy Information as an ICS calendar 84 9.3.5 Calendaring / iCalendar (ICS) 85 9.3.5.1 ICS Configuration of Thunderbird/Lightning and Sunbird 86 9.3.5.2 ICS Configuration of MS Outlook 86 9.3.5.3 ICS Configuration of Zimbra 87 9.3.5.4 ICS Configuration of iPhone 87 9.3.5.6 iCalender Guard Event 89 9.3.6.2 CalDAV Configuration of Thunderbird/Lightning and Sunbird 92 9.3.6.3 CalDAV Configuration of MS Outlook 92 9.3.6.4 CalDAV Configuration of iPhone (OS3.0+, iOS4+) 93 9.3.7 Calendaring / Timeline 95 9.4.1 Configuring the openCRX IMAP Port 97 9.4.2 Configuring the IMAP Maildir Cache 98 9.4.2.1 Maildir Configuration with Apache Tomcat 98 9.4.3 Enabling SSL Support for IMAP 98 9.4.4 IMAP Configuration of Thunderbird 99 9.4.5 IMAP Configuration of MS Outlook 100 10 openCRX AirSync Server (ActiveSync compatible) 101 10.1 Configuring the AirSync Directory 101 10.2 Mapping of openCRX Objects to AirSync Objects 102 10.3 A User's AirSync Profile 103 10.3.1 Creation of a User's AirSync Profile 103 10.3.2 Creating/Configuring an AirSync Calendar Feed 104 10.3.3 Creating/Configuring an AirSync Contacts Feed 104 10.3.4 Configuration of AirSync E-Mail 107 10.3.5 AirSync Security – Deleting Data on Devices 107 10.4 Connecting ActiveSync Clients to an AirSync Profile 108 10.4.1 iPhone (iOS 3.0+, iOS4.0+) 108 10.4.1.1 Setting up an Exchange Account on the iPhone 108 10.4.1.2 Setting up Synchronization for Contacts 110 10.4.1.3 Setting up Synchronization for Calendars 112 10.4.1.4 Setting up Synchronization for Mail 113 10.4.2 HTC Desire (Android 2.2 - Froyo) 114 10.4.2.1 Setting up an Exchange Account on the HTC Desire 114 10.4.2.2 Setting up Synchronization 117 11 openCRX AirSync Client (ActiveSync compatible) 119 11.1 AirSync Client Profile 120 11.1.1 Creation of an AirSync Client Profile 120 11.1.2 ActiveSync Provisioning 121 11.1.3 Synchronizing Folders 121 11.1.3.1 Prepare your MS Exchange Account 122 11.1.3.2 Retrieve Synchronizable Folders / Sync Feeds 123 11.1.3.3 Synchronization with MS Exchange Contact Folders 123 11.1.3.4 Synchronization with MS Exchange Calendar Folders 124 11.1.3.5 Synchronization with MS Exchange Task Folders 125 11.1.3.6 Synchronization with MS Exchange E-Mail Folders 126 11.1.4 Synchronizing Items 126 11.1.5 Resync – Clear all items of a feed on server 126 11.1.6 Resync – Replace all items of a feed on server 126 11.1.7 Automating Synchronization 126 12.1.1 Register with Twitter 127 12.1.2 Create Twitter Account 128 12.1.3 Using openCRX Wizards 128 12.1.4 Using the SendDirectMessageWorkflow 128 13 openCRX is a REST Service (Web Service) 129 14.1 Importing Data into openCRX 130 14.2.1 Importing Excel Files ( openCRX Accounts) 133 14.2.2 Importing vCard Files ( openCRX Contacts) 137 14.3 Exporting Data from openCRX 138 14.3.1 Exporting XML Files 138 14.3.2 Exporting Data to MS Excel / Open Office Calc Files 139 14.3.3 Exporting openCRX Contacts ( MS Excel Files) 140 14.3.4 Exporting openCRX Contacts ( vCard Files) 141 14.3.5 Exporting openCRX Meetings ( iCalendar Files) 142 15.2.1 Enabling/Disabling Root Menu Entries 146 16 Integration with Office Application 148 16.1 MS Word, LibreOffice Writer, OpenOffice Writer, etc. 148 16.2 MS Excel, LibreOffice Calc, OpenOffice Calc, etc. 149 16.3 MS Outlook, Thunderbird/Lightning, Sunbird, etc. 149 17.3 Large Scale Reporting 151 18.1 Configuration of AutoCompleter 153 18.2 Extended Service for openCRX/Tomcat Management 154 18.2.1 Multiple Instances of Tomcat 154 18.2.2 IMAPServer: pause / resume 154 18.2.3 WorkflowController: pause / resume 155 18.3 SNMP Monitoring (with Sun JVM) 156 18.4 Tomcat w/ openCRX and LDAP-based Authentication 157
List of Figures Figure 1: Security Realms, Principals and Subjects after Initial Setup 13 Figure 2: Segment Administration 14 Figure 3: Role Drop Down with list of available Segment Login Principals 14 Figure 4: openCRX UML Model – Class Diagram SecureObject 15 Figure 5: System attributes of an openCRX object as shown in the GUI 16 Figure 6: Table OOCKE1_SEGMENT after default installation 19 Figure 7: Table OOCKE1_SEGMENT after modification 19 Figure 8: Result of Check Permissions 21 Figure 9: Role Drop Down with list of available Segment Login Principals 22 Figure 10: New user guest – step 1 25 Figure 11: New user guest – step 2 25 Figure 12: New user guest – step 3 25 Figure 13: New user guest – step 4 26 Figure 14: New user guest – step 4 26 Figure 15: New user guest – step 5 26 Figure 16: New user guest – step 6 27 Figure 17: Operation Actions > Import Login Principals (admin-Root) 28 Figure 18: Operation Actions > Import Users (admin-Standard) 29 Figure 19: Disabling of Segment Login Principal guest by admin-Standard 30 Figure 20: 3-Tier with Apache Tomcat / OpenEJB 31 Figure 21: 4-Tier with multiple Tomcat / OpenEJB instances 31 Figure 22: 3-Tier with J2EE-compliant Application Server 31 Figure 23: 4-Tier with Clustered Application and DB Servers 32 Figure 24: Multiple Data Segments in a single DB 33 Figure 25: Dedicated DB for each Entity 34 Figure 26: Accessing the openCRX Workflow Controller 35 Figure 27: openCRX 2.7.1 Workflow Controller 35 Figure 28: Default Configuration of WorkflowController 36 Figure 29: openCRX Administration – WorkflowController 37 Figure 30: Workflow Controller Configuration – serverURL 38 Figure 31: Workflow Controller Configuration – pingrate and autostart 38 Figure 32: Default Workflow Processes created by WorkflowHandler 41 Figure 33: Event and Notification Service 43 Figure 34: Standard Topics included in the openCRX distribution 44 Figure 35: Create a new Subscription 45 Figure 36: Create a Subscription with Filters 46 Figure 37: Flow of e-mail messages between openCRX, MTA and MUA 48 Figure 38: Create a new E-Mail Account – step 1 53 Figure 39: Create a new E-Mail Account – step 2 53 Figure 40: Create a new E-Mail Account – step 3 54 Figure 41: E-mail subject prefix and Web access URL 54 Figure 42: Send E-Mail from openCRX – Overview 56 Figure 43: Send E-Mail from openCRX with Actions > Follow Up 56 Figure 44: Send E-Mail as Attachment from openCRX – Overview 57 Figure 45: Export E-Mail from openCRX with Actions > Follow Up 57 Figure 46: E-Mail Address UNASSIGNED 60 Figure 47: Import E-Mails from Mail Client 63 Figure 48: Envelope E-Mail with attached E-Mail to be imported 65 Figure 49: Activity Tracker E-Mail is created automatically 66 Figure 50: Activity Creator Default E-mail Creator 67 Figure 51: E-Mail Audit – import all inbound/outbound e-mail messages 68 Figure 52: Thunderbird LDAP Configuration 72 Figure 53: MS Outlook LDAP Configuration 73 Figure 54: openCRX Activity Groups / openCRX Activity Filters 76 Figure 55: An openCRX activity's iCal representation 80 Figure 56: An openCRX activity in the standard GUI 81 Figure 57: iCalendar conversion between VEVENT and VTODO 81 Figure 58: Configuration of Thunderbird's FreeBusy Add-on 83 Figure 59: Inviting Attendees with Thunderbird using free busy information 83 Figure 60: Lightning Inverse Edition – entering Freebusy URL 83 Figure 61: Timeline visualizes time-based events 95 Figure 62: E-Mail Address UNASSIGNED 97 Figure 63: Thunderbird IMAP Configuration 99 Figure 64: MS Outlook IMAP Configuration 100 Figure 65: openCRX AirSync Server – Over The Air (OTA) Synchronization 101 Figure 66: openCRX AirSync Client – backend-sync with Exchange 119 Figure 67: XML import from 3rd party system – overview 131 Figure 68: Interactive import of XML Files 131 Figure 69: Interactive import of XML Files 132 Figure 70: Import Accounts from Excel Sheet – Sample Excel Sheet 133 Figure 71: Import Accounts from Excel Sheet – Import Report 136 Figure 72: Operation vCard Import 137 Figure 73: Exporting SalesOrder as XML File 138 Figure 74: XML Exporter provides XML data file and code tables as ZIP file 138 Figure 75: Exporting SalesOrder as Spreadsheet File 139 Figure 76: Exported Spreadsheet File 140 Figure 77: Manually Export Contact as vCard 141 Figure 78: Export individual Contact as vCard with Wizard 141 Figure 79: Export multiple Contacts as vCards with Wizard 141 Figure 80: Exporting Meeting / Sales Visit as iCalendar File 142 Figure 81: Export individual Activity as iCal with Wizard 142 Figure 82: Launch Wizard User Settings 146 Figure 83: Wizard User Settings – enable/disable Root Menu Entries 146 Figure 84: RTF Document generated by merging live data with template 148 Figure 85: Contacts Export Dialog 149
List of Listings Listing 1: File Format Subjects and Application Login Principals 28 Listing 2: Example File Subjects and Application Login Principals 28 Listing 3: File Format Users 29 Listing 4: Example File Users 29 Listing 5: web.xml – auto startup of the Workflow Controller 37 Listing 6: DocumentScannerServlet – init-param for WorkflowController 40 Listing 7: DocumentScannerServlet – Servlet Declaration 40 Listing 8: DocumentScannerServlet – Mapping 40 Listing 9: Servlets managed by Workflow Controller log to server.log 42 Listing 10: File openejb.xml – mail resource outgoing mail 49 Listing 11: File openejb.xml – mail resource incoming mail POP3 50 Listing 12: File openejb.xml – mail resource incoming mail POP3S 50 Listing 13: File openejb.xml – mail resource incoming mail IMAP 50 Listing 14: File openejb.xml – mail resource incoming mail IMAPS 50 Listing 15: Uncomment mail resource definition (outgoing mail) in web.xml 51 Listing 16: add mail resource definition (incoming mail) in web.xml 51 Listing 17: add path name of MailImporterServlet to web.xml 51 Listing 18: add class name of MailImporterServlet to web.xml 52 Listing 19: add servlet mapping of MailImporterServlet to web.xml 52 Listing 20: Importing certificate into keystore cacerts 52 Listing 21: Debug Output of MailImporterServlet 66 Listing 22: Importing Certificate 69 Listing 23: init-param tags required to enable LDAP SSL 71 Listing 24: init-param tags required to enable IMAP SSL 98 Listing 25: Set org.opencrx.airsyncdir for Apache Tomcat 101 Listing 26: Importing Certificate 121 Listing 27: Locales in web.xml 144 Listing 28: Activating/Deactivating Locales in web.xml 144 Listing 29: Packages in web.xml 145 Listing 30: Activating/Deactivating Packages in web.xml 145
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 servlet container's login procedure is not entirely controlled by openCRX you might have to consult the documentation of your respective servlet container (e.g. Tomcat or JBoss) or ask your 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 (and hence openCRX security)! 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/Sdk27.CustomProject. 6 Workflow Controller and ServletsWith 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 of each segment individually. 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 the tab [Administration] and then clicking on the icon of the WorkflowController: Figure 29: openCRX Administration – WorkflowController In case you create the WorkflowController configuration manually, please note that both name and qualifier are equal to the string 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: 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): 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, E-mail Notifications and Twitter Updates (see chapter 12.1 Twitter) 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 DocumentScannerServletThe DocumentScannerServlet scans a file system directory and its subdirs for files and maps them to openCRX Documents and DocumentFolders. The DocumentScannerServlet is configured in the file web.xml as follows: Listing 6: DocumentScannerServlet – init-param for WorkflowController ... Listing 7: DocumentScannerServlet – Servlet Declaration ... Listing 8: DocumentScannerServlet – Mapping ...
The servlet can be configured as admin-Root by adding entries to the WorkflowControll configuration (see chapter 6.1 Workflow Controller Configuration). The following options are supported:
All options are multi-valued, i.e. can optionally have an index suffix [0]..[9]. All options must be prefixed with {Provider name}.{Segment name}., e.g. CRX.Standard.scanDir or MyProvider.MySegment.urlPrefix. The openCRX administrator can set the pingrate and autostart options; alternatively, you can call it servlet with cron/cUrl.
6.5 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.6 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 9: 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.7.1 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 (MUA) 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 possible flows 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 MUA 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 JavaMailDetailed installation instructions are provided at the JavaMail home: http://java.sun.com/products/javamail/FAQ.html And here is the short version:
8.1.2 Mail Resource for openCRX on Apache Tomcat8.1.2.1 Add resource definition(s) to openejb.xmlOpen the file TOMCAT_HOME\conf\openejb.xml and add (or modify) the mail resource definition. Typically you would add one (smtp) mail resource definition per provider for outgoing mail and one mail resource definition for each segment that requires the MailImporterServlet. Below are some sample files which you can use as a starting point (adapt the highlighted strings to your own environment): Listing 10: File openejb.xml – mail resource outgoing mail ...
Please note that the above mail resource definition for provider “CRX” will apply to all segments (including “Standard”) of that provider.
The following mail resource definitions apply to the segment “Standard” (of the provider “CRX”) and show default configurations for the various mail protocols supported by mail.jar (pop3, pop3s, imap and imaps): Listing 11: File openejb.xml – mail resource incoming mail POP3 ...
Listing 12: File openejb.xml – mail resource incoming mail POP3S ...
Listing 13: File openejb.xml – mail resource incoming mail IMAP ...
Listing 14: File openejb.xml – mail resource incoming mail IMAPS ...
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 to activate outgoing mail: Listing 15: Uncomment mail resource definition (outgoing mail) in web.xml
...
The following steps are only required if you want to activate incoming mail (i.e. MailImporterServlet) for a particular segment (e.g. “Standard”):
Listing 16: add mail resource definition (incoming mail) in web.xml
...
Listing 17: add path name of MailImporterServlet to web.xml
...
Listing 18: add class name of MailImporterServlet to web.xml
...
Listing 19: add servlet mapping of MailImporterServlet to web.xml
... Restart Tomcat for these changes to become active. Please note that additional steps are required to fully configure the MailImporterServlet (see chapter 8.3.3 Inbound E-mail with MailImporterServlet).
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:
8.2.2 Outgoing E-mail's FROM valueThe openCRX Workflow Handler uses the mail.from value in the file openejb.xml (see chapter 8.1.2.1 Add resource definition(s) to openejb.xml). If mail is sent as an openCRX user, the FROM value of outgoing e-mails is determined as follows:
8.2.3 Export E-mailsPlease refer to chapter 9.4 Mailstore / IMAP. 8.2.4 Send E-mails directly from openCRXAny openCRX E-Mail Activity can be sent as e-mail directly from openCRX: Figure 42: Send E-Mail from openCRX – Overview The idea behind this functionality is less that you will use openCRX as a mail client (MUA), 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 43: Send E-Mail from openCRX with Actions > Follow Up
8.2.5 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 (MUA): Figure 44: 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 45: Export E-Mail from openCRX with Actions > Follow Up
8.2.6 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-mailInstead of offering platform-specific plugins for a multitude of mail clients like MS Outlook, MS Outlook Express, Thunderbird, Eudora, Elm, etc. openCRX features a platform-neutral IMAP adapter. The advantages are obvious:
In addition to the IMAP adapter there is also the possibility to import e-mails (previously saved as eml files) with a wizard (see Inbound E-mail with Wizard Upload E-Mail) or with the MailImporterServlet (see Inbound E-mail with MailImporterServlet). 8.3.1 Inbound E-mail with IMAP AdapterThe openCRX IMAP adapter is well-suited to import e-mails from your mail client (MUA) into openCRX. Importing an e-mail into openCRX is as easy as dragging/dropping it on an openCRX IMAP folder in your mail client.
Assuming you have configured your mail client to connect to the openCRX IMAP adapter and subscribed to the relevant folders (openCRX Activity Groups) you can import an e-mail message into openCRX as follows:
The IMAP adapter features some advanced import functionality that helps you import mail messages and automatically link them with new or already existing activities including creation of follow ups. This functionality is quite powerful in the context of e-mail based support and incident management. Let's look at a simple example:
If you import all the e-mails related to this support case you will have the complete history of your exchange with the client available as follow ups in your incident #10009555. If you prefer, the IMAP adapter can even create new activities upon importing e-mails. All you have to do is provide the necessary information in the subject line of wrapper message. You can build a wrapper message by creating a new e-mail message and then adding the e-mail(s) to be imported as attachments; the subject line of the wrapper message is interpreted by the IMAP adapter. If the subject line starts with "> " the message is treated as wrapper message. All attachments are treated as mime messages which are imported instead of the message itself. The subject line of the wrapper message has the following form: > @<email creator name> [#<activity creator name or activity#>] <subject>
Example subject lines: > @E-mails #10009555 log file with exception > @E-mails #GadgetASupport does not boot > @E-mails #10009555 log file with exception > @E-mails #10009555 log file with exception
This allows the user to specify the email creator and an optional activity creator or an activity number. If an activity creator is specified, an activity is created (name = subject, detailed description = body) and the imported email(s) are linked with this activity using linkToAndFollowUp(). If an activity number is specified than the imported email(s) are simply linked with this activity using linkToAndFollowUp().
8.3.2 Inbound E-mail with Wizard Upload E-MailIf you only want to import the occasional e-mail message you can save such messages as eml files and import them with the Wizard Upload E-Mail as follows:
The wizard also supports imports with a wrapper message with the same functionality as the IMAP adapter if you launch it from the tab [Activities] (see chapter 8.3.1 Inbound E-mail with IMAP Adapter). 8.3.3 Inbound E-mail with MailImporterServletThe following figure shows an overview of how you can import e-mails from your mail client (MUA) into openCRX:
Figure 47: Import E-Mails from Mail Client The whole setup is quite straightforward; in a first step you configure the MailImporterServlet so that it fetches e-mails from a mailbox, e.g. named “import”. Optionally, you can create a custom-tailored Activity Creator to handle imported E-mails exactly the way you like, but in most cases the provided Default E-mail Creator is sufficient. To import an e mail message from your mail client into openCRX, you create a new message to be sent to your importer mailbox, e.g. by entering import@company.com into the TO field of the new message. Optionally you can specify the name of the Activity Creator in the Subject of the new message. Next you attach the message(s) to be imported to that new message (yes, you can attach multiple e-mail messages and if those messages contain attachments themselves they will also be imported) and send it off. Once delivered to the appropriate mailbox (called “import” in our example) the MailImporterServlet will fetch it from there and then import the messages attached to that envelope message. This process works for messages in any of your mail client's folders, e.g. Inbox, Outbox, Sent, Trash, etc. See chapters 8.1.2.1 (Add resource definition(s) to openejb.xml) and 8.1.2.2 (Mail Resource in web.xml) for details on activating/configuring the MailImporterServlet the MailImporterServlet. With the following steps you can configure the MailImporterServlet:
Test your settings by sending an e-mail to the account specified in the steps above (import@company.com). Attach the message to be imported to this “envelope” e-mail (please note that the attached e-mail only is imported by the MailImporterServlet): Figure 48: Envelope E-Mail with attached E-Mail to be imported
Once the Workflow Controller triggers the MailImporterServlet you will see the debug output of the servlet on the console (or Tomcat's catalina.log): Listing 21: Debug Output of MailImporterServlet
18:42:57,810 INFO [STDOUT] DEBUG: setDebug: JavaMail version
1.3.3
Figure 49: Activity Tracker E-Mail is created automatically
8.4 Use openCRX as an E-mail Archive/Audit ToolopenCRX can easily keep track of all your e-mail traffic, inbound and/or outbound (and given the increasingly more stringent rules on e-mail retention – Sarbanes-Oxley, etc. – it is probably worthwhile considering the advantages of importing all e-mail messages by default). The following figure shows a configuration where the mail server puts a copy of each received message (inbound traffic) and all sent messages (outbound traffic) into the mailbox audit; configuring such audit accounts can easily be done with most Mail Transport Agents (MTAs) like qmail, postfix, etc. With the appropriate configuration (see Inbound E-mail), the MailImporterServlet can import all messages from that audit mailbox and attach it to an Activity Tracker of your choice: Figure 51: E-Mail Audit – import all inbound/outbound e-mail messages 8.5 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:
For information about over-the-air synchronization of PDAs, mobile phones, etc. with openCRX please refer to chapter 10 openCRX AirSync Server (ActiveSync compatible). 9.1 Directory Service / LDAPopenCRX provides LDAP Server functionality (get more information about LDAP or read what Wikipedia has to say about LDAP). In a nutshell this means that you can use any LDAP client to connect to openCRX and view openCRX accounts. Furthermore, openCRX LDAP service supports SSL. The following information is required to connect to openCRX with an LDAP client:
9.1.1 Configuring the openCRX LDAP PortThe 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 web.xml
located in Look for the param-name 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.
9.1.2 Enabling SSL Support for LDAPWith the following steps you can enable SSL support for LDAP:
Listing 23: init-param tags required to enable LDAP SSL
...
9.1.3 LDAP Configuration of ThunderbirdThe following steps are required to configure Thunderbird 3 for LDAP:
9.1.4 LDAP Configuration of MS OutlookThe following steps are required to configure MS Outlook 2007 for LDAP:
Figure 53: MS Outlook LDAP Configuration
9.2 openCRX vcard ServletThe 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. 9.2.1 Account SelectorsopenCRX 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):
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
9.2.1.1 Connecting MS Outlook to the openCRX vcard servletDetailed instructions on how to connect MS Outlook are available from http://www.opencrx.org/opencrx/2.4/Outlook_ICS_VCF_adapter.htm
9.2.1.2 Connecting Thunderbird to the openCRX vcard servletA Thunderbird add-on (supporting both TB2 and TB3) is available that enables you to map Thunderbird address books to openCRX account selectors: 9.3 Calendaring9.3.1 Calendar as a Set of ActivitiesopenCRX supports a wide range of types of activities, including E-Mails, Tasks, Meetings, Phone Calls, etc. Even though all activities are kept in a flat structure (think of a box containing activities), openCRX offers a multitude of ways to structure, filter, and group activities:
To fully understand the power of this approach, consider a large project X (e.g. building a power plant) with millions and 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 a milestone of 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 54: 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. 9.3.2 Calendar Selectors (ICS and CalDAV)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):
CalDAV calendar selectors look as follows (R=read, U=update, C=create):
The wizard can also build URLs for CalDAV calendar collections (iPhone, etc.):
Example: http://demo.opencrx.org/opencrx-caldav-CRX/CRX/Standard/user/guest/profile/MyCals
9.3.3 Mapping of Activities to Calendar Events and TasksBoth the openCRX ical servlet and the openCRX caldav servlet map openCRX activities to calendar events (VEVENT) and tasks (VTODO) as follows based on the openCRX activity class and the iCal type at hand:
Hence, all openCRX activities correspond to either calendar events (VEVENT) or tasks (VTODO). An openCRX activitiy's iCal representation is stored in the iCal attribute:
Figure 55: An openCRX activity's iCal representation In the openCRX standard GUI the same activity is presented as follows:
Figure 56: An openCRX activity in the standard GUI 9.3.3.1 Conversions between VEVENT and VTODOMany 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 and 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, edit the activity and change the value of the iCal type dropdown:
Figure 57: iCalendar conversion between VEVENT and VTODO
9.3.4 Calendaring / Free BusyFree 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 Example:
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).
openCRX calculates/derives the free busy information for each activity on the fly based on the following algorithm: If the requesting user has at least one resource assignment with workingUnitPercentage > 0 then TRANSP=OPAQUE, otherwise TRANSP=TRANSPARENT. TRANSP is managed by the CalDAV, ICS and FREEBUSY servlets. The attribute TRANSP TRANSP is mapped to the activity's assigned resources. 9.3.4.1 Free Busy Configuration of Thunderbird/LightningThunderbird 3.x supports free busy if the following add-ons are installed: For detailed information on how to configure Thunderbird's Free/Busy add-on, please refer to the information provided by the respective developer. With version 1.3 of this add-on one can specify a pattern for both e-mail addresses and URLs to retrieve the free busy data from: Example:
Figure 58: Configuration of Thunderbird's FreeBusy Add-on Once the Free/Busy add-on is configured, it will retrieve free busy information directly from your openCRX server whenever you invite attendees:
Figure 59: Inviting Attendees with Thunderbird using free busy information Apparently, the add-on Mozilla Lightning – Inverse Edition also supports scheduling of meetings with free busy information. Once installed, Contact Cards of the Thunderbird Address Book will feature a tab CalDAV. This is where you can enter the URL (specific for each contact in the address book): Figure 60: Lightning Inverse Edition – entering Freebusy URL Unfortunately, it is not possible to automatically populate the Freebusy URL and the add-on does not support a generic pattern-based approach. 9.3.4.2 Free Busy Configuration of MS OutlookSee http://support.microsoft.com/kb/291621. Please note that Outlook does not support SSL with free busy.
9.3.4.3 Free Busy Information as an ICS calendarIt is also possible to view the free busy information in the form of an ICS calendar. This may be useful for users who frequently plan events on behalf of another user without access to the full calendar of that person. Given a free busy URL you simply add &type=ics to retrieve the respective ICS calendar: Free Busy URL as an ICS calendar: http://<crxServer>:<Port>/opencrx-ical-<Provider>/freebusy Example:
The free busy ICS calendar is read-only and the title of events is set to ***, description and location are not available for privacy reasons.
9.3.5 Calendaring / iCalendar (ICS)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 Example:
While the mapping of most of openCRX's activity attributes to iCal attributes is obvious, the following hints might still be helpful: VEVENT:
VTODO:
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). 9.3.5.1 ICS Configuration of Thunderbird/Lightning and SunbirdThunderbird 3.0 with the Lightning add-on (or Sunbird, the stand-alone client) is a fully-fledged calendar client. Creating a remote calendar (hosted on your openCRX server) is rather straightforward:
Version 1.0 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. 9.3.5.2 ICS Configuration of MS OutlookOut of the box Redmond's flagship MS Outlook does not offer you much choice with ICS calendars. You are stuck with one of the following 2 options:
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 9.3.5.3 ICS Configuration of ZimbraZimbra (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:
9.3.5.4 ICS Configuration of iPhoneWith iPhone OS3.0 and iOS4 you can connect to any remote ICS calendar (read-only) as follows:
9.3.5.5 Deleting EventsThe 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:
9.3.5.6 iCalender Guard EventIf you retrieve an iCalender from the openCRX ICS Adapter, the very first event is a so-called Guard Event:
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.
9.3.6 Calendaring / CalDAVCalDAV 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:
CalDAV URL for CalDAV calendar collection: http://<crxServer>:<Port>/opencrx-caldav-<Provider>/<Provider>/ <Segment>/user/<principal name>/profile/<Calendar Profile> Example:
9.3.6.1 CalDAV CollectionsSome CalDAV clients (e.g. Apple's iPhone) support CalDAV collections. With openCRX you can define CalDAV collections as follows:
9.3.6.2 CalDAV Configuration of Thunderbird/Lightning and SunbirdThunderbird 3.x with the Lightning add-on (at least version 1.x) is a fully-fledged calendar client and offers virtually the same calendaring functionality as the stand-alone calendar client Sunbird (at least version 1.x). Creating a remote calendar (hosted on your openCRX server) is rather straightforward:
9.3.6.3 CalDAV Configuration of MS OutlookMS 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
9.3.6.4 CalDAV Configuration of iPhone (OS3.0+, iOS4+)Connect to any openCRX calendar collection as follows with your iPhone:
9.3.6.5 Deleting EventsThe 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 openCRX standard GUI. 9.3.7 Calendaring / TimelineTimeline 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 61: Timeline visualizes time-based events CrxObjects with sets of activities (e.g. Userhome, Activity Groups, Activity Filters, etc.) typically feature the wizard Timeline. Simply call that wizard to construct a timeline to visualize activities right in your browser:
9.4 Mailstore / IMAPInstead 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:
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. Please refer to chapter 8.3.1 Inbound E-mail with IMAP Adapter for details.
The following information is required to connect an IMAP client to openCRX:
9.4.1 Configuring the openCRX IMAP PortThe 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 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. 9.4.2 Configuring the IMAP Maildir CacheFor 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.
9.4.2.1 Maildir Configuration with Apache TomcatAdd the option -Dorg.opencrx.maildir="%CATALINA_HOME%\maildir" to the JAVA_OPTS in your Tomcat start batch file (e.g. tomcat.bat, run.sh, etc.). 9.4.3 Enabling SSL Support for IMAPWith the following steps you can enable SSL support for IMAP:
Listing 24: init-param tags required to enable IMAP SSL
...
9.4.4 IMAP Configuration of ThunderbirdThe following information is required to configure an IMAP account:
Figure 63: Thunderbird IMAP Configuration
9.4.5 IMAP Configuration of MS OutlookThe following steps are required to configure MS Outlook 2007 for LDAP:
Figure 64: MS Outlook IMAP Configuration 10 openCRX AirSync Server (ActiveSync compatible)openCRX AirSync allows you to connect your ActiveSync-enabled PDAs and mobile phones (e.g. Apple's iPhone, Android-based devices, RIM's BlackBerry, Windows Mobile devices, etc.) with openCRX to synchronize e-mails, contacts, events and tasks, including push functionality:
Figure 65: openCRX AirSync Server – Over The Air (OTA) Synchronization
10.1 Configuring the AirSync DirectoryThe openCRX AirSync Adapter stores information about the “Folders to be monitored” in a directory on the server (one .ser file per ActiveSync client). The location of this AirSync directory can be set as a JAVA_OPTS (e.g. in a batch file like tomcat.bat, run.bat, run.sh, etc.): Listing 25: Set org.opencrx.airsyncdir for Apache Tomcat
...
10.2 Mapping of openCRX Objects to AirSync ObjectsThe openCRX AirSync servlet maps openCRX objects to ActiveSync objects (Contacts, Events, Tasks, Mails) as follows based on the openCRX object class and additional information at hand:
10.3 A User's AirSync Profile10.3.1 Creation of a User's AirSync ProfileopenCRX users can create a personal AirSync profile as follows:
10.3.2 Creating/Configuring an AirSync Calendar FeedopenCRX users have a private Activity Tracker <username>~Private (e.g. guest~Private for the user named guest) and several private Activity Creators:
Activities created with one of the above Activity Creators are automatically assigned to the respective user's Activity Tracker <username>~Private and security is set such that only the respective user can read/write such activities. If you only need one private “calendar” to manage your activities, the wizard User Settings does all the work for you, i.e. there is nothing more to configure. You can, however, add more calendar feeds (activity group calendar feeds or activity filter calendar feeds) to your AirSync profile just as you would add calendar feeds to a calendar profile (see chapter 9.3.6.1 CalDAV Collections). 10.3.3 Creating/Configuring an AirSync Contacts FeedopenCRX users have a private Account Group called <username>~Private (e.g. guest~Private for the user named guest). Any openCRX Account that is a referenced by a member of this Account Group is synchronized through your AirSync Contacts Feed. Think of a Contacts Feed as an Address Book. The private Account Group created by the wizard “User Settings” is empty initially, i.e. there are no members defined. You can add members to your private Account Group as follows:
10.3.4 Configuration of AirSync E-MailopenCRX users have a private Activity Tracker called <username>~Private (e.g. guest~Private for the user named guest). E-Mail Activities assigned to this Activity Tracker will be synchronized with a corresponding E-Mail folder <username> – Mails (e.g. guest – Mails) in your ActiveSync client. Furthermore, all the alerts on your homepage are mapped to E-Mails that are also synchronized with an E-Mail folder named <username> – Alerts (e.g. guest – Alerts):
10.3.5 AirSync Security – Deleting Data on DevicesSome devices (like the iPhone, for example) feature built-in security (e.g. deletion of data if the pin or access codes is not entered correctly) and it is also possible to force deletion of data on the device as soon as the device synchronizes with openCRX. All you have to do is to deactivate all the Sync Feeds of the respective device-specific AirSync Profile (see the tip at the end of chapter 10.3.1 Creation of a User's AirSync Profile for details on how to create a device-specific profile).
10.4 Connecting ActiveSync Clients to an AirSync ProfileIn principle, any ActiveSync client should be able to connect to an openCRX AirSync Profile. The following clients have been tested and confirmed to work:
10.4.1 iPhone (iOS 3.0+, iOS4.0+)Here are the steps to configure your iPhone to connect to an openCRX AirSync Profile:
10.4.1.1 Setting up an Exchange Account on the iPhone
10.4.1.2 Setting up Synchronization for Contacts
10.4.1.3 Setting up Synchronization for Calendars
10.4.1.4 Setting up Synchronization for Mail
10.4.2 HTC Desire (Android 2.2 - Froyo)Here are the steps to configure your HTC Desire to connect to an openCRX AirSync Profile:
10.4.2.1 Setting up an Exchange Account on the HTC Desire
10.4.2.2 Setting up Synchronization
11 openCRX AirSync Client (ActiveSync compatible)The openCRX AirSync Client enables backend-synchronization of contacts and calendars between openCRX and MS Exchange. Thus, MS Outlook and PDAs connecting to MS Exchange get easy access to contacts and calendars that are managed in openCRX, without the need to install any additional software or changing the configuration:
Figure 66: openCRX AirSync Client – backend-sync with Exchange
11.1 AirSync Client ProfileEach MS Exchange account that should be synchronized with openCRX requires an AirSync Client Profile. 11.1.1 Creation of an AirSync Client ProfileopenCRX users can create an AirSync Client profile as follows:
11.1.2 ActiveSync ProvisioningActiveySync Provisioning (see
http://msdn.microsoft.com/en-us/library/dd299443(v=EXCHG.80).aspx)
specifies an XML-based format to communicate security policy
settings to client devices (in this case openCRX, acting as an
ActiveySync client). Depending on the settings/configuration of your
account on the MS Exchange server you might have to run the
provisioning wizard to enable synchronization. You can fetch the
provisioning information from the MS Exchange server by navigating
to your AirSync Client Profile and running the wizard AirSync
– Provision:
11.1.3 Synchronizing FoldersYou can retrieve a list of all the synchronizable folders, converted to openCRX Sync Feeds, from the MS Exchange Server by navigating to your AirSync Client Profile and running the wizard AirSync – Synchronize Folders. Sync Feeds created by this wizard are initially set to inactive and the reference to Account group (for Contact Feeds), Activity group (for Activity Group Feeds) or Activity filter (for Activity Filter Feeds) respectively are not set. You will find such feeds in the tab [All Sync Feeds]. 11.1.3.1 Prepare your MS Exchange AccountIn principle you can synchronize any Exchange folder with openCRX. It might make sense, however, to create a set of special folders, i.e. prepare your Exchange account as follows (use your own openCRX username instead of guest):
11.1.3.2 Retrieve Synchronizable Folders / Sync FeedsNow that your Exchange account is prepared you can navigate to your AirSync Client Profile and run the wizard AirSync – Synchronize Folders to retrieve the Sync Feeds:
In the tab [All Sync Feeds] you should now see various Sync Feeds including the following ones corresponding to the folders you created with MS Outlook:
11.1.3.3 Synchronization with MS Exchange Contact FoldersIn order to configure synchronization between an MS Exchange contact folder and an openCRX Account Group (see also 10.2 Mapping of openCRX Objects to AirSync Objects) follow these steps:
With the next execution of the wizard Synchronizing Items the synchronization will be initiated. 11.1.3.4 Synchronization with MS Exchange Calendar FoldersIn order to configure synchronization between an MS Exchange calendar folder and an openCRX Activity Group (see also 10.2 Mapping of openCRX Objects to AirSync Objects) follow these steps:
In case you want to synchronize with an openCRX Activity Filter instead of an openCRX Activity Group, follow these steps:
With the next execution of the wizard Synchronizing Items the synchronization will be initiated.
11.1.3.5 Synchronization with MS Exchange Task FoldersIn order to configure synchronization between an MS Exchange task folder folder and an openCRX Activity Group or an openCRX Activity Filter (see also 10.2 Mapping of openCRX Objects to AirSync Objects) follow these steps:
In case you want to synchronize with an openCRX Activity Filter instead of an openCRX Activity Group, follow these steps:
With the next execution of the wizard Synchronizing Items the synchronization will be initiated.
11.1.3.6 Synchronization with MS Exchange E-Mail FoldersMS Exchange servers do not support pushing e-Mails from an ActiveSync client to a folder on the MS Exchange server (which is one of the reasons why you cannot store draft e-mails written on your iPhone to the MS Exchange server, for example). The only way to transfer e-mails from an ActiveSync client to an MS Exchange server is by actually sending the e-mail (which is not exactly what you want in order to synchronize). On an experimental basis the import of e-mails from MS Exchange into openCRX using AirSync is implemented, but we actually recommend the use of the openCRX IMAP Adapter (see 9.4 Mailstore / IMAP for more information). 11.1.4 Synchronizing ItemsThe wizard AirSync – Synchronize Items synchronizes active Sync Feeds. Please note that per sync call up to 50 items are synchronized per feed, i.e. you might have to call this wizard multiple times for a full synchronization if there are a lot of changes. 11.1.5 Resync – Clear all items of a feed on serverIncreasing the value of a feed's Generation by 1 leads to the removal of all items of that feed on the MS Exchange server. The wizard Resync – Clear all items on the server automates this task. 11.1.6 Resync – Replace all items of a feed on serverIncreasing the value of a feed's Generation by 1 and setting the value of a feed's SyncKey.Client to 0 leads to the replacement of all items of that feed on the MS Exchange server followed by the removal of items on the MS Exchange server that are no longer included in the feed. The wizard Resync – Replace all items on the server automates this task. 11.1.7 Automating SynchronizationOne way of automating synchronization is by setting up a cron job and have curl call the wizard WizardInvoker.jsp with the appropriate parameters, e.g. curl
"http://localhost:8080/opencrx-core-CRX/WizardInvoker.jsp 12 Social Media12.1 TwitteropenCRX features to support/connect to Twitter:
12.1.1 Register with Twitter
If registration is successful you should get a 'Consumer Key' and a 'Consumer Secret' for your application.
12.1.2 Create Twitter Account
12.1.3 Using openCRX WizardsOn most objects the following two wizards are available:
12.1.4 Using the SendDirectMessageWorkflowThe SendDirectMessageWorkflow works much the same way as the SendMailNotificationWorkflow. However, instead of sending an e-mail to the user in case of alert updates, the alert title including a tiny url pointing to the underlying openCRX object is sent as direct message to the default Twitter account of the subscribing user. The SegmentSetupWizard (can be executed by the segment administrator, e.g. admin-Standard) creates the required entries for the workflow and topic. Users simply need to subscribe to the topic Alert Modifications (Twitter). 13 openCRX is a REST Service (Web Service)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
You might also want to look at the following Wiki
page: 14 Data Import/ExportThere 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:
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.
14.1 Importing Data into openCRXThe 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.
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. 14.2 Importing XML FilesYou 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 67: XML import from 3rd party system – overview You can import schema-compliant XML files with the following methods:
14.2.1 Importing Excel Files ( openCRX Accounts)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 70: Import Accounts from Excel Sheet – Sample Excel Sheet The following field attributes are supported by the importer wizard:
The Importer produces a detailed on-screen report with clickable links and a summary report stating the total number of created/updated accounts: Figure 71: Import Accounts from Excel Sheet – Import Report
14.2.2 Importing vCard Files ( openCRX Contacts)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:
Figure 72: Operation vCard Import
14.2.3 Importing E-MailsPlease refer to the Chapter 8 E-mail Services, in particular chapter Error: Reference source not found Error: Reference source not found. 14.2.4 Other OptionsThere 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. 14.3 Exporting Data from openCRXThe 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.
14.3.1 Exporting XML FilesNavigate to the object to be exported as XML file and execute the operation File > Export Advanced as shown below: Figure 73: 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 74: 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 Example:
14.3.2 Exporting Data to MS Excel / Open Office Calc FilesNavigate to the object to be exported as spreadsheet file and execute the operation File > Export Advanced as shown below: Figure 75: 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 76: 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. 14.3.3 Exporting openCRX Contacts ( MS Excel Files)These are the steps to manually export group of contacts to an Excel file:
14.3.4 Exporting openCRX Contacts ( vCard Files)These are the steps to manually export a contact to a vCard file:
Figure 77: 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 78: 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 79: Export multiple Contacts as vCards with Wizard 14.3.5 Exporting openCRX Meetings ( iCalendar Files)These are the steps to export an individual activity (e.g. a meeting or a sales visit) to an iCalendar file:
Figure 80: 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 81: 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). 14.3.6 Exporting E-MailsPlease refer to the Chapter 8 E-mail Services, in particular chapter 8.2.3 Export E-mails. 14.3.7 Other OptionsThere 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. 15 Customizing openCRXPlease refer to the guides available at http://www.opencrx.org/documents.htm for detailed information regarding UI customization and localization. 15.1 Managing LocalesThe 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 27: Locales in web.xml <!-- locales
-->
You can deactivate locales by simply commenting them out. The following example shows how to deactivate the locale de_CH. Listing 28: Activating/Deactivating Locales in web.xml <!-- locales
-->
15.2 Managing PackagesThe 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 29: Packages in web.xml <!-- Admin
-->
You can deactivate packages by simply commenting them out. The following example shows how to deactivate the package depot1: Listing 30: Activating/Deactivating Packages in web.xml
...
15.2.1 Enabling/Disabling Root Menu EntriesIndividual user can enable/disable root menu entries with the wizard User Settings (available on a user's Homage): Figure 82: Launch Wizard User Settings Once the wizard has loaded, uncheck entries you don't need: Figure 83: Wizard User Settings – enable/disable Root Menu Entries
15.3 Role-based UIRequires Model Permissions (which are not implemented yet). The same goal can easily be achieved with multiple web applications, however. 15.3.1 Model PermissionsModel permissions are not implemented yet. 15.3.2 Custom Layout JSPsopenCRX is distributed with 2 default layout JSPs located in the directory opencrx-core-CRX\opencrx-core-CRX\WEB-INF\config\layout\en_US:
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.
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.
16 Integration with Office ApplicationopenCRX provides various technologies that enable you to easily integrate common office suites like Open Office or Microsoft Office. 16.1 MS Word, LibreOffice Writer, OpenOffice Writer, etc.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:
Figure 84: 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:
With this approach it is quite easy to generate all kinds of documents, including letters, invoices, purchase orders, etc. 16.2 MS Excel, LibreOffice Calc, OpenOffice Calc, 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:
Figure 85: Contacts Export Dialog
You might also want to look at the information provided in the chapters
16.3 MS Outlook, Thunderbird/Lightning, Sunbird, etc.See chapters 9 Groupware Services and 10 openCRX AirSync Server (ActiveSync compatible) for more information. 17 ReportingopenCRX provides various technologies that enable you to create reports of a wide variety, anything from simple ad-hoc reports to large scale bulk reports. 17.1 Standard ReportsIncluded in the openCRX standard distribution are the following reports:
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\
You can test – for example – the Report Account List with the following steps:
17.2 Ad-hoc ReportingSee chapter 14.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. 17.3 Large Scale ReportingIf 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.
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:
18 Miscellaneous Topics18.1 Configuration of AutoCompleterThe AutoCompleter works by default with objects in the current segment. To determine the so called 'lookup object' it also considers the 'root objects' configured in web.xml. By default, web.xml has two configured UOM segments:
If there are multiple root objects of the same type, the AutoCompleter takes the first (see org.openmdx.portal.servlet.DefaultPortalExtension.getLookupObject() for details). Hence, if you want to give the root UOMs priority you can switch the orders of the UOM XRIs in the web.xml. If you want to have some more sophisticated logic you can override the method getLookupObject() or getAutoCompleter(). 18.2 Extended Service for openCRX/Tomcat Management18.2.1 Multiple Instances of TomcatExtended Service is a Tomcat extension which allows to start multiple Tomcat instances with the same configuration and allows to stop / start the connectors of these instances individually. The class org.openmdx.catalina.core.ExtendedService allows to handle the requested scenario. Adapt the server.xml as follows: ...
The system properties are set per Tomcat instance, e.g. Instance A:
Instance B:
* Start instance A. The connectors are started. * Start instance B. The connectors can not be started because of port conflicts. Switch from instance A to B as follows: * telnet localhost 8006 and enter command stopConnectors * telnet localhost 8106 and enter command startConnectors If the property org.openmdx.catalina.core.ExtendedService.autostartConnectors is unset or the property is set to true then the connectors will be started at startup of Tomcat. Otherwise the connectors are not started. 18.2.2 IMAPServer: pause / resumeThe IMAPServlet (opencrx-imap-CRX/IMAPServlet) provides a GUI which allows to pause and resume the IMAPServer. The Wizard IMAPServer.jsp available as admin-Root redirects to the IMAPServlet. The IMAPServlet accepts the system property org.openmdx.catalina.core.ExtendedService.autostartConnectors. If unset or set to true, the IMAPServer is started at startup. If set to false, then the IMAPServer has to be started manually. 18.2.3 WorkflowController: pause / resumeThe WorkflowControllerServlet accepts the new commands pause and resume. Pause stops pinging the controlled WorkflowServlets. The new commands are available via the GUI. The WorkflowControllerServlet accepts the system property org.openmdx.catalina.core.ExtendedService.autostartConnectors. If it is unset or set to true the WorkflowController is activated on startup. If set to false the WorkflowController has to be started/resumed manually. 18.3 SNMP Monitoring (with Sun JVM)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.
#The communities public and private are allowed access from the local host.
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. This approach only works for the Sun JVM. 18.4 Tomcat w/ openCRX and LDAP-based AuthenticationYou can connect Tomcat w/ openCRX with OpenLDAP as follows:
<Realm
# Users
# Groups
18.5 OpenEJB / Reestablishing dropped DB ConnectionAdd the 3 highlighted lines (TimeBetweenEvictionRunsMillis, ValidationQuery, TestWhileIdle) to the datasource definition in the file openejb.xml so that dropped database connections are reestablished automatically:
<?xml version="1.0"
encoding="UTF-8"?> More information is available from http://openejb.apache.org/3.0/containers-and-resources.html. 19 Next StepsYou 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 2010 ©
CRIXP Corp. All rights reserved. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() | ![]() |