It is often desirable 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.
Scheduled Job Scopes:
It is important to understand that the ‘command’ API methods that are invoked via the scheduled job are designed to be run in one of three scopes;
• at the server level
• at a customer level (applies to all sites/users/groups under that customer)
• at a site level
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. What this means is that if an administrator is going to create a new scheduled job at the ‘site’ level, then only job definitions that call site level commands will be shown to the administrator.
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 with 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:
Additionally, you can see that the formfields section of the XML controls which property widgets display in the Scheduled Job Properties dialog when an administrator creates or edits an existing scheduled job. For each required argument in the target command API method, you need to have a corresponding formfield in the XML.
By specifying the fieldtype for a formfield you can control which widget is used to prompt the administrator in the dialog. See the table below and refer to the sample XML.
|
FieldType |
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 paperthin.com (requires login).
For technical support:
The following guides are available locally on your CommonSpot Server: