If you want to add support for an unsupported database system, you found the right documentation. This step-by-step guide describes all the steps that need to be processed in order to support a new database system.
1.1 QA Test suite
First we need to make sure, what is the qa test suite. With Activiti there are two projects that make up the qa. These are:
These tests need to be run successfully before we consider Activiti to support a database system.
1.2 Run a test with H2
Before we start to go through all the steps, we should execute the test scripts on an already supported database. We assume, you already checked out the activiti project, setup the demo and configured ant and maven on your system.
Before we can run the test, we need to provide a database connection. This is done via a properties file located in <user_home>/.activiti/jdbc. There create a file called h2.properties adding this content:
This setup assumes an installed h2 database with no tables in it! All tests are constructed to create the database before running the test and dropping the database after finishing the tests. If you have setup the database and the configuration file, you can proceed with the next command.
Navigate to the “activiti-engine-examples”-project and execute following command:
mvn --Ddatabase=h2 clean install
You should see lots of info on the console. Most important are the tests that are run with this command. You also saw the creation and dropping of the database before and after the testing. This defines another point in the configuration for a new database system.
2 Step-by-Step Guide
Now we will describe the parts that have to be completed for the purpose of this document. These are:
- Setup a database with schema and user
- Modify the database creation and deletion
- Add configuration file to activiti´s user_home
- Modify the pom.xml
- Running the test project
- Analyze test-results
- Run QA Test suite script
2.1 Setup a database with schema and user
This should be the easiest part of the description. You need to setup the database you want to test with a schema and a user. The user needs to have enough privileges to execute all the following sql statements.
You may already write down the information that is needed to connect to this database and fetch the jdbc driver for this database. Then you can proceed to the next step.
2.2 Modify the database creation and deletion
Activiti uses two sql files to create and drop the database tables. These are located at:
<db-profile> is an identifier; you would also use it to run your tests against. We did that in chapter “Run a test with H2”. Before you can start the testing of Activiti against a new database, you need to setup these two scripts. Start with copying the two files and rename them to your <db-profile> setting. After that you need to work out create, alter and drop statements for your database system. Be cautious to place those files in the same directory!
2.3 Add configuration file to activiti´s user home
As we did in the introduction sample, you have to provide the database connection configuration in the activiti user home directory. Please create a properties file like this:
You need to add the jdbc parameters like this
This is just a sample configuration for h2! You need to change the properties to your database environment.
2.4 Modify the pom.xml
Since the database connection is achieved by jdbc, you need to provide a jdbc-driver for the tests. There are two ways you can provide the jdbc driver:
- Adding the appropriate dependency to maven pom.xml
- Install jdbc driver to your local maven repository
If you have a maven dependency xml snippet for your jdbc driver, fine! Then you can skip the next step and go directly to step 2 “Modify maven pom.xml”. Otherwise you need to install the library into your local maven repository first.
1 Install the library into your local maven repository
mvn install:install-file -Dfile=<path to library> -DgroupId=<groupId>-DartifactId=<artifactId> -Dversion=<version> -Dpackaging=jar
Example for mysql:
mvn install:install-file -Dfile=mysql.jar -DgroupId=mysql -DartifactId=mysql-connector-java driver -Dversion=5.1.6 -Dpackaging=jar
After having installed the library you should now get the dependency snippet like this:
You can this example as basis and add your dependency information here. Make sure you have the scope property set to “test”. This dependency is only needed for tests. In a running Activiti scenario you would provide the jdbc driver for the activiti-engine. But this goes beyond the scope of this document.
2 Modify the pom.xml
If you open the pom.xml from one of the mentioned projects, you will see an xml file. Navigate to the dependencies area of the database profile. This should like this:
You can add your database driver dependency at the marked location. Save the file and proceed to the next step. You may return to this step to also modify the pom.xml for the other activiti project.
2.5 Runing the test project
You can run the test from the command line located in the appropriate test project. This is either “activiti-engine-examples” or “activiti-engine-test-api”. To be sure that your changes in project activiti-engine are up to date, run
mvn clean install
from the activiti-engine project location. After that execute this command:
mvn --Ddatabase=<db-profile> clean install
* *If you got lucky and the test didn´t fail one test, you can proceed with the other project. For the unlucky guys like mine, proceed with the next step!
2.6 Analyze test results
This is the hardest part and I can only give you some advice how to get to the cause of test failures. Any test logs errors and output to the target folder. In case of errors search for
These reports should help you a lot to get the conditions on which those errors rely on. The following points are at least a checklist or advice list I found out adding support for some databases:
- If tests fail, drop the database table yourself before running the mvn command once again. The database will only be dropped, if the tests fail on assertion, not on exceptions.
- Debugging tests might help to get the processing right. This helped me a lot to encounter wrong myBatis sqls.
- If you get errors like “database not clean” or “expected 0 got 3”, this could be due to timing problems. We had lots of them adding mysql! But these might also derive from system performance. At least for some tests with timers.
- Sorting algorithm might also be a point you should consider.
- Always start investigating on the first job that failed. The others might be due to the circumstances that flawed test consigned.
If you encounter a bug in the test, you can file a bug in JIRA! Otherwise after you fixed something you can once again run the test.
2.7 Run QA test suite script
Last step is to successfully run the qa script. This test combines creation of activiti-engine and executing all tests for database support. If this test is successful, you have added support for your database environment. We would be happy, if you would provide those scripts to the community.