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 name of runs
• 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

• 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 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.

Common attributes

• format—Make 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:

Examples of filters:

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

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 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.

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:

Filter example:

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
• request_ids—Array of integer IDs of associated requests

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
• auto_promote—Boolean value to allow the run to promote automatically to the next plan stage after successful completion of the requests in the run. If set to true, on completion of all requests, the run is promoted to the next plan stage automatically.

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

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.

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:

An example for multiple request IDs:

Filter example:

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
• auto_promote—Boolean value to allow the run to promote automatically to the next plan stage after successful completion of the requests in the run. If set to true, on completion of all requests, the run is promoted to the next plan stage automatically.

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

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 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.

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:

An example toggling the archive status of an object:

An example of starting a run using the state machine:

An example of using the auto_promote parameter set to true:

Filter example:

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:

Sample output

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

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