REST plan stages
Plan stages belong to the plan templates and define the primary gateways an application has to pass through in order to be successfully deployed. While these often have the same names as environments in BMC Release Process Management (RPM), they are distinct in order to allow environments to be scaled (dev1, dev2, dev3) or temporarily borrowed and assigned to a differently named stage such as when a QA environment is borrowed for work in the development stage for a diagnostic routine.
GET /v1/plan_stages
Returns all the plan stages.
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. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
plan_stages | plan_template, request_templates, plan_stage_dates, environment_type |
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/plan_stages?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/plan_stages?token=[api_token]
Filter example:
curl -i -H "accept: application/json" -H "Content-type: application/json" -d '{ "filters": { "include_except":"plan_template, request_templates" }}' -X GET https://[rails_host]/v1/plan_stages?token=[api_token]
GET /v1/plan_stages/[id]
Returns a plan stage by the 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 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 |
|---|---|
plan_stages | plan_template, request_templates, plan_stage_dates, environment_type |
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/plan_stages/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/plan_stages/[id]?token=[api_token]
Filter example:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"plan_template,request_templates" }}' https://[rails_host]/v1/plan_stages/[id]?token=[api_token]
POST /v1/plan_stages
Creates a new plan stage from a posted data.
Required attributes
- name—String name of the plan_stage (unique for each plan template)
- plan_template_id—Integer ID of the plan template ID
- environment_type_id—Integer ID of the environment type ID
Optional attributes
- insertion_point—Integer of the position order of the plan stage
- auto_start—Boolean value for auto start
- requestor_access—Boolean value for whether requester roles should be able to modify requests in this stage (defaults true)
- request_template_ids—Array of integer IDs for related request template IDs that should be turned into requests when a plan is created based on this template.
- run_ids—Array of integer IDs for runs
- required—Boolean value for required plan stages
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. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
plan_stages | plan_template, request_templates, plan_stage_dates, environment_type |
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 '<plan_stage><name>Sample Plan Stage</name><plan_template_id>1</plan_template_id> <request_template_id>1</request_template_id><environment_type_id>1</
environment_type_id></plan_stage>' http://[rails_host]/v1/plan_stages?token=[api_token]
environment_type_id></plan_stage>' http://[rails_host]/v1/plan_stages?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"plan_template_id":1,"name":"Sample Plan Stage", "request_template_id":1, "environment_type_id":1 }' http://[rails_host]/v1/plan_stages/?token=[api_token]
Filter example:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "plan_stage": {"plan_template_id":1,"name":"Rest Plan Stage 1", "environment_type_id":1 }, "filters": {"include_except" : "plan_template, request_templates"}}' https://[rails_host]/v1/plan_stages/?token=[api_token]
PUT /v1/plan_stages/[id]
Updates an existing plan stage.
Editable attributes
- name—String name of the plan_stage (unique for each plan template)
- plan_template_id—Integer ID of the plan template ID
- environment_type_id—Integer ID of the environment type ID
- insertion_point—Integer of the position order of the plan stage
- auto_start—Boolean value for auto_start
- requestor_access—Boolean value for whether requestor roles should be able to modify requests in this stage (defaults true)
- request_template_ids—Array of integer IDs for related request template IDs that should be turned into requests when a plan is created based on this template.
- run_ids—Array of integer IDs for runs
- required—Boolean value for required plan stages
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. See the table below for the items and their associated items.
Item | Associated items |
|---|---|
plan_stages | plan_template, request_templates, plan_stage_dates, environment_type |
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 '<plan_stage><name>Renamed Plan Stage</name></plan_stage>' http://[rails_host]/v1/plan_stages/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "plan_stage": { "name" : "Renamed Plan Stage"}}' http://[rails_host]/v1/plan_stages/[id]?token=[api_token]
Filter example:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "plan_stage": {"plan_template_id":1,"name":"Renamed Plan Stage 1", "environment_type_id":1 }, "filters": { "include_except":"plan_template, request_templates" }}' https://[rails_host]/v1/plan_stages/[id]?token=[api_token]
DELETE /v1/plan_stages/[id]
Deletes a plan stage.
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/plan_stages/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/plan_stages/[id]?token=[api_token]
Sample output
The following JSON is a sample output from GET /v1/plan_stages:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "b261c106fd9c1404958c021e14a99687"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 928e17ba31435509a12e2fbbe271eb08
X-Runtime: 1.280000
Content-Type: application/json;charset=utf-8
Content-Length: 1009
Date: Wed, 24 Oct 2012 00:47:53 GMT
[{
"auto_start": false,
"created_at": "2012-10-23T19:51:05-04:00",
"environment_type_id":2
"id": 2,
"name": "QA",
"plan_template_id": 1,
"position": 2,
"requestor_access": true,
"required":true,
"updated_at": "2012-10-23T19:51:05-04:00",
"plan_template": {
"id": 1,
"is_automatic": false,
"name": "Sample Deploy Template"
},
"request_templates": [{
"id": 1,
"name": "Sample Request"
}],
"plan_stage_dates": []
"environment_type": {
"description":"A default environment type.",
"id":2,
"name":"Development"
}
}]
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "b261c106fd9c1404958c021e14a99687"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 928e17ba31435509a12e2fbbe271eb08
X-Runtime: 1.280000
Content-Type: application/json;charset=utf-8
Content-Length: 1009
Date: Wed, 24 Oct 2012 00:47:53 GMT
[{
"auto_start": false,
"created_at": "2012-10-23T19:51:05-04:00",
"environment_type_id":2
"id": 2,
"name": "QA",
"plan_template_id": 1,
"position": 2,
"requestor_access": true,
"required":true,
"updated_at": "2012-10-23T19:51:05-04:00",
"plan_template": {
"id": 1,
"is_automatic": false,
"name": "Sample Deploy Template"
},
"request_templates": [{
"id": 1,
"name": "Sample Request"
}],
"plan_stage_dates": []
"environment_type": {
"description":"A default environment type.",
"id":2,
"name":"Development"
}
}]
The following XML is a sample output from GET /v1/plan_stages/1:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "3a08f8c8dae46685d0eee0ee715472b3"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: edfe3b573d3896ec1179068fc8cc5981
X-Runtime: 2.024000
Content-Type: application/xml;charset=utf-8
Content-Length: 1237
Date: Wed, 24 Oct 2012 00:46:44 GMT
<plan-stage>
<auto-start type="boolean">false</auto-start>
<created-at type="datetime">2012-10-23T19:50:58-04:00</created-at>
<environment-type-id type="integer">2</environment-type-id>
<id type="integer">1</id>
<name>Dev</name>
<plan-template-id type="integer">1</plan-template-id>
<position type="integer">1</position>
<requestor-access type="boolean">true</requestor-access>
<required type="boolean">true</required>
<updated-at type="datetime">2012-10-23T19:50:58-04:00</updated-at>
<plan-template>
<id type="integer">1</id>
<is-automatic type="boolean">false</is-automatic>
<name>Sample Deploy Template</name>
</plan-template>
<request-templates type="array">
<request-template>
<id type="integer">1</id>
<name>Sample Request</name>
</request-template>
</request-templates>
<plan-stage-dates type="array"/>
<members type="array">
<member type="PlanMember">
<position type="integer">1</position>
<stage>
<id type="integer">1</id>
<name>Dev</name>
<position type="integer">1</position>
</stage>
<request>
<aasm-state>created</aasm-state>
<name>Sample Request</name>
<number type="integer">1003</number>
</request>
</member>
</members>
<environment-type>
<description>A default environment type.</description>
<id type="integer">2</id>
<name>Development</name>
</environment-type>
</plan-stage>
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "3a08f8c8dae46685d0eee0ee715472b3"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: edfe3b573d3896ec1179068fc8cc5981
X-Runtime: 2.024000
Content-Type: application/xml;charset=utf-8
Content-Length: 1237
Date: Wed, 24 Oct 2012 00:46:44 GMT
<plan-stage>
<auto-start type="boolean">false</auto-start>
<created-at type="datetime">2012-10-23T19:50:58-04:00</created-at>
<environment-type-id type="integer">2</environment-type-id>
<id type="integer">1</id>
<name>Dev</name>
<plan-template-id type="integer">1</plan-template-id>
<position type="integer">1</position>
<requestor-access type="boolean">true</requestor-access>
<required type="boolean">true</required>
<updated-at type="datetime">2012-10-23T19:50:58-04:00</updated-at>
<plan-template>
<id type="integer">1</id>
<is-automatic type="boolean">false</is-automatic>
<name>Sample Deploy Template</name>
</plan-template>
<request-templates type="array">
<request-template>
<id type="integer">1</id>
<name>Sample Request</name>
</request-template>
</request-templates>
<plan-stage-dates type="array"/>
<members type="array">
<member type="PlanMember">
<position type="integer">1</position>
<stage>
<id type="integer">1</id>
<name>Dev</name>
<position type="integer">1</position>
</stage>
<request>
<aasm-state>created</aasm-state>
<name>Sample Request</name>
<number type="integer">1003</number>
</request>
</member>
</members>
<environment-type>
<description>A default environment type.</description>
<id type="integer">2</id>
<name>Development</name>
</environment-type>
</plan-stage>
Related topic
Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*