Skip to Content

REST procedures

Procedures are collections of steps that you can reuse in multiple requests and associate with applications.

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

Returns all procedures.

Filters

  • object_states—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. The default object state is draft.

  • name—String for the procedure name
  • app_id—Integer for the related application ID
  • archived—Boolean value for showing the archived status (can be combined with unarchived to show both)
  • unarchived—Boolean value for showing the unarchived status (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

procedures

steps

Common attributes

  • format—Be sure to include this as 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/procedures?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/procedures?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 Procedure" } }' http://[rails_host]/v1/procedures?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"steps" }}' https://[rails_host]/v1/procedures?token=[api_token]

GET /v1/procedures/[id]

Returns a procedure by ID.

Common attributes

  • id—Unique numerical ID for a procedure
  • format—Be sure to include this as 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

procedures

steps

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

Filter example:

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

POST /v1/procedures

Creates a new procedure from posted data.

Required attribute

  • name—String name of the procedure

Optional attributes

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

    Warning

    Note

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

  • description—String description of the procedure
  • app_ids—Array of integer values for the related application IDs

  • step_ids—Array of integer values for the related step IDs

    Error
    Warning

    Do not use step_ids to add steps to a procedure, because they will be linked directly rather than cloned. Use step_ids_to_clone to clone existing steps and add them to a procedure.

  • step_ids_to_clone—Array of integer related step IDs to be cloned and associated with the procedure. Fields to be cloned are controlled by the metadata list titled IncludeInSteps

    Warning

    Note

    When you create or update procedures, you can clone a set of existing steps and assign the clones — not the original steps — to the step_ids attribute. Use step_ids_to_clone, not step_ids, to add steps to a procedure. If steps are already associated with the procedure, the clones are added to that array.

Common attributes

  • format—Be sure to include this as 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

procedures

steps

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 '<procedure><name>REST Procedure</name><app_ids>1</app_ids><app_ids>2</app_ids><step_ids_to_clone>8</step_ids_to_clone><step_ids_to_clone>11</step_ids_to_clone></procedure>' http://[rails_host]/v1/procedures?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json"  -X POST -d '{"name":"Rest Procedure", "app_ids":[1,2], "step_ids_to_clone":[10,11,12,13]}' http://[rails_host]/v1/procedures/?token=[api_token]

Filter example:

curl -k -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "procedure": { "name" : "Rest Procedure 1"}, "filters": {"include_except" : "steps"}}' https://[rails_host]/v1/procedures?token=[api_token]

PUT /v1/procedures/[id]

Updates an existing procedure with values from a posted document.

Editable attributes

  • name—String name of the procedure
  • description—String description of the procedure

  • 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_state. The archived_state can only be reached if the current state is retired. If the current object state is archived_state, the only available state is retired. The default object state is draft.

  • app_ids—Array of integer values for the related application IDs

  • step_ids—Array of integer values for the related step IDs

    Error
    Warning

    Do not use step_ids to add steps to a procedure, because they will be linked directly rather than cloned. Use step_ids_to_clone to clone existing steps and add them to a procedure.

  • step_ids_to_clone—Array of integer related step IDs to be cloned and associated with the procedure. Fields to be cloned are controlled by the metadata list titled IncludeInSteps

    Warning

    Note

    When you create or update procedures, you can clone a set of existing steps and assign the clones — not the original steps — to the step_ids attribute. Use step_ids_to_clone, not step_ids, to add steps to a procedure. If steps are already associated with the procedure, the clones are added to that array.

Toggle archival status

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

    Warning

    Note

    You can only toggle the archive status when the state is Archived or Retired.

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

procedures

steps

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 '<procedure><name>Renamed Procedure</name></procedure>' http://[rails_host]/v1/procedures/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "procedure": { "name" : "Renamed Procedure"}}'  http://[rails_host]/v1/procedures/[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/procedures/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "procedure": { "name" : "Renamed Procedure 1"}, "filters": { "include_except":"steps" }}' https://[rails_host]/v1/procedures/[id]?token=[api_token]

DELETE /v1/procedures/[id]

Deletes a procedure.

Common attributes

  • id—Unique numerical ID of the procedure
  • 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/procedures/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/procedures/[id]?token=[api_token]

Sample output

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

[{
"archive_number": null,
"archived_at": null,
"created_at": "2012-08-29T21:41:02-04:00",
"description": "Steps from request #1001",
"id": 1,
"name": "Sample Procedure",
"updated_at": "2012-08-29T21:41:02-04:00",
"steps": [{
"aasm_state": "locked",
"id": 8,
"name": "Step 1"
}, {
"aasm_state": "locked",
"id": 9,
"name": "Step 2"
}, {
"aasm_state": "locked",
"id": 10,
"name": "Step 3"
}, {
"aasm_state": "locked",
"id": 11,
"name": "Step 2"
}, {
"aasm_state": "locked",
"id": 12,
"name": "Step 4"
}, {
"aasm_state": "locked",
"id": 13,
"name": "Step 7"
}]
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "c9ff133fb107fb979f3b1002e8c69afe"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 3aab000dde7aa338dc5ba841145dd885
X-Runtime: 0.167000
Content-Type: application/xml;charset=utf-8
Content-Length: 1172
Date: Thu, 30 Aug 2012 02:16:37 GMT

<?xml version="1.0" encoding="UTF-8"?>
<procedure>
 <archive-number nil="true"></archive-number>
 <archived-at type="datetime" nil="true"></archived-at>
 <created-at type="datetime">2012-08-29T21:41:02-04:00</created-at>
 <description>Steps from request #1001</description>
 <id type="integer">1</id>
 <name>Sample Procedure</name>
 <updated-at type="datetime">2012-08-29T21:41:02-04:00</updated-at>
 <steps type="array">
   <step>
     <aasm-state>locked</aasm-state>
     <id type="integer">8</id>
     <name>Step 1</name>
   </step>
   <step>
     <aasm-state>locked</aasm-state>
     <id type="integer">9</id>
     <name>Step 2</name>
   </step>
   <step>
     <aasm-state>locked</aasm-state>
     <id type="integer">10</id>
     <name>Step 3</name>
   </step>
   <step>
     <aasm-state>locked</aasm-state>
     <id type="integer">11</id>
     <name>Step 2</name>
   </step>
   <step>
     <aasm-state>locked</aasm-state>
     <id type="integer">12</id>
     <name>Step 4</name>
   </step>
   <step>
     <aasm-state>locked</aasm-state>
     <id type="integer">13</id>
     <name>Step 7</name>
   </step>
 </steps>
</procedure>

Related topic

Managing-procedures

 

 

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

BMC Release Process Management 5.0