REST v.2 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 v2/steps/[step_ID]

Returns the details of the specified step.

Common attributes

• format — Ensure to include an accept header or add .json to the last path element
• token — Your API Token for authentication

Errors caused

• ERROR 403 Forbidden — When the token is invalid
• ERROR 404 Not Found — When no records are found

Example

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:

new in 5.0.03 PUT v2/steps/[step_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)
• 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 step
• 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)
• 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
• 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)

  If the start_at_scheduled_time attribute is set to true, the start_by_date/hour/minute/meridianattributes 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

  • 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.
• property_id—Integer ID for the property to be updated. Also specify installed_component_id for updating properties for a step.
• server_property_id—Integer value for one or more server properties to be updated for a step. Specify server_id and server_property_id if you are updating properties for a server or server group only. 
• server_id—Integer value for the server to be updated. Specify server_id to update properties for server and server groups. 

• server_aspect_id—Integer value for one or more server properties to be udpated for a step. Specify server_aspect_id and server_property_id if you are updating properties for a server level or server level group. 

  Example for updating server properties and properties for a step

  "property_values": {
     // Installed component is used to update the property values.
     "installed_component": {
                 "installed_component_id": {
                                 "property_id": "Property Value"
                 },
     },
    // Server and server_aspect is used to update the server properties values.
     "server": {
                 "server_id": {
                                "server_property_id": "Server & Server Group Property Value"
                },
     },
     "server_aspect": {
                "server_aspect_id": {
                                "server_property_id": "Server Level & Server Level group property Value"
                },
     },
  }
• 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 deployment_dependency attribute. 
• continue_on_failure—Boolean value to determine the execution condition of a step within a request. If the value is true, the request continues running when the step fails. If the value is false, the request stops running when the step fails.

Common attributes

• format — Ensure to include an accept header or add .json to the last path element
• token — Your API Token for authentication

Errors caused

• ERROR 403 Forbidden — When the token is invalid
• ERROR 404 Not Found — When no records are found

Example

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 demonstrates that execution of the step, API Step is dependent on the step with ID, 1036.

PUT /v2/steps/[Id]/update_status

Updates the status of an existing step.

State machine events

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

• ready—Moves a step to the Ready state
• 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. If the automation script fails, the step is resolved without again running the script and you can move the step into other states, such as block and done.
• resolve_with_rerun—Used only for an automated step. Resolves the step with the Problem state and restarts the step. Only the status of the step changes to In Process. If the automation script fails, the step is resolved and the script runs again. If the script still has issues, step is moved to the Problem state.
• unblock_ready—Moves a step from the Blocked to the Ready state
• unblock_in_process—Moves a step from the Blocked to the In Process state
• enable—Enables a step if a step is disabled
• disable—Disables a step. A disabled step is bypassed and the system moves to next step. 

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