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 CVS repository?
• Where is the documentation of the openCRX API (aka Javadoc)?
• Where are the openCRX UML models and how can I browse them?

Groupware Features

• Which ActiveSync clients can I use to connect to openCRX?
• Which CalDAV 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?

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 CVS repository.

^top

Where is the openCRX CVS respository?

This project's CVS repository can be checked out through anonymous (pserver) CVS with the following instruction set. The CVS tree is publicly accessible for anonymous read-only access, approved contributors will also be given commit access to appropriate packages. When prompted for a password for anoncvs, enter anoncvs.

Linux / Unix / BSD	Windows
CVSROOT=:pserver;username=anoncvs;password=anoncvs:cvs.opencrx.org:/var/cvs export CVSROOT cvs login    # enter anoncvs when prompted for a password cvs checkout opencrx	TortoiseCVS Settings

Please note that building openCRX from CVS 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.

^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.6.0:

• Apple's iPhone with OS3 works flawlessly.

Configuration hints are available in the openCRX Admin Guide.

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

^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 works flawlessly.
• Mozilla's Sunbird and Mozilla's Lightning, the calendaring add-on for Mozilla's Thunderbird, are not only the best-tested cross-platform CalDAV clients, they also work flawlessly with openCRX. We tested Sunbird 1.0 (beta 1) and Lightning 1.0 (beta 1) (with Thunderbird 3.0). These CalDAV clients work very well in a setting where you're always online (i.e. connected with the openCRX server) as changes to remote calendars are submitted immediately. Neither Sunbird nor Lightning are well suited for working offline (e.g. it is not possible to enter/change information while offline so that it will get synchronized reliably during the next online session).
• 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.
• Mulberry kind of works - seems a bit sluggish, though.

Configuration hints for various clients are available in the openCRX Admin Guide.

We have not been able to get OpenConnector's CalDAV feature to work properly with Outlook and openCRX, but based on the information published on the project's website (http://openconnector.org/) you will probably have to wait for a later version or hope for Microsoft to get their act together and add CalDAV support to Outlook (apparently, Microsoft joined CalConnect on 15 August 2007 - let's hope they did not join to slow down everything...). As an alternative that works for sure you might consider our Outlook ICS Adapter.

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

^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 Sunbird and Mozilla's Lightning, the calendaring add-on for Mozilla's Thunderbird, are not only the best-tested cross-platform ICS/iCalendar clients, they also work flawlessly with openCRX. We tested Sunbird 1.0 (beta 1) and Lightning 1.0 (beta 1) (with Thunderbird 3.0). These calendar clients work very well in a setting where you're always online (i.e. connected with the openCRX server) as changes to remote calendars are submitted immediately. Neither Sunbird 1.0 nor Lightning 1.0 are well suited for working offline (e.g. it is not possible to enter/change information while offline so that it will get synchronized reliably during the next online session).
• KDE Contact works very well with openCRX
• Apple's iPhone works flawlessly with openCRX (even though iPhone OS 3.0 subscriptions to openCRX ICS calendars are read-only)
• Microsoft Outlook 2003 and Microsoft Outlook 2007 : use our Outlook ICS Adapter

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.

Additional information about IMAP 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.4.0 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 (both MS SQL 2000 and MS SQL 2005)
	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 v8.3.5 (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/Sdk24.FromHSQLDBToOtherDB.

^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 Oracle's JRockit (formerly BEA JRockit). Unfortunately, the latter is not really free anymore, i.e. unless you have a license to use JRockit your choice will be the Sun Java VM.

^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:

• IE 6.0 SP1+, IE 7.0, IE 8.0
• Opera 9.10+, Opera 10.0++
• Mozilla 1.7.3+
• Firefox 2.0+ , Firefox 3.0+, Firefox 3.5+
• Safari 3.0+, Safari 4.0+
• Google Chrome 1.0+, Google Chrome 2.0+, Google Chrome 3.0+, Google Chrome 4.0+, Google Chrome 5.0+

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.5.3 to v2.6.0
(upgrade instructions for previous releases can be found here):

Upgrading from openCRX v2.5.3 to openCRX v2.6.0

	Do NOT upgrade from 2.5.0/2.5.1 to 2.5.2 directly - you must first upgrade to v2.5.3 to prepare for the upgrade to v2.6.0
	DB Scripts are contained in the openCRX SDK Installer pre-built EARs are contained in the openCRX Server Installer in the directory {Server Installation Directory}\apache-tomcat-6\apps
	If you have custom projects, don't forget to adapt the schema paths in the ui and code files as indicated in the release notes.

• stop the servlet container (Tomcat, application server)
• backup your database
• upgrade your database as follows (DB scripts are available in the openCRX SDK, in the directory {openCRX_SDK_Install_Directory}\opencrx-2.6.0\core\src\sql):
  • drop all (openCRX) views (statements are available in the script dbcreate-views.sql)
  • execute the script upgrade-from-2.5-to-2.6.sql
  • execute the script migrate-from-2.5-to-2.6.sql
  • execute the script drop-from-2.5-to-2.6.sql
  • on the upgraded database, execute the script dbcreate-views.sql
    

    Hint: in case execution of the script is stopped and rolled back because of failing statements, you need to investigate the issue. DROP statements of non-existing tables/views can safely be deleted from the script. However, the CREATE statements must execute without errors. You can safely execute this script multiple times until there are no more errors.

  • on the upgraded database, execute the script dbcreate-indexes.sql

    Hint: execution of this script is optional; we just provide some indices as a starting point; DB tuning depends very much on the data, the usage pattern, and obviously on the DBMS you are using. Hence, running is script is no replacement for database tuning. You might have to remove statements trying to create indices that already exist.

  • on the upgraded database, execute the script populate-preferences.sql

    Hint: execution of this script is required to configure the database plugin - if there are any errors you must investigate the issue. You can safely execute this script multiple times until there are no errors left.

• install openCRX 2.6.0 with the openCRX Server Installer in a new directory (that is the easiest way to get the new files, but you could also download and install the openCRX 2.6.0 Software Development Kit to build the same files) and then proceed as follows to upgrade your existing installation:
  • create the new directory {TOMCAT_INSTALL_DIR}/airsyncdir
  • delete the contents of the following directories of your existing installation:
    • {TOMCAT_INSTALL_DIR}/apps
    • {TOMCAT_INSTALL_DIR}/temp
    • {TOMCAT_INSTALL_DIR}/work
    • {TOMCAT_INSTALL_DIR}/conf/Catalina/localhost
  • delete the following files of your existing installation:
    • {TOMCAT_INSTALL_DIR}/lib/catalina.jar
    • {TOMCAT_INSTALL_DIR}/lib/openmdx-base.jar
  • copy the files openmdx-base.jar and catalina.jar from the new installation to your existing installation (directory {TOMCAT_INSTALL_DIR}/lib)
  • copy the files opencrx-core-CRX.ear and opencrx-apps-CRX.ear (the latter is only needed if you want to run openCRX/Store) from the new installation to your existing installation (directory {TOMCAT_INSTALL_DIR}/apps)
  • start Tomcat of your old/upgraded installation
• 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
  • import codes and data
  • set the access levels of codes (you must change to the Perspective Advanced)
  • start openCRX
• in the case of HSQLDB, copy your upgraded DB over the DB installed by the openCRX Server Installer, or if you use another DBMS, adapt the database connector to your own database as explained here.
• you can now uninstall the new installation of openCRX as it is no longer needed
• for each of your segments (e.g. Standard) login as segment administrator (e.g. admin-Standard) and delete the pre-configured
  • favorites (Home > Favorites)
  • export profiles (Home > Export Profiles)
  • document templates (Label Template, Contract Templates, ...) (Folders & Documents > Folders)
  • document folders (Mail Merge Templates, Opportunity Templates, etc.) (Folders & Documents > Folders)
• 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

^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