FAQ

General Questions

• Is openCRX a true Open Source project?
• How can I support the development of openCRX?
• What is the roadmap of openCRX?
• What is the goal of the openCRX project?
• How large is the openCRX development team?
• Where can I read about Model Driven Architecture (MDA) before diving into openMDX?

Downloads, Repositories, and Documentation

• From where can I download openCRX distributions?
• Where is the openCRX GIT repository?
• Where is the documentation of the openCRX API (aka Javadoc)?
• Where are the openCRX UML models and how can I browse them?

Cloud/Groupware Features

• Which ActiveSync clients can I use to connect to openCRX?
• Which CardDAV clients can I use to connect to openCRX?
• Which CalDAV clients can I use to connect to openCRX?
• Which FreeBusy clients can I use to connect to openCRX?
• Which ICS/iCalendar clients can I use to connect to openCRX?
• Which IMAP mail clients can I use to connect to openCRX?
• Which WebDAV clients can I use to connect to openCRX?

Installation Issues

• Installer aborts with error: too many open files

Technical Questions

• Should I read the README ?
• Which DBMS (Database Management System) can/should I use with openCRX ?
• How can I migrate from HSQLDB to another DBMS ?
• Where is the openCRX API ?
• How can I synchronize DBs from multiple openCRX instances ?
• Which Java VM do you recommend with openCRX ?
• What are the hardware requirements to run openCRX ?
• What do you recommend to tune the performance of openCRX ?
• Is an Application Server required to run openCRX ?
• openCRX v2.0+ Deployment Matrix
• What is the openCRX/openMDX/JDK version compatibility ?
• Which browser can I use with openCRX (HTML GUI) ?
• How to upgrade openCRX from a previous version ?
• How to add additional languages to openCRX ?
• How to load a language-specific login page ?

Is openCRX a true Open Source Project?

The answer is yes. openCRX has always been published with an OSI certified BSD-style license. We have nothing to hide and none of our code is proprietary.

By the way, you should not understimate the importance of your question. Numerous CRM applications claim to be Open Source when in fact they are not. Read Will The Real Open Source CRM Please Stand Up? on the OSI Blog for additional information.

^top

How can I support the development of openCRX?

It is the hope of the openCRX team that lots of bright people are going to join the effort to make openCRX the tool of choice for limitless relationship management. If you can contribute or want to co-operate or have a look at the information on our community page. Any kind of support is appreciated.

If you want to make a donation to support the development of openCRX, you can do so through PayPal:

^top

What is the roadmap of openCRX?

The current roadmap of openCRX is available on the project page.

^top

What is the goal of the openCRX project?

It is our goal to establish openCRX as the core reference model for relationship management (XRM) and enterprise resource planning (ERP). Starting with openCRX v2.0 we've also begun to move into the realm of Groupware and we intend to position openCRX as an Open Source Groupware server.

^top

How large is the openCRX development team?

The core team consists of 3 people (although we should probably make this 4 due to the close co-operation with the openMDX team). Please do not jump to conclusions like "too small, no power, etc. " just because you are not familiar with MDA (Model Driven Architecture). It is quite appropriate to apply a quality-adjusted productivity factor of at least 10. Furthermore, consider the lack of overhead as we do not need to synchronize hundreds of developers.

In addition to the core team there are lots of translators (see list of available locales here) and dozens of community members providing important input to keep openCRX moving. Several companies (from very small to very large) provide important resources (ideas, people, funding).

^top

Where can I read about Model Driven Architecture (MDA) before diving into openMDX?

There is a lot of material available at OMG's MDA site. If you just want to get a quick overview, try An introduction to Model Driven Architecture by Allan Brown and Jim Conallen:

• An introduction to Model Driven Architecture (Part I)
• An introduction to Model Driven Architecture (Part II)
• An introduction to Model Driven Architecture (Part III)

You might also want to read the openMDX Introduction available from the openMDX website.

^top

From where can I download openCRX distributions?

openCRX distributions are availble from Sourceforge. There is also a GIT repository.

^top

Where is the openCRX GIT respository?

The GIT repository of the openCRX project is available in read-only mode from http://sourceforge.net/p/opencrx/opencrx2-git/.

Please note that building openCRX from GIT is likely to fail unless you check out properly tagged files. If you want to build openCRX from scratch/source we recommend you get the openCRX SDK which contains the complete source code.

^top

Where is the documentation of the openCRX API (aka Javadoc)?

The openCRX API (also known as Javadoc) is available here.

^top

Where are the openCRX UML Models and how can I browse them?

openCRX UML Models are included in the openCRX SDK. In order to browser the UML models you need Eclipse and the UML2 Tools. Detailed instructions are available here.

^top

Which ActiveSync Clients can I use to connect to openCRX?

Please note that your preferred client might still work with openCRX, even if it is not listed below. We have tested the following clients against openCRX v2.9.1:

• Apple's iPhone works flawlessly.
• HTC Desire (with Android v2.3) works flawlessly (syncs 1 calendar only, though)
• Google Nexus S (with Android v4.0.3 ICS) works flawlessly (requires fronting Apache server and syncs 1 calendar only, though)

Configuration hints are available in the openCRX Admin Guide. The Wizard "Connection Helper" provides all the necessary information to connect.

Additional information about ActiveSync is available from Microsoft or read what Wikipedia is saying about ActiveSync.

^top

Which CardDAV Clients can I use to connect to openCRX?

Please note that CardDAV is only supported since openCRX v2.10. Please also note that your preferred client might still work with openCRX, even if it is not listed below:

• Apple's iPhone (iOS 5.x)
• The SOGo Connector, an add-on for Mozilla's Thunderbird is a CardDAV client. We tested SOGo Connector 10.0.1 (with Thunderbird 11.0.1) and it works fine in read-only mode.
• While Android does not support CardDAV out of the box, you can get CardDAV-Sync from the Android Market (search for "CardDAV"); this app has full support for CardDAV collections and it's easy to setup/configure.

Configuration hints are available in the openCRX Admin Guide. The Wizard "Connection Helper" provides all the necessary information to connect.

Additional information about CardDAV is available from Wikipedia.

^top

Which CalDAV Clients can I use to connect to openCRX?

Please note that your preferred client might still work with openCRX, even if it is not listed below.

• Apple's iPhone (requires openCRX v2.10 or newer)
• Mozilla's Lightning, the calendaring add-on for Mozilla's Thunderbird is the best-tested cross-platform CalDAV client. We tested Lightning 1.4 (with Thunderbird 12.0.1).
• Chandler Desktop by OSAF (Open Source Applications Foundation) works very well with openCRX in both online and offline settings. We tested Chandler 0.7.1.
• While Android does not support CalDAV out of the box, you can get CalDAV-Sync from the Android Market (search for "CalDAV"); this app has full support for CalDAV collections and it's easy to setup/configure. Another option that works is aCal.

Configuration hints are available in the openCRX Admin Guide. The Wizard "Connection Helper" provides all the necessary information to connect.

If you're using Microsoft Outlook you best forget about CalDAV even though Microsfot joined CalConnect on 15 August 2007 and MS Outlook 2010 apparently can connect to CalDAV Providers in read-only mode. MS Outlook is a client for MS Exchange and it's basically useless if you want to connect to other servers that use standard protocols (like CalDAV, for example). If you're into tinkering with VBA code, you might try our Outlook ICS Adapter, but it's really just a start...

Additional information about CalDAV is available from http://www.caldav.org/ or read what Wikipedia is saying about CalDAV.

^top

Which FreeBusy Clients can I use to connect to openCRX?

Please note that your preferred client might still work with openCRX, even if it is not listed below.

• Mozilla's Thunderbird, works fine with the Free/Busy add-on (we tested with Thunderbird 15).

Configuration hints are available in the openCRX Admin Guide. The Wizard "Connection Helper" provides all the necessary information to connect.

Additional information about FreeBusy is available from Wikipedia.

^top

Which ICS/iCalendar Clients can I use to connect to openCRX?

Please note that your preferred client might still work with openCRX, even if it is not listed below.

• Mozilla's Lightning, the calendaring add-on for Mozilla's Thunderbird, is the best-tested cross-platform ICS/iCalendar client. We tested Lightning 1.4 (with Thunderbird 12.0.1).
• KDE Contact works very well with openCRX
• Apple's iPhone
• Microsoft Outlook 2003 and Microsoft Outlook 2007: use our Outlook ICS Adapter

Configuration hints are available in the openCRX Admin Guide. The Wizard "Connection Helper" provides all the necessary information to connect.

Additional information about iCalendar is available from Wikipedia.

^top

Which IMAP Clients can I use to connect to openCRX?

We have tested Mozilla Thunderbird, Microsoft Outlook 2003 and 2007, and Evolution. We would assume, however, that virtually any IMAP client will work just fine. Give it a try.

Configuration hints are available in the openCRX Admin Guide.

Additional information about IMAP is available from Wikipedia.

^top

Which WebDAV Clients can I use to connect to openCRX?

We have tested the following clients, but there are certainly many more that will work:

• Linux: Nautilus (Gnome) and Dolphin (KDE) work just fine. You might have to install the davfs2 package.
• Windows: you might want to use a third-party tool like BitKinex to avoid the quirky implementation of Microsoft's web folders. The following hint regarding Windows 7 was submitted by a user: Start Regedit and then in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\WebClient\Parameters set BasicAuthLevel to 2.
• Android: look at WebDAV File Manager (free)
• iPhone: look at the WebDAV Navigator (free version available) and GoodReader

The Wizard "Connection Helper" provides all the necessary information to connect.

Additional information about WebDAV is available from Wikipedia.

^top

Installer aborts with error "too many open files"

This is mostly an issue on Linux-based systems. Open a shell and type
ulimit -a
to verify your open file limit. If it is set to 1024 you might want to increase it to 2048 (or even 4096). On CentOS, for example, you can set this limit in the /etc/security/limits.conf file. See here or here for information on other Linux distributions, Solaris, and OS X.

^top

Should I read the README?

It is always a good idea to read the README because it typically contains important information.

^top

Which DBMS (Database Management System) can/should I use with openCRX?

The "can"-part of the question is easy to answer: openCRX v2.9.2 has been tested with

	HSQLDB (v2.0 or newer) [not recommended for production use]
	MySQL (v5.0 or newer) [not recommended for production use, unless you are very good at tuning]
	PostgreSQL (v8.3 or newer)
	MS SQL (MS SQL 2000, MS SQL 2005, MS SQL 2008)
	Oracle (v9 or newer)
	DB2 (v9.5 or newer)
	MaxDB (formerly SAP DB) [not supported anymore]
	Firebird [not supported]

The "should"-part of the question is more difficult to answer without knowing more about your requirements and constraints. While the table below may be somewhat helpful in your decision making process, the answer to your question boils down to getting clarity on the following 3 issues:

• how much performance/scalability do you need in terms of #concurrent users, database size, etc.?
• how much money are you willing to spend on DB licenses?
• if you already use a DBMS that would work with openCRX why use another DBMS?

If you have no constraints we would recommend PostgreSQL v9 (or newer) for best performance.

A note on free DBs: due to the pressure from Open Source DBs various vendors of commercial DBs started offering free versions of their commercial products. Before you jump to any conclusions, however, it is worthwhile reading the small print of those offers. It pays off to understand the limitations/conditions/licenses in order to avoid an unwanted lock-in (example: any free offer with a limit on the size of the database is going to hurt you sooner or later as using/working with openCRX is equivalent to adding data - 4GB may sound like a lot today but once you've added 100'000 accounts and 200'000 sales orders you will probably be past that limit...).

* Please note that we do not recommend HSQLDB or MySQL for production use. The lack of cursor-support leads to lots of table scans resulting in low performance for large data sets. MySQL v5.x might solve some of these problems. If you are a very experienced MySQL DBA you might be able to tune your instance so that it performs.

Please note that the "limitations" listed in the above table are not hard numbers, but they are based on our experience and on the assumption that users expect decent response times.

openCRX includes all the required configuration/deployment files for HSQLDB, MySQL, PostgreSQL, MS SQL, DB2, and Oracle.

^top

How can I migrate from HSQLDB to another DBMS?

Very detailed instructions for migrating from HSQLDB to another DMBS are available at
http://sourceforge.net/apps/trac/opencrx/wiki/Sdk29.DatabaseMigration.

^top

Where is the openCRX API?

Have a look at the openCRX UML Model or the openCRX Javadoc.

If you are looking for the schema files (*.xsd) to verify data files or REST requests, you will find the schema files in opencrx-kernel.jar (e.g. located in {TOMCAT_INSTALL_DIR}apps\opencrx-core-CRX\APP-INF\lib).

^top

How can I synchronize DBs from multiple openCRX instances?

Depending on your DBMS (see also which DBMS should I use with openCRX) there are typically advanced (but DB-specific) tools available. For example, MySQL supports replication out of the box: http://dev.mysql.com/doc/refman/5.0/en/replication.html

For a more generic overview of DBMS neutral tools, have a look at http://en.wikipedia.org/wiki/Multi-master_replication.

A Java-based tool is available from http://symmetricds.sourceforge.net/

^top

Which Java VM do you recommend with openCRX?

We test openCRX with both the Sun Java VM and OpenJDK.

^top

Is an Application Server required to run openCRX?

openCRX v1.x required an application server. However, openCRX v2.0+ can be deployed on Apache Tomcat resulting in much reduced complexity without loss of functionality and a performance gain of at least a factor of 2. Hence, there is really no need (and no reason) to deploy openCRX on an application server. Save yourself the trouble (and money) and do with Apache Tomcat.

For those who can't resist, an openCRX community member provided some information on how to deploy openCRX v2.5.2 on JBoss 5:
http://sourceforge.net/apps/trac/opencrx/wiki/Sdk25.InstallOnJBoss

^top

openCRX v2.5+ Deployment Matrix

openCRX v2.5+ is a J2EE application and openCRX EARs can be deployed on Apache Tomcat 6 and - in principal - on any J2EE-compliant Application Server. The openCRX project officially tests and supports the following deployment scenario:

If you need support for a particular deployment scenario, please contact one of the openCRX Partners or CRIXP Corp.

^top

What are the hardware requirements to run openCRX?

openCRX is the kind of enterprise-class J2EE application that will not make you happy if you install it on your old PIII-500 with 128MB of RAM. Use the following information to arrive at a rough estimate of your requirements:

* concurrent users means users generating server requests concurrently - under normal working conditions 1 concurrent user is roughly equivalent to 5 to 20 typical users.

In an environment with considerable load it is advisable to consider a multi-tier deployment scenario; additionally, you might consider setting up clusters for tiers with heavy load; clustering is also used to increase availability and to introduce fault tolerance. The following chart shows a 4-tier deployment scenario with clustering, providing mission-critical services suitable for tens of thousands of concurrent users:

^top

What do you recommend to tune the performance of openCRX?

The following list should get you moving in the right direction if your openCRX deployment does not perform as expected:

• make sure you are using adequate hardware (see hardware requirements for more information)
• use an adequate DBMS
• verify your deployment scenario - while a single server (4 x 3GHz CPU, 8GB RAM) can typically handle up to a few hundred concurrent users, you should consider a multi-tiered deployment scenario (potentially with clustering) to distribute the total system load. Consider an approach as follows:
  
  • Deploy Tomcat on a JVM so that it can use (potentially multiple) multi-core CPUs. Tomcat is threaded and nicely scales with cores and CPUs. Based on our experience you can typically handle between 30 and 50 concurrent users per core.
  • If you don't get enough performance with the above setup, "copy" this setup as many times as you like (each Tomcat will connect to your DB(-cluster); front your Tomcat array with an http(s) load balancer; the load balancer must be configured such that subsequent session requests get sent to the same Tomat instance (i.e. do not distribute requests of the same session across multiple Tomcats.
• DB tuning - while the default distribution of openCRX includes some indexes, you need a good DBA to carefully look at the DB performance; as you learn about the load creating patterns of your users, your DBA will be able to ensure maximum performance by tuning the DB
• Servlet Container Tuning - Install the Apache Portable Runtime (particularly useful to speed up SSL)
• Java VM tuning - as with any J2EE application there is a lot to gain from tuning the Java VM (memory size settings, garbage collecting, etc.). Depending on your platform you might also observe performance differences among different Java VMs (e.g. BEA JRockit vs. Sun Java VM)
• on any multi-CPU box (real, multi-core or hyperthreaded) you should verify that the Java VM and the DBMS are actually using more than 1 CPU; we have come across many installations where people spent a lot of money on high performance servers with multiple CPUs without actually putting more than 1 of them to work... (for example, on certain versions of Redhat/CentOS the Java VM will use multiple CPUs only if you install compat-libstdc++-3.2-1.i386.rpm)
• make sure that your servlet container / application server sends compressed (zipped) pages to browsers; with JBoss, for example, add/set the Tomcat option compression="on" in the file server.xml (details on the http connector reference page of the Apache Jakarta Project) - compressed pages are smaller than uncompressed pages by a factor of 10, thereby reducing the load on your network and improving the experience of users connected to the openCRX server with "less than optimal" bandwidth specs
• enable gzip compression filters and cache header filters in the applications web.xml (depending on the distribution some of the filters are commented out).

Application performance tuning is a time-consuming (and therefore expensive) task because it often times involves detailed analysis (and good understanding) of the various components involved; for example, every DBMS has different quirks and at some point you really need to deal with the DBMS your are actually using, i.e. it is not sufficient to do some generalized high-level DB tweaking. While we have a tradition of investing resources on a continuous basis to deliver a well-performing application, it is no secret that one could do even more. We appreciate any hints to enhance performance. In case you want to contribute financially, please visit our Community page.

^top

What is the openCRX/openMDX/JDK/AppServer version compatibility?

The openCRX version determines which openMDX version to use. Depending on your preferred JDK version you select matching distributions of openCRX and openMDX for the same JDK.

Please note that older versions of the Servlet Containers listed in the table below might work, but we tested openCRX with the versions listed below:

^top

Which browser can I use with openCRX (HTML GUI)?

If you have a recent standards-compliant browser you should be fine. We develop and test with the following browsers on Windows XP:

• Internet Explorer IE 7.0 or newer
• Opera 9.10+, Opera 10.0++
• Mozilla 1.7.3+
• Firefox (any version)
• Safari 3.0+, Safari 4.0+
• Google Chrome (any version)

If you get the impression that the rendering of pages is broken you might want to upgrade your browser. If you detect problems in our HTML code or in our Javascripts we would certainly appreciate it if you could post your insights to the bug forum.

^top

How to upgrade openCRX from a previous version?

We identify an openCRX version with 3 numbers x, y, and z (i.e. openCRX x.y.z). x.y.z is the Implementation Version, x.y is the corresponding Specification Version. The meaning of individual numbers is listed in the table below:

What follows are detailed instructions for upgrading openCRX from v2.10.0 to v2.11.0
(upgrade instructions for previous releases can be found here):

Upgrading from openCRX v2.10.1 to openCRX v2.11.0

	Do NOT upgrade from a version older than 2.0.0 directly - you must first upgrade to at least v2.0.0 to prepare for the upgrade to v2.11.0
	DB Scripts are no longer required as DB upgrades are now managed with the DB schema wizard a pre-built EAR is contained in the openCRX Server Installer in the directory {Server Installation Directory}\apache-tomee-webprofile-1.0.0\apps

• stop the openCRX server (i.e. the servlet container Tomcat/application server, etc. and HSQLDB [if running])
• backup your database
• install openCRX 2.11.0 with the openCRX Server Installer in a new directory
• in case you made changes to the standard configuration of your previous openCRX installation, amend the changes in the new openCRX installation:
  • verify {openCRX_INSTALL_DIR}/apache-tomee-webprofile-1.x.x/bin/sentenv.sh (or setenv.bat on Windows)
  • verify {openCRX_INSTALL_DIR}/apache-tomee-webprofile-1.x.x/conf/tomee.xml (called openejb.xml in older versions)
  • verify {openCRX_INSTALL_DIR}/apache-tomee-webprofile-1.x.x/conf/server.xml
  • verify {openCRX_INSTALL_DIR}/apache-tomee-webprofile-1.x.x/conf/tomcat-users.xml
  • copy JARs (e.g. JDBC-drivers, etc.) you added to {openCRX_INSTALL_DIR}/apache-tomee-webprofile-1.x.x/lib
• in case you use HSQLDB as a database:
  • copy {openCRX_INSTALL_DIR_OLD}/data/crx/crx.script to {openCRX_INSTALL_DIR}/data/crx/crx.script
  • in case you get the error

        2013-04-03T13:18:56.971+0200  WARNING  unexpected token: REGULAR
        org.hsqldb.HsqlException: unexpected token: REGULAR

    when starting the HSQLDB, open the file {openCRX_INSTALL_DIR}/data/crx/crx.script with a text editor and remove the line

        SET DATABASE SQL REGULAR NAMES TRUE

• start openCRX Server (the newly installed instance); you can either use the shortcut created by the installer or open a shell/cmd window and
  • cd to {openCRX_INSTALL_DIR}/apache-tomee-webprofile-1.x.x/bin and
  • execute ./opencrx.sh run (or opencrx.bat run on Windows)
• once you have openCRX running again, proceed as follows (detailed instructions are available in the openCRX Installation Guide for Tomcat 6):
  • login as admin-Root
  • launch the "Database schema wizard" from Wizards > Database schema wizard
  • Hint: some databases do not support create/update view and you will have to manually delete all views in your openCRX database so that the database schema wizard can create the new views; you have to do this with your preferred database administration tool (e.g. pgAdmin for PostgreSQL)
  • click on the button [Validate and Fix] (the wizard will upgrade your DB schema to the appropriate version of openCRX; the wizard will not delete/drop any tables or columns, i.e. if there are validation messages that you have extra tables/columns in your database, you should drop those manually with your preferred DB admin tool, e.g. pgAdmin for PostgreSQL)
  • if there are validation messages that you have extra tables/columns in your database, you might want to drop those manually (the wizard does not drop tables/columns ever); please note, however, that the wizard does not know about tables/columns related to model extensions in custom-projects, i.e. double-check any table/column before you actually drop it
  • click on the button [Validate] to verify the database schema; it is important that the schema validation reports NO errors before you continue - if there are errors reported, try another cycle of [Validate and Fix] followed by [Validate]; if that doesn't help, try deleting the views manually as explained above and then try another cycle of [Validate and Fix] followed by [Validate]
  • delete all codes as follows:
    • navigate to [Codes]
    • in the grid [Codes] select View > Show 500 rows
    • in the grid [Codes] click the checkbox to the left of the header Identity to select all code rows
    • in the gird [Codes] select Edit > Delete to delete all code entries
  • import codes and data as follows:
    • navigate to [Administration]
    • in the grid [Administration] select View > Reload to import the new codes and data
  • set the access levels of codes to 4, 3, 2, 1 as follows:
    • navigate to [Codes]
    • in the grid [Codes] select Security > Set Access Level
    • set the drop downs in the dialog Set Access Level to the following values:
      4 for Browse access level
      3 for Update access level
      2 for Delete access level
      1 for Mode
  • stop openCRX Server; it is important to shut down openCRX properly - you can either use the shortcut created by the installer or open a shell/cmd window and
    • cd to {openCRX_INSTALL_DIR}/apache-tomee-webprofile-1.x.x/bin and
    • execute ./opencrx.sh stop (or opencrx.bat stop on Windows
• start openCRX Server
• for each of your segments (e.g. Standard) login as segment administrator (e.g. admin-Standard) and run the wizard Segment Setup ([Home] - Wizards > Segment Setup) to bring your configuration up to date
• optionally: you can now uninstall the new installation of openCRX as it is no longer needed

^top

How to add additional languages to openCRX?

The openCRX Language Localization Guide explains in detail how you can add new languages to openCRX or even make your own openCRX language pack. From a technical point of view, adding languages is a trivial issue; the big task is translating all the code tables, labels and tool tips.

The following languages are currently available or being worked on:

If you want to contribute and are ready to translate a bunch of strings into a new language, .

^top

How to load a language-specific login page?

If a login page supports locale xx_YY you can request the login page in that locale xx_YY by appending the string "?locale=xx_YY" to the default login URL.
Example: the URL http://demo.opencrx.org/opencrx-core-CRX/Login.jsp?locale=de_CH directly loads the German login page.

^top