OpenCms documentation
OpenCms documentation

Scheduled jobs app

scheduler

OpenCms allows jobs to be run at a certain date and time, or to repeat jobs at 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.

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 at 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 task scheduled for one-time execution 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., overnight.

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

Administration view for scheduled jobs management

The "Scheduled Jobs Management"-view provides options to create a new job (magic wand in the toolbar) and to view the list of existing jobs.

Via the context menu of a job you can

  • Edit the job
  • Activate/deactivate the job
  • Copy the job
  • Delete the job
  • Run the job manually.

When adding a new job or editing an existing job, a form appears.You provide information necessary for every job, and optionally parameters handed over to the Java class that executes the job.

Dialog for editing a scheduled job (page 1)

In the dialog, as shown in the screenshot above, you can fill out the following options for the job:

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 performed.

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".

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.

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.
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.

The configuration of scheduled jobs is saved in the opencms-scheduler.xmlUp to OpenCms 10.5 it was part of 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-scheduler.xml. Here's an example configuration:

<opencms>
  <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>
</opencms>

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.