Creating and Managing Scheduled Jobs

The command API methods invoked via the scheduled job are designed to run under 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 it is important 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. In addition, 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 must be managed individually for each replication target.

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

• Job name
• Job scope (whether the job runs at the Server, Customer, or Site level)
• The component/method to call
• The arguments to pass to the job
• The labels and field types to display during job configuration

CommonSpot provides more than a dozen out-of-the-box job definitions that are automatically "imported" during installation or upgrade. 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:

• A name, which becomes the default name for the scheduled job
• A description
• The component and method for the command API call

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

You can schedule any of the CommonSpot Command Engine API methods to run as a scheduled job by:

1. Creating an XML Job Definition.
2. Registering the New Job Definition.
3. Importing that definition as a new Scheduled Job.

1. Choose the Command Engine API method you want to call. API methods are documented in CommonSpot API Help.
2. Identify the arguments that method takes. At minimum, you need to build a Job Definition XML file that prompts for all required fields
3. Build a Job-definition XML file. See the example re-index-collections.xml in the commonspot/samples directory.

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 example XML and README file in /samples/.

FieldType	Widget Rendered	Options
input	A standard input field	validationtype - a valid CommonSpot 'type' or an empty string for no validation defaultvalue required - boolean (1 or 0) maxlength - required
textarea	A text area control	validationtype - a valid CommonSpot 'type' or an empty string for no validation defaultvalue required - boolean (1 or 0) maxlength - required
radio	A single radio button	validationtype - an enumeration type, or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels defaultvalue required - boolean (1 or 0) maxlength - required, set to 0
checkbox	A single checkbox	validationtype - an enumeration type, or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels defaultvalue required - boolean (1 or 0) maxlength - required, set to 0
multicheckboxlist	A group of checkboxes	validationtype - an enumeration type, or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels defaultvalue required - boolean (1 or 0) maxlength - required, set to 0
selectionlist	A selection list	validationtype - an enumeration type, or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels defaultvalue required - boolean (1 or 0) maxlength - required, set to 0
radiobuttonlist	A group of radio buttons	validationtype - an enumeration type, or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels defaultvalue required - boolean (1 or 0) maxlength - required, set to 0
subsitelist	A selection list of subsites	validationtype - an enumeration type, or empty string defaultvalue - subsite ID required - boolean (1 or 0) maxlength - required, set to 0
custompicker	Enables defining a picker function in the dialog it is called from	validationtype - an enumeration type (PlainText), or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels required - boolean (1 or 0) maxlength - required, set to 0
documentpicker	A list of documents with a summary of the current selection, if available. Presented with a Choose button.	validationtype - an enumeration type (MultimediaID), or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels required - boolean (1 or 0) maxlength - required, set to 0
hidden	A field that does not render but that can provide defaulted data	validationtype - an enumeration type (PlainText), or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels required - boolean (1 or 0) maxlength - required, set to 0
readonly	A display-only field.	validationtype - an enumeration type (PlainText), or empty string. If an enumeration type is passed, enumvalues and enumlabels is ignored enumvalues - comma-delimited list of values enumvalues - comma-delimited list of values enumlabels - comma-delimited list of labels required - boolean (1 or 0) maxlength - required, set to 0
socialmediachannellist	A list of defined social media channels	validationtype - an enumeration type (SocialMediaChannelIDList), or empty string defaultvalue required - boolean (1 or 0) maxlength - required, set to 0

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

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:

• Jobs can be scheduled from within Customer Administration for any customer, and/or
• Jobs can be scheduled from within Site Administration for any site under any of the customers

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

• Jobs can be scheduled from within Customer Administration for that particular customer, and/or
• Jobs can be scheduled from within Site Administration for any site under that particular customer

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

• Jobs can only be scheduled within Site Administration for that particular site

You cannot import:

• A job definition associated with a server- or customer-level scope from Site Administration for any site.
• A job definition associated with a server-level scope from Customer Administration or Site Administration for any site or customer
• A job definition associated with a server-, site-, or customer-level scope, from Server Administration.

You can only import a job definition:

• Associated with a site- or customer-level scope from Customer Administration for any customer.
• Associated with a site-level scope within Site Administration for any site.

Enter the new Job Definition through Server/Site/Customer Admin > Utilities > Scheduled Jobs > Manage Scheduled Job Definitions > Add New Job Definition.

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.