Skip to content
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:

Name of the job used in the job list.

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.

A cron expression that specifies when the job should be executed. See below for the syntax of cron expressions.

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.

If checked the job performed at the specified dates (see the cron expression). If unchecked, the job is still listed, but not performed.

Name of the user that is used to execute the job.

Project in which the job is executed

The site root to which URLs are relative. By default this is "/"

The requested URI set in the context used when the job is executed. By default it is "/".

The locale set in the context used when the job is executed. By default it is "en".

The character encoding set in the request context used to execute the job. By default it is "UTF-8"

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.

Checks internal relations and sends the result via email.

Supports time based publishing of a project.

Creates a complete static export of a site.

Checks external links (resource type "pointer").

Writes information about the server's memory usage to the OpenCms log-file.

Rebuilds search indexes.

Sends notification emails to responsible users if content has not changed in a certain time period or is released or expired.

Checks the size of all images in the OpenCms VFS and downscales them if configured.

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.