REST steps

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

You can use the aasm_event parameter in REST PUT requests for steps to manage step status, including starting, holding, blocking, resetting, changing a step to the problem state and resolving the problem state. For more information, see State machine events.

GET /v1/steps

Returns all steps.

Filters

• aasm_state—String value for the Acts as State Machine (aasm) state of the step (for example: locked, ready, in_process, blocked, problem, being_resolved, complete)
• name—String for the step 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

• 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.
• continue_on_failure—Boolean value to determine the execution flow of a request if the step fails. If the value is true, the request continues running when the step fails. If it is false, the request stops running when the step fails.
  
  

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:

Filter example:

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 Number <request_number>, Step: <step_position>:<step_name>

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

  <request_number>, <request_name>
  "Request ID: <request_ID> (this value should be used for accessing through the REST API)"

  Message from <script_name> : <time of start>

  <body>

• 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.
• continue_on_failure—Boolean value to determine the execution flow of a request if the step fails. If the value is true, the request continues running when the step fails. If it is false, the request stops running when the step fails.

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:

Filter example:

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

• start_at_scheduled_time—Boolean value that shows if a step starts at the scheduled time (defaults to false)

  Warning

  Note

  If the start_at_scheduled_time attribute is set to true, the start_by_date hour minute meridian attributes are required.

  • start_by_date—Date when a scheduled step should start
  • start_by_hour—Hour when a scheduled step should start
  • start_by_minute—Minute when a scheduled step should start
  • start_by_meridian—A.M. or P.M. of the scheduled step time
• start_automatically —Boolean value that shows if a step must start automatically (defaults to false)
• server_names—An array of server names used in the step

• server_ids—An array of server IDs used in the step

  Warning

  Note

  Either the server_name or server_id attribute can be used in the same request.

• deployment_dependency—Boolean value that indicates whether the execution of this step is dependent on a request or step (defaults to false)
• dependent_request_id—ID of the request on which the execution of the current step is dependent. This attribute is required if you have set the deployment_dependency attribute to true.
• dependent_step_id—ID of the step on which the execution of the current step is dependent. This attribute is optional if you have set the deployment_dependency attribute to true and set the value of the dependent_request_id attribute. 
• continue_on_failure—Boolean value to determine the execution flow of a request if the step fails. If the value is true, the request continues running when the step fails. If it is false, the request stops running when the step fails.

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

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.

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:

The following example creates the step, Step_3 with various other attributes. The execution of Step_3 is dependent on the step with step ID, 30. 

Filter example:

The following example shows a request when the continue_on_failure flag is set to true:

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

• start_at_scheduled_time—Boolean value that shows if a step starts at the scheduled time (defaults to false)

  Warning

  If the start_at_scheduled_time attribute is set to true, the start_by_date/ hour/ minute/ meridian attributes are required.

  • start_by_date—Date when a scheduled step should start
  • start_by_hour—Hour when a scheduled step should start
  • start_by_minute— Minute when a scheduled step should start
  • start_by_meridian—A.M. or P.M. of the scheduled step time
• start_automatically—Boolean value that shows if a step must start automatically (defaults to false)
• server_name—String value for one server name or array of strings for many server names used in the step

• server_id—Integer value for one server ID or array of integers for many server IDs used in the step

  Warning

  Notes

  • Either the server_name or server_id attribute can be used in the same request.
  • When you update servers used in a step with a new value, the new value overwrites the previous value. For example, if you have server_ids: [1, 2] used in a step, and then you update the step with server_ids: [3, 4], the step now is associated with server_ids: [3, 4] only.
• deployment_dependency—Boolean value that indicates whether the execution of this step is dependent on a request or step (defaults to false)
• dependent_request_id—ID of the request on which the execution of the current step is dependent. This attribute is required if you have set the deployment_dependency attribute to true.
• dependent_step_id—ID of the step on which the execution of the current step is dependent. This attribute is optional if you have set the deployment_dependency attribute to true and set the value of the dependent_request_id attribute. 
• continue_on_failure—Boolean value to determine the execution flow of a request if the step fails. If the value is true, the request continues running when the step fails. If it is false, the request stops running when the step fails.

State Machine Events

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

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.

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:

The following example updates the step, Step_4 with various other attributes. The execution of Step_4 is dependent on the step with step ID, 30. 

The following example updates the step, Step_4. This step is no more dependent on any request or step. 

Filter example:

The following example shows a request when the continue_on_failure flag is set to true:

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:

Sample output

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

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