Job-v20.xml

From ControlTier

Requires Version: 3.6.0

The 'job' XML file declares job entries for CTL Center in ControlTier 3.6.

This is a demonstration document using all possible elements in the current CTL Center "jobs" XML. Loading and unloading This file can be batch loaded via ctl-jobs load command:

ctl-jobs load --file /path/to/jobs.xml

CTL Center job definitions can be dumped and saved to a file via ctl-jobs list command:

ctl-jobs list --file /tmp/jobs.xml

joblist

The root (aka "top-level") element of the jobs XML file.

Example

<joblist>
  <job>
   ...
  </job>
  <job>
   ...
  </job>
</joblist>

job

The job element is a sub-element of #joblist and defines a job executable in CTL Center. The following elements are used to describe the job. Only one of each element is allowed.

Job command modes

Jobs execute a sequence of commands. Commands come in several styles:

• System command.
• A script
• A script file
• A command defined in a CTL module.
• Another defined job

Examples System Example: Execute the Unix 'who' command

<joblist>
  <job>
    <name>who's logged in?</name>
    <description>Runs the unix who command</description>
    <additional/>
    <group>sysadm/users</group>
    <context>
      <project>default</project>
    </context>
    <sequence>
      <command>
        <!-- the Unix 'who' command -->
        <exec>who</exec>
      </command>
     </sequence>
    <nodefilters excludeprecedence="true">
      <include>
        <os-family>unix</os-family>
      </include>
    </nodefilters>
    <dispatch>
      <threadcount>1</threadcount>
      <keepgoing>true</keepgoing>
    </dispatch>
  </job>
</joblist>

Script Example: Execute the Bash script

<joblist>
  <job>
    <name>a simple script</name>
    <description>Runs a trivial bash script</description>
    <additional/>
    <group>sysadm/users</group>
    <context>
      <project>default</project>
    </context>
    <sequence>
      <command>
        <script><![CDATA[#!/bin/bash
echo this is an example job running on $(hostname)
echo whatever
exit 0 ]]></script>
      </command>
     </sequence>
    <dispatch>
      <threadcount>1</threadcount>
      <keepgoing>true</keepgoing>
    </dispatch>
  </job>
</joblist>

Defined command Example: Execute the 'testAll' command defined in module, coretests

<joblist>
  <job>
    <name>test coreutils</name>
    <description/>
    <additional/>
    <context>
      <project>default</project>
    </context>
    <sequence>
        <!-- the coretests 'testAll' command -->
        <command name="testAll" module="coretests">
            <arg line=""/>
        </command>
    </sequence>
    <dispatch>
      <threadcount>1</threadcount>
      <keepgoing>false</keepgoing>
    </dispatch>
  </job>
</joblist>

Multiple commands Example: Execute a sequence of other commands, scripts and jobs:

<joblist>
  <job>
    <name>test coreutils</name>
    <description/>
    <additional/>
    <context>
      <project>default</project>
    </context>
    <sequence>
      <!-- the coretests 'testAll' command -->
     <command module="coretests" name="testAll">
     </command>
     <!-- the Unix 'who' command -->
     <command>
        <exec>who</exec>
     </command>
     <!-- a Job named test/other tests -->
     <command>
        <jobref group="test" name="other tests"/>
     </command>
    </sequence>
    <dispatch>
      <threadcount>1</threadcount>
      <keepgoing>false</keepgoing>
    </dispatch>
  </job>
</joblist>

id

The job identifier is a sub-element of #job. This is normally defined by CTL Center upon job creation. If it is specified, job will be created with this id. If a job was already defined with this id, it will be updated with the included job definition.

name

The job name is a sub-element of #job. The combination of 'name' and #group must be unique if the #id identifier is not included.

description

The job description is a sub-element of #job and allows a short description of the job.

additional

The additional element is a sub-element of #job and provides a place to declare additional user information.

Markdown syntax can be used inside this element.

<additional>
Here's a link to [Additional tag reference](http://controltier.org/wiki/Job-v20.xml#additional "Wiki"). 
</additional>

group

The group is a sub-element of #job and defines the job's group identifier. This is a "/" (slash) separated string that mimics a directory structure. Example

<job>
    <name>who</name>
    <description>who is logged in?</description>
    <additional/>
    <group>/sysadm/users</group>
</job>

schedule

schedule is a sub-element of #job and specifies periodic job execution using the stated schedule. The schedule can be specified using embedded elements as shown below, or using a single #crontab attribute to set a full crontab expression.

Example

Run the job every morning at 6AM, 7AM and 8AM.

<schedule>
	 <time hour="06,07,08" minute="00"/>
	 <weekday day="*"/>
	 <month month="*"/>
</schedule>

Run the job every morning at 6:00:02AM, 7:00:02AM and 8:00:02AM only in the year 2010:

<schedule>
	 <time hour="06,07,08" minute="00" seconds="02"/>
	 <weekday day="*"/>
	 <month month="*"/>
	 <year year="2010"/>
</schedule>

Run the job every morning at 6:00:02AM, 7:00:02AM and 8:00:02AM only in the year 2010, using a single crontab attribute to express it:

<schedule crontab="02 00 06,07,08 ? * * 2010"/>

For more information, see http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html or Stonebranch

crontab

Attribute of the #schedule, sets the schedule with a full crontab string. For more information, see [1].

If specified, then the embedded schedule elements are not used.

time

The #schedule time to run the job

weekday

The #schedule weekday to run the job

month

The #schedule month to run the job

context

The #job context.

project

The #context project name.

options

The #context options that correspond to the called #command.

Example

<options>
        <option name="detail" value="true"/>
</options>

Valid for Defined Command jobs and Workflow jobs (since 3.5.3).

option

Defines one option within the #options.

Example

Define defaults for the "port" option.

<option name="port" value="80" values="80,8080,8888" enforcedvalues="true" regex="\d+"/>

valuesUrl JSON

The data returned from the valuesUrl can be formatted as a map:

{"x label":"X value","y label":"Y value", "z label":"Z value"}

or as array:

["x value","y value", "z value"]

dispatch

The #job dispatch options. See the Dispatcher options for general information.

Example

<dispatch>
      <threadcount>1</threadcount>
      <keepgoing>false</keepgoing>
</dispatch>

threadcount

Defines the number of threads to execute within #dispatch. Must be a positive integer.

keepgoing

Boolean describing if the #dispatch should continue of an error occurs (true/false). If true, continue if an error occurs.

loglevel

The #job logging level. The lower the more profuse the messages.

1. DEBUG
2. VERBOSE
3. INFO
4. WARN
5. ERR

  <job>
    <name>Build</name>
    <description>Build the Duke's Bank application using the specified release version.</description>
    <additional>Edit the job's definition and change the buildstamp option to the required release version.</additional>
 
    <loglevel>WARN</loglevel>
 
    <group>Build/DukesBank</group>
    <context>
      <project>demo</project>
      <type>JBossAntBuilder</type>
      <object>dukesBank</object>
      <command>Build</command>
    </context>
   .
   .
   .

nodefilters

The #job nodefilters options. See Dispatcher options for a general description.

Example

<nodefilters excludeprecedence="true">
      <include>
        <hostname/>
        <type/>
        <tags>tomcats</tags>
        <os-name/>
        <os-family/>
        <os-arch/>
        <os-version/>
        <name/>
      </include>
</nodefilters>

include

See #Include/exclude patterns

exclude

See #Include/exclude patterns

Include/exclude patterns

The #nodefilters include and exclude patterns.

sequence

The #job workflow sequence.

The strategy attribute determines the way that the workflow is executed. "node-first" means execute the full workflow on each node prior to the next. "step-first" means execute each step across all nodes prior to the next step.

command

Defines an item for a workflow #sequence.

The different types of sequence items are defined in different ways.

See:

• #Defined command item
• #Script sequence item
• #Job sequence item

Defined command item

Use a command element in the following way:

Optional "arg" element can be embedded:

Example Module context:

<command name="listening" module="netutil">
    <arg line="-port 8080" />
</command>

Example Resource context:

<command name="Build" module="AntBuilder" resource="application1">
    <arg line="-buildstamp 123" />
</command>

arg

For a #Defined command item

Script sequence item

Script items can be defined in three ways within a command element:

• Simple shell command using exec element.
• Embedded script using script element.
• Script file using scriptfile and scriptargs elements.

Example exec item:

<command>
 <exec>echo this is a shell command</exec>
</command>

Inline script. Note that using CDATA section will preserve linebreaks in the script. Simply put the script within a script element:

<command>
    <script><![CDATA[#!/bin/bash
echo this is a test
echo whatever
exit 2 ]]></script>
</command>

Script File:

<command >
    <scriptfile>/path/to/a/script</scriptfile>
    <scriptargs>-whatever something</scriptargs>
</command>

Job sequence item

Define a #jobref element within the command element

jobref

Optional "arg" element can be embedded:

Example:

<command >
    <jobref group="My group" name="My Job"/>
</command>

Example passing arguments to the job:

<command >
    <jobref group="My group" name="My Job">
         <arg line="-option value -option2 value2"/>
    </jobref>
</command>

notification

Defines email notifications for Job success and failure, with in a #job definition.

Example:

<notification>
    <onfailure>
        <email recipients="test@example.com,foo@example.com" />
    </onfailure>
    <onsuccess>
        <email recipients="test@example.com" />
    </onsuccess>
</notification>

onsuccess

Embed a #email to send email on success, within #notification.

onfailure

Embed a #email to send email on failure or kill, within #notification.

email

Define email recipients for Job execution result, within #onsuccess or #onfailure.