Skip to Content
Information
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 plan templates

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

Success

Tip

In BMC Release Process Management 2.5.01 and earlier,  plans were called lifecycles. All references to lifecycles, lifecycle_templates, lifecycle_stages, and lifecycle_members were renamed as plans or with the plan_ prefix

GET /v1/plan_templates

Returns all plan templates.

Filters

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

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

An example of 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]

GET /v1/plan_templates/[id]

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

POST /v1/plan_templates

Creates a new plan template from a posted data.

Required attributes

  • name — Unique string name of the plan template
  • plan_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

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 and 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><plan_template_type>deploy</plan_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", "plan_template_type":"deploy" }}' http://[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
  • plan_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

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 '<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]

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

DELETE /v1/plan_templates/[id]

Deletes a plan template.

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_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 a 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 a 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-commands

 

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

BMC Release Process Management 4.3