CTL-JOBS Command Reference
From ControlTier
Requires Version: 3.5.2
Contents |
Synopsis
ctl-jobs <action> [-h] [-v] [action options...] ctl-jobs [list] [-n name] [-g group] [-i idlist] [-p project] [-c command] [-r resource] [-t type] [-f file] ctl-jobs load -f file
Since CTL 3.5
Overview
The ctl-jobs command lists Jobs stored on the server and optionally downloads them as XML, or uploads Job XML to the server from a file.
(This command takes the place of the ProjectBuilder's commands "load-jobs" and "find-jobs" from ControlTier 3.4)
The tool provides two actions:
- list
- list the stored Jobs on the server (default action)
- load
- upload XML job definitions up to the server
Related Tools
- ctl-run runs a Job stored on the server.
- ctl-queue lists the running job executions, and can kill executions.
- ctl and ctl-exec can use the
-Qflag to submit "transient" executions to the Central Dispatcher
General Options
| Option | alternate | argument | description |
|---|---|---|---|
| -h | --help | false | Displays help and usage information |
| -v | --verbose | false | Enable verbose output |
List Action
Options:
| Option | alternate | argument | description |
|---|---|---|---|
| -g | --group | true | Group name. List jobs within this group or sub-group |
| -i | --idlist | true | Job ID List. List Jobs with these IDs explicitly. Comma-separated, e.g.: 1,2,3. |
| -c | --command | true | Command name. List Jobs for Defined commands using this command. |
| -n | --name | true | Job Name. List jobs matching this name. |
| -p | --project | true | Project name. List jobs within this project. |
| -r | --resource | true | Resource name. List jobs for Defined commands using this resource. |
| -t | --type | true | Type name. List Jobs for Defined commands using this type. |
| -f | --file | true | File path. For list action, path to store the job definitions found in XML. |
The List action queries the server for a list of matching jobs, and displays the result list.
Optionally the definitions of the matching jobs can be stored in a file if -f is specified.
The jobs can be specifed explicitly by ID using the -i/--idlist option. Otherwise they are searched using the options as filter criteria, and all matching Jobs are returned.
If no options to the list action are supplied, then all Jobs on the server are returned.
Execution
List all jobs on the server:
ctl-jobs
List only a single job by ID:
ctl-jobs -i 123
List a set of jobs by ID and store them in a file:
ctl-jobs -i 1,23,4 --file out.xml
List all jobs in the project "demo"
ctl-jobs -p demo
List all Jobs that run a command on the JBossServer resource named "qaJboss1"
ctl-jobs -t JBossServer -r qaJboss1
List all Jobs that run a "Deploy" command
ctl-jobs -c Deploy
Output from the command will list the job name, ID number in brackets, and the URL to view the Job in the server.
Found 5 jobs: 1: Build all [38] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/38> 2: Build and Update Server0 [31] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/31> 3: Build and Update Server1 [17] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/17> 4: Build and Update Server2 [45] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/45> 5: Deploy Server4 [46] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/46>
Load Action
Options:
| Option | alternate | argument | description |
|---|---|---|---|
| -d | --duplicate | true | Duplicate job behavior option. When loading jobs, treat definitions that already exist on the server in the given manner: 'update' existing jobs,'skip' the uploaded definitions, or 'create' them anyway. (load action. default: update) |
| -f | --file | true | File path. For load action, path to an XML file to upload. (required) |
The Load action uploads the specified file to the server, and the list of loaded jobs are displayed. If any Jobs cannot be stored (e.g. the user is unauthorized to run a certain command), the list of unsuccessfully created jobs are also displayed.
The -d/--duplicate option lets you specify what should happen if any of the Job definitions have the same Name and Group of an existing Job on the server. The default option is "update", which means to overwrite the existing definitions with the new version. "skip" means to ignore the uploaded definition. "create" means to create a new Job with the uploaded definition (hence making the Group+Name non-unique).
Execution
Load a file to the server:
ctl-jobs load -f jobs.xml
Output:
Total Jobs Uploaded: 2 jobs Succeeded creating/updating 2 Jobs: 1: Build and Update Server2 [45] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/45> 2: Deploy Server4 [46] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/46>
If a Job was not successfully created, you will see it mentioned along with a message about why it failed. The number next to the Job name indicates the index of the definition in the uploaded XML:
ctl-jobs load -f jobs.xml
Output:
Total Jobs Uploaded: 3 jobs Failed to add 1 Jobs: 3: Build Server1 : Project was not found: north Project was not found: north Succeeded creating/updating 2 Jobs: 1: Build and Update Server2 [45] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/45> 2: Deploy Server4 [46] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/46>
If the -d skip is specified, then any jobs definitions that were skipped will be listed:
ctl-jobs load -f jobs.xml -d skip
Output:
Total Jobs Uploaded: 2 jobs Skipped 2 Jobs: 1: Build and Update Server2 [45] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/45> 2: Deploy Server4 [46] <http://Venkman.local:9090/ctlcenter/scheduledExecution/show/46>
| ||||||||||||||
