Changing Repository Database

Documentation home 

 

Introduction

 

All elements created using the Ebase Xi Designer are stored in the Repository Database, and Ebase Xi is supplied with a Repository Database using embedded Apache Derby. This document contains instructions for switching the Repository Database to another database provider. There are three supported databases in addition to Apache Derby: Mysql, Oracle and MS Sql Server. Other databases can also be used but database schema scripts are not supplied; these would need to be created using standard database tools.

 

The process consists of the following steps:

 

·         Export existing content

·         Create the new database with minimum content

·         Configure the server to use the new database

·         Import existing content (from step 1)

 

Please follow the detailed instructions below. You should follow all steps even if you have not yet created anything using the designer.

 

Note: if you have installed Ebase Xi to the “Program Files” folder on a Windows system, you may experience problems editing some of the configuration files mentioned below as the files are read only. If you have this problem, you will need to launch the editing tools e.g. Notepad as administrator e.g. right click on the application in the start menu and select Run as administrator.

Export existing content

 

1.      Check that the export file location is configured. Open file UFSSetup.properties in folder UfsServer/tomcat/webapps/ufs/WEB-INF/classes; check that parameter Ufs.export.location is specified. In the distributed system, this parameter contains the value ../../transport_files/  which resolves to UfsServer/transport_files. If not already specified, configure parameter Ufs.export.location and restart the server.

 

2.      Check that the export file location directory from the previous step exists. If not, create it.

 

3.      In the Ebase Designer, open the export dialog from the menu: Tools --> Migration --> Export.

 

4.      Click on the Export to directory tab.

 

5.      Check Export all and uncheck Exclude Security.

 

 

6.      Click View details and export, then click Export on the next screen.

 

Create the new database

 

1.      The database schema script files are located in directory databaseSchemas of the standard Ebase Xi distribution. These script files have been tested using MySQL-Front (Mysql),  SqlPlus (Oracle), Enterprise manager (MS Sql Server) and may need slight adjustments when used with other tools.

Run the following scripts where x is the database type (e.g. 01-create_DB_oracle.sql).

 

  • 01-create_DB_x.sql

Creates 2 databases/schemas – ufs and ebase_samples

Note: The following scripts create and populate tables in these 2 databases/schemas. You may change the database/schema names to suit your own naming conventions.

  • 02-repository_tables_x.sql

Connect to database/schema ufs before running the script.

Creates repository tables in ufs and populates tables with minimum data to allow the server to start and user ebaseuser to login to the designer.

  • 03-sample_forms_tables_x.sql  (optional – used by examples and tutorials)

Connect to database/schema ebase_samples before running the script.

Creates and populates tables in ebase_samples used by Test and Sample forms.

 

For MS Sql Server, ignore any warning messages about maximum row sizes.

Configure the server to use the new database

 

2.      Open file ufs.xml in directory UfsServer/tomcat/conf/Catalina/localhost.

 

3.      Comment the existing Derby resource definitions at the top of this file for jdbc/UFSREPOSITORY and jdbc/EBASE_SAMPLES (Comments begin with <!-- and end with -->).

 

4.      This file contains commented examples of resource definitions for all supported databases. Remove the comments lower down in the file for resources jdbc/UFSREPOSITORY and jdbc/EBASE_SAMPLES for your database system (Mysql, Oracle or MS Sql Server).

 

5.      Change the url, username and password parameters for both of these resources to point to the database system where you have created the new databases.

 

6.      If you are switching to either Oracle or Mysql and this is the first time you have connected to one of these databases, you must also install the appropriate JDBC driver file. These can be downloaded using these links:

 

 

Copy the JDBC driver file to UfsServer/tomcat/lib.

 

7.      Restart the server – ignore any error messages relating to missing System Services: WORKFLOW_ASSIGNMENT_SERVICE or LOGON_SERVICE.

 

Possible errors restarting the server

Editing the ufs.xml can often cause problems restarting the server. This includes..

 

Error messages indicating that the system cannot connect to the repository database are issued when the server is started. Frequently, the error messages are not specific enough to identify the reason for the failure.

Possible causes include:

  • Syntax error in the ufs.xml file. Check that the any comment blocks are correctly closed <!--  -->.
  • url parameter is incorrect – database system is not running on the target host, the port is incorrect etc
  • username or password parameter is incorrect
  • JDBC driver file is not installed

 

No error messages or information messages are shown when the server is started. Cannot connect using the designer.

  • There is probably a syntax error in the ufs.xml file. Check that the any comment blocks are correctly closed <!--  -->.

 

If you cannot resolve these problems, revert to using the supplied Apache Derby embedded database. Then use the Database Connection Wizard from the designer to check if you can connect to the new database (Tools --> Database Connection Wizard).

Import existing content

 

8.      Sign on to the designer using user ebaseuser, password ebaseuser.

 

9.      Open the import dialog from the menu: Tools --> Migration --> Import.

 

10.  Click on the Import from directory tab.

 

11.  Check Clean Build and uncheck Exclude Security.

 

 

12.  Click View details and import, then click Import on the next screen.