Connect to an External Terminology Database

You can connect Acrolinx to a database other than the freely distributed database formats, which are installed with the Acrolinx Core Platform.

Configuring the connection requires knowledge of the operating system in use, TCP/IP networks, client-server systems, and the necessary communication protocols as well as knowledge of XML. You must also be familiar with the Acrolinx Administration Guide.

Major Steps

To connect to an external terminology database, confirm that your database format is supported, create a new database and database user for Acrolinx, and configure the persistence properties file in your Acrolinx installation. If you’re migrating an existing terminology database, ensure that you back up your terms first.

To connect to an external terminology database, follow these major steps:

  1. If you’re migrating terms from a native Acrolinx terminology database, create a database backup from your existing terminology database.
  2. If you’re installing the Acrolinx Core Platform on a new computer, install Acrolinx and guidance packages according to the standard installation procedures in the Acrolinx Administration Guide.
  3. Prepare the external terminology database
  4. Edit the database configuration properties in the persistence properties file.
  5. If you’re migrating terms from a native Acrolinx terminology database, restore your database backup.

Supported Database Formats

For an up-to-date list of supported database formats, see the "Database" tab of the Acrolinx compatibility guide.

As of Core Platform 5.5 we no longer ship the DB2 driver.

Creating a Database Backup from an Existing Terminology Database

If you’re migrating an existing Acrolinx terminology database to an external database, you must first create a database backup from your existing Acrolinx Core Platform installation.

To open the database backups page:

  • In the Navigation Menu, click Terminology > Import and Export > Database Backups.

To create a database backup, follow these steps:

  1. Click Create Database Backup.
  2. Right-click the Download Link that appears, and click Save Target As.

Preparing an External Terminology Database

To prepare an external terminology database for Acrolinx, follow these steps:

  1. Create a new empty database on your database server with the name of your choice.
    • We recommend selecting UTF-8 encoding for the database as this encoding type guarantees the ability to store terms in any language.
    • If you use a Microsoft SQL Server database, you must select a case-sensitive collation such as "SQL_Latin1_General_CP1_CS_AS" for the database. The default case-insensitive collation can cause problems with Acrolinx.
    • If you use a MySQL database, you must select a case-insensitive UTF-8 collation for the database. Case-sensitive collations can cause problems with Acrolinx.
  2. Configure a username and password, which has full write permissions on your new database.
    • If you use an Oracle database to store reporting and terminology data, ensure that the username for the terminology database is different to the username for the reporting database. In Oracle databases, usernames are associated with a specific database schema.

Editing the Database Configuration Properties

You can configure a connection to an external terminology database by creating an overlay of the installed persistence properties file. You update the persistence properties overlay with the connection details for your database and restart Acrolinx.

To configure the Acrolinx Terminology Manager to connect to your database, follow these steps:

  1. Stop the core server.
  2. Open your overlay of the following file:

    If you haven’t yet created an overlay of this file, create a new version of the file at the following location:


    Don’t edit the installed version of the file. Instead, always edit your overlay copy in the configuration directory.

  3. Add the following properties:


    Replace the placeholder values with the connection details for your database:

    • Replace the placeholder <DATABASE_TYPE_SHORTNAME> with one of the following values:


    • Replace the placeholder <DATABASE_USERNAME> with the username that you defined in the procedure 'Preparing a Database'.
    • Replace the placeholder <DATABASE_PASSWORD> with the password that you defined in the procedure 'Preparing a Database'.
    • Replace the placeholder <DATABASE_URL> with the location of your database.

      The syntax of the jdbcUrl parameter can vary depending on the database format. To help you understand the syntax, sample values for the jdbcUrl parameter have been provided in the installed persistence properties file. The jdbcUrlparameter usually requires the IP address, the port, and the name of the database. The following table lists the standard syntax of the jdbcUrl parameter for the different database types:

      Database TypeSyntax of the jdbcUrl ParameterExample
      MS SQLjdbc:jtds:sqlserver://<DB_SERVER_ADDRESS>:<DB_PORT>/<DB_NAME>jdbc:jtds:sqlserver://

      If you’re connecting to a MySQL database, ensure that you use UTF-8 character encoding when configuring the connection to your database server. You configure UTF-8 character encoding by adding the parametersuseUnicode=yes&characterEncoding=UTF-8 to the database URL. The file contains an example of a MySQL database URL that you can use as a reference.

    If you want to connect to a database on a Microsoft SQL Server, change your properties to look something like the example properties below. Be sure to adjust the user, password, and jdbcUrl values, which are specific to your environment:

  4. Save your changes and restart the core server.
  5. Check the core server log file for any errors or warnings.

Restoring Your Database Backup

If you’ve configured the Acrolinx to connect to a different database for storing terminology and want to use existing terminology data, you must restore a database backup made from your original terminology database.

To open the database backups page:

  • In the Navigation Menu, click Terminology > Import and Export > Database Backups.

To restore a database backup, follow these steps:

  1. Locate the database backup file using the Browse button.
  2. Click Restore Database Backup.
  3. In the security dialog, which appears, enter the word yes and click OK.

    This type of dialog is an extra precaution to prevent you from overwriting your terminology database unintentionally.

    The import operation starts and a confirmation prompt appears when the import has completed.

  4. Restart all servers (for more information, see the Acrolinx Server Administration Guide).

    If the configurations of all installed language servers aren’t reloaded, the term help files don’t load correctly.