Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

REST runs

A run is an ordered collection of requests that can be executed serially or in parallel as a deployment activity. You can schedule multiple runs to be executed on different dates and at different times. A plan stage might require one or more runs to complete all the tasks for that stage.

GET /v1/runs

Returns all runs

Filters

  • name — String for runs name
  • aasm_state — String value for Acts as State Machine (aasm) state (created, planned, started, held, blocked, completed, cancelled, deleted)
  • stage_id — Integer value for a related stage ID
  • owner_id — Integer value for a related user ID in the role of owner
  • requestor_id — Integer value for a related user ID in the role of requester
  • started_at — Date-time string in Coordinated Universal Time, or UTC (for example, 2012-10-24 15:24:03 UTC) that returns any run scheduled to start that same day
  • end_at — Date-time string in UTC (for example, 2012-10-24 15:24:03 UTC) that returns any run scheduled to finish that same day
  • time — Date-time string in UTC (for example, 2012-10-24 15:24:03 UTC) falling between run start and end dates, inclusive

Common attributes

  • format — Ensure 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/runs?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/runs?token=[api_token]

An example of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "name":"Sample Run" } }' http://[rails_host]/v1/runs?token=[api_token]

GET /v1/runs/[id]

Returns a run by ID.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure 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 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/runs/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/runs/[id]?token=[api_token]

POST /v1/runs

Creates a new run from posted data

Required attributes

  • name — String name of the run
  • owner_id — ID of user that owns the run
  • plan_id — ID of related plan
  • plan_stage_id — ID of related plan_stage
  • requestor_id — ID of user that requested the run

Optional attributes

  • description — String value for the description of the run
  • duration — Integer value for the duration
  • end_at_date — Alternate simple string accessors for setting the time data
  • end_at_hour — Alternate simple string accessors for setting the time data
  • end_at_meridian — Alternate simple string accessors for setting the time data (AM or PM)
  • end_at_minute — Alternate simple string accessors for setting the time data
  • end_at — Date-time value for the run end
  • start_at_date — Alternate simple string accessors for setting the time data
  • start_at_hour — Alternate simple string accessors for setting the time data
  • start_at_meridian — Alternate simple string accessors for setting the time data (AM or PM)
  • start_at_minute — Alternate simple string accessors for setting the time data 
  • start_at — Date-time value for the run start

Note

You can set the start_at and end_at time stamp fields by using a complete date-time string in UTC (2012-10-24 15:24:03 UTC) or by providing a date and values for the hour, minute, and meridian (AM or PM) by using the following alternate simple string accessors: _hour, _minute, _meridian, and _date.

Common attributes

  • format — Ensure 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 422 Unprocessable entity — Occurs when validation fails, objects and errors are returned

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" -H "Content-type: text/xml" -X POST -d '<run><name>Sample Run</name><owner_id>1</owner_id><plan_stage_id>1</plan_stage_id><plan_id>8</plan_id><requestor_id>1</requestor_id></run>' http://[rails_host]/v1/runs?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"name":"Sample Run", "owner_id":1, "plan_stage_id":1, "plan_id":1, "requestor_id":1}' http://[rails_host]/v1/runs/?token=[api_token]

PUT /v1/runs/[id]

Updates an existing run with values from a posted document

Editable attributes

  • name — String name of the run
  • owner_id — ID of user that owns the run
  • plan_id — ID of related plan
  • plan_stage_id — ID of related plan_stage
  • requestor_id — ID of user that requested the run
  • description — String value for the description of the run
  • duration — Integer value for the duration
  • end_at_date — Alternate simple string accessors for setting the time data
  • end_at_hour — Alternate simple string accessors for setting the time data
  • end_at_meridian — Alternate simple string accessors for setting the time data (AM or PM)
  • end_at_minute — Alternate simple string accessors for setting the time data
  • end_at — Date-time value for the run end
  • start_at_date — Alternate simple string accessors for setting the time data
  • start_at_hour — Alternate simple string accessors for setting the time data
  • start_at_meridian — Alternate simple string accessors for setting the time data (AM or PM)
  • start_at_minute — Alternate simple string accessors for setting the time data
  • start_at — Date-time value for the run start

Note

You can set the start_at and end_at time stamp fields by using a complete date-time string in UTC (2012-10-24 15:24:03 UTC) or by providing a date and values for the hour, minute, and meridian (AM or PM) by using the following alternate simple string accessors: _hour, _minute, _meridian, and _date.

State machine events

  • aasm_event — Can be submitted to transition a run to the next state. Supported events: plan_it, start, hold, block, cancel, complete, delete.

Toggle archival status

  • toggle_archive — Boolean value that will toggle the archive status of an object

Common attributes

  • format — Ensure 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 record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails, objects and errors are returned

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" -H "Content-type: text/xml" -X PUT -d '<run><name>Renamed Run</name></run>' http://[rails_host]/v1/runs/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "run": { "name" : "Renamed Run"}}'  http://[rails_host]/v1/runs/[id]?token=[api_token]

An example toggling the archive status of an object:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "toggle_archive": true }'  http://[rails_host]/v1/runs/[id]?token=[api_token]

An example of starting a run using the state machine:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "run": { "aasm_event":"start" }}' http://[rails_host]/v1/runs/[id]?token=[api_token]

DELETE /v1/runs/[id]

Deletes a run.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure 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 DELETE http://[rails_host]/v1/runs/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/runs/[id]?token=[api_token]

Sample output

The following JSON is a sample output from GET /v1/runs:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "780b255cc0a19530c3425a737799d5d1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: a15b2dbd4bd0f27cdcfe2cba34a8d8a3
X-Runtime: 0.072000
Content-Type: application/json;charset=utf-8
Content-Length: 462
Date: Fri, 08 Feb 2013 16:32:54 GMT

[{
"aasm_state": "created",
"created_at": "2013-02-08T11:17:45-05:00",
"description": null,
"duration": null,
"end_at": null,
"id": 1,
"name": "Sample Run",
"owner_id": 1,
"plan_id": 1,
"plan_stage_id": 1,
"requestor_id": 1,
"start_at": null,
"updated_at": "2013-02-08T11:17:45-05:00",
"plan": {
"aasm_state": "created",
"id": 1,
"name": "Sample Plan"
},
"plan_stage": {
"id": 1,
"name": "uat"
},
"plan_members": [{
"id": 1,
"position": 1,
"request": {
"aasm_state": "created",
"id": 3,
"name": "Sample Request 2"
}
}]
}]

The following XML is a sample output from GET /v1/runs/1:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "f954e84ef179588e8bc37dbcccd18a71"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: f24be9bedeee2e8a0f3140c0c0352fd1
X-Runtime: 0.143000
Content-Type: application/json;charset=utf-8
Content-Length: 460
Date: Fri, 08 Feb 2013 17:53:20 GMT

{
"aasm_state": "created",
"created_at": "2013-02-08T11:17:45-05:00",
"description": null,
"duration": null,
"end_at": null,
"id": 1,
"name": "Sample Run",
"owner_id": 1,
"plan_id": 1,
"plan_stage_id": 1,
"requestor_id": 1,
"start_at": null,
"updated_at": "2013-02-08T11:17:45-05:00",
"plan": {
"aasm_state": "created",
"id": 1,
"name": "Sample Plan"
},
"plan_stage": {
"id": 1,
"name": "uat"
},
"plan_members": [{
"id": 1,
"position": 1,
"request": {
"aasm_state": "created",
"id": 3,
"name": "Sample Request 2"
}
}]
} 

Related topic

REST-API-commands

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*