REST tickets

Tickets represent a tracking model that enables external ticketing systems to connect to plans or steps in a request. Tickets enable integration with external systems and automation in steps. An example of an external ticket is a change request ticket from BMC Remedy.

Note

The include_except and alone filters are available in only 5.0.03.004 and later versions of RPM. Use these filters to limit the data in API response and hence, reduce the API response time.

GET /v1/tickets

Returns all tickets

Filters

  • app_name — String for related application name
  • app_id — Integer ID of a related application
  • plan_id — integer ID of a related plan
  • step_id — Integer ID of a related step
  • request_id — Integer ID of a related request
  • foreign_id — String ID from the external ticketing system (unique per project server)
  • project_server_id — Integer ID of a related project server
  • ticket_type — String value for ticket type
  • 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.

Item

Associated items

tickets

project_server, plans,
related_tickets,
steps, extended_attributes,
app

Common attributes

  • format — Ensure that you 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/tickets?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/tickets?token=[api_token]

Examples of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "foreign_id":"DE12345" }}' http://[rails_host]/v1/tickets?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"project_server,plans" }}' https://[rails_host]/v1/tickets?token=[api_token]

GET /v1/tickets/[id]

Returns a ticket by ID.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure that you 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.

Item

Associated items

tickets

project_server, plans,
related_tickets,
steps, extended_attributes,
app

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

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"project_server,plans,extended_attributes" }}' https://[rails_host]/v1/tickets/[id]?token=[api_token]

POST /v1/tickets

Creates a new ticket from posted data.

Required attributes

  • foreign_id — String foreign ID of the ticket
  • name — String name of the ticket
  • project_server_id — Integer ID of the project server that this ticket belongs to (required)

Optional attributes

  • app_id — Integer ID of a parent application
  • plan_ids — Array of integer IDs of the plans this ticket should be attached to
  • related_ticket_ids — Array of integer IDs of the tickets to which the ticket is related
  • status — String status of the ticket
  • step_ids — Array of integer IDs of the steps to which the ticket relates
  • ticket_type — String type of the ticket
  • url — URL of the ticket's artifact at an external system

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.

Item

Associated items

tickets

project_server, plans,
related_tickets,
steps, extended_attributes,
app


Search methods

  • app_name — String name of an application
  • plan_names — Array of string names of plans

Tip

To find an application by name, you can use the full name or a short code prefix separated from the main name by a delimiter, |. If the application name is "BMC Release Process Management," a name with a short code might be "BRPM_|_Release Process Management." To find this application, the value for "name" could be either "BRPM" or "Release Process Management."

Nested attributes

  • extended_attributes_attributes — Nested attributes model that permits the setting of arbitrary name value pairs for the ticket. Valid fields are "name" (acting as the key for the pair) and "value_text" (acting as the value for the pair).

Common attributes

  • format — Ensure that you 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 '<ticket><name>Sample Ticket</name><foreign_id>DE12345</foreign_id><project_server_id>1</project_server_id></ticket>' http://[rails_host]/v1/tickets?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"ticket": {"name":"Sample Ticket", "project_server_id":1, "foreign_id":"DE12345" }}' http://[rails_host]/v1/tickets/?token=[api_token]

An example creating child extended attributes in the same call:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"ticket": {"name":"Sample Ticket", "project_server_id":1, "foreign_id":"DE12345", "extended_attributes_attributes": [{"name":"Sample Value Key 1", "value_text":"Sample Extended Value 1"}, {"name":"Sample Value Key 2", "value_text":"Sample Extended Value 2"}] }}' http://[rails_host]/v1/tickets/?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "ticket": { "name" : "Rest Ticket 1", "project_server_id":1, "foreign_id":"DE12345"}, "filters": {"include_except" : "project_server,plans,extended_attributes"}}' https://[rails_host]/v1/tickets/?token=[api_token]

PUT /v1/tickets/[id]

Updates an existing ticket with values from a posted document.

Editable attributes

  • app_id — Integer ID of a parent application
  • foreign_id — String foreign ID of the ticket
  • name — String name of the ticket
  • plan_ids — Array of integer IDs of the plans this ticket should be attached to
  • project_server_id — Integer ID of the project server that this ticket belongs to
  • related_ticket_ids — Array of integer IDs of the tickets to which the ticket is related
  • status — String status of the ticket
  • step_ids — Array of integer IDs of the steps to which the ticket relates
  • ticket_type — String type of the ticket
  • url — URL of the ticket's artifact at an external system

Search methods

  • app_name — String name of an application
  • plan_names — An array of string names of plans

Tip

To find an application by name, you can use the full name or a short code prefix separated from the main name by a delimiter, |. If the application name is "BMC Release Process Management," a name with a short code might be "BRPM_|_Release Process Management." To find this application, the value for "name" could be either "BRPM" or "Release Process Management."

Nested attributes

  • extended_attributes_attributes — Nested attributes model that permits the setting of arbitrary name value pairs for the ticket. Valid fields are "name" (acting as the key for the pair) and "value_text" (acting as the value for the pair)

Toggle archival status

  • toggle_archive — Boolean that will toggle the archive status of an object

Common attributes

  • format — Ensure that you 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.

Item

Associated items

tickets

project_server, plans,
related_tickets,
steps, extended_attributes,
app

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

An example toggling the archive status of an object:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "toggle_archive": true }'  http://[rails_host]/v1/tickets/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "ticket": { "name" : "Renamed Ticket 1"}, "filters": { "include_except":"project_server,plans,extended_attributes" }}' https://[rails_host]/v1/tickets/[id]?token=[api_token]

DELETE /v1/tickets/[id]

Deletes a ticket.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure that you 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/tickets/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/tickets/[id]?token=[api_token]

Sample output

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "45fc395380a559628a48a66e61b297c0"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 8d5508efe00975b2717eed48c1a09480
X-Runtime: 0.152000
Content-Type: application/json;charset=utf-8
Content-Length: 674
Date: Wed, 05 Sep 2012 18:52:52 GMT

[{
 "app_id"=>nil,
   "created_at"=>"2013-03-27T11:30:24-04:00",
   "foreign_id"=>"Ticket 1",
   "id"=>1,
   "name"=>"This is Ticket 1",
   "project_server_id"=>1,
   "status"=>"Unknown",
   "ticket_type"=>"cool_type",
   "updated_at"=>"2013-03-27T11:30:24-04:00",
   "project_server"=>{
     "id"=>1,
     "name"=>"project_servers 1"},
   "plans"=>[],
   "related_tickets"=>[],
   "steps"=>[],
   "extended_attributes"=>[],
"url" => "http://www.rally.com/?id=123"
},{
 "app_id"=>1,
   "created_at"=>"2013-03-27T11:30:24-04:00",
    "foreign_id"=>"Ticket 2",
    "id"=>2,
    "name"=>"cool name",
    "project_server_id"=>2,
    "status"=>"Unknown",
    "ticket_type"=>"General",
    "updated_at"=>"2013-03-27T11:30:24-04:00",
    "project_server"=>{
      "id"=>2,
      "name"=>"project_servers 2"},
    "app"=>{
      "id"=>1,
      "name"=>"cool_app"},
    "plans"=>[],
    "related_tickets"=>[],
    "steps"=>[],
    "extended_attributes"=>[],
"url" => "http://www.remedy.com/?ticket=zbc"
},{
  "app_id"=>nil,
    "created_at"=>"2013-03-27T11:30:24-04:00",
    "foreign_id"=>"Ticket 3",
    "id"=>3,
    "name"=>"This is Ticket 2",
    "project_server_id"=>3,
    "status"=>"Unknown",
    "ticket_type"=>"General",
    "updated_at"=>"2013-03-27T11:30:24-04:00",
    "project_server"=>{
      "id"=>3,
      "name"=>"project_servers 3"},
    "plans"=>[],
    "related_tickets"=>[],
    "steps"=>[],
    "extended_attributes"=>[],
"url" => "http://www.ticketplus.com/?ticket=zbc"
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "eca0d346b835f58b10d60cf06b5b113c"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 41adf309a41e3b7c29ef45e76e0722e4
X-Runtime: 0.246000
Content-Type: application/xml;charset=utf-8
Content-Length: 949
Date: Fri, 26 Oct 2012 07:46:56 GMT

<?xml version="1.0" encoding="UTF-8"?>
<ticket>
 <app-id type="integer">1</app-id>
 <archive-number nil="true"></archive-number>
 <archived-at type="datetime" nil="true"></archived-at>
 <created-at type="datetime">2012-10-26T03:44:44-04:00</created-at>
 <foreign-id>DE35636376</foreign-id>
 <id type="integer">1</id>
 <name>Sample Remedy Ticket</name>
 <project-server-id type="integer">1</project-server-id>
 <status>Unknown</status>
 <ticket-type>General</ticket-type>
 <updated-at type="datetime">2012-10-26T03:44:44-04:00</updated-at>
 <project-server>
   <id type="integer">1</id>
   <name>Remedy AO</name>
 </project-server>
 <plans type="array">
   <plan>
     <id type="integer">1</id>
     <name>Sample Plan</name>
   </plan>
 </plans>
 <related-tickets type="array"/>
 <steps type="array"/>
 <extended-attributes type="array"/>
 <app>
   <id type="integer">1</id>
   <name>SmartRelease</name>
 </app>
 <url>http://www.superticket.com?issue=xyz</url>
</ticket>

 

Related topic

REST-API-version-1

 

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