Scheduled jobs

OpenCms allows to perform jobs at a certain date and time, or to repeat jobs in a certain interval. A whole set of useful jobs is already predefined and can be configured. But you can also write, configure and schedule your own jobs. We describe how to schedule an already defined job and provide a short description of the already predefined jobs.

Page Navigation

1 Why scheduling jobs?

Many actions, you may want to take place instantly. But for some actions there are good reasons to perform them at a certain time or date, or to automatically repeat them in a specified time interval. For example:

Publish a project's resources at a certain time when they should go "online".
Clean up the image cache frequently
Delete expired resources from time to time
...

The reason for executing a one-time-task scheduled may have two different reasons. Either, the task's result should not appear before a certain date, or the task is resource intensive and should be performed at a time when your website is not visited too often, e.g., over night.

2 The interface to manage scheduled jobs

In the administration view, you find the "Scheduled Jobs" administraion. When you click it, the "Scheduled Jobs Management" opens.

Fig. [administration_scheduled_jobs]: Administration view for scheduled jobs management

The "Scheduled Jobs Management"-view provides options to create a new job and to view the list of existing jobs.

The list's colums show:

E: Click the icon in the cell to edit the scheduled job.
A: Activate or deactive a job by clicking the icon in the cell (deactivated jobs have a gray icon, actived a blue one).
C: Click the icon in the cell to copy the scheduled job and thus create a new, similar job.
D: Click the icon in the cell to delete the job.
X: Click the icon to execute the scheduled job directly.
Name: Shows the name of the job. Clicking at the name, you can edit the job.
Class: The fully qualified name of the Java class that handles the job.
Last Execution: The date when the job was executed last.
Next Execution: The date when the job is executed next.
Check box: Check/uncheck all jobs by clicking the checkbox in the header or select/unselect single jobs to activate, deactivate or delete all selected jobs by clicking the respective buttons at the right-hand side directly above the table.

Using the "Search" option, you can filter jobs in the list by their name. By the options on the right-hand side above the list, you can show or hide information about the context and the parameters configured for a job, or show a printable version of the job list.

3 Adding and editing jobs

For adding a new job or editing an existing job, a form appears. It has two pages, where on the first page you provide information necessary for every job, and on the second page you can set parameters handed over to the Java class that executes the job.

Fig. [edit_scheduled_job]: Dialog for editing a scheduled job (page 1)

At the first page of the dialog for editing jobs, as shown in Figure [edit_scheduled_job], you first get displayed the current server time and then you can fill out the following options for the job.

Job settings

Job name: Name of the job used in the job list.
Java class: Java class that executes the job. The class has to implement org.opencms.scheduler.I_CmsScheduledJob. There are several classes shipped with OpenCms. They can be selected via a drop-down list.
Cron expression: A cron expression that specifies when the job should be executed. See below for the syntax of cron expressions.
Reuse instance: If checked, an instance of the class executing the job is created only when the job is executed the first time. The instance is then used for all repetitions of the job. If unchecked, the job is performed by a new instance each time.
Active: If checked the job performed at the specified dates (see the cron expression). If unchecked, the job is still listed, but not permformed.

In another box, you have to provide context information. Each job performed in OpenCms must be performed in a context, i.e., by a user, in a project, for a locale, etc. The context specific settings are:

Context settings

User name: Name of the user that is used to execute the job.
Project: Project in which the job is executed
Site root: The site root to which URLs are relative. By default this is "/"
Requested URI: The requested URI set in the context used when the job is executed. By default it is "/".
Locale: The locale set in the context used when the job is executed. By default it is "en".
Encoding: The character encoding set in the request context used to execute the job. By default it is "UTF-8"
Remote address: The remote address set in the request context used to execute the job. By default it is "127.0.0.1".

The parameters configured at the second page depend only on the Java class that executes the job. So look the available parameters up at the respective classes.

3.1 Writing correct cron expressions

Cron expressions specify when a job should be executed. The syntax for specifying the dates is inspired by the cron job scheduler. An overview on how to write cron expressions and a lot of example expressions are given in the JavaDoc of the class org.opencms.scheduler.CmsScheduledJobInfo.

4 Job classes shipped with OpenCms

OpenCms already ships with classes to perform typical jobs. Here's a brief description of the classes. For further information consult the JavaDoc.

Most of the classes can be configured by parameters. Information on the parameters is found in the JavaDoc.

Provided classes to perform jobs

org.opencms.relations.CmsInternalRelationsValidationJob: Checks internal relations and sends the result via email.
org.opencms.scheduler.jobs.CmsPublishJob: Supports time based publishing of a project.
org.opencms.scheduler.jobs.CmsStaticExportJob: Creates a complete static export of a site.
org.opencms.relations.CmsExternalLinksValidator: Checks external links (resource type "pointer").
org.opencms.monitor.CmsMemoryMonitor: Writes information about the server's memory usage to the OpenCms log-file.
org.opencms.search.CmsSearchManager: Rebuilds search indexes.
org.opencms.notification.CmsContentNotificationJob: Sends notification emails to responsible users if content has not changed in a certain time period or is released or expired.
org.opencms.scheduler.jobs.CmsCreateImageSizeJob: Checks the size of all images in the OpenCms VFS and downscales them if configured.
org.opencms.scheduler.jobs.CmsImageCacheCleanupJob: Clears the image cache for scaled images that exceed a specified age.
org.opencms.scheduler.jobs.CmsHistoryClearJob: Clears the file history.
org.opencms.scheduler.jobs.CmsDeleteExpiredResourcesJob: Deletes expired resources.
org.opencms.scheduler.jobs.CmsUnsubscribeDeletedResourcesJob: Unsubscribes deleted resources.

5 Background on the job configurations

The configuration of scheduled jobs is saved in the opencms-system.xml. Instead of using the graphical user interface in the administration view, you could also directly write the job configurations into opencms-system.xml. Here's an example configuration:

<scheduler>
  <job>
    <name>Search index</name>
    <class>org.opencms.search.CmsSearchManager</class>
    <reuseinstance>false</reuseinstance>
    <active>true</active>
    <cronexpression>0 15 1 * * ?</cronexpression>
    <context>
      <user>Guest</user>
      <project>Online</project>
      <siteroot>/sites/default/</siteroot>
      <requesteduri>/</requesteduri>
      <locale>en</locale>
      <encoding>UTF-8</encoding>
      <remoteaddr>127.0.0.1</remoteaddr>
    </context>
  </job>
</scheduler>

6 Writing your own job classes

If necessary, you can write your own job classes. The class must implement the interface org.opencms.scheduler.I_CmsScheduledJob, which specifies the method

String launch(CmsObject cms, java.util.Map<java.lang.String,java.lang.String> parameters)

that is called with an CmsObject, instantiated according to the context specified for the job and a map containing all the specified parameters and their values.