You are here: Administrators Reference > Server and Customer Administration > Server Administration Left Panel > Utilities > Server Scheduled Jobs > Scheduled Jobs Overview


Scheduled Jobs Overview

It is often best to perform site maintenance tasks at scheduled times without human intervention. For example, you might want to rebuild site cache on the authoring server during off business hours, or route a nightly report of broken links to page owners or administrators.

To accomplish these kinds of tasks, CommonSpot provides a robust and flexible facility for creating and managing the execution of background scheduled jobs on one or more servers.

Under the covers, each Scheduled Job invokes a specific CommonSpot API "command" call, including defined properties, at a specified time, on one or more specified servers. Any of the 1,000+ command API calls can be called a CommonSpot scheduled job.

The first step in creating a scheduled job is choosing which job definition to use. Definitions identify the command API method to invoke and which input parameters are required. Site administrators can create XML job definitions and import them into CommonSpot. Once imported, non-technical users can then create schedules for jobs based on the imported definition.

NOTE: As of the Winter 2012 release, CommonSpot refreshes credentials for any scheduled jobs a user owns, which may result in scheduled jobs not running unless the owner is logged in. Administrators must be aware of this when changing permissions or group membership for users who own scheduled jobs. If a job owner is unavailable, another user with the appropriate administrative rights (for the level the job runs) can enable jobs by simply submitting job properties or the schedule dialog to refresh credentials (no changes are needed).

Scheduled Job Scopes:

It is important to understand that the command API methods invoked via the scheduled job are designed to run under one of three scopes;

When defining a scheduled job definition you need to correctly identify which scope the scheduled job applies to. If the scope is incorrectly specified in the job definition the command API call will fail. Additionally, based on the identified scope, the job definition will only be available for selection at the appropriate level. This means that administrators creating a new scheduled job at the Site level, will only see job definitions that call site level commands.

Note that scheduled jobs can be managed from the authoring server for shared-database clusters, but for replication targets, they must be managed individually for each server.

Details of a Scheduled Job Definition:

As stated, Scheduled Job definitions are specified in XML and then imported into CommonSpot. The main components of XML definitions are:

CommonSpot provides 10 out-of-the-box job definitions, that are automatically "imported" during installation time. You can view the XML for these job definitions in the /commonspot/schema/sched-tasks directory.

Create and manage scheduled jobs from the authoring server.

Scheduled jobs can run at specified times on a single server or on all servers at your site. CommonSpot presents a single convenient interface for managing all scheduled jobs and takes care of all of the details of inserting the jobs you create into the ColdFusion scheduler and managing changes.

Jobs are defined by selecting Manage Job Definitions in the Server, Customer, or Site Scheduled Job dialog and uploading an XML job description through the Scheduled Job Definitions dialog.

For example, this XML:

Results in this dialog when an administrator creates or edits a scheduled job

As you can see, the XML job definition includes:

Also note that the formfields section of the XML controls which property widgets display in the Scheduled Job Properties dialog to administrators creating or editing scheduled jobs. For each required argument in the target command API method, you must have a corresponding formfield in the XML.

By specifying the fieldtype for a formfield you can control which widgets to use as prompts for administrators completing these dialogs. See the table below and refer to the sample XML.


Widget Rendered

input A standard input field
radio A single radio button
checkbox A single checkbox
multicheckboxlist A group of checkboxes
selectionlist A selection list
radiobuttonlist A group of radio buttons
Subsitelist A selection list of subsites

Note the validationtype tag specifies a CommonSpot command API type that identifies the valid options. See the command API documentation for details.

Registering Scheduled Job Definitions

You can import (or "register") scheduled job definitions from Server, Customer, or Site Administration. Where you import the job definition XML, affects the visibility of the job definition. For example, a server configuration may support multiple customers, each of which has one or more sites. To apply a particular job definition to a specific site, import the definition from Site Administration for that particular site.

Similarly, to make a job definition available to all sites for a specific customer (but not to all customers), import the job definition within Customer Administration for that customer.

Here are some rules to remember:

If a job definition is imported at the server level:

If a job definition is imported within Customer Administration for a specific customer:

If a job definition is imported within Site Administration for a particular site:

You cannot import:

You can only import a job definition:

Define jobs by selecting Manage Job Definitions in the Server, Customer, or Site Scheduled Job dialog and uploading an XML job description through the Scheduled Job Definitions dialog.

Importing a job at the server level makes it available to all sites using that server. Importing the same job at the customer level limits its availability to sites running for that customer.

Job definitions imported at the site level are available to that site only.

Jobs with a target scope of Server are imported at the server level only.

You can import jobs with a target scope of Customer at the server level, making it available for all customers, or import it at the Customer level, restricting use to that customer.

You can view both source scope and target scope for jobs at your site through the Scheduled Job Definitions dialog. This dialog lists jobs installed with CommonSpot, as well as any custom jobs defined for your site.

Note: You cannot modify or delete CommonSpot standard jobs.

Once jobs are defined, administrators can set scheduling and other configuration parameters, hide or suspend jobs, and copy them. See Site Scheduled Jobs, Server Scheduled Jobs, and Customer Scheduled Jobs.


Related Links

You can download PDF versions of the Content Contributor's, Administrator's, and Elements Reference documents from the support section of (requires login).

For technical support: