REST job runs
Job runs are models that track the progress of automated background processes in BMC Release Process Management, usually user-initiated automations as part of a request or a step. This REST interface enables you to query the currently running job pool. Unlike most REST controllers in BMC Release Process Management, this model does not support the RESTful creation (POST), updating (PUT), or deletion (DELETE) of job runs because they can be initiated and modified only by internal processes.
GET /v1/job_runs
Returns all job runs.
Filters
- currently_running — Boolean value, true returns if the job list is currently running
- run_key — Integer value for the run_key
- status— String value for status
- job_type — String value for job type (automation, notification)
- process_id — Integer for process ID
- automation_id — Integer for the automation ID
- user_id — Integer value for the user ID
- step_id — Integer value for step ID
- include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
- alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
job_runs | step |
Common attributes
- format — Be sure to include an accept header or add .xml or .json to the last path element
- token — Your API Token for authentication
Errors caused
- ERROR 403 Forbidden — Occurs when the token is invalid
- ERROR 404 Not Found — Occurs when no records are found
Examples
To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:
curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/job_runs?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/job_runs?token=[api_token]
Example of filters:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "currently_running":true } }' http://[rails_host]/v1/job_runs?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -d '{ "filters": { "include_except":"step" }}' -X GET https://[rails_host]/v1/job_runs?token=[api_token]
GET /v1/job_runs/[id]
Returns a job run by ID.
Common attributes
- id — Numerical unique ID for record
- format — Be sure to include an accept header or add .xml or .json to the last path element
- token — Your API Token for authentication
Filters
- include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
- alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
job_runs | step |
Errors caused
- ERROR 403 Forbidden — Occurs when the token is invalid
- ERROR 404 Not found — Occurs when record to show is not found
Examples
To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:
curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/job_runs/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/job_runs/[id]?token=[api_token]
Filter example"
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"step" }}' https://[rails_host]/v1/job_runs/[id]?token=[api_token]
POST /v1/job_runs
This method is not allowed for job runs.
Errors caused
- ERROR 403 Forbidden — Occurs when the token is invalid
- ERROR 405 Method not allowed — This method is not allowed
PUT /v1/job_runs/[id]
This method is not allowed for job runs
Errors caused
- ERROR 403 Forbidden — Occurs when the token is invalid
- ERROR 405 Method not allowed — This method is not allowed
DELETE /v1/job_runs/[id]
This method is not allowed for job runs.
Errors caused
- ERROR 403 Forbidden — Occurs when the token is invalid.
- ERROR 405 Method not allowed — This method is not allowed.
Sample output
The following JSON is a sample output from GET /v1/job_runs:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "ca4ca01a368a303e669f3bfa6c0e5169"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: a79edb8e09618408dd0288a307fc9dd1
X-Runtime: 0.106000
Content-Type: application/json;charset=utf-8
Content-Length: 594
Date: Tue, 04 Sep 2012 19:43:54 GMT
[{
"automation_id": 6,
"created_at": "2012-09-04T15:34:44-04:00",
"finished_at": "2012-09-04T15:37:18-04:00",
"id": 1,
"job_type": "automation",
"process_id": 7408,
"results_path": "[...]/Portal/public/automation_results/request/SmartRelease/1003/step_35/output_1346787283.txt",
"run_key": 1346787283,
"started_at": "2012-09-04T15:34:44-04:00",
"status": "Complete",
"stderr": null,
"stdout": null,
"updated_at": "2012-09-04T15:37:18-04:00",
"step": {
"aasm_state": "complete",
"id": 35,
"name": "Test Automation",
"request": {
"aasm_state": "complete",
"id": 3,
"name": "Request Example"
}
}
}]
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "ca4ca01a368a303e669f3bfa6c0e5169"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: a79edb8e09618408dd0288a307fc9dd1
X-Runtime: 0.106000
Content-Type: application/json;charset=utf-8
Content-Length: 594
Date: Tue, 04 Sep 2012 19:43:54 GMT
[{
"automation_id": 6,
"created_at": "2012-09-04T15:34:44-04:00",
"finished_at": "2012-09-04T15:37:18-04:00",
"id": 1,
"job_type": "automation",
"process_id": 7408,
"results_path": "[...]/Portal/public/automation_results/request/SmartRelease/1003/step_35/output_1346787283.txt",
"run_key": 1346787283,
"started_at": "2012-09-04T15:34:44-04:00",
"status": "Complete",
"stderr": null,
"stdout": null,
"updated_at": "2012-09-04T15:37:18-04:00",
"step": {
"aasm_state": "complete",
"id": 35,
"name": "Test Automation",
"request": {
"aasm_state": "complete",
"id": 3,
"name": "Request Example"
}
}
}]
The following XML is a sample output from GET /v1/job_runs/1:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "c97e27338fe5b440031db9d9dd7d87e3"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 4185487e7a4f67e362f8e114aa64ab4a
X-Runtime: 1.858000
Content-Type: application/xml;charset=utf-8
Content-Length: 1061
Date: Tue, 04 Sep 2012 19:42:27 GMT
<?xml version="1.0" encoding="UTF-8"?>
<job-run>
<automation-id type="integer">6</automation-id>
<created-at type="datetime">2012-09-04T15:34:44-04:00</created-at>
<finished-at type="datetime">2012-09-04T15:37:18-04:00</finished-at>
<id type="integer">1</id>
<job-type>automation</job-type>
<process-id type="integer">7408</process-id>
<results-path>[...]/Portal/public/automation_results/request/SmartRelease/1003/step_35/output_1346787283.txt</results-path>
<run-key type="integer">1346787283</run-key>
<started-at type="datetime">2012-09-04T15:34:44-04:00</started-at>
<status>Complete</status>
<stderr nil="true"></stderr>
<stdout nil="true"></stdout>
<updated-at type="datetime">2012-09-04T15:37:18-04:00</updated-at>
<step>
<aasm-state>complete</aasm-state>
<id type="integer">35</id>
<name>Test Automation</name>
<request>
<aasm-state>complete</aasm-state>
<id type="integer">3</id>
<name>Request Example</name>
</request>
</step>
</job-run>
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "c97e27338fe5b440031db9d9dd7d87e3"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 4185487e7a4f67e362f8e114aa64ab4a
X-Runtime: 1.858000
Content-Type: application/xml;charset=utf-8
Content-Length: 1061
Date: Tue, 04 Sep 2012 19:42:27 GMT
<?xml version="1.0" encoding="UTF-8"?>
<job-run>
<automation-id type="integer">6</automation-id>
<created-at type="datetime">2012-09-04T15:34:44-04:00</created-at>
<finished-at type="datetime">2012-09-04T15:37:18-04:00</finished-at>
<id type="integer">1</id>
<job-type>automation</job-type>
<process-id type="integer">7408</process-id>
<results-path>[...]/Portal/public/automation_results/request/SmartRelease/1003/step_35/output_1346787283.txt</results-path>
<run-key type="integer">1346787283</run-key>
<started-at type="datetime">2012-09-04T15:34:44-04:00</started-at>
<status>Complete</status>
<stderr nil="true"></stderr>
<stdout nil="true"></stdout>
<updated-at type="datetime">2012-09-04T15:37:18-04:00</updated-at>
<step>
<aasm-state>complete</aasm-state>
<id type="integer">35</id>
<name>Test Automation</name>
<request>
<aasm-state>complete</aasm-state>
<id type="integer">3</id>
<name>Request Example</name>
</request>
</step>
</job-run>
Related topic
Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*