3.2 Walkthrough: Scheduling a System Job

This section demonstrates how you can use the Orchestrate Development Client to deploy and schedule an existing system job named auditcleaner.job. This example job is included in the examples directory of your PlateSpin Orchestrate installation.

This section includes the following information:

3.2.1 Deploying a Sample System Job

Before a job can run, the PlateSpin Orchestrate administrator must deploy it, which involves moving it from a developed package state to a state where it is ready and available for users. Only the administrator has the necessary rights to deploy a job.

There are four methods you can use to deploy a job:

  • Deploy it from the PlateSpin Orchestrate Development Client by right-clicking the Jobs container in the Explorer panel.

  • Deploy it from the PlateSpin Orchestrate Development Client by selecting the Actions menu in the Orchestrate Development Client.

  • Deploy it from the zosadmin command line (zosadmin deploy path_to_job).

  • Copy the deployable component to the “hot” deployment directory under the Orchestrate Server instance directory. Typically, this directory is located at /var/opt/novell/zenworks/zos/server/deploy. Using this method, deployment proceeds within a few seconds. PlateSpin Orchestrate monitors this directory.

A runnable job can also be scheduled, which means that the schedule for running the job and the trigger or triggers that initiate or “fire” the schedule (or both) are configured and packaged with the job.

For this walkthrough, you deploy one of several system jobs (auditCleaner.job) developed for PlateSpin Orchestrate customers to demonstrate how system jobs are deployed and run. This job package, which is actually a .jar archive, includes only a .policy component and a .jdl component. It does not have a .sched component. You can use the Job Scheduler in the Orchestrate Development Client to add the .sched component separately.

NOTE:A PlateSpin Orchestrate job developer can create and package jobs that include a .jdl file, a .policy file, a .trig file (trigger), and a .sched file (schedule). The presence of the .sched file in the job package is also typical of the predeployed discovery jobs installed with PlateSpin Orchestrate, which run without intervention when the criteria for firing the schedule are satisfied. Such jobs are visible in the Job Scheduler because they already include the .sched components.

For more information about developing jobs and schedules in a job archive, see Job Scheduling in the PlateSpin Orchestrate 2.0 Developer Guide and Reference.

Although this walkthrough demonstrates only the first method listed above for deploying, the other methods are relatively simple, so no further examples are provided to illustrate them.

  1. In the Explorer panel of the PlateSpin Orchestrate Development Client, right-click the Jobs container, then click Deploy Job to open the Select the Component File to Deploy dialog box.

  2. Open the Look In drop-down list, then navigate to the location of the job you want to deploy.

    Although a job developer can store PlateSpin Orchestrate jobs at any location on the network, the sample jobs shipped with PlateSpin Orchestrate are limited to the directories where the product is installed. For this walkthrough, navigate to the /opt/novell/zenworks/zos/server/components/systemJobs directory.

  3. Select auditCleaner.job, then click OK to deploy the job to the Jobs container.

    The job appears in the all container and in the examples container in the tree.

3.2.2 Creating a New Schedule for the Job

When a job has been deployed, you can create a schedule to specify when you want it to run. In this walkthrough, you create a schedule for the auditCleaner job by using the Scheduler tool in the Orchestrate Development Client.

  1. From the toolbar in the Orchestrate Development Client, click the Job Scheduler icon to open the Job Scheduler view.

  2. In the Job Scheduler view, click New to open the Enter Unique Schedule Name dialog box.

  3. Specify a name for the schedule you want to create for this job. For this walkthrough, specify the name cleaner in the Schedule Name field, then click OK to return to the Job Scheduler view.

    The new schedule is highlighted in the Job Schedules Table and is flagged with a pencil icon, signifying that the schedule has not been committed yet. Continue with Section 3.2.3, Defining the New Schedule to define this new schedule by adding the specific information you want.

3.2.3 Defining the New Schedule

Defining a new job schedule consists of selecting its general properties, its specific properties, and the triggers you want to be associated with it. This section includes the following information:

Choosing General Properties for a New Schedule

After you have created a new job schedule, its name cannot be changed, but you can add properties to it that help to identify and classify it in a general way. Use the following steps to add these properties:

  1. In the Job Schedule Editor panel of the Scheduler view, select the Job drop-down list.

  2. From the list of available jobs, select auditCleaner as the job to which this schedule applies.

  3. In the Job Schedule Editor, select the User drop-down list.

  4. From the list of available users, select zosSystem as the user who runs this job.

    The zosSystem user is the built-in user that is always present. It is commonly used for routine jobs like this example.

  5. In the Job Schedule Editor, select the Priority drop-down list.

  6. From the list of available priorities, select high as the priority for this job schedule.

    The maximum selectable priority is dependent on an attribute associated with the selected user.

  7. Click the Save icon on the toolbar of the Orchestrate Development Client to save the general properties you have selected for the new schedule.

    The schedule is now committed, and the attribute columns in the Job Schedules Table are populated with the name of the job that the schedule will run, the user it will run as, the priority at which it will run, and its current status. Because the schedule has not been activated yet, it remains in a Disabled state.

When you have chosen the general properties of the new schedule, you can either continue by (Optional) Adding Specific Parameters to the New Schedule or by proceeding directly to Creating and Assigning a Time Trigger for the New Schedule.

Creating and Assigning a Time Trigger for the New Schedule

A job already defined in a schedule can be triggered with two main themes: the occurrence of an event or the arrival of a point in time. In this walkthrough, you define a time trigger for the cleaner schedule.

In this example, there are no defined time triggers in the Job Scheduler, so use the following steps to define a time trigger.

  1. In the Job Schedule view, click Edit Triggers to display the Triggers dialog box.

    Time triggers are shareable across schedules. After a time trigger is defined, it is added to a list of triggers in this dialog box. You can select a predefined trigger from this list when you create a new schedule, or you can create a new time trigger, as the next steps demonstrate.

    NOTE:For detailed information about cron syntax, see Understanding Cron Syntax in the Job Scheduler.

  2. In the Triggers dialog box, click New to clear and activate the fields in the dialog box for the creation of a unique time trigger.

  3. In the Enter Unique Trigger Name dialog box, specify 24 hour as the unique name of this time trigger, then click OK.

  4. In the Description field, specify Runs every 24 hours at noon as the description for this time trigger.

  5. Click Fire Using CRON Expression to activate the fields for defining a cron expression.

  6. Click the drop-down list of sample cron expressions, then select the default cron expression, 0 0 12 * * ?, which is listed first.

    The sample expressions in the drop-down list show cron strings with accompanying descriptions to remind you how a cron string is constructed. The examples are selectable and editable and can be used in the schedule, just as you have done in this step.

  7. Click Save to save the trigger you just created, then click Close to return to the Job Scheduler view.

  8. From the Job Scheduler view, make sure that the cleaner schedule is selected, then click Choose Triggers to display the Choose Triggers dialog box.

  9. In the Choose Triggers dialog box, select 24 hour (the name of the trigger you created), click Add to move the trigger definition to the Scheduled Job Triggers list, then click OK to return to the Job Scheduler view.

    NOTE:You can select and combine as many time triggers as you want to apply to a given schedule. You can also combine time triggers with event triggers on a given schedule.

    In the Triggers list of the Job Scheduler view, the 24 hour trigger is now associated with the new schedule.

  10. Click the Save icon to update the Orchestrate Server with the new schedule/trigger association.

(Optional) Adding Specific Parameters to the New Schedule

You can now add specific parameters to the schedule to edit its job arguments, to choose whether you want to pass the user environment variables to the schedule, or to specify policy constraints to further focus the purpose of this schedule when it fires.

For the purpose of this walkthrough, none of these specific parameters is modified, although a general overview of how to do so is explained.

The following specific parameters can be managed in the Job Scheduler Editor:

Job Arguments

As explained in Section 3.1.2, Creating or Modifying a Job Schedule, a job argument defines the values that can be passed in to the process when a job is invoked. These values let you statically define and control job behavior. The job arguments that appear in the Job Arguments tab of the Schedule Editor depend on the job. The job might have no arguments.

By default, the auditCleaner job lists only one job argument, jobargs.days.

Figure 3-11 The Job Arguments Tab of the Job Schedule Editor

According to the tool tip text, this argument is the number of days of job history to keep, so this job cleans up the history of the job in the PlateSpin Orchestrate audit database after the job reaches the age of 60 days. Data older than 60 days is to be deleted. If you want to, you can change this parameter, or any other parameter in a job argument.

If the default value for a job argument parameter is missing, the job might fail, so you should inspect these parameters carefully.

User Environment

As explained in Section 3.1.2, Creating or Modifying a Job Schedule, a user’s environment variables are available in the Job Scheduler only if that user utilizes the zos command line tool and elects to pass those environment variables to the server at login time or when he or she runs a job (running the job creates the environment variables as facts in the job). The zos run command passes the environment for that particular job run only.

In this walkthrough, the zosSystem user shows no user environment variables.

Figure 3-12 The User Environment Tab of the Job Scheduler Editor, No User Environment Variables Available

Because there are no environment variables listed, there are none to pass to the schedule, so it is not necessary to select the Pass User Environment check box. By default, this check box is not selected, even if environment variables are present for a user specified to run the job.

Sometimes a job is written to work from a user’s environment variables. In this case, if a user has not logged in or has not run the job from the zos command line using the necessary environment option, the schedule must pass those variables to the job when it is invoked.

If you associated a user who had user environment variables with this schedule, you would see a list of those environment variables as they would be passed to the job.

Figure 3-13 The User Environment Tab of the Job Schedule Editor, User Environment Variables Available

Selecting the Pass User Environment check box in this scenario would create these variables as facts used for this job invocation.

Constraints

As explained in Section 3.1.2, Creating or Modifying a Job Schedule, the Constraints tab displays a constraint editor that you can use to create additional constraints for the job being scheduled.

Figure 3-14 The Constraints Tab of the Job Schedule Editor

Any other constraints associated with the context of this job invocation (including but not limited to this job), with the user you’ve selected, with that user’s group, with the jobs group, with the resources that the job uses, or with the resource groups that the job uses, run in spite of the policy that you define here. These additional constraints usually restrict or refine what the job does when this schedule fires.

These constraints are passed to the job only when this schedule is invoked. For example, you could add a start constraint to delay the start of a job, a resource constraint to run on only one of three named machines, or a continue constraint to automatically time out the job if it takes too long to run. Anything you can do with a regular job policy constraint, you can add as a special constraint here for this particular schedule invocation.

Click Save icon to update the Orchestrate Server with the new schedule.

For more information about policies, see Policy Elements in the PlateSpin Orchestrate 2.0 Developer Guide and Reference.

3.2.4 Activating the New Schedule

When the new schedule has been created and its triggers defined, you need to take it from the disabled state to an active state where it is ready to run.

  1. In the Job Scheduler view, select the newly created job. The job shows that it is in a Disabled state.

  2. Click Enable to enable the schedule.

    The schedule is now enabled, but has not run yet.

3.2.5 Running the New Schedule Immediately

You can trigger the schedule immediately, rather than waiting for the triggers to fire.

  1. In the Job Schedules Table of the Job Scheduler view, select cleaner (the name of the schedule you want to run), click Run Now, then click the job monitor icon on the toolbar (Jobs) to open the Job Monitor view.

    The joblet icon shows that the job is running.

  2. Click the Job Scheduler icon on the toolbar to open the Job Scheduler view.

    The cleaner schedule is listed as an active job. This indicates that the schedule has started the job as anticipated.

    If you click the refresh icon , you can see that the job now has a Job ID.

    If the job invocation fails, as in this example, a red exclamation icon is also displayed.