REST v.2 requests

Requests are the primary process model of BMC Release Process Management (BRPM). They can belong to plans and projects and typically have one or more steps that do manual or automated work to complete the release.

Note

When you open a request in BRPM, the request URL contains a request number. To receive a request ID, subtract 1000 from a request number. For example:

  • PostgreSQL: If the number specified in the request URL is 1001, then the request ID is 1.
  • Oracle: If the number specified in the request URL is 11001, then the request ID is 10001.

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

GET /v2/requests/[id]

Returns a request by request ID.

Common attributes

  • id—Numerical unique ID for record
  • format—An accept header or JSON added 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.

To get the required request by ID, run the following REST call:

curl -i -H "accept: application/json" -H "Content-Type: application/json" -X GET http://[rails_host]/v2/requests/[id]?token=[api_token]

To export a request in the PDF format

Note

 A file with the exported request is saved to the location from which you opened a terminal.

curl -H "accept: application/pdf" -X GET 'http://[rails_host]/v2/requests/[id]?token=[api_token]&export=true' > [file_name].pdf

To export a request in the XML format

curl -H "accept: application/xml" -X GET 'http://[rails_host]/v2/requests/[id]?[api_token]&export=true' > [file_name].xml

To export a request in the HTML format

curl -H "accept: application/xhtml+xml" -X GET 'http://[rails_host]/v2/requests/[id]?[api_token]&export=true' > [file_name].html

POST /v2/requests

Creates a new request in a release from the posted data.

Required attributes

  • release_plan_id—Integer ID of a release
  • plan_stage_id—Integer ID of a plan stage to which you want to deploy a request
  • environment_id—Integer ID of an environment where you want to deploy a request

Optional attributes

To schedule a request for the specific date and time, you can specify either the scheduled_at attribute, or the  scheduled_at_date,  scheduled_at_hour,  scheduled_at_minute, and  scheduled_at_meridian attributes. 

  • scheduled_at—Date and time to start a request 
  • scheduled_at_date—Date when a scheduled step should start
  • scheduled_at_hour—Hour when a scheduled step should start
  • scheduled_at_minute—Minute when a scheduled step should start
  • scheduled_at_meridian—AM or PM of the scheduled step time
  • start_now—Boolean value to start a request automatically after the creation scheduled_at sets the planned date and time at which the request should start. If you want the request to be started automatically at the scheduled date and time, use scheduled_at_date, scheduled_at_hour, scheduled_at_minute, scheduled_at_meridian, and start_now. 
    For examples, see To create a scheduled request.
  • continue_on_failure—Boolean value to determine the execution condition of a request. If the value is true, the Continue On Failure function for this request is activated.

Common attributes

  • format—An accept header or JSON added 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 the URL or your valid API key and application host into a browser or HTTP client like Wget or cURL.

To create a request without a schedule:

curl -i -H "accept: application/json" -H "Content-Type: application/json" -X POST -d '{ "request": { "release_plan_id": 10002, "plan_stage_id": 10001, "environment_id": 10000 }}' http://[rails_host]/v2/requests?token=[api_token]

To create a scheduled request:

curl -i -H "accept: application/json" -H "Content-Type: application/json" -X POST -d '{ "request": { "release_plan_id": 10001, "plan_stage_id": 10005, "environment_id": 10000, "scheduled_at":"24/05/2016 10:03 AM"} }' http://[rails_host]/v2/requests?token=[api_token]
curl -i -H "accept: application/json" -H "Content-Type: application/json" -X POST -d '{ "request": { "release_plan_id": 10001, "plan_stage_id": 10005, "environment_id": 10000, "scheduled_at_date": "2016-6-3", "scheduled_at_hour": "04", "scheduled_at_minute": "55", "scheduled_at_meridian": "PM"}}' http://[rails_host]/v2/requests?token=[api_token]

To create and start a request at once after creation:

curl -i -H "accept: application/json" -H "Content-Type: application/json" -X POST -d '{ "request": { "release_plan_id": 10001, "plan_stage_id": 10005, "environment_id": 10000, "start_now": true} }' http://[rails_host]/v2/requests?token=[api_token]

PUT /v2/requests/[id]/update_status

Updates the status of an existing request.

State machine events

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

  • plan_it—Moves the request to the Planned state
  • start—Starts the request that is in the Planned state
  • put_on_hold—Puts the request on hold.
  • problem—Moves the request to the Problem state
  • resolve—Resolves the request with the Problem state and restarts the request. Status of the request changes to In Process.
  • finish—When all the steps are complete, the request moves to the Complete state.
  • reopen—Reopens a completed request.
  • cancel—Cancels a request which is in In Progress state.

Note

The state of the request cannot be changed randomly. If an incorrect state is provided, the request goes into a problem 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: application/json" -H "Content-type: application/json" -X PUT -d '{ "request": {"aasm_event":"plan_it"}}' http://[rails_host]/v2/requests/[ID]?token=[API_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "request": {"aasm_event":"cancel"}}' http://[rails_host]/v2/requests/[ID]?token=[API_token]

Related topic

Managing-requests

 

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