REST request templates

Request templates are a companion model to requests that allow new requests to be created based on the structure and contents of an original request. When a request template is made in the user interface from an existing request, the request is first copied into a new invisible request. A request template model is then added that refers to that source request and provides the methods needed for cloning the source request under various conditions.

GET /v1/request_templates

Returns request templates that are not deleted nor archived.

Filters

• object_states—String name of a valid status of the object state

  Note

  Valid status of object states are draft, pending, released, retired, and archived_state(or any combination separated with ',' or ', '). The default object state is draft.

• name—String for the phase name
• archived—Boolean value for showing the archived status (It can be combined with unarchived to show both.)
• unarchived—Boolean value for showing unarchived (On by default, it can be combined with unarchived to show both.)
• parent_id—Integer ID of the request template used to create a sibling or request template variant
• environment_id—Integer ID of the environment to which the source request was originally associated
• app_id—Integer ID of the application to which the source request was originally associated

• 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.

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

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:

The following examples show filters:

GET /v1/request_templates/[id]

Returns a request template by request template ID.

Common attributes

• id—Unique numerical ID for the record
• 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.

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:

Filter example:

POST /v1/request_templates

Creates a new request template from posted data.

Required attributes

• name—String value of the name of the request template
• request_id_to_clone—Integer ID of an existing request to clone as the basis of this new request template

Optional attributes

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

  Note

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

• team_id—Integer ID for the team associated with the request template
• parent_id—Integer ID for the parent request ID from which this request template was created as a template
• {{status colour="Green" title="New in 5.0.03.005"/}}
  
  global—Boolean value to indicate whether the template is global.

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.

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:

The following example creates a global request template, Deploy Oracle, from a request with ID, 1. 

Filter example:

PUT /v1/request_templates/[id]

Updates an existing request template with values from a posted document.

Editable attributes

• name—String value of the name of the request template
• team_id—Integer ID for the team associated with the request template

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

  Note

  Valid statuses of the object states are draft, pending, released, retired, and archived_state (or any combination separated with ',' or ', '). If the current object state is retired, the only available state is archived_state. If the current object state is archived_state, the only available state is retired. The default object state is draft.

Optional attribute

{{status colour="Green" title="New in 5.0.03.005"/}}

global—Boolean value to indicate whether the template is global.

Toggle archival status

• toggle_archive—Set value to string "true" to toggle the archive status of an object to and from archived and unarchived if the request template is not assigned to any plan templates through plan stages.

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.

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:

The following example marks the the Oracle Deploy template as global, making it a global template.

The following example toggles the archive status of an object:

Filter example:

DELETE /v1/request_templates/[id]

Deletes a request template.

Common attributes

• id—Unique numerical ID for the 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 sample output from GET /v1/request_templates:

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

Related topic

Managing-requests