Configure the Scheduler

This configuration is available only for the global (repository) scope. If you are not familiar with the basics of the different scopes, you may want to review: The Administration Interface. The configuration is specified in the Scheduler topic of Administration.

Reference information, including cron expressions and examples for configuring jobs, is embedded on the Scheduler configuration page (scroll down if necessary to see it). The same information is available in the Administration Reference.

Access the Scheduler configuration:

1. Log in with administrator permissions for the repository.

2. Enter Administration from the Tool view of Navigation).

3. In the Open Project or Project Group dialog box, select Repository.

4. In Navigation, select Scheduler.

   The Scheduler page opens. This page has an embedded XML editor which displays the XML code of the current configuration.

5. In the Scheduled Jobs Configuration section, edit the XML code as needed to make the changes or additions you want. Refer to the embedded help text that appears below the embedded XML editor.

6. Click the Save button to save the changes to the Scheduler configuration. Changes are immediately in effect - it is not necessary to restart the server.

Jobs can spawn other jobs. The ID for such a job is multi.job. Jobs to spawn are referenced by their names from schedule.xml. It is possible to run jobs either sequentially (default) or in parallel, and possible to terminate sequential execution if a job fails. Default is to ignore the failure. The job reports failure if at least one of the executed jobs fails.

The following listing shows the multi.job scheduler configuration:

<job id="multi.job" ...>
    <parallel>_true_OR_false_</parallel>
    <terminateOnFailure>_true_OR_false_</terminateOnFailure>
    <delegateFailure>_true_OR_false_</delegateFailure>
    
    <jobs>
        <job>_JOB_NAME_</job>
        . . .
    </jobs>
<job>

It is possible to fail the job if at least one of the executed jobs fails. Default is to finish successfully no matter what. Aborting will always fail the multi.job.

Extended configurability:

• JOB_NAME_ may contain a runtime expression. This expression consists of:

  • Job name

  • Sequential operator ,

  • Parallelization operator |

• Operator precedence is (from highest to lowest): | ,

• Sequential operator will execute job groups in sequence. Failures coming from these jobs are ignored and not delegated.

• Parallelization operator will execute job groups in parallel. Failures coming from these jobs are ignored and not delegated.

For example: J1,J2|J3|J4,J5 will execute three groups of jobs in parallel. The first group consists of sequence J1,J2, the second group is a single job J3, and the last group is a sequence of J4 and J5.

Scheduled jobs should be reviewed for a multiserver cluster, and convenient Node selectors (the node attribute of <job> elements) should be specified depending on the nature of the job. The following default jobs should have node="*" specified for them in a clustered setup:

• Index Checker

• Suspend DB History Creator

• Resume DB History Creator

You can define a job that runs a custom script. The job ID in the scheduler must be script.job. Groovy (groovy) and JavaScript/ECMAScript (js) scripts are supported. Script files must be stored in the scripts folder of the Polarion installation's file system.

The job has the following required parameters:

• scriptName: Name of the script to run

• scriptEngine: Name of the scripting engine to use (groovy or js)

In the script you will be able to access following variables:

• logger: A com.polarion.platform.jobs.ILogger you can use to log messages for the job

• scope: A com.polarion.platform.context.IContext that represents the scope of the job.

• workDir: A java.io.File pointing to the working directory of the job.

• jobUnit: The com.polarion.platform.jobs.IJobUnit that runs the script.

Every property is defined inside the <properties> element of the job. The property in the example below would be accessible as variable with the name myProperty containing the value myPropertyValue.

<job name="Script Job" id="script.job" cronExpression="" disabled="true" scope="system">
    <scriptName>test.js</scriptName>
    <scriptEngine>js</scriptEngine>
    <properties>
        <myProperty>myPropertyValue</myProperty>
    </properties>
</job>

The internal script engine that executes scripts via jobs, and also script-based workflow conditions and functions for Work Items and Documents (ScriptCondition, ScriptFunction) can run a script without installing it into the scripts folder. To run a script directly, direct your web browser to: [POLARION SERVER]/polarion/scripting (where [POLARION SERVER] is replaced with the actual domain of your server).

The page provides an interface that you can use to input and run a script. The variables visible to the script are the same as for script jobs. (Actually, the script is run as a job). The system property com.polarion.scripting.servlet.enabled must be enabled in the system properties file in order to run scripts directly. By default, only administrators are allowed to run scripts this way, as it is potentially dangerous.

As mentioned, Jobs are defined (scheduled) and run in the global scope. You can start or stop the Scheduler from the Scheduler topic in Global Administration.

To invoke one of these operations:

1. Log on to Polarion with administrator permissions for the repository.

2. Enter Administration.

3. In the Open Project or Project Group dialog box, select Repository to work in the global scope.

   A button appears at the top of the Scheduler page, just under the main heading. If the Scheduler is currently running, the button label is Stop Scheduler. If the Scheduler is currently stopped, the button label is Start Scheduler.

4. Click the button for the operation you want to invoke. When the Scheduler is stopped, configured scheduled jobs will not run. When the Scheduler is started and running, the configured jobs will be run according to the configured schedule.

You can run any scheduled job immediately from the Monitor topic. The Scheduler must be running (see Starting and Stopping the Scheduler.) Check the job(s) you want to run in the Scheduled Jobs section and click the Execute Now button to launch the job(s) you selected.

You can use the execute.command job to immediately run some system command or utility. For example, the following will run the PDT diagnostic utility.

<job id="execute.command" name="PDT" scope="system">
    <command>$[com.polarion.home]/diagtool/run$[shellExtension]</command>
    <arguments>
        <argument>-sendResults</argument>
        <argument>no</argument>
        <argument>-resultsDir</argument>
        <argument>$[jobDir]</argument>
    </arguments>
</job>

Administrators can set com.siemens.polarion.security.executeCommandJob.enabled=false in the polarion.properties file to disable all execute.command jobs for increased security.

When set to False, users will not be able to run execute.command jobs, and will be prompted with a security warning if they attempt to do so.

You can see the status of all Jobs in the Monitor topic. This topic is available in the Navigation pane when you exit from Administration and return to project or portal content topics.

1. In the Open Project or Project Group dialog, select either Repository or a Project (you must have the relevant permissions).

2. If you are in Administration, click the link in the top panel of Navigation to return to the portal Home or the project.

3. In Navigation, select Monitor.

Jobs create temporary folders, which in turn store job logs. At some point, you will want to clean up these folders. There is a job jobs.cleanup that deletes these temporary folders and their data. The job can be scheduled to run periodically, or launched explicitly. You can optionally use the preserveAgeHours to specify how long to preserve temporary file after jobs start. The value of the parameter is hours (see the following example). If the parameter is not specified, the job defaults to 24 hours.

Example:

<job cronExpression="0 55 * ? * *" id="jobs.cleanup" name="Cleanup of Temporary Files" scope="system">
   <preserveAgeHours>36</preserveAgeHours>
</job>	

In this example, temporary folders and data are preserved for 36 hours.