Skip to Content

REST plan templates

A plan template is a blueprint by which child plans receive their stages, default request templates, and security properties.

Warning

Note

The include_except and alone filters are available in only 5.0.03.004 and later versions of RPM. Use these filters to limit the data in API response and hence, reduce the API response time.

GET /v1/plan_templates

Returns all plan templates.

Filters

  • object_states—String name of a valid status of the object state 

    Warning

    Note

    Valid status of object states are draft, pending, released, retired, and archived_state (or any combination separated with ',' or ', '). The default object state is draft.

  • name—String for plan_template name
  • archived—Boolean value for showing archived (can be combined with unarchived to show both)
  • unarchived—Boolean value for showing unarchived (on by default, can be combined with archived to show both)
  • 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_templates

plans, stages

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

The following examples show filters:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "name":"Sample Plan Template" }}' http://[rails_host]/v1/plan_templates?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"plans" }}' https://[rails_host]/v1/plan_templates?token=[api_token]

GET /v1/plan_templates/[id]

Returns a plan template by ID.

Common attributes

  • id—Unique numerical ID for the 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_templates

plans, stages

Errors caused

  • ERROR 403 Forbidden—Occurs when the token is invalid
  • ERROR 404 Not found—Occurs when the 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_templates/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/plan_templates/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"plans" }}' https://[rails_host]/v1/plan_templates/[id]?token=[api_token]

POST /v1/plan_templates

Creates a new plan template from the posted data.

Required attributes

  • name—Unique string name of the plan template
  • template_type—String name of a valid template type (continuous_integration, deploy, release_plan)

Optional attributes

  • is_automatic—Boolean value for whether the template should be considered automatic

  • aasm_state—String name of a valid status of the object state

    Warning

    Note

    For a POST operation, only the draft state is allowed. The default object state is draft.

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

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_templates

plans, stages

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_template><name>Sample Deploy Template</name><template_type>deploy</template_type></plan_template>' http://[rails_host]/v1/plan_templates?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"plan_template": {"name":"Sample Deploy Template", "template_type":"deploy" }}' http://[rails_host]/v1/plan_templates/?token=[api_token]

Filter example:

curl -k -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "plan_template": { "name" : "Rest Plan Template 1", "template_type":"deploy"}, "filters": {"include_except" : "plans"}}' https://[rails_host]/v1/plan_templates?token=[api_token]

PUT /v1/plan_templates/[id]

Updates an existing plan template with values.

Editable attributes

  • name—Unique string name of the plan template
  • template_type—String name of a valid template type (continuous_integration, deploy, release_plan)
  • is_automatic—Boolean value for whether the template should be considered automatic

  • aasm_state—String name of a valid status of the object state

    Warning

    Note

    Valid statuses of object states are draft, pending, released, retired, and archived_state (or any combination separated with ',' or ', '). If the current object state is retired, the only available state is archived_state. If the current object state is archived_state, the only available state is retired. The default object state is draft.

Toggle archival status

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

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

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_templates

plans, stages

Errors caused

  • ERROR 403 Forbidden—Occurs when the token is invalid
  • ERROR 404 Not found—Occurs when the 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_template><name>Renamed Plan Template</name></plan_template>' http://[rails_host]/v1/plan_templates/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "plan_template": { "name" : "Renamed Plan Template"}}'  http://[rails_host]/v1/plan_templates/[id]?token=[api_token]

The following example toggles 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/plan_templates/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "plan_template": { "name" : "Renamed Plan Template 1"}, "filters": { "include_except":"plans" }}' https://[rails_host]/v1/plan_templates/[id]?token=[api_token]

DELETE /v1/plan_templates/[id]

Deletes a plan template.

Common attributes

  • id—Unique numerical ID for the 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

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_templates/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/plan_templates/[id]?token=[api_token]

Sample output

The following JSON is sample output from GET /v1/plan_templates:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "5299ba19c76e4806340ee9c039c712f3"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 1b66bdaef2963f832569b03485e0f6ea
X-Runtime: 0.164000
Content-Type: application/json;charset=utf-8
Content-Length: 328
Date: Wed, 24 Oct 2012 00:20:52 GMT

[{
"archive_number": null,
"archived_at": null,
"created_at": "2012-10-23T19:50:52-04:00",
"id": 1,
"is_automatic": false,
"name": "Sample Deploy Template",
"template_type": "deploy",
"updated_at": "2012-10-23T19:50:52-04:00",
"plans": [{
"id": 1,
"name": "Sample Plan"
}],
"stages": [{
"id": 1,
"name": "Dev"
}, {
"id": 2,
"name": "QA"
}, {
"id": 3,
"name": "Prod"
}]
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "9e0d7cdb830cd5f5f6d322aba62cf202"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 5124dfa011cb796377688a593d5ff631
X-Runtime: 1.301000
Content-Type: application/xml;charset=utf-8
Content-Length: 919
Date: Wed, 24 Oct 2012 00:20:30 GMT

<?xml version="1.0" encoding="UTF-8"?>
<plan-template>
 <archive-number nil="true"></archive-number>
 <archived-at type="datetime" nil="true"></archived-at>
 <created-at type="datetime">2012-10-23T19:50:52-04:00</created-at>
 <id type="integer">1</id>
 <is-automatic type="boolean">false</is-automatic>
 <name>Sample Deploy Template</name>
 <template-type>deploy</template-type>
 <updated-at type="datetime">2012-10-23T19:50:52-04:00</updated-at>
 <plans type="array">
   <plan>
     <id type="integer">1</id>
     <name>Sample Plan</name>
   </plan>
 </plans>
 <stages type="array">
   <stage type="PlanStage">
     <id type="integer">1</id>
     <name>Dev</name>
   </stage>
   <stage type="PlanStage">
     <id type="integer">2</id>
     <name>QA</name>
   </stage>
   <stage type="PlanStage">
     <id type="integer">3</id>
     <name>Prod</name>
   </stage>
 </stages>
</plan-template>

Related topic

REST-API-version-1

 

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

BMC Release Process Management 5.0