Configure the Runtime built-in scheduler

The runtime built-in scheduler uses a database to stores all of its schedules, and saves its options in an XML file.

The default database is an HSQL database built into the runtime, only accessible from the runtime itself by default. It provides a ready-to-use configuration. In production environments, use a certified database server instead.

Overview

To configure the runtime scheduler for your environment:

  1. In the certified database system of your choice, set up a database and schema to host the schedules.

  2. Create a database user to access the new schema.

  3. Use the provided scripts to create the required scheduler tables in the target schema.

  4. Configure the properties/engineParameters.xml file as explained furthe in this article.

  5. Restart the runtime.

If you are using the default runtime configuration, you can skip most of these steps.

Configuring the scheduler

Configuration file

The main runtime scheduler options are in the configuration file engineParameters.xml, in the properties subdirectory of the runtime installation path. The scheduler options are between <scheduler></scheduler> XML tags.

Example 1. Sample scheduler configuration (engineParameters.xml)
<parameters>
  <...>
  <scheduler>
    <!-- Main properties -->
    <parameter name="org.quartz.scheduler.instanceName" value="RUNTIME_HSQL_STD"/>
    <parameter name="org.quartz.scheduler.instanceId" value="RUNTIME_HSQL_STD"/>
    <!-- Configure ThreadPool -->
    <parameter name="org.quartz.threadPool.class" value="org.quartz.simpl.SimpleThreadPool"/>
    <parameter name="org.quartz.threadPool.threadCount" value="3"/>
    <!-- Configure Jobstore -->
    <parameter name="org.quartz.jobStore.misfireThreshold" value="10000"/>
    <parameter name="org.quartz.jobStore.class" value="org.quartz.impl.jdbcjobstore.JobStoreTX"/>
    <parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.StdJDBCDelegate"/>
    <parameter name="org.quartz.jobStore.useProperties" value="false"/>
    <parameter name="org.quartz.jobStore.dataSource" value="internal"/>
    <parameter name="org.quartz.jobStore.tablePrefix" value="STB_"/>
    <parameter name="org.quartz.jobStore.isClustered" value="false"/>
    <!-- Configure Datasources -->
    <parameter name="org.quartz.dataSource.internal.driver" value="org.hsqldb.jdbcDriver"/>
    <parameter name="org.quartz.dataSource.internal.URL" value="jdbc:hsqldb:file:internalDb/scheduler/scheduler"/>
    <parameter name="org.quartz.dataSource.internal.user" value="backend-user"/>
    <parameter name="org.quartz.dataSource.internal.password" value="backend-password"/>
    <parameter name="org.quartz.dataSource.internal.connectionProvider.class" value="com.indy.engine.scheduler.XdiQuartzConnectionProvider"/>
    <parameter name="org.quartz.dataSource.internal.maxConnections" value="5"/>
    <parameter name="org.quartz.dataSource.internal.module" value="internal"/>
    <...>
  </scheduler>
  <...>
</parameters>

Legacy configuration file

Previous versions of Runtime used an engineScheduler.properties file to store scheduler configuration information. Runtime still supports this file for compatibility purposes.

To use an engineScheduler.properties file from previous Runtime versions:

  1. Remove the <scheduler></scheduler> section from the engineParameters.xml file.

  2. Add your engineScheduler.properties file to the properties directory in the Runtime installation directory.

Support for this file may be removed in future releases.

Settings

The runtime uses the Quartz library. You can add or modify its parameters in the configuration file.

Notable settings

The org.quartz.jobStore.misfireThreshold parameter defines how long in milliseconds the runtime should wait after a delivery schedule has misfired, before moving on to its next schedule. For example, a schedule may misfire because another one was still running, so the runtime waits before continuing.

Use the built-in HSQL database system

You can keep most scheduler settings as-is to use the built-in HSQL database.

Change the scheduler database directory

When using the built-in database, the runtime looks for a database directory and files, and creates them as necessary. The directory and database names are defined in a JDBC URL, in the org.quartz.dataSource.internal.URL parameter.

The default is internalDb/scheduler/scheduler, which corresponds to a scheduler database in the internalDb/scheduler path relative to the installation directory:

Example 2. Default scheduler database directory and file names
<parameter name="org.quartz.dataSource.internal.URL" value="jdbc:hsqldb:file:internalDb/scheduler/scheduler"/>

You can set the path in the JDBC URL to a different relative or absolute filesystem path. If you change the path, make sure the location has filesystem write permissions enabled.

Use another database system

In production environments, use a certified database server to store scheduler information. Follow these steps to get them working.

Prepare the database

First, prepare your chosen database system.

Create the database and schema

Create a database and database schema to host the schedules. Then create a database user to access this schema, and set its password.

Create the tables

Go to the scripts/scheduler subdirectory of the runtime installation path, and find the script which corresponds to your database technology.

Open this script in a text editor. Find the lines which contain the text XDI_RUNTIME_SCHEDULER. They may look like this, depending on your choice of database:

INSERT INTO stb_locks values('XDI_RUNTIME_SCHEDULER', 'TRIGGER_ACCESS');
INSERT INTO stb_locks values('XDI_RUNTIME_SCHEDULER', 'JOB_ACCESS');
INSERT INTO stb_locks values('XDI_RUNTIME_SCHEDULER', 'CALENDAR_ACCESS');
INSERT INTO stb_locks values('XDI_RUNTIME_SCHEDULER', 'STATE_ACCESS');
INSERT INTO stb_locks values('XDI_RUNTIME_SCHEDULER', 'MISFIRE_ACCESS');

This text define the scheduler instance name and ID. You can leave the lines as-is, or change all instances of XDI_RUNTIME_SCHEDULER to a single unique name of your choice. If you change the script, save the file.

Run this script on the database schema you created.

Add JDBC drivers

For the runtime to communicate with the database hosting your schedules, you must install its JDBC driver and libraries to a Runtime module.

The modules subdirectory of the runtime installation directory contains other subdirectories, and each one corresponds to a module. Install your JDBC driver to a new or existing directory, and note the directory name for the next step.

Edit the configuration file

Edit the engineParameters.xml file to add database settings. You need to change at least the following parameters:

Parameter Description

org.quartz.scheduler.instanceName

Scheduler instance name. Set this parameter to the value in the setup script, XDI_RUNTIME_SCHEDULER` by default.

org.quartz.scheduler.instanceId

Scheduler instance ID. Set this parameter to the value in the setup script, XDI_RUNTIME_SCHEDULER` by default.

org.quartz.jobStore.driverDelegateClass

Choice of the Quartz driver delegate for the appropriate database.

org.quartz.dataSource.internal.URL

JDBC URL for your chosen database.

org.quartz.dataSource.internal.user

Chosen database username.

org.quartz.dataSource.internal.password

Chosen database password.

org.quartz.dataSource.internal.module

Name of the module directory you installed JDBC drivers to.

The following examples show the relevant parameters and example values. Modify them for your environment as needed.

Example 3. Scheduler configuration for Microsoft SQL Server
<!-- Main properties -->
<parameter name="org.quartz.scheduler.instanceName" value="XDI_RUNTIME_SCHEDULER"/>
<parameter name="org.quartz.scheduler.instanceId" value="XDI_RUNTIME_SCHEDULER"/>
<...>
<!-- Configure Jobstore -->
<parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.MSSQLDelegate"/>
<...>
<!-- Configure Datasources -->
<parameter name="org.quartz.dataSource.internal.driver" value="com.microsoft.sqlserver.jdbc.SQLServerDriver"/>
<parameter name="org.quartz.dataSource.internal.URL" value="jdbc:sqlserver://mssql-server-url.net:1433;sendStringParametersAsUnicode=false;encrypt=true;trustServerCertificate=true"/> (1)
<parameter name="org.quartz.dataSource.internal.user" value="mssql-user"/> (2)
<parameter name="org.quartz.dataSource.internal.password" value="mssql-password"/> (2)
<...>
<parameter name="org.quartz.dataSource.internal.module" value="default"/> (3)
1 Change the URL and parameters to those of your database server.
2 Change to your SQL server username and password.
3 Change to the name of the module with the Microsoft SQL Server JDBC driver.
Example 4. Scheduler configuration for Oracle Database
<!-- Main properties -->
<parameter name="org.quartz.scheduler.instanceName" value="XDI_RUNTIME_SCHEDULER"/>
<parameter name="org.quartz.scheduler.instanceId" value="XDI_RUNTIME_SCHEDULER"/>
<...>
<!-- Configure Jobstore -->
<parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.oracle.OracleDelegate"/>
<...>
<!-- Configure Datasources -->
<parameter name="org.quartz.dataSource.internal.driver" value="oracle.jdbc.driver.OracleDriver"/>
<parameter name="org.quartz.dataSource.internal.URL" value="jdbc:oracle:thin:@xdi-runtime-backend-database.net:1521:xe"/> (1)
<parameter name="org.quartz.dataSource.internal.user" value="oracle-user"/> (2)
<parameter name="org.quartz.dataSource.internal.password" value="oracle-password"/> (2)
<...>
<parameter name="org.quartz.dataSource.internal.module" value="default"/> (3)
1 Change the URL and parameters to those of your database server.
2 Change to your Oracle server username and password.
3 Change to the name of the module with the Oracle JDBC driver.
Example 5. Scheduler configuration for PostgreSQL
<!-- Main properties -->
<parameter name="org.quartz.scheduler.instanceName" value="XDI_RUNTIME_SCHEDULER"/>
<parameter name="org.quartz.scheduler.instanceId" value="XDI_RUNTIME_SCHEDULER"/>
<...>
<!-- Configure Jobstore -->
<parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.PostgreSQLDelegate"/>
<...>
<!-- Configure Datasources -->
<parameter name="org.quartz.dataSource.internal.driver" value="org.postgresql.Driver"/>
<parameter name="org.quartz.dataSource.internal.URL" value="jdbc:postgresql://xdi-runtime-backend-database.net:5432/postgres"/> (1)
<parameter name="org.quartz.dataSource.internal.user" value="postgres-user"/> (2)
<parameter name="org.quartz.dataSource.internal.password" value="postgres-password"/> (2)
<...>
<parameter name="org.quartz.dataSource.internal.module" value="default"/> (3)
1 Change the URL to that of your database server.
2 Change to your PostgreSQL server username and password.
3 Change to the name of the module with the PostgreSQL JDBC driver.

Restart the runtime

Restart the runtime to apply your settings. The runtime now uses your database for runtime scheduling.