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.

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

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]

An example 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]

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

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]

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

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]

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

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]

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

 

 

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