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 steps

A step is an important subprocess model of BMC Release Process Management. Steps belong to requests, can be grouped into procedures for reuse, and represent manual or automated work to be completed for a release.

Warning

Note

Starting with BMC Release Process Management version 4.4.00.05 and later, you can user the aasm_event  parameter in REST PUT requests for steps to manage the step status, including starting, holding, blocking, resetting, changing the step to the problem state and resolving the problem state. For more information, see  State machine events.

TEST

GET /v1/steps

Returns all steps.

Filters

  • aasm_state — String value for the aasm state of the step (for example: locked, ready, in_process, blocked, problem, being_resolved, complete)
  • name — String for the request name
  • request_id — Integer ID of the parent request
  • running — If set to true, returns all steps in process, ready, or running aasm_states.
  • owner_id — User ID of the owner of a step
  • installed_component_id — Integer ID of the installed component
  • component_version — String value of the component version
  • version_tag_id — Integer ID of the version tag
  • custom_ticket_id — Integer ID of the custom ticket
  • package_template_id — Integer ID of the package template
  • script_id — Integer ID of the script
  • runtime_phase_id — Integer ID of the runtime phase
  • phase_id — Integer ID of the phase
  • procedure_id — Integer ID of the free floating procedure
  • parent_id — Integer ID of the step acting as a procedure that contains steps
  • category_id — Integer ID of the category
  • work_task_id — Integer ID of the work task

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

GET /v1/steps/[id]

Returns a step by ID.

Filters

notify — Object that allows you to send email notifications from the step REST API call. The notify object has the following parameters:

  • recipients — String for the email addresses of the notification recipients, separated by commas. If you do not specify this parameter, the notification is sent to the default step notification recipients. For more information, see Managing-requests.
  • subject — String for the notification subject. If you do not specify this parameter, the following subject template is used:
    Subject: Notification from <request_ID>, Step: <step_position>:<step_name>

  • body — String for the notification body text. This body value is attached to the following notification text:

    <request_ID>, <request_name>

    Message from <script_name> : <time of start>

    <body>

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

POST /v1/steps

Creates a new step from posted data.

Required attributes

  • owner_id — Integer ID of the owner (User) (required unless a procedure)
  • owner_type — String value of the owner type (User, Group)
  • script_id — Integer ID of the script (required if manual is false)
  • script_type — String value of the script type (BladelogicScript, HudsonScript, CapistranoScript) (required if manual is false)
  • request_id — Integer ID of the request (required if not a member of a procedure)
  • procedure_id — Integer ID of the procedure (required if a member of a procedure)

Optional attributes

  • name — String name of the request
  • manual — Boolean value if manual step (not an automation step) (defaults to true; if set to false, script_id must be set)
  • procedure — Boolean value if the step is a procedure container (procedure_id required if this is true)
  • installed_component_id — Integer ID of the installed component for the step (required if component_id is set)
  • component_id — Integer ID of the component for the step (required if installed_component_id is set)
  • description — Text description of the step
  • version_tag_id — Integer ID of a version tag if using integration server for version control
  • own_version — Boolean value value for whether installed component version should be updated to this step's version value upon completion (defaults to false)
  • component_version — String for version of the assigned installed component (see also "own_version" Boolean value to commit that value on step completion)
  • custom_ticket_id — Integer ID for a custom ticket
  • release_content_item_id — Integer ID of a release content item
  • change_request_id — Integer ID of a ServiceNow change request
  • completion_state — String for ServiceNow change request step completion state values
  • on_plan — Boolean value for whether the step should appear on the Operations Tickets lists in a Release Plan
  • package_template_id — Integer ID for a package template
  • package_template_properties — String for package template properties
  • phase_id — Integer ID for a phase
  • runtime_phase_id — Integer ID for a runtime phase
  • should_execute — Boolean value for inclusion in request execution plan (defaults to true)
  • execute_anytime — Boolean value for anytime execution (defaults to false)
  • start_by — Time stamp for starting date and time
  • category_id — Integer ID for related category
  • location_detail — String for detailed location information
  • estimate — Integer for estimated time in minutes
  • different_level_from_previous — Boolean value for serial (true) or parallel (false) step execution behavior (defaults to true)

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 '<step><request_id>1</request_id><name>Step 2</name><owner_id>1</owner_id><owner_type>User</owner_type><installed_component_id>5</installed_component_id></step>' http://[rails_host]/v1/steps?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"step": {"request_id":1,"name":"Step 2", "owner_id":1, "owner_type":"User", "installed_component_id":5 }}' http://[rails_host]/v1/steps/?token=[api_token]

PUT /v1/steps/[id]

Updates an existing step with values from a posted document.

Editable attributes

  • owner_id — Integer ID of the owner (User) (required unless a procedure)
  • owner_type — String value of the owner type (User, Group)
  • script_id — Integer ID of the script (required if manual is false)
  • script_type — String value of the script type (BladelogicScript, HudsonScript, CapistranoScript) (required if manual is false)
  • request_id — Integer ID of the request (required if not a member of a procedure)
  • procedure_id — Integer ID of the procedure (required if a member of a procedure)
  • name — String name of the request
  • manual — Boolean value if manual step (not automation step) (defaults to true, if set to false script_id must be set)
  • procedure — Boolean value if the step is a procedure container (procedure_id required if this is true)
  • installed_component_id — Integer ID of the installed component for the step (required if component_id is set)
  • component_id — Integer ID of the component for the step (required if installed_component_id is set)
  • description — Text description of the step
  • version_tag_id — Integer ID of a version tag if using integration server for version control
  • own_version — Boolean value value for whether installed component version should be updated to this step's version value upon completion (defaults to false)
  • component_version — String for version of the assigned installed component (see also "own_version" Boolean value to commit that value on step completion)
  • custom_ticket_id — Integer ID for a custom ticket
  • release_content_item_id — Integer ID of a release content item
  • change_request_id — Integer ID of a ServiceNow change request
  • completion_state — String for ServiceNow change request step completion state values
  • on_plan — Boolean value for whether the step should appear on the Operations Tickets lists in a release plan
  • package_template_id — Integer ID for a package template
  • package_template_properties — String for package template properties
  • phase_id — Integer ID for a phase
  • runtime_phase_id — Integer ID for a runtime phase
  • should_execute — Boolean value for inclusion in request execution plan (defaults to true)
  • execute_anytime — Boolean value for anytime execution (defaults to false)
  • start_by — Time stamp for starting date and time
  • category_id — Integer ID for related category
  • location_detail — String for detailed location information
  • estimate — Integer for estimated time in minutes
  • different_level_from_previous — Boolean for serial (true) or parallel (false) step execution behavior (defaults to true)

State Machine Events

Starting with BMC Release Process Management version 4.4.00.05, you can change the step status by changing the aasm_event parameter.

Warning

Note

The state of the step cannot be changed randomly. If an incorrect state is provided the step status does not change.

aasm_event — moves a step to another state. Supported events are the following:

  • start — starts the step that is in the Ready state
  • block — moves a step from the Ready or In Process state to the Blocked state
  • done — moves a step from In Process state to the Completed state
  • reset — resets the step from the Completed state to the Locked state. Before using the reset event, ensure that the request that the step is assigned to is in the planned state
  • problem — moves the step and the request that the step is assigned to the Problem state
  • resolve — resolves the step with the Problem state and restarts the step. Statuses of the step and the request that the step is assigned to changes to In Process
  • force_resolve — resolves the step with the Problem state and restarts the step. Only the status of the step changes to In Process
  • unblock_ready — moves a step from the Blocked to the Ready state{{code language="none"}}


    {{/code}}

  • unblock_in_process  — moves a step from the Blocked to the In Process state

     

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

DELETE /v1/steps/[id]

Deletes a step.

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

Sample output

The following JSON is a sample output from GET /v1/steps/19:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "ef607b6fddbbeb945cb3ee3c149a02c8"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 390e1552667857cce2382799752fe000
X-Runtime: 1.665000
Content-Type: application/json;charset=utf-8
Content-Length: 1331
Date: Mon, 15 Sep 2014 15:45:38 GMT

{
    "aasm_state": "locked",
    "complete_by": "2014-09-29T12:30:00-04:00",
    "component_version": "2.0",
    "created_at": "2014-08-22T04:41:08-04:00",
    "custom_ticket_id": null,
    "description": "sample step",
    "different_level_from_previous": true,
    "estimate": 15,
    "execute_anytime": false,
    "id": 19,
    "location_detail": null,
    "manual": false,
    "name": "step 1",
    "on_plan": false,
    "own_version": true,
    "owner_type": "User",
    "position": 2,
    "procedure": false,
    "ready_at": null,
    "release_content_item_id": null,
    "script_type": "General",
    "should_execute": true,
    "start_by": "2014-09-29T12:15:00-04:00",
    "updated_at": "2014-09-29T03:18:23-04:00",
    "work_finished_at": null,
    "work_started_at": null,
    "number": "2",
    "property_values": {
        "prop 2": "prop 2aa",
        "new": "prop 2 changed"
    },
"all_servers":{
        "selected_servers":{
                "target_servers":{
                        "Server Level Group: SL_LEVEL_GROUP sl_3":[
                           {"created_at":"2014-07-
07T13:01:41+03:00","description":"","id":10000,"name":"SL_S3","parent_id":10043,"parent_type":"Server","server_level_id":10000,"updated_at":"
2014-07-07T13:01:41+03:00"},
                           {"created_at":"2014-10-
15T19:13:07+03:00","description":"","id":10020,"name":"SL_4_add","parent_id":10042,"parent_type":"Server","server_level_id":10020,"updated_at":"
2014-10-15T19:13:07+03:00"}
                          ]
                   },
                   "alternate_servers":[
                           {"created_at":"2014-07-17T13:01:42+03:00","description":"","id":10100,"name":"Another
server","parent_id":10045,"parent_type":"Server","server_level_id":10050,"updated_at":"2014-07-17T13:01:42+03:00"},
                       ]
                 },
                 "available_servers":{
                         "Server Level Group: SL_LEVEL_GROUP sl_3":[
                           {"created_at":"2014-10-15T19:13:07+03:00","description":"","id":10020,"name":"SL_4_add","parent_id":10042,
"parent_type":"Server","server_level_id":10020,"updated_at":"2014-10-15T19:13:07+03:00"},
                           {"created_at":"2014-07-07T13:01:41+03:00","description":"","id":10000,"name":"SL_S3","parent_id":10043,
"parent_type":"Server","server_level_id":10000,"updated_at":"2014-07-07T13:01:41+03:00"}
                                            ]
                              }
               },  
   "owner": {
        "email": "admin@example.com",
        "id": 1,
        "login": "admin"
    },
    "script": {
        "id": 6,
        "name": "Direct_execute"
    },
    "work_task": {
        "id": 1,
        "name": "new WT"
    },
    "phase": {
        "id": 1,
        "name": "new phase"
    },
    "runtime_phase": {
        "id": 2,
        "name": "runtime phase 1"
    },
    "installed_component": {
        "application_component_id": 6,
        "application_environment_id": 4,
        "id": 13,
        "app": {
            "a_sorting_comps": false,
            "a_sorting_envs": false,
            "active": true,
            "app_version": "1.0",
            "created_at": "2014-05-16T09:16:06-04:00",
            "default": false,
            "id": 2,
            "name": "app1",
            "strict_plan_control": false,
            "updated_at": "2014-08-22T04:07:25-04:00"
        },
        "component": {
            "active": true,
            "created_at": "2014-05-16T09:15:46-04:00",
            "id": 6,
            "name": "comp 1",
            "updated_at": "2014-05-16T09:15:46-04:00"
        },
        "environment": {
            "active": true,
            "created_at": "2011-04-29T00:12:28-04:00",
            "default": false,
            "default_server_group_id": null,
            "deployment_policy": "opened",
            "environment_type_id": null,
            "id": 2,
            "name": "production",
            "updated_at": "2014-07-03T11:34:06-04:00"
        }
    },
    "component": {
        "id": 6,
        "name": "comp 1"
    },
    "request": {
        "aasm_state": "created",
        "id": 13,
        "name": "sample request",
        "number": 1013
    }
}

The following XML is a sample output from GET /v1/steps/19:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: _brpm_session_development_base-rhel6u2x6422ea0c44a45ae6045149fc69ee8de6a1=4SUwXxutbwrtj6eYayox2DEl; Path=/brpm
X-UA-Compatible: IE=Edge,chrome=1
ETag: "cadf991c162d587ca6d1daa64d01522a"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 743f7391667aa7c73d09f618b402ffc8
X-Runtime: 0.202000
Date: Mon, 29 Sep 2014 07:24:07 GMT
X-Rack-Cache: miss
Content-Type: application/json;charset=utf-8
Content-Length: 1740

<?xml version="1.0" encoding="UTF-8"?>
<step>
 <aasm-state>locked</aasm-state>
 <complete-by type="datetime">2014-09-29T12:30:00-04:00</complete-by>
 <component-version>2.0</component-version>
 <created-at type="datetime">2014-08-22T04:41:08-04:00</created-at>
 <custom-ticket-id type="integer" nil="true"/>
 <description>sample step</description>
 <different-level-from-previous type="boolean">true</different-level-from-previous>
 <estimate type="integer">15</estimate>
 <execute-anytime type="boolean">false</execute-anytime>
 <id type="integer">19</id>
 <location-detail nil="true"/>
 <manual type="boolean">false</manual>
 <name>step 1</name>
 <on-plan type="boolean">false</on-plan>
 <own-version type="boolean">true</own-version>
 <owner-type>User</owner-type>
 <position type="integer">2</position>
 <procedure type="boolean">false</procedure>
 <ready-at type="datetime" nil="true"/>
 <release-content-item-id type="integer" nil="true"/>
 <script-type>General</script-type>
 <should-execute type="boolean">true</should-execute>
 <start-by type="datetime">2014-09-29T12:15:00-04:00</start-by>
 <updated-at type="datetime">2014-09-29T03:18:23-04:00</updated-at>
 <work-finished-at type="datetime" nil="true"/>
 <work-started-at type="datetime" nil="true"/>
 <number>2</number>
 <property-values>
   <prop-2>prop 2aa</prop-2>
   <new>prop 2 changed</new>
 </property-values>
 <all-servers>
  <selected-servers>     
   <target-servers>
    <Server-Level-Group:-SL-LEVEL-GROUP-sl-3 type="array">         
     <Server-Level-Group:-SL-LEVEL-GROUP-sl-3>           
      <created-at type="datetime">2014-07-07T13:01:41+03:00</created-at>           
      <description></description>
      <id type="integer">10000</id>           
      <name>SL_S3</name>           
      <parent-id type="integer">10043</parent-id>           
      <parent-type>Server</parent-type>           
      <server-level-id type="integer">10000</server-level-id>
      <updated-at type="datetime">2014-07-07T13:01:41+03:00</updated-at>         
     </Server-Level-Group:-SL-LEVEL-GROUP-sl-3>         
     <Server-Level-Group:-SL-LEVEL-GROUP-sl-3>           
      <created-at type="datetime">2014-10-15T19:13:07+03:00</created-at>
      <description></description>
       <id type="integer">10020</id>           
      <name>SL_4_add</name>           
      <parent-id type="integer">10042</parent-id>           
      <parent-type>Server</parent-type>           
      <server-level-id type="integer">10020</server-level-id>           
      <updated-at type="datetime">2014-10-15T19:13:07+03:00</updated-at>         
     </Server-Level-Group:-SL-LEVEL-GROUP-sl-3>       
    </Server-Level-Group:-SL-LEVEL-GROUP-sl-3>
   </target-servers>     
   <alternate-servers type="array"/>   
  </selected-servers>   
  <available-servers>     
   <Server-Level-Group:-SL-LEVEL-GROUP-sl-3 type="array">       
    <Server-Level-Group:-SL-LEVEL-GROUP-sl-3>         
     <created-at type="datetime">2014-10-15T19:13:07+03:00</created-at>         
     <description></description>
     <id type="integer">10020</id>         
     <name>SL_4_add</name>         
     <parent-id type="integer">10042</parent-id>         
     <parent-type>Server</parent-type>
     <server-level-id type="integer">10020</server-level-id>         
     <updated-at type="datetime">2014-10-15T19:13:07+03:00</updated-at>       
    </Server-Level-Group:-SL-LEVEL-GROUP-sl-3>       
    <Server-Level-Group:-SL-LEVEL-GROUP-sl-3>         
     <created-at type="datetime">2014-07-07T13:01:41+03:00</created-at>         
     <description></description>
     <id type="integer">10000</id>         
     <name>SL_S3</name>         
     <parent-id type="integer">10043</parent-id>         
     <parent-type>Server</parent-type>         
     <server-level-id type="integer">10000</server-level-id>         
     <updated-at type="datetime">2014-07-07T13:01:41+03:00</updated-at>       
    </Server-Level-Group:-SL-LEVEL-GROUP-sl-3>     
   </Server-Level-Group:-SL-LEVEL-GROUP-sl-3>   
  </available-servers>
 </all-servers>
 <owner>
   <email>admin@example.com</email>
   <id type="integer">1</id>
   <login>admin</login>
 </owner>
 <script>
   <id type="integer">6</id>
   <name>Direct_execute</name>
 </script>
 <work-task>
   <id type="integer">1</id>
   <name>new WT</name>
 </work-task>
 <phase>
   <id type="integer">1</id>
   <name>new phase</name>
 </phase>
 <runtime-phase>
   <id type="integer">2</id>
   <name>runtime phase 1</name>
 </runtime-phase>
 <installed-component>
   <application-component-id type="integer">6</application-component-id>
   <application-environment-id type="integer">4</application-environment-id>
   <id type="integer">13</id>
   <app>
     <id type="integer">2</id>
   </app>
   <component>
     <id type="integer">6</id>
   </component>
   <environment>
     <id type="integer">2</id>
   </environment>
 </installed-component>
 <component>
   <id type="integer">6</id>
   <name>comp 1</name>
 </component>
 <request>
   <aasm-state>created</aasm-state>
   <id type="integer">13</id>
   <name>1111</name>
   <number type="integer">1013</number>
 </request>
</step>

Related topic

Managing-steps

 

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

BMC Release Process Management 4.4