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.

GET /v1/plan_templates

Returns all plan templates.

Filters

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

    Warning

    Note

    Valid status of object states are draft, pending, released, retired, and archived. By default, the aasm_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)

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 example shows 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 — 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

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]

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

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

    Warning

    Note

    For a POST operation, only the Draft state is allowed. By default, the aasm_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

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

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

    Warning

    Note

    Valid status of object states are draft, pending, released, retired, and archived. The aasm_state Archived can only be reached if the current aasm_state is Retired. If the current aasm_state is Archived, the only available state is Retired. By default, the aasm_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

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]

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

 

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

BMC Release Process Management 4.8