7.7 Working with Facts and Constraints

You can incorporate facts and constraints into the custom jobs you create to manage your data center resources using PlateSpin Orchestrate. You should already be familiar with the concepts related to controlling jobs using job facts and constraints. For more information, see the following JDL links:

This section contains the following topics:

7.7.1 Grid Objects and Facts

Every resource and service discovered in an PlateSpin Orchestrate-enabled network is identified and abstracted as an object. Within the PlateSpin Orchestrate management framework, objects are stored within an addressable database called a grid. Every grid object has an associated set of facts and constraints that define the properties and characteristics of either physical or virtual resources. Essentially, by building, deploying, and running jobs on the Orchestrate Server, you can individually change the functionality of any and all system resources by managing an object’s facts and constraints.

The components that have facts include resources, users, jobs, repositories, and vmhosts. The grid server assigns default values to each of the component facts, although they can be changed at anytime by the administrator (unless they are read-only).

However, the developer wants certain constraints to be used for a job and might specify these in the policy. These comprise a set of logical clauses and operators that are compared with the respective component’s fact values when the job is run by the Job Scheduling Manager.

Remember, all properties appear in the job context, which is an environment where constraints are evaluated. These constraints provide a multilevel filter for a job in order to ensure the best quality of service the grid can provide.

7.7.2 Defining Job Elements

When you deploy a job, you can include an XML policy file that defines constraints and facts. Because every job is a grid object with its own associated set of facts (job.id, etc.), it already has a set of predefined facts, so jobs can also be controlled by changing job arguments at run time.

As a job writer, you define the set of job arguments in the job args fact space. Your goal in writing a job is to define the specific elements a job user is permitted to change. These job argument facts are defined in the job XML policy for every given job.

The job argument fact values are passed to a job when the job is run. Consequently, the Orchestrate Server run command passes in the job arguments. Similarly, for the job scheduler, you can define which job arguments you want to schedule or run a job. You can also specify job arguments when using the Server Portal.

For example, in the following quickie.job example, the number of joblets allowed to run and the amount of sleep time between running joblets are set by the arguments numJoblets and sleeptime as defined in the policy file for the job. If no job arguments are defined, the client cannot affect the job:

          # Launch the joblets
          numJoblets = self.getFact("jobargs.numJoblets")
          print 'Launching ', numJoblets, ' joblets'

          self.schedule(quickieJoblet, numJoblets)

class quickieJoblet(Joblet):

     def joblet_started_event(self):
          sleeptime = self.getFact("jobargs.sleeptime")          time.sleep(sleeptime)

To view the complete example, see quickie.job.

As noted, when running a job, you can pass in a policy file, which is another method the client can use to control job behavior. Policy files can pass in additional constraints to the job, such as how a resource might be selected or how the job runs. The policy file is an XML file defined with the .policy extension.

For example, as shown below, you can pass in a policy for the job named quickie, with an additional constraint to limit the chosen resources to those with a Linux OS. Suppose a policy file name linux.policy in the directory named /mypolicies with this content:

<constraint type="resource">    <eq fact="resource.os.family" value="linux" /></constraint>

To start the quickie job using the additional policy, you would enter the following command:

>zos run quickie --policyfile=/mypolicies/linux.policy

Creating Constraints Outside of the Constraint Evaluation

When you create constraints, it is sometimes useful to access facts on a Grid object that is not in the context of the constraint evaluation. An example scenario would be to sequence the running of jobs triggered by the Job Scheduler.

In this example, you need to make job2 run only when all instances of job1 are complete. To do this, you could add the following start constraint to the job2 definition:

<constraint type="start">
  <eq fact="job[job1].instances.active" value="0"/>

Here, the job in the context is job2, however the facts on job1 (instances.active) can still be accessed. The general form of the fact name is:


PlateSpin Orchestrate supports specific Grid object access for the following grid objects

  • Users
  • Jobs
  • Resources
  • VMHosts
  • Repositories

Currently, explicit group access is not supported.

7.7.3 Job Arguments and Parameter Lists

Part of a job’s static definition might include job arguments. A job argument defines what values can be passed in when a job is invoked. This allows the developer to statically define and control how a job behaves, while the administrator can modify policy values.

You define job arguments in an XML policy file named with the same base name as the job. The example job cracker.jdl, for example, has an associated policy file named cracker.policy. The cracker.policy file contains entries for the <jobargs> namespace, as shown in the following partial example from cracker.policy.

          <fact name="cryptpw"
           description="Password of abc"
        <fact name="joblets"
           description="joblets to run"

The above policy defines two facts in the jobargs namespace for the cracker job. One is a String fact named cryptpw with a default value. The second jobargs fact is an integer named joblets. Both of these facts have default values so they do not require been set on job invocation. If the default value was omitted, then job would require that the two facts be set on job invocation. The job will not start unless all required job argument facts are supplied at job invocation. The default values of job argument facts can be overridden at job invocation. Job arguments are passed to a job when the job is invoked. This is done in one of the following ways:

  • From the Orchestrate Server run command from the CLI, as shown in the following example:

    >zos run cracker cryptpw="dkslsl"
  • From within a JDL job script when invoking a child job, as shown in the following job JDL fragment:

    self.runjob("cracker", { "cryptpw" : "asdfa" } )
  • From the Job Scheduler, either with the Orchestrate Development Client or by a .sched file.