![]() |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Version
Table of Contents 1.2 What do you need to understand this book 7 3.1.1 Basic Concepts and Conventions 9 3.1.2 Permissions / Access Control 12 3.4 Security Settings of New Objects 16 3.5.1 Application Server Login 17 4.1.1 Create Users Manually 20 4.1.2 Import Subjects and Application Login Principals 21 4.2 Disable/Deactivate Users 23 4.2.1 Disabling Users at the level Application Server 23 4.2.2 Disabling Users at the level openCRX 23 5.1 Typical Deployment Scenarios 24 5.2 Multi Entity Deployment Scenarios 25 5.2.1 Multiple Data Segments in a single DB 25 5.2.3 Multiple Applications 26 5.3 openCRX Custom Applications 26 6.1 Workflow Controller Configuration 29 6.1.1 Startup Configuration in web.xml 29 6.1.3 Handler pingrate and autostart 30 6.2 Servlet SubscriptionHandler 31 6.3 Servlet WorkflowHandler 32 6.5 Trouble Shooting Servlets 34 7 Subscribe / Notify Services 35 7.1 Example Subscription – Activity Modifications 37 7.2 Example Subscription with Filtering 39 7.3 Trouble Shooting Notification Services 40 8.1 Import E-mails from a Mail Client into openCRX 42 8.2 Use openCRX as an E-mail Archive/Audit Tool 43 8.3 Send E-mail directly from openCRX 44 8.4 Export E-mails from openCRX to your Mail Client 45 8.5 Install and Configure Mail Resource and E-Mail Services 47 8.5.1 Installation of JavaMail and JAF 47 8.5.2 Create mail-service.xml 47 8.5.3 Mail Resource in web.xml and jboss-web.xml 49 8.5.6 Trouble Shooting E-mail Services 57 9.1 Importing Data into openCRX 59 9.2.1 Importing vCard Files ( openCRX Contacts) 62 9.2.2 Importing iCalendar Files ( openCRX Meetings) 62 9.3 Exporting Data from openCRX 63 9.3.2 Exporting openCRX Contacts ( vCard Files) 64 9.3.3 Exporting openCRX Contacts ( Outlook Contacts) 65 9.3.4 Exporting openCRX Meetings ( iCalendar Files) 66 10.3.2 Multiple Applications 69
List of Figures Figure 1: Security Realms, Principals and Subjects after Initial Setup 10 Figure 2: Segment Administration 11 Figure 3: Role Drop Down with list of available Segment Login Principals 11 Figure 4: openCRX UML Model – Class Diagram SecureObject 12 Figure 5: System attributes of an openCRX object as shown in the GUI 13 Figure 6: Table kernel_Segment after default installation (QuickStart) 15 Figure 7: Table kernel_Segment after modification 15 Figure 8: Role Drop Down with list of available Segment Login Principals 17 Figure 9: Operation Actions > Import Login Principals (admin-Root) 21 Figure 10: Operation Actions > Import Users (admin-Standard) 22 Figure 11: Disabling of Segment Login Principal guest by admin-Standard 23 Figure 12: 3-Tier with Application Server 24 Figure 13: 4-Tier with Application Server 24 Figure 14: 4-Tier with Clustered Application Servers 24 Figure 15: 4-Tier with Servlet Engine 24 Figure 16: Multiple Data Segments in a single DB 25 Figure 17: Dedicated DB for each Entity 26 Figure 18: Accessing the openCRX Workflow Controller 27 Figure 19: openCRX 1.10.0 Workflow Controller 27 Figure 20: Default Configuration of WorkflowController 28 Figure 21: openCRX Administration – WorkflowController 29 Figure 22: Workflow Controller Configuration – serverURL 30 Figure 23: Workflow Controller Configuration – pingrate and autostart 30 Figure 24: Default Workflow Processes created by WorkflowHandler 32 Figure 25: openCRX MailImporterServlet 33 Figure 26: MailImporterServlet – Configuration 33 Figure 27: Event and Notification Service 35 Figure 28: Standard Topics included in the openCRX distribution 36 Figure 29: Create a new Subscription – step 1 37 Figure 30: Create a new Subscription – step 2 37 Figure 31: Create a new Subscription – step 3 38 Figure 32: Create a new Subscription – step 4 38 Figure 33: Create a Subscription with Filters 39 Figure 34: Flow of messages between openCRX, mail server and mail client 41 Figure 35: Import E-Mails from Mail Client 42 Figure 36: E-Mail Audit – import all inbound/outbound e-mail messages 43 Figure 37: Send E-Mail from openCRX – Overview 44 Figure 38: Send E-Mail from openCRX with Actions > Follow Up 44 Figure 39: Export E-Mail from openCRX – Overview 45 Figure 40: Export E-Mail from openCRX with Actions > Follow Up 45 Figure 41: Envelope E-mail with exported E-Mail Activity as attachment 46 Figure 42: MS Outlook – Resend This Message to edit/send e-mail 46 Figure 43: MS Outlook – Send message 47 Figure 44: Create a new E-Mail Account – step 1 50 Figure 45: Create a new E-Mail Account – step 2 50 Figure 46: Create a new E-Mail Account – step 3 51 Figure 47: E-mail subject prefix and Web access URL 51 Figure 48: Example of outbound E-mail Action Log Entries 52 Figure 49: Envelope E-Mail with attached E-Mail to be imported 53 Figure 50: Activity Tracker E-Mail is created automatically 54 Figure 51: Activity Tracker E-Mail with newly imported e-mail 54 Figure 52: Newly imported e-mail 55 Figure 53: Activity Creator Default E-mail Creator 56 Figure 54: XML import from 3rd party system – overview 60 Figure 55: Interactive import of XML Files 60 Figure 56: Interactive import of XML Files 61 Figure 57: Operation vCard Import 62 Figure 58: Exporting Contact as XML File 63 Figure 59: XML Exporter provides XML data file and code tables as ZIP file 64 Figure 60: Export Contact as vCard 64 Figure 61: Export Contact to MS Outlook 65 Figure 62: MS Outlook Contact created from openCRX Contact 65 Figure 63: Exporting Meeting / Sales Visit as iCalendar File 66
List of Listings Listing 1: File Format Subjects and Application Login Principals 21 Listing 2: Example File Subjects and Application Login Principals 21 Listing 3: File Format Users 22 Listing 4: Example File Users 22 Listing 5: web.xml – auto startup of the Workflow Controller 29 Listing 6: Iterate all auditees and check for new audit entries 31 Listing 7: Mark Audit Entries as visited by Subscription Handler 31 Listing 8: Servlets managed by Workflow Controller log to server.log 34 Listing 9: File mail-service.xml 48 Listing 10: Uncomment mail resource definition in web.xml 49 Listing 11: Uncomment mail resource definition in jboss-web.xml 49 Listing 12: Importing certificate into keystore cacerts 49 Listing 13: Debug Output of MailImporterServlet 53 Listing 14: Importing Certificate 57 Listing 15: Locales in web.xml 67 Listing 16: Activating/Deactivating Locales in web.xml 67 Listing 17: Locales in web.xml 68 Listing 18: Activating/Deactivating Locales in web.xml 68
1 About this BookThis book describes various configuration settings and tasks an openCRX administrator should know about. openCRX is the leading enterprise-class open source CRM suite. openCRX is based on openMDX, an open source MDA framework based on the OMG's model driven architecture (MDA) standards. This guarantees total openness, standards compliance, a state-of-the-art component-based architecture, and virtually unlimited scalability. 1.1 Who this book is 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 3 SecurityIn this chapter we will present a high-level overview of openCRX security and discuss a few select issues.
3.1 Introduction3.1.1 Basic Concepts and Conventions
The following figure shows the situation after the initial setup of openCRX (assuming you worked through the QuickStart guide):
Figure 1: Security Realms, Principals and Subjects after Initial Setup Summarizing the above:
The segment administrator (e.g. admin-Standard) creates principals and User Homepages 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 distinction between Ownership Permissions (i.e. permissions granted on a particular object are based on object ownership) and Model Permissions (i.e. permissions are granted on a particular model element). As the latter is not yet implemented we only talk about Ownership Permissions in this guide. Ownership permissions are used to control browse/delete/update access to openCRX objects by Users and UserGroups. Ownership access control was introduced with openCRX v1.4.0. Every openCRX object is a SecureObject. The following figure shows an extract from the UML model (if you are interested in all the details and the formally correct and complete specifications you should refer to the latest openCRX UML models):
Figure 4: openCRX UML Model – Class Diagram SecureObject
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.2 Default SettingsDefault access level settings for non-Root segments (e.g. segment Standard) after a clean install are as follows:
Figure 6: Table kernel_Segment after default installation (QuickStart) Due to the setting access_level_browse = 4 (global) any user with access to a particular segment is allowed to browse top level objects (e.g. browse all accounts, browse all activities). These default settings are suitable for test environments and deployments in smaller companies/teams with a liberal access policy; for most real-world applications, however, it is more appropriate to set access_level_browse = 3 (deep) for non-Root segments. You can do this by changing the values in the column access_level_browse from 4 to 3 (table kernel_Segment). After this change, the table kernel_Segment will look as shown in the following figure:
Figure 7: Table kernel_Segment after modification
3.3 Activating SecurityThe openCRX security provider manages all security data and provides access control services for all requests through the openCRX API. Hence, you can rely on openCRX access control even if you write you own clients or adapters for openCRX. Security (including Access Control) is not just an add-on, rather it is an integral part of openCRX; openCRX Access Control is always activated.
3.4 Security Settings of New ObjectsNew objects are by default created with the following security settings:
3.5 Login ProcedureThe openCRX login procedure consists of 2 levels: 3.5.1 Application Server LoginThe 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 application server login is not really under control of openCRX. Many login problems are related to incomplete/faulty application server configuration settings. 3.5.2 Segment 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 8: Role Drop Down with list of available Segment Login Principals It is possible to deploy user-specific implementations of the DefaultRoleMapper so that you can adapt the segment login procedure to your requirements. 3.5.3 Disabling LoginPlease refer to the chapter “Disable/Deactivate Users”. 3.6 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 UsersThe following steps are required to create a new openCRX user:
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 ManuallyThe openCRX QuickStart guide (http://www.opencrx.org/documents.htm) contains a very detailed step-by-step example of how to manually create a new openCRX user. In addition to the procedure described in the openCRX QuickStart guide where a new Subject and a new Principal are created manually, there is also fast procedure if subject name and principal name are identical:
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 9: 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 10: Operation Actions > Import Users (admin-Standard) Listing 3: File Format Users User;<principal>;<account alias>;<account full name>;<primary group>;<password>[;group [, group] ]
Please note that <password> is a clear-text value. The optional parameter group can be used to make the Segment Login Principal member of the respective Principal Groups of that segment. Listing 4: Example File Users User;joe;JD;Doe,
Joe;Users;2%jOd.IT
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 Disabling Users at the level 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 with JBoss you can simply remove users from the file users.properties to prevent access to openCRX. If you block access at the level Application Server such users are locked out from accessing any application and any openCRX segment. However, as the Application Server Login procedure is not entirely controlled by openCRX you must consult the documentation of your respective AppServer or your AppServer Admin for details. 4.2.2 Disabling Users at the level 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 11: Disabling of Segment Login Principal guest by admin-Standard
5 Deployment Scenarios5.1 Typical Deployment ScenariosThe following table lists some of the pros and cons of the 4 most common deployment scenarios:
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.) can lead to situations where a user is granted access to the data of a particular company/client that should not be accessible (please note that human error is the root cause here, not a malfunction of openCRX). Furthermore, this setup is not recommended if users can get direct access to the database, e.g. with third party reporting tools as those tools typically bypass the openCRX API.
Figure 16: Multiple Data Segments in a single DB 5.2.2 Multiple 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 17: Dedicated DB for each Entity 5.2.3 Multiple ApplicationsMultiple (differently) customized Web-EARs can access the same App-EAR. The build process creates the following EARs:
5.3 openCRX Custom Applications<documentation pending> 6 Workflow ControllerWith the Workflow Controller the openCRX Root administrator (admin-Root) can enable/disable various servlets (configured in web.xml) included in the openCRX distribution. This chapter gives an overview over the currently available servlets and explains how to start/stop them. You can access the Workflow Controller by navigating to the URL http://127.0.0.1:8080/opencrx-core-CRX/WorkflowController or starting the Workflow Controller Wizard as shown in the figure below:
Figure 18: Accessing the openCRX Workflow Controller
The following
figure shows the Workflow Controller of openCRX
Figure 19: openCRX
You can manually start (stop) servlets that are managed by the Workflow Controller by clicking on “Turn On” (“Turn Off”). Please note that you can control servlets on a segment by segment basis. For example, if you created a segment “MySegment” in addition to the segment “Standard” you can start/stop servlets of the segment “MySegment” without interfering with the servlets of the segment “Standard”. 6.1 Workflow Controller 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 accessible to the openCRX Root administrator (admin-Root) by navigating to Administration and then clicking on the icon of the WorkflowController:
Figure 21: openCRX Administration – WorkflowController
6.1.1 Startup Configuration in web.xmlYou can start the Workflow Controller manually by navigating to the URL http://127.0.0.1:8080/opencrx-core-CRX/WorkflowController or starting the Workflow Controller Wizard. However, it is also possible to start the Workflow Controller automatically by activating the corresponding option in the file web.xml: Listing 5: web.xml – auto startup of the Workflow Controller <!--
WorkflowController -->
6.1.2 ServerURLAdapt the value of serverURL to your environment (e.g. http://127.0.0.1:8080/opencrx-core-CRX):
Figure 22: Workflow Controller Configuration – serverURL 6.1.3 Handler pingrate and autostartUse the pingrate to define the interval (in minutes) between successive calls of the respective handler and autostart (true/false) to start the respective handler automatically:
Figure 23: Workflow Controller Configuration – pingrate and autostart 6.2 Servlet SubscriptionHandlerThe openCRX SubscriptionHandler is the backbone of the openCRX Subscribe / Notify Services. The Subscription Handler does not require any configuration by the openCRX administrator other than setting the pingrate and autostart options, i.e. it is designed to work “out of the box”. Turning on the SubscriptionHandler of a particular segment is required if you want that segment to provide Alerts and E-mail Notifications to its Users. The polling frequency can be set by the Root administrator (see Figure 23: Workflow Controller Configuration – pingrate and autostart). The SubscriptionHandler checks openCRX audit entries on a regular basis and – if matching Subscriptions exist – executes the Workflow Process referenced by the Subscription using Userhome.executeWorkflow(). Listing 6: Iterate all auditees and check for new audit entries for(
Userhome.executeWorkflow() – implemented by the openCRX plugin – creates an entry in Userhome.wfProcessInstance (accessible through the grid Workflow Process Instances) and executes synchronous workflows immediately. Beyond creating entries for asynchronous workflows, executeWorkflow() does not do anything with them (the Servlet WorkflowHandler is specialized in dealing with asynchronous workflows – see below for details). 6.3 Servlet 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 23: Workflow Controller Configuration – pingrate and autostart). Please note that the WorkflowHandler is required for outbound E-Mail Services. The WorkflowHandler executes Workflow Process Instances that have not been executed yet.
6.4 MailImporterServletThe MailImporterServlet provides generic E-mail Services. The servlet regularly connects to e-mail boxes and fetches messages to be imported into openCRX.
Figure 25: openCRX MailImporterServlet The configuration of the MailImporterServlet is explained in detail in the chapter E-mail Services). The Root administrator (admin-Root) can set a few select options in the MailImporterServlet's ComponentConfiguration. The figure below shows the default configuration as it is created the first time the MailImporterServlet is started:
Figure 26: MailImporterServlet – Configuration Polling frequency and autostart can also be set (see Figure 23: Workflow Controller Configuration – pingrate and autostart). 6.5 Trouble Shooting ServletsAll the openCRX servlets controlled by the Workflow Controller log their actions to the server log file (e.g. D:\jboss-4.0.3SP1\server\default\log\server.log on JBoss). The following log file extract shows, for example, that both the Subscription Handler and the Workflow Handler seem to be working fine, whereas the MailImporterServlet cannot connect to the mail box (due to missing configuration): Listing 8: Servlets managed by Workflow Controller log to server.log 2006-04-04
14:04:25,936 INFO [STDOUT] Tue Apr 04 14:04:25 CEST 2006:
openCRX/SubscriptionHandler:
CRX/Standard openCRX Exceptions (like NullPointers, etc.), however, are still logged to the application log file as configured during the installation (see QuickStart guide). It is always worth checking whether the Workflow Handlers actually are active; they must be started by the Root administrator. You can find out by connecting to the Workflow Controller (see Figure 19: openCRX 1.10.0 Workflow Controller).
7 Subscribe / Notify ServicesopenCRX features a powerful event subscription and notification service:
Figure 27: Event and Notification Service Once a topic is created, openCRX users can subscribe to it. Users manage their subscriptions individually on their UserHomes. If a topic has subscribed users and a monitored event occurs then the predefined actions are performed. If the action is set to – for example – creating an alert for subscribed users, then each subscribed user will receive an alert on her UserHome.
The openCRX distribution includes quite a few default topics (see Figure 28: Standard Topics included in the openCRX distribution) to get you started:
Figure 28: Standard Topics included in the openCRX distribution Users can easily custom-tailor their subscriptions with filters and by selecting event types like Object Creation, Object Replacement, and Object Removal.
7.1 Example Subscription – Activity ModificationsIn this example we will create a subscription to the standard Topic Activity Modifications for the user “guest”.
Figure 29: Create a new Subscription – step 1
Figure 30: Create a new Subscription – step 2
Figure 31: Create a new Subscription – step 3
Figure 32: Create a new Subscription – step 4
7.2 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 ActivityTrackers DivisionA:ProjectX and DivisionA:ProjectY and some of your users are interested in receiving notifications related to activities of ProjectX only, some users want to receive notifications related to activities of ProjectY only, and some users want to receive notifications from both projects. Such a situation could be handled as follows:
Figure 33: Create a Subscription with Filters Enter the name of the attribute (owner in our example) into the name field and then enter the value(s) to match into the value field (Standard:DivisionA.ProjectX and Standard:DivisionA.ProjectY in our case)
7.3 Trouble Shooting Notification ServicesThe following table lists some of the common issues and how to fix them:
8 E-mail ServicesPlease note that you can use your favorite e-mail client with openCRX. None of our E-mail services are platform dependent and they work with any e-mail client and with any mail server as long as they support standard protocols like SMTP, POP3, POP3S, IMAP, IMAPS, etc. Inbound and outbound E-mail services are based on JavaMail. Installation of JavaMail is not required to run openCRX, but it is required if you want to make use of openCRX E-Mail services. The following figure shows the flow of mail
messages between openCRX, mail server, and mail client as it is
supported with openCRX
Figure 34: Flow of messages between openCRX, mail server and mail client In the following few sections we will first discuss various important use cases and subsequently show how to configure openCRX in order to make use of the available functionality. 8.1 Import E-mails from a Mail Client into openCRXInstead 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 e-mail importer. The advantages are:
The following figure shows an overview of how you can import e-mails from your mail client into openCRX:
Figure 35: Import E-Mails from Mail Client The whole setup is quite straightforward; in a first step you configure the MailImporterServlet (see Inbound E-mail) 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. This default Activity Creator assigns imported E-Mails to the Activity Tracker E-Mails. To import an e mail message from your mail client into openCRX:
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. 8.2 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 36: E-Mail Audit – import all inbound/outbound e-mail messages 8.3 Send E-mail directly from openCRXAny openCRX E-Mail Activity can be sent as e-mail directly from openCRX:
Figure 37: Send E-Mail from openCRX – Overview The idea behind this functionality is less that you will use openCRX as a mail client, rather the SendMailWorkflow is an important element of the openCRX campaign management functionality. E-Mail Activities of type “E-Mails” are controlled by the Activity Process E-mail Process. Send E-Mail Activities to all recipients by executing the operation Actions > Follow Up and then selecting the Transition Send as mail as shown below:
Figure 38: Send E-Mail from openCRX with Actions > Follow Up
8.4 Export E-mails from openCRX to your Mail ClientAny openCRX E-Mail Activity can be exported to your mail client:
Figure 39: Export E-Mail from openCRX – Overview 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. 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 40: Export E-Mail from openCRX with Actions > Follow Up
The following figure shows an example envelope e-mail with the attachment “test message.msg” representing the exported E-Mail Activity:
Figure 41: Envelope E-mail with exported E-Mail Activity as attachment With a few simple steps you can typically open and edit the exported message and then send it. The following example shows how to do this with MS Outlook (but the steps are similar for other mail clients):
Figure 42: MS Outlook – Resend This Message to edit/send e-mail
Figure 43: MS Outlook – Send message 8.5 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.5.1 Installation of JavaMail and JAFDetailed installation instructions are provided at the JavaMail home: http://java.sun.com/products/javamail/FAQ.html And here is the short version:
8.5.2 Create mail-service.xmlNext you need to create the file mail-service.xml in the directory (on JBoss) d:\pgm\jboss-4.0.5.GA\server\default\deploy (Windows) or /opt/jboss/server/default/deploy (Linux). In the sample file below you must at least adapt the highlighted strings to your own environment: Listing 9: File mail-service.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
Additional information about configuration options of JavaMail are available from the JavaMail home: http://java.sun.com/products/javamail/FAQ.html
8.5.3 Mail Resource in web.xml and jboss-web.xmlIn the file web.xml in the directory (JBoss on Windows) d:\pgm\jboss-4.0.5.GA\server\default\deploy\opencrx-core-CRX-Web.ear\opencrx-core-CRX.war\WEB-INF\ or (JBoss on Linux) /opt/jboss/server/default/deploy/opencrx-core-CRX-Web.ear/opencrx-core-CRX.war/WEB-INF/ you must uncomment the following section: Listing 10: Uncomment mail resource definition in web.xml
...
Similarly, in the file jboss-web.xml in the directory (JBoss on Windows) d:\pgm\jboss-4.0.5.GA\server\default\deploy\opencrx-core-CRX-Web.ear\opencrx-core-CRX.war\WEB-INF\ or (JBoss on Linux) /opt/jboss/server/default/deploy/opencrx-core-CRX-Web.ear/opencrx-core-CRX.war/WEB-INF/ you must uncomment the following section: Listing 11: Uncomment mail resource definition in jboss-web.xml
... <resource-ref> <res-ref-name>mail/provider/CRX</res-ref-name> <jndi-name>java:/mail/provider/CRX</jndi-name>
</resource-ref> Restart the application server for these changes to become active.
8.5.4 Outbound E-mailopenCRX 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 44: Create a new E-Mail Account – step 1
Figure 45: Create a new E-Mail Account – step 2
The various fields have the following meanings:
Figure 46: Create a new E-Mail Account – step 3
Figure 47: 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 Activity Modifications (see Example Subscription – Activity Modifications) and then work through the following steps:
Figure 48: Example of outbound E-mail Action Log Entries 8.5.5 Inbound E-mailThe configuration of inbound E-mail is explained in detail in the chapters MailImporterServlet and Import E-mails. You can test your settings as follows:
Figure 49: Envelope E-Mail with attached E-Mail to be imported
Listing 13: Debug Output of MailImporterServlet
18:42:57,779 INFO [STDOUT] DEBUG: JavaMail version
1.3.3
Figure 50: Activity Tracker E-Mail is created automatically
Figure 51: Activity Tracker E-Mail with newly imported e-mail
Figure 52: Newly imported e-mail The mail importer will automatically link imported e-mails with corresponding objects (if they exist in openCRX) and create various additional useful objects:
8.5.6 Trouble Shooting E-mail ServicesThe following table lists some of the common issues and how to fix them:
9 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.
9.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 Importing iCalendar Files) in addition to the XML importer. 9.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-1.10.0\jre-1.4\core\lib\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-Web.ear\opencrx-core-CRX.war\WEB-INF\config\data\ Root\uom_SI_and_Paper.xml). An XML import from a third party system might typically involve the following steps:
Figure 54: XML import from 3rd party system – overview You can import schema-compliant XML files with the following methods:
9.2.1 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 57: Operation vCard Import
9.2.2 Importing iCalendar Files ( openCRX Meetings)iCalendar is a standard for calendar data exchange (additional information is for example available from http://en.wikipedia.org/wiki/ICalendar). These are the steps to import an iCalendar file:
9.2.3 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. 9.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. 9.3.1 Exporting XML FilesNavigate to the object to be exported as XML file and execute the operation File > Export XML as shown below:
Figure 58: Exporting Contact 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. The default reference filter is :*/:* meaning that all composites and referenced objects up to 2 levels deep will be exported together with the main object (this should be sufficient for most use cases). Limiting the scope of the export by providing a reference filter as in the example above might be necessary to limit the size of the XML file. If the export is successful the exporter will terminate with status OK and you will be provided with a link to a zip file containing the raw data and all the referenced code tables:
Figure 59: XML Exporter provides XML data file and code tables as ZIP file 9.3.2 Exporting openCRX Contacts ( vCard Files)These are the steps to export a contact to a vCard file:
Figure 60: Export Contact as vCard If the export operation was successful the result will contain a link to the vCard file. Click on that link to download the vCard file from the openCRX server. 9.3.3 Exporting openCRX Contacts ( Outlook Contacts)Navigate to the contact you want to export to MS Outlook and execute the Wizard Export to MS Outlook:
Figure 61: Export Contact to MS Outlook
The Wizard creates a new MS Outlook Contact from the openCRX Contact. If you want to add it permanently to your MS Outlook file, simply click the button [Save and Close], otherwise close the Contact window to discard:
Figure 62: MS Outlook Contact created from openCRX Contact An animation is available at http://www.opencrx.org/opencrx/1.9/new.htm#ops 9.3.4 Exporting openCRX Meetings ( iCalendar Files)These are the steps to export a meeting (or a sales visit) to an iCalendar file:
Figure 63: Exporting Meeting / Sales Visit as iCalendar File 9.3.5 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. 10 Customizing openCRXPlease refer to the guides available at http://www.opencrx.org/documents.htm for detailed information regarding UI customization and localization. 10.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-Web.ear\opencrx-core-CRX.war\WEB-INF\web.xml Look for the section <!-- locales --> to find a list of available locales: Listing 15: 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 16: Activating/Deactivating Locales in web.xml <!-- locales
-->
10.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-Web.ear\opencrx-core-CRX.war\WEB-INF\web.xml Look for the section <!-- Admin --> to find a list of available packages: Listing 17: Locales in web.xml <!-- Admin
-->
You can deactivate packages by simply commenting them out. The following example shows how to deactivate the package depot1: Listing 18: Activating/Deactivating Locales in web.xml
... <param-value>xri:@openmdx:org.opencrx.kernel.document1/provider/CRX/segment/${SEGMENT}</param-value> </init-param> <!--
Buildings -->
10.3 Role-based UIRequires Model Permissions (which are not implemented yet). The same goal can easily be achieved with Multiple Applications, however. 10.3.1 Model PermissionsModel permissions are not implemented yet. 10.3.2 Multiple ApplicationsPlease refer to the chapter Multiple Applications. 10.3.3 Custom Layout JSPsopenCRX is distributed with 2 default layout JSPs located in the directory opencrx-core-CRX-Web.ear\opencrx-core-CRX.war\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 your application server your new layout JSP will be active.
11 Integration with Office SuitesopenCRX provides various technologies that enable you to easily integrate common office suites like Open Office or Microsoft Office. 11.1 MS Office11.1.1 MS WordSee information published
at 11.1.2 MS ExcelSee information published
at 11.1.3 MS OutlookSee chapters E-mail Services, Importing iCalendar Files, Importing vCard Files, Exporting openCRX Meetings ( iCalendar Files), Exporting openCRX Contacts ( vCard Files), Exporting openCRX Contacts ( Outlook Contacts), and information published at http://www.opencrx.org/opencrx/1.9/new.htm#ops. 11.2 Open Office11.2.1 OpenOffice WriterSee information published
at 11.2.2 OpenOffice CalcSee information published
at 12 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 2007 ©
CRIXP Corp. All rights reserved. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||