Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

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*