JobScheduler - Tutorial 4 - Editing and Running a JITL Job

Introduction

This tutorial will show how to take two of the JobScheduler's JITL (JobScheduler Template Library) Jobs and configure them for your environment.

The JITL Jobs are intended to be easy to configure and help users get started with the most common job scheduling tasks.

Note that the other tutorials in this series are:

• JobScheduler - Tutorials - Introduction and Requirements
• JobScheduler - Tutorial 1 - Running a simple job using JOC
• JobScheduler - Tutorial 2 - Editing a Simple Job with JOE
• JobScheduler - Tutorial 3 - Running an Order Using the Run Time Parameter
• JobScheduler - Tutorial 4 - Editing and Running a JITL Job (this tutorial)

About JITL jobs

The JITL jobs that are most likely to be of immediate use are pre-installed in the JobScheduler's live/sos folder. They are grouped together in a number of sub-folders and can be most easily seen in the JOC Jobs tab as shown in the screen-shot below:

Please note:

• The exact list of jobs that you will see here will depend on the packages that you selected during installation of your JobScheduler:
  • dailyschedule - is always installed
  • events - is only installed if the "Configure JobScheduler as event handler" option was selected during installation
  • housekeeping - is only installed if the Housekeeping Jobs package was selected 
  • jitl - is always installed
  • notification - is always installed
  • update - is installed if the Update Service package was selected
• Some of the jobs come with orders as can be seen from the green-colored text in the above screen-shot:
  • Some of these orders are active - a Next start time is listed - for example, the orders for the dailyschedule jobs
  • Other orders - such as those for the notifications jobs - have the state pending - i.e they will only run when required and are listed with "never" as their Next start time.

Further JITL Jobs

• Comparing the list of jobs shown above with the full list of JITL jobs will quickly show that a large proportion of the JITL jobs are not shown in the above screenshot.
  This is because the remaining JITL jobs are available by way of a wizard that is integrated in JOE and that will be fully described in a later tutorial.

About This Tutorial

The JITL jobs that are probably most important for users considering regular use of their JobScheduler are:

• the scheduler_rotate_log job (job documentation ) that rotates and compresses the JobScheduler's log files and
• the scheduler_cleanup_files job (job documentation) that removes temporary files e.g. for output to stdout or stderr.

These jobs prevent an accumulation of temporary files or over-large log files from slowing down JobScheduler and possibly its host computer.

Both these jobs are part of the JobScheduler's Housekeeping Package and because of their practical use their configuration and scheduling is the subject of this tutorial.
Note that we recommend that you configure these jobs to run on any computer on which you use JobScheduler regularly on and schedule them to run automatically.

This tutorial will use the scheduler_rotate_log job to show how to set Parameters and Run Options and to see how the job is running. It will the be easy to repeat the process for the scheduler_cleanup_files job.

Configuring the scheduler_rotate_log Job in JOE

Setting the job Parameters

1. Follow the procedures already described in these tutorials to start JOE and open the .\live\sos\housekeeping folder, which contains the scheduler_rotate_log job.
2. Open the Jobs element in the Scheduler Elements pane by clicking on the triangle to the left of the element and repeat the procedure to open the scheduler_rotate_log element.
3. Select the Parameter element, which will open the Parameter form at the Parameter tab as shown in the screen-shot below:
   
4. Click on the Wizard button at the right as shown in the screen-shot above.
   This will open the wizard mentioned in the introduction to this tutorial.
   The wizard opens with the form shown in the screenshot below.
   Note that this form is listed as "Step 3 of 8". This is because the scheduler_rotate_log job has already been configured and steps 1 and 2 of the wizard have already been completed.
   
5. All the parameters for the scheduler_rotate_log job are shown together with their default values in the screenshot above.
   To demonstrate the configuration of this job and yet remain within the scope of a simple tutorial, we recommend that at this stage you only change the file_age parameter, which is highlighted in the screen-shot above and the from its default value and the delete_file_age parameter:
    - the file_age parameter determines the age in days after which files are compressed and
    - the delete_file_age parameter the age after which log files are deleted.
   
   However, if you have used a custom installation path for your log files, you will also need to modify the file_path parameter, which is also shown in the above screen shot.
   
   The procedure to modify and or set the value of a parameter in this wizard is always the same:
   • Parameters that are to be used with their default values are listed in the left hand pane of the wizard.
   • Parameters that are to be used with a custom value should be listed in the right hand pane.
   • Only parameters that are shown in the right hand pane when the wizard is closed will be retained. Any other parameters that have been modified and moved back to the left hand pane will be ignored.
     
     
   1. To set a custom value for a parameter - in this case the file_age parameter:
      1. Select the parameter/value pair in the left hand pane, as shown in the screen-shot above
      2. Click on the " > " Accept these parameters Button in the middle of the wizard.
         This will cause the parameter/value pair to be moved from the left hand pane to the right hand one and its name and value to be shown in the Name and Value fields as shown in the next screen shot:
         
      3. Change the parameter value by clicking on the value field and entering the new value. The value of 2 shown in the screen shots was selected to allow users to follow the working of this job quickly but is actually to short to be recommended for use in a production system. A more realistic value would be between 7 and the default value of 14.
         Values for the file_age parameter are days. If you have been using your JobScheduler for a number of days you can set the file_age and delete_file_age parameters to match for some but not all of your log files and follow the operation of the job in your file structure.
         Save the changed value by clicking on the Apply button.
         Note that the value of 2 shown in the screen shots was selected to quickly allow users to follow the working of this job. It is, however, really too short to be recommended for use in a production system. A more realistic value would be between 7 and the default value of 14.
      4. Repeat steps i to iii for the delete_file_age parameter, whose default value of 0 means that files will not be deleted.
      5. Click on the Finish button to close the wizard.
         Note that at this point the new parameter values have not been permanently saved.
         
      6. The modified parameters will now have been added to the job Parameter tab as shown in the screenshot below.
         To save the modified parameters click on the Save Configuration symbol at the top of the JOE window as shown:
         
6. The scheduler_rotate_log job parameters have now been set. The next step is to set the job to run regularly
   Note that parameter name/values can be modified added and removed directly in the parameter tab, as shown in the next screen shot. Use of the Wizard is, however, recommended to avoid any possible errors due to misspelling of parameter names.
   

Setting the job Run Times

The scheduler_rotate_log job is intended to be run at regular intervals.
For the purposes of this tutorial it is suggested that the job is run once a day. In a production environment this job would typically be run with a frequency between once a day and once a month, depending on the number and nature of jobs being run and on the overall scheduling environment.

For the purpose of this tutorial and to keep things simple, it is suggested that job is run with similar Run Time settings to those described in the previous 'Running an Order Using the Run Time Parameter' tutorial but that they are set for the scheduler_rotate_log job and not for an Order. A look at the left hand pane of the following screenshot should make this clear:

Checking the functioning of the scheduler_rotate_log job

This job compresses and deletes file from the JobScheduler logs folder. If the default settings were used for installing your JobScheduler, this will be a sub-folder in the Scheduler Data folder.

• On systems running Windows Vista and newer, the Scheduler Data folder is:
  • C:\ProgramData\sos-berlin.com\jobschedulerId
• and on Unix systems it is:
  • /home/[user]/sos-berlin.com/jobschedulerId

where jobschedulerId is the Id you set for the JobScheduler during installation.

Immediately after the scheduler_rotate_log job has run you should see the following:

• You will no longer have any scheduler-... log files older than the number of days that you set for the delete_file_age parameter
• Log files older than the number of days that you set for the file_age parameter will have been compressed and now carry the extension .gz
• You will have a new scheduler.log file, carrying a timestamp from when the scheduler_rotate_log job ran and sized 0kb.