3.1 Understanding the Job Scheduler View

Click Scheduler on the main toolbar of the PlateSpin Orchestrate Development Client to open the Job Scheduler view.

Figure 3-1 Job Scheduler View of the Orchestrate Development Client

This section includes information to help you understand the functions of the Job Scheduler and how to use it to launch PlateSpin Orchestrate jobs.

3.1.1 Navigating The Job Schedules Table

PlateSpin Orchestrate includes several predefined and predeployed discovery jobs that have predefined launch schedules. Among these jobs are the cpuinfo, findapps, osinfo, and other jobs, depending on the options (that is, the “server profile”) you chose and the configuration you used during the installation. After installation, these jobs are listed by name in a table in the Job Scheduler view.

Figure 3-2 The Job Schedules Table in the Job Scheduler View

By default, PlateSpin Orchestrate uses schedule names that are similar to the job name so that schedules are easy to match (although this is not required). The schedules list shows all of the existing job schedules that accompany predefined jobs, along with the schedules that you create in the Job Scheduler.

NOTE:The Job Scheduler view is not a real-time monitor view of jobs, so if a job attribute (for example, Last Job Status or Last Fire Time) has changed, it might not be displayed until you click Refresh.

The Job Schedules Table has functionality that lets you decide how you want to display information about the job schedules:

  • You can drag any column in the table to move it left or right in the table according to your preference.

  • You can mouse over any column heading in the table to view tool tip text about the purpose of the data in that column.

  • You can right-click any column heading in the table to open the Job Scheduler Column Editor dialog box.

    Figure 3-3 Job Scheduler Column Editor Dialog Box

    You can select any column heading in this dialog box to display it in the Job Schedules Table. The columns display the attributes of a previously configured job schedule. As the figure shows, this dialog box also includes text that clarifies the purpose of the data in each column.

In the Job Scheduler view, there are seven function buttons next to the Job Schedules Table (see Figure 3-2) that let you take action on any schedule you select inside the table. (Only one schedule at a time can be selected.)

  • New: Opens a dialog box where you can create a new schedule. When you create a new schedule, the Job Scheduler adds a new line to the Job Schedules Table. When the new line is added, you can use the Job Schedule Editor to edit the attributes of the schedule. A new schedule must be given a unique schedule name.

    The Job Scheduler forces a new schedule to be created in the Disabled state to prevent it from running while it is being defined. You click Enable when a job is ready to be used.

  • Copy: Copies a schedule you have selected in the Job Schedules Table. Clicking this button opens a dialog box where you rename the copy. If you want to create a schedule similar but not identical to an existing schedule, use this button to save time in adding attributes to a job schedule configuration. A copy of a schedule must be given a unique schedule name.

  • Deploy: Opens a dialog box where you can select a schedule (that is, a deployable .sched file) to deploy.

  • Delete: Deletes the selected schedule from the Job Schedules Table. You cannot recover a deleted job schedule.

    NOTE:Deleting a schedule that was deployed as part of a .job or .sar displays a confirmation dialog box. Deleting the schedule undeploys all contents of the .job or .sar that contains the schedule.

  • Disable: Disables the selected schedule in the Job Schedules Table. The jobs associated with the schedule are not re-run, but any currently running instances of this job continue to run.

  • Enable: Enables a disabled job schedule.

  • Run Now: Forces the specified schedule to run immediately. This updates statistics such as Last Fire Time.

Removed Jobs or Users: Scheduler Behavior

If a job or a user is undeployed or removed from PlateSpin Orchestrate, the Job Schedules Table continues to list the schedule previously associated to that removed grid object, but the removed grid object no longer displays the icon that represents the object (job or user).

Figure 3-4 Some User Object and Job Object Icons Not Displayed

In the preceding figure, the CpuDiscovery schedule displays no Job icon for the cpuInfo job in the schedules table. Even though the job has been undeployed, the schedule is still listed.

In the osinfo schedule, the system user has no User icon. That user has been removed from PlateSpin Orchestrate.

If you choose a new user or job to be associated with a schedule, a deleted or undeployed user or job is never displayed in the popup menu for that schedule again.

3.1.2 Creating or Modifying a Job Schedule

The Job Schedule Editor is located immediately below the Job Schedules Table in the Job Scheduler view.

Figure 3-5 The Job Schedule Editor in the Job Scheduler View

There are several times when you can use this part of the Job Scheduler tool:

  • When you create a new schedule by clicking New.

  • When you modify the attributes of an existing schedule (available when you select a schedule in the table).

  • When you create a copy of an existing schedule by clicking Copy.

The Job Schedule Editor lets you create or modify a job schedule by specifying its attributes.

You can use the following controls and data when you create or modify a job schedule:

Schedule Name

When you create a new schedule, the unique name you specify is displayed in this field. If you select a schedule from the Job Schedules Table, the name of the schedule is displayed in this field. The field is not editable, because schedules cannot be renamed after they are created. (You can use a copy if this is required.)

Job

When you create a new schedule, you need to associate a deployed job with it. You can select the job you want to run from this drop-down list.

If you want to use a previously created schedule to run a different job, you can change the job here.

User

When you create a new schedule, you need to associate a user with it. The user represents the user for whom the job will run. The choice of user might affect the permissions, privileges and constraints of the job. You can select the user from this drop-down list.

If you want a different user to run a job on a previously created schedule, you can change the user here.

If you decide to change the user who runs the job, check the Priority field to make sure that the priority you want is selected.

Priority

When you create a new schedule and associate a job and a user with it, a list of possible run priorities becomes available in this drop-down list. The list of priorities varies, depending on the user that is specified in the previous field. In this field, you select the priority of the job that is to be run so that if other jobs are to start concurrently or are competing for resources, PlateSpin Orchestrate can determine which job takes priority.

Description

For predeployed jobs, this field contains a default description of what the job’s schedule does. The field is editable, so you can enter a description of your own for job schedules that you create.

Matching Resources

This button displays a list of resources where the job runs now or where it could run. This list is useful for checking the context of constraints that might have been affected by a choice of user or by manually specifying additional constraints under the Policy tab. The list is also useful to verify that a discovery job (that is, one that is triggered by the Run on Resource Start option) runs on the preferred set of machines.

Test Schedule Now

Click this button to test the new or modified schedule you are working with. The test runs the new or modified schedule without permanently saving the current configuration of the schedule or recording statistics. This control differs from the Run Now control in the Job Schedules Table, which runs a saved (persisted) schedule, disregarding any unsaved modifications that have been made to it in the Job Schedule Editor.

Triggers

When you click the Triggers tab in the Job Scheduler view, the following page opens:

Figure 3-6 The Schedule Triggers Page in the Job Scheduler

In this view, you can add or define the triggers you want to associate with job schedules. A trigger is the signal to the Job Scheduler to initiate, or “fire” a schedule at a given time or at the occurrence of a given event. Job Scheduler triggers can be classified with regard to two conditions: events and time.

The Triggers table on this page has functionality that lets you decide how you want to display information about the triggers:

  • You can drag any column in the table to move it left or right in the table according to your preference.

  • You can mouse over any column heading in the table to view tool tip text about the purpose of the data in that column.

  • You can right-click any column heading in the table to open the Triggers table column editor dialog box.

    Figure 3-7 Trigger Table Column Editor Dialog Box

    You can select any column heading in this dialog box to display it in the Triggers table. The columns display the attributes of a previously configured Triggers table. As the figure shows, this dialog box also includes text that clarifies the purpose of the data in each column.

You can create as many triggers as you want to meet any scheduling situation you might have. Multiple time triggers can be associated with a schedule and multiple schedules can use the same trigger. The triggers you create are retained by the Job Scheduler for you to choose from when you create a schedule for a job. The currently associated triggers are displayed in the list along with a description.

Choose Triggers

This button opens a dialog box where you can choose both predefined and user defined time triggers to associate with this job schedule.

Figure 3-8 Choose Triggers Dialog Box

In this dialog box, you can click Add to move a selected trigger to the active, scheduled triggers that are to be associated with this job schedule. You can also click Remove to unassociate a trigger.

When a trigger is moved to the scheduled list, it becomes associated to the job schedule and it is displayed in the Job Scheduler view.

Most example jobs in PlateSpin Orchestrate are associated with event triggers, which are shown in the previous illustration. The dialog box can also list other job schedule triggers that are based on time.

Event Triggers

An Event trigger is the signal to the Job Scheduler to initiate, or “fire” a job when a given event occurs. An Event can be one of three types:

  • Event objects: These objects are user defined events that are fired when an event rule is triggered. If an event object is deployed, it automatically shows in the trigger chooser as a possible choice.

  • built-in events: These events are system wide events such as when a resource comes online or when a resource health condition change occurs. Built-in events are always available as a trigger choice. The Job Scheduler has eight possible built-In event triggers:

    • AGENT_VERSION_MISMATCH

    • RESOURCE_ONLINE

    • REPOSITORY_HEALTH

    • RESOURCE_HEALTH

    • SERVER_UP

    • USER_HEALTH

    • USER_ONLINE

    • VMHOST_HEALTH

    You can select any combination of these event triggers for a single schedule.

    The first trigger, AGENT_VERSION_MISMATCH, triggers the job when a PlateSpin Orchestrate Agent of an incompatible version attempts to connect to this Orchestrate Server. It can be used to initiate a configuration management tool for an agent software update or the job could e-mail an administrator to report the incompatible agent. The other seven available built-in event triggers are listed with accompanying descriptions in the dialog box.

  • External events: These events are fired by an outside process. These are not automatically shown as choices in the trigger chooser, but must be defined by the trigger editor.

An event trigger can be used in conjunction with a time trigger to allow flexibility in scheduling the job application for maximum effectiveness or convenience. Jobs triggered by events require that their job arguments contain a dictionary named context. For example, your event-triggered job should have this jobarg element in its policy:

<policy>
   <jobargs>
      <fact name="context" type="Dictionary"
            description="Dictionary containing the context for the event" />
   </jobargs>
</policy>

The key/values of the dictionary are dependent on the event type. For event objects, the jobargs.context dictionary contains the matching context of the triggered rule. For built-in events, the jobargs.context dictionary contains the key of the object type corresponding to the built-in event and the object ID that caused the event.

For example, if the USER_ONLINE event triggers because the user named foo logs in, the jobargs.context dictionary contains:

{ user : foo }

Likewise, if the RESOURCE_ONLINE event is triggered because the resource agent named “vmhost1” comes online, the jobargs.context dictionary contains:

{ resource : vmhost1 }

For the AGENT_VERSION_MISMATCH event, the jobargs.context dictionary contains more information, as shown in the following table:

Table 3-1 Dictionary Information

Key

Type

AgentBuild

Long

AgentIP

String

AgentId

String

AgentMajor

Integer

AgentMinor

Integer

AgentPoint

Integer

JavaMajor

Integer

JavaMinor

Integer

JavaPoint

Integer

JavaVendor

String

JavaVersion

String

OsMajor

Integer

OsMinor

Integer

OsName

String

OsPoint

Integer

OsVendor

String

OsVersion

String

SystemArch

String

UsingJRE

Boolean

resource

String

Time Triggers

A time trigger is the signal to the Job Scheduler to initiate, or “fire” a job when a prescheduled time occurs. A time trigger can be used in conjunction with an event trigger to allow flexibility in scheduling the job application for maximum effectiveness or convenience. No default time triggers are defined in the Job Scheduler. You need to create new time triggers by clicking Edit Triggers.

Edit Triggers

Click Edit Triggers to open the Triggers dialog box.

Figure 3-9 The Triggers Dialog Box

The following controls and information are available in the dialog box:

  • New: Opens a secondary dialog box where you can create a new time trigger name. When you create the trigger name, the attribute fields in the Triggers dialog box are cleared and you can specify new attributes for the trigger. A new trigger must be given a unique trigger name.

  • Copy: Lets you modify an existing time trigger by giving it a new name and attributes. This can be helpful if there are only slight differences in the new attributes. A copy of a trigger must be given a unique trigger name.

  • Deploy: Opens a file chooser where you can choose an existing, stored trigger (that is, a .trig file) to deploy.

  • Delete: Deletes a selected time trigger.

    IMPORTANT:Deleted triggers are not recoverable. If the trigger is used by existing schedules, it is removed from all of those schedules when it is deleted.

  • Trigger Name: Specifies the unique name of the trigger you are creating or modifying. This name is displayed in the Job Scheduler if you choose to associate this trigger with a schedule. After you create the trigger name, it cannot be modified.

  • Description: Specifies a description for the time trigger you are creating or modifying. The description is optional and can be as detailed as you want.

    If the number of characters in the description string exceeds the space in the Description field, a button is enabled that opens a string editor when clicked.

  • Save: Clicking this icon saves the defined time trigger and its attributes.

  • Fire Starting In: Displays multiple fields specifying the time increment and frequency to be used by the trigger to fire the job. If you select this type of time trigger, the Fire using CRON Expression button becomes inactive.

    NOTE:You can use the Fire Starting In control to create either a “one-shot” time trigger or a “reoccurring” time trigger.

    A one-shot time trigger fires just once after a specified period of time. To specify a one-shot trigger, click Fire Starting in, specify the amount of time before firing, then specify 0 as the time to Repeat Indefinitely.

    A reoccurring time trigger fires after a specified period and then either fires repeatedly for an indefinite number of times or it fires for a specified number of times. To specify a reoccurring, indefinite trigger, click Fire Starting in, specify the amount of time before firing, then select Repeat Indefinitely. To specify a reoccurring but finite trigger, click Fire Starting in, specify the amount of time before firing, select Repeat Range, then specify the number of times you want the trigger to fire.

  • Fire using CRON Expression: Specifies the cron expression that enables the job to fire automatically at a specified time or date. You need to be familiar with cron to use this field.

    The Examples list box of selected cron expressions and their associated descriptions is located just below this button. You can use a listed expression as is, or use it as a template to modify the expression to meet your needs.

    If you select this type of time trigger, the Fire Starting In and the Fire Using Event buttons become inactive.

    For an example of how a cron expression can be implemented in a trigger, see Creating and Assigning a Time Trigger for the New Schedule. For detailed information about cron syntax, see Understanding Cron Syntax in the Job Scheduler.

  • Fire Using Event: Specifies a deployed event or an external event that enables the job to fire when a specified event occurs. Deployed events are defined using an XML syntax. You can specify a deployed event from Events (that is, listed in the Events drop down list) or you can enter the name of an external event. For more information on creating and firing an event, see

    If the number of characters in the Fire Using Event description string exceeds the space in the field, a button is enabled that opens a string editor when clicked.

Job Arguments

This tab displays an area (in the lower left corner of the Job Schedule Editor) where possible job arguments are listed. If you select an existing schedule in the Job Schedules Table, any optional job arguments (jobargs) for the associated job are displayed in this area.

Figure 3-10 The Job Arguments Area of the Job Scheduler View

The jobargs are defined by the deployed job. Some jobs might already have a default value displayed, but others must have values specified in order for the job to be able to run.

IMPORTANT:Job arguments displayed in blue are required. You must supply data in the accompanying fields.

A job argument defines the values that can be passed in when a job is invoked. These values let you statically define and control job behavior. To learn more about each job argument, mouse over each jobarg line to display tool tip text.

The Job Scheduler uses the values you enter into the fields of this area to build a jobargs namespace in the policy for this job.

Each job argument has an accompanying Lock check box. When Lock is not selected, the accompanying job argument uses the default value specified in the job’s policy. When Lock is selected, the value specified in the field is locked down and overrides the default value in the policy. A locked value continues to be used even if the policy value is modified.

You can click Restore Jobargs to restore job arguments to the values specified in the job policy. This function removes any changes you might have specified in the Job Scheduler and deselects all Lock check boxes.

For more information, see Job Arguments and Parameter Lists in the PlateSpin Orchestrate 2.0 Developer Guide and Reference.

User Environment

This tab displays an area (in the lower left corner of the Job Schedule Editor) that includes the Pass User Environment check box. Select this check box if you want to pass the assigned user’s environment variables to the job when it runs. When environment variables are recorded on the user account, selecting the Pass User Environment check box makes those environment variables available to the job and joblet.

A user’s environment is recorded under the user.env fact on his or her account. This fact can be set when a user logs in to PlateSpin Orchestrate and is persisted until changed. A user’s environment variables can be uploaded with the zos command line tool at login time in one of two variations:

  • zos login --user=foo --env

    This command uploads the entire environment to the Job Scheduler. The upload can also be seen on the User object in the Orchestrate Development Client.

  • zos login --user=foo --env=PATH

    When the user logs in, he or she can specify one or more environment variables to use at login. The example above would result in just the PATH environment variable being uploaded.

    Multiple environment variables can be specified by delimiting with a comma, as in the following example:

    --env=PATH,LD_PATH,ID

NOTE:The user’s environment variables can also be passed to the server when the user implements the zos command line tool when running a job (as opposed to logging in). The command passes the environment variable only for that particular job run.

zos run jobname --env=environment_variable

Constraints

This tab displays a constraint editor that you can use to create additional constraints for the job being scheduled. Typically, additional “resource constraints” (such as “start”) are useful to delay the start of a job when it is triggered. For more information about working with constraints, see Constraints in the PlateSpin Orchestrate 2.0 Developer Guide and Reference.

3.1.3 Understanding Cron Syntax in the Job Scheduler

The cron triggers you can configure in the PlateSpin Orchestrate Job Scheduler use a Quartz crontrigger class for deciding when to invoke job execution. This is based on the standard Quartz format that you can find further described on the OpenSymphony Web site, or the KickJava Web site.

This section includes the following information:

Format

A cron expression is a string comprised of 6 or 7 fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. The fields are explained in the following table:

Table 3-2 Fields in a Cron Expression

Field Name

Mandatory?

Allowed Values

Allowed special Characters

Seconds

Yes

0-59

, - * /

Minutes

Yes

0-59

, - * /

Hours

Yes

0-23

, - * /

Day of the Month

Yes

1-31

, - * ? / L W

Month

Yes

1-12 or JAN-DEC

, - * /

Day of the Week

Yes

1-7 OR SUN-SAT

, - * ? / L #

Year

No

EMPTY, 1970-2099

, - * /

So cron expressions can be as simple as this:

* * * * ? *

Or cron expressions can be more complex, like this:

0 0/5 14,18,3-39,52 ? JAN,MAR,SEP MON-FRI 2002-2010

Special Characters

Cron syntax incorporates logical operators, special characters that perform operations on the values provided in the cron fields.

Table 3-3 Special Characters in PlateSpin Orchestrate Cron Syntax

Operator

Purpose

Example

asterisk ( * )

Specifies all possible values for a field

An asterisk in the hour time field is equivalent to “every hour.”

question mark (?)

A question mark ( ? ) is allowed in the day-of-month and day-of-week fields. It is used to specify “no specific value,” which is useful when you need to specify something in one of these two fields, but not in the other.

If you want a trigger to fire on a particular day of the month (for example, the 10th), but you don't care what day of the week that is, enter 10 in the day-of-month field, and ? in the day-of-week field. See the examples below for clarification.

dash ( - )

Specifies a range of values

2-5, which is equivalent to 2,3,4,5

comma ( , )

Specifies a list of values

1,3,4,7,8

slash ( / )

Used to skip a given number of values

*/3 in the hour time field is equivalent to 0,3,6,9,12,15,18,21. The asterisk ( * ) specifies “every hour,” but the /3 means only the first, fourth, seventh.

You can use a number in front of the slash to set the initial value. For example, 2/3 means 2,5,8,11, and so on.

L (“last”)

The L character is allowed for the day-of-month and day-of-week fields.

Specifies either the last day of the month, or the last xxx day of the month.

The value L in the day-of-month field means “the last day of the month”––day 31 for January, day 28 for February in non-leap years. If you use L in the day-of-week field by itself, it simply means 7 or SAT. But if you use it in the day-of-week field after another value, it means “the last xxx day of the month.” For example, 6L means “the last Friday of the month.”

HINT:When you use the L option, be careful not to specify lists or ranges of values. Doing so causes confusing results.

W (“weekday”)

The W character is allowed for the day-of-month field.

Specifies the weekday (Monday-Friday) nearest the given day.

If you specify 15W as the value for the day-of-month field, the meaning is “the nearest weekday to the 15th of the month.” So if the 15th is a Saturday, the trigger fires on Friday the 14th. If the 15th is a Sunday, the trigger fires on Monday the 16th. If the 15th is a Tuesday, it fires on Tuesday the 15th. However, if you specify 1W as the value for day-of-month, and the 1st is a Saturday, the trigger fires on Monday the 3rd, because it does not “jump” over the boundary of a month’s days. The W character can only be specified when the day-of-month is a single day, not a range or list of days.

HINT:You can combine the L and W characters for the day-of-month expression to yield LW, which translates to “last weekday of the month.”

pound sign ( # )

The pound sign ( # ) character is allowed for the day-of-week field. This character is used to specify “the nth” xxx day of the month.

The value of 6#3 in the day-of-week field means the third Friday of the month (day 6 = Friday and #3 = the 3rd one in the month).

Other Examples: 2#1 specifies the first Monday of the month and 4#5 specifies the fifth Wednesday of the month. However, if you specify #5 and there are fewer than 5 of the given day-of-week in the month, no firing occurs that month.

NOTE:The legal characters and the names of months and days of the week are not case sensitive. MON is the same as mon.

You can specify days in two fields: month day and weekday. If both are specified in an entry, they are cumulative, meaning that both of the entries are executed.

Examples of Cron Syntax

The following table shows examples of full cron expressions and their respective meanings.

Table 3-4 Results of Altered Cron Syntax on Execution Times

Cron Expression Example

Description

0 0 12 * * ?

Fire at 12:00 p.m. (noon) every day

0 15 10 ? * *

Fire at 10:15 a.m. every day

0 15 10 * * ?

Fire at 10:15 a.m. every day

0 15 10 * * ? *

Fire at 10:15 a.m. every day

0 15 10 * * ? 2008

Fire at 10:15 a.m. every day during the year 2008

0 * 14 * * ?

Fire every minute starting at 2:00 p.m. and ending at 2:59.p.m., every day

0 0/5 14 * * ?

Fire every five minutes starting at 2:00 p.m. and ending at 2:55 p.m., every day

0 0/5 14,18 * * ?

Fire every five minutes starting at 2:00 p.m. and ending at 2:55 p.m., and fire every five minutes starting at 6:00 p.m. and ending at 6:55 p.m., every day

0 0-5 14 * * ?

Fire every minute starting at 2:00 p.m. and ending at 2:05.p.m., every day

0 10,44 14 ? 3 WED

Fire at 2:10 p.m. and at 2:44 p.m. every Wednesday in the month of March

0 15 10 ? * MON-FRI

Fire at 10:15 a.m. every Monday, Tuesday, Wednesday, Thursday and Friday

0 15 10 15 * ?

Fire at 10:15 a.m. on the 15th day of every month

0 15 10 15 * ?

Fire at 10:15 a.m. on the last day of every month

0 15 10 ? * 6L

Fire at 10:15 a.m. on the last Friday of every month

0 15 10 ? * 6L 2008-2011

Fire at 10:15 a.m. on every last Friday of every month during the years 2008, 2009, 2010, and 2011

0 15 10 ? * 6#3

Fire at 10:15 a.m. on the third Friday of every month

0 0 12 1/5 * ?

Fire at 12:00 p.m. (noon) every five days every month, starting on the first day of the month

0 11 11 11 11 ?

Fire every November 11th at 11:11 a.m.

Cron Scheduling Precautions

You should remember the following items when you use cron scheduling:

  • Always check the effect of adding the ? and * characters in the day-of-week and day-of-month fields to make sure the expected behavior fires correctly.

  • Support for specifying both a day-of-week and a day-of-month value is not complete (you must currently use the ? character in one of these fields).

  • Be careful when setting fire times to occur between 12:00 a.m. and 1:00 a.m.— changing to or out of Daylight Saving Time can cause a skip or a repeat in the schedule firing, depending on whether the clock moves backward or forward.