Assembla FAQ and Documentation

What is Rest (Representational State Transfer)?: It's an architectural style, not a standard. Find out more in the Wikipedia or read the following article if you want to know about REST in Rails

TABLE OF CONTENTS

• Ticket Rest API
  • Ticket XML Representation
  • List of tickets (GET)
  • List of tickets in a portfolio (GET)
  • Create ticket (POST)
    • Custom Fields
  • Show ticket(GET)
  • Update ticket (PUT)
  • Delete ticket (DELETE)
  • List of comments (GET)
  • List of components (GET)
  • List of available custom fields
  • List of available custom statuses (GET)
  • List of available custom reports (GET)
  • Create a component (POST)
  • Create a ticket related time entry

TICKET REST API

Tickets are our resources here which can be referred to using this global identifier (URI):
http://www.assembla.com/spaces/<space_id>/tickets/

Where <space_id> is the id of the space with the Ticket Tool you are trying to access. p>

In which types can you retrieve the information?

Currently, HTML or XML. HTML is what you already have in your Ticket Tool. What we add now is the possibility to retrieve the information in other types (for now, xml).

So, what can I do and how can I do it?

TICKET XML REPRESENTATION

<ticket> 	
   <attribute>Value</attribute>
</ticket>

REQUIRED ATTRIBUTES(can't be blank)

* number(type="integer"): Ticket number. You must use this number in the tickets url to access the methods (show,update). You can change it, but you are encourage not to. You should not repeat ticket numbers in the same space

* summary: Summary of the ticket

* reporter-id (or reported_id for FORM) Id of user who report the ticket. Automatically fill on create with your user (or with acts_as_user_id in case you are using that functionallity).

* priority(type="integer"): Must be between 1 and 5.

* status: A valid existing status name from space. Note: For legacy support it will be render as a number in the XML returned from the response (New - 0; Accepted - 1, Invalid - 2, Fixed - 3, Test - 4). If you need to get the name in the XML response you should check <status-name> tag

OTHER ATTRIBUTES

* description: Description of the ticket

* user-comment (or user_comment for FORM): Include this field in your ticket and a comment will be added attached to your ticket.

* assigned-to-id (or assigned_to_id for FORM): Id of user assigned to the ticket (You can get user ID through user API, ).

* milestone-id(type="integer") (or milestone_id for FORM): Id of the milestones assigned to the ticket

* component-id(or component_id for FORM): Id of component assigned to the ticket.

* user-comment(or user_comment for FORM): Only available when updating tickets to add a user comment to the changes.

* created-on (type="datetime") (or created_on for FORM): Create date of ticket. Automatically completed but you can modify if you want (only when creating a ticket. You can't change it with an update ticket request).

* updated-at(or updated_at for FORM): Automatically fill on every update.

* acts-as-user-id (or acts_as_user_id for FORM):  Id of user you want to act as. Logged user must have ALL priviliges in the space in order to act as another user. This fields allow you to create tickets, update changes or add comments as other users (of special interest during imports from other systems).

* skip-alerts (or skip_alerts for FORM): Default: false. Set it to true if you want to avoid generating alerts when a ticket is created or updated. User must have ALL priviliges in the space to set skip_alerts to true.

* working-hours(or working_hours for FORM): Work hours remaining for the ticket.

* estimate: If a ticket tool have an estimation type enabled, you can use this field to update it, if estimation type is set to points or total time you can use float numbers to set it's value, also you'l get floats when you'l request their values. If estimation type is set to Small/Medium/Large type can set it's value to none/small/medium/large/None/Small/Medium/Large also on request you will get the string value of this field.

READ ONLY ATTRIBUTES

* assigned-to will display the user object*

* reporter will display the user object*

* ticket-comments / ticket-comment / user will display the user object*

Note*: user object contains next fields: id, login, login_name(deprecated), name, email, organization, website, phone, im, im2.

SYSTEM ATTRIBUTES (can't be modified)

* id (type="integer"): Unique identifier of the ticket among all spaces. This value is not the one you use in the ticket routes (See number attribute). You may only use this value in the documents api
* space-id: Id of the space the ticket belongs to.

TICKETS YOU FOLLOW AND TICKETS ASSIGNED TO YOU (GET)

You can fetch the list of tickets logged user is following by sending a GET request to http://www.assembla.com/followed_tickets.xml.

Or, if you want to get tickets only assigned to logged in user, you can send a GET request to http://www.assembla.com/followed_tickets.xml

Examples with cURL:

Example, followed tickets

curl -i http://user:password@www.assembla.com/followed_tickets.xml

An expected result should be a list of tickets user is following form all spaces he is participating in, formatted to a xml body.

Example, only tickets assigned to a user

curl -i http://user:password@www.assembla.com/tickets.xml

An expected result should be a list of tickets that are assigned to user from all spaces he is participating in, formatted to a xml body.

LIST OF TICKETS (GET)

To access the list of your tickets you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

IMPORTANT:(new!)  Every ticket list is limited to 1000 results. If you have a report with more than 1000 tickets, you will need to add a page paremeter to your request to gather the next 1000 results. Page numbers starts in 1 (default if not provided)

You can get the list of tickets updated after a specific time, this may help you get only tickets that were updated instead of the whole list, to do so you should add a &updated_from=yyyy-mm-dd hh:mm:ss parameter to your query string, please ensure that date format is yyyy-mm-dd hh:mm:ss.

For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)

RESPONSE: You will get an xml like this:

<tickets>
	<ticket>
		<assigned-to-id></assigned-to-id>
		<component-id type="integer"></component-id>
		<created-on type="datetime">2007-12-03T09:57:47-03:00</created-on>

		<description>This is the ticket description</description>
		<milestone-id type="integer"></milestone-id>
		<number type="integer">1</number>
		<priority type="integer">3</priority>

		<reporter-id>user_id</reporter-id>
		<space-id>space_id</space-id>
		<status type="integer">0</status>
                <status-name>New</status-name>
		<summary>This is the summary</summary>

		<updated-at type="datetime">2007-12-03T11:12:01-03:00</updated-at>
                <working_hour type="float">4.0</working_hour>
       </ticket>
</tickets>

If you created some Custom Fields from the Ticket Settings page, for example:

 You will get another RESPONSE:

	<ticket>
		<assigned-to-id></assigned-to-id>
		<component-id type="integer"></component-id>
		<created-on type="datetime">2007-12-03T09:57:47-03:00</created-on>
		<description>This is the ticket description</description>
		<milestone-id type="integer"></milestone-id>
		<number type="integer">1</number>
		<priority type="integer">3</priority>
		<reporter-id>user_id</reporter-id>
		<space-id>space_id</space-id>
		<status type="integer">0</status>
                <status-name>New</status-name>
		<summary>This is the summary</summary>
 		<updated-at type="datetime">2007-12-03T11:12:01-03:00</updated-at> 
                <working_hour type="float">4.0</working_hour>
                <custom-fields>
                  <custom-field name="Type" type="List" id="11">defect</custom-field>
                  <custom-field name="Version" type="Text" id="55">1.0</custom-field>
                  <custom-field name="Team List" type="Team List" id="66">aGgivCEQar3AwZabTJSnCg</custom-field>
                  <custom-field name="Date" type="Date" id="99">2008/09/10</custom-field>
               </custom-fields> 
       </ticket>
</tickets>

To access one of Assembla's Default Ticket report, you need to send a GET request to:

http://www.assembla.com/spaces/<space_id>/tickets/report/<report_id>

where <report_id> is a number (0 - 10) from this list:

IMPORTANT: (new!) Every ticket list is limited to 1000 results. If you have a report with more than 1000 tickets, you will need to add a page paremeter to your request to gather the next 1000 results. Page numbers starts in 1 (default if not provided)

E.g: curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets/report/5

E.g (Second Page) : curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets/report/5?page=2

LIST OF TICKETS IN CUSTOM REPORTS (GET)

To access the list of your tickets you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/custom_report/<report_id>

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

You can find custom reports IDs by accessing custom reports in your browser and pick the id from the URL in tickets_report_id=u<report_id>parameter or fetch the api query to get a list of custom reports available for your space.

Note: If you find the ID of a custom report in an URL, it will probably contain an "u" letter before the ID itself, the correct report ID contain numbers only, e.g.: www.assembla.com/spaces/_space_id/tickets?tickets_report_id=u35094" this URL contains and ID of "u35094" this record should be used in the API queries as "35094".

CREATE TICKET (POST)

To create a new ticket you need to send a POST request to: http://www.assembla.com/spaces/<space_id>/tickets/

Be sure to include "Accept:application/xml" in your request header.

You can send the new ticket information in the request body with an XML:

Note: Update a ticket status is not available when creating tickets, to get the status of a ticket updated you have to send an update request with the new status.

XML Example(only for summary).

Be sure to add Content-Type:application/xml to your header

<ticket>
	<summary>This is a summary</summary>

</ticket> 

Example XML Request with curl:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<ticket><summary>This is a Summary</summary><priority>3</priority></ticket>" http://user:password@www.assembla.com/spaces/my_space_id/tickets

RESPONSE:

If you success on creating the ticket you will get a Response with 201 Status and with the new ticket xml representation. If the creation fails you will get a 422 Status and an xml representation of the errors. Eg:

<errors>
	<error>Summary can't be blank</error>
</errors> 

LIST OF TICKETS IN PORTFOLIO (GET)

To get a ticket list from your portfolio based on a report filter you should send a GET request to http://username:password@_your_portfolio.assembla.com/p/tickets/:report_id/list.xml

Note: report_id will always be of a format u(id) where (id) is proper report id, e.g. a correct report id is u10

First, you have to create a custom report, or use a pre-defined report on http://your_portfolio.assembla.com/p/tickets/list page, to get the URL with the report id use the XML url on right top corner of tickets list, between RSS Feed, and CSV urls

Example using cURL(assuming report id is u10):

curl -i http://username:password@my_portfolio.assembla.com/p/tickets/u10/list.xml

Or, if you want use the Accept: application/xml header instead of .xml termination of the URL you could use:

curl -i -H "Accept: application/xml" http://username:password@my_portfolio.assembla.com/p/tickets/u10/list

An expected output should be a list of tickets for report you have created converted to a xml body.

AVAILABLE CUSTOM FIELDS

To get the information about available custom fields for a ticket tool send a get request to https://www.assembla.com/spaces/:space_id/tickets/custom_fields

cURL example:

curl -H "Accept: application/xml" https://username:password@www.assembla.com/spaces/:space_id/tickets/custom_fields

An expected response body should be

<?xml version="1.0" encoding="UTF-8"?>
<CustomFields>
  <CustomField name="Text Field" id="10" type="Text"/>
  <CustomField name="list" default_value="asd" id="28" type="List" values="asd,dsa,aaa"/>
</CustomFields>

CUSTOM FIELDS: 

Example to edit a custom field name "My Custom Field"

The simplest way to edit a custom field is by using it's name. In case your custom field name include spaces, you should replace them with an underscore (or dash). Note that the name match is CASE SENSITIVE.

<ticket>
    <summary> My ticket with a custom field</summary>
    <custom-fields>
       <My-Custom-Field>My Custom Value</My-Custom-Field>
    </custom-fields>
</ticket>

Example XML Request with curl:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<ticket><summary>My ticket with a custom field</summary><custom-fields><My-Custom-Field>My Custom Value</My-Custom-Field></custom-fields></ticket>" http://user:password@www.assembla.com/spaces/my_space_id/tickets

Another way to edit a custom field is by using it's id. This option is recommended only if your custom field name has unsupported XML characters or in case you plan to change your custom field name in the future. In that case you need to:

1. Find the custom field id. For that you can look at the XML representation of a ticket with that field. For example, in this XML, you can see that the id of “My Custom Field” is 3657.
2. Then, assuming the value you want is “My Custom Value”, your XML should look like:

<ticket>
    <summary> My ticket with a custom field</summary>
    <custom-fields>
       <3657>My Custom Value</3657>
    </custom-fields>
</ticket>

Example XML Request with curl:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<ticket><summary>My ticket with a custom field</summary><custom-fields><3657>My Custom Value</3657></custom-fields></ticket>" http://user:password@www.assembla.com/spaces/my_space_id/tickets

SHOW TICKET (GET)

To access the representation of a simple ticket you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/<ticket_number>

Where <ticket_number> is the number of the ticket you are trying to access that belongs to the space with <space_id>

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets/1

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)

RESPONSE: You will get an xml like this, representing your ticket:

<ticket>
	<assigned-to-id></assigned-to-id>
	<component-id type="integer"></component-id>
	<created-on type="datetime">2007-12-03T09:57:47-03:00</created-on>

	<description>This is the ticket description</description>
	<milestone-id type="integer"></milestone-id>
	<number type="integer">1</number>
	<priority type="integer">3</priority>

	<reporter-id>user_id</reporter-id>
	<space-id>space_id</space-id>
	<status type="integer">0</status>
        <status-name>New</status-name>
	<summary>This is the summary</summary>

	<updated-at type="datetime">2007-12-03T11:12:01-03:00</updated-at>	
</ticket>

In case the ticket does not exist you will get a Not Found 404 Status in the response

UPDATE TICKET (PUT)

To update a simple ticket you need to send a PUT request to: http://www.assembla.com/spaces/<space_id>/tickets/<ticket_number>

Where <ticket_number> is the number of the ticket you are trying to update that belongs to the space with <space_id>

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header. To send the new ticket information, send it in the body as it is explained in the CREATE TICKET (POST) section.

IMPORTANT (new!)<status>#number</status> will still work with legacy status numbers (0-4) only if space still uses default Assembla workflow (New, Accepted, Invalid, Fixed, Test). Setting other statuses by numbers is not available. This is deprecated and will be removed later. Pleaseuse <status>status_name</status> when editing ticket (PUT) from now on.

Example XML Request with curl:

curl -i -X PUT -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<ticket><description>Take this description</description></ticket>" http://user:password@www.assembla.com/spaces/my_space_id/tickets/1

RESPONSE:

If you success on updating the ticket you will get a Response with 200 Status incluing the updated ticket xml representation. If the update fails you will get a 422 Status and an xml representation of the errors.

DELETE TICKET (DELETE)

To delete a simple milestone you need to send a DELETE request to:http://www.assembla.com/spaces/<space_id>/tickets/<ticket_number>

Where <ticket_number> is the number of the ticket you are trying to update that belongs to the space with <space_id>

Example with curl:

curl -i -X DELETE -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets/1

RESPONSE:

If you success on deleting the ticket you will get a Response with 200 OK Status. If the ticket is not found you will get a 404 Not Found Status.

LIST OF COMMENTS (GET)

To access the list of your tickets you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/<ticket_number>/comments

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header (XML is the only format supported right now).

 For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets/ticket_number/comments

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)

Eg: https://www.assembla.com/spaces/breakout/tickets/2823/comments.xml

LIST OF COMPONENTS (GET)

To access the list of your available components you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/components

For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets/components

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)

Eg:  Here you can check our list of components https://www.assembla.com/spaces/breakout/tickets/components.xml

LIST OF AVAILABLE CUSTOM STATUSES

To access the list of your available custom statuses you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/custom_statuses

For example, if you use curl:

curl -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets/custom_statuses

(Note: http://user:password@www.assembla.com/ is the way you use basic authenticate with curl. You need to find out how to use it with your application)

LIST OF AVAILABLE CUSTOM REPORTS

To access the list of your available custom reports(user reports and team reports) you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/custom_reports

For example, if you use curl:

curl -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/custom_reports

(Note: http://user:password@www.assembla.com/ is the way you use basic authenticate with curl. You need to find out how to use it with your application) 

CREATE A COMPONENT (POST)

Command:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" \
      -d "<component_name>Core</component_name>" \
      http://user:password@www.assembla.com/spaces/my_space_id/tickets/create_component

Result

<?xml version="1.0" encoding="UTF-8"?>
<component>
  <name>Core</name>
  <id type="integer">1</id>
</component>

NOTES:

1) You need to have Ticket Tool installed in you space to access this API.

Ticket associations

List of associations for a ticket

You can fetch the list of ticket associations by sending a GET request to https://www.assembla.com/spaces/:space_id/tickets/list_associations

cURL example:

curl -i -H "Accept: application/xml" https://user:password@www.assembla.com/spaces/:space_id/tickets/list_associations

Example output

<?xml version="1.0" encoding="UTF-8"?>
<ticket-associations type="array">
  <ticket-association>
    <ticket2-id type="integer">2151</ticket2-id>
    <created-at type="datetime">2011-10-24T09:21:27Z</created-at>
    <relationship type="integer">0</relationship>
    <id type="integer">25</id>
    <ticket1-id type="integer">8</ticket1-id>
    <ticket1-number type="integer">1</ticket1-number>
    <ticket2-number type="integer">2</ticket2-number>
  </ticket-association>
</ticket-associations>

Add associations

You can add ticket associations by sending POST requests to https://www.assembla.com/spaces/:space_id/tickets/:ticket_number/api_add_association

Send with request a xml body with the next content

<association>
  <with>:ticket_number</with>
  <relationship>:relationship</relationship>
</association>

In relationship field you can set one of three values

cURL example:

curl -i -X POST -H "Accept: application/xml" -H "Content-type: application/xml" -d "181" https://user:password@www.assembla.com/spaces/:space_id/tickets/17/api_add_association

If query results successfully a list of associations will be returned, otherwise an xml array of errors will be returned

Remove associations

You can remove ticket associations by sending DELETE requests to https://www.assembla.com/spaces/:space_id/tickets/:ticket_number/api_remove_association

Send with request a xml body with the next content

<association>
  <id>:association_id</id>
</association>

To get the list of available associations for a ticket send a GET request to show ticket URL: curl -i -X GET -H "Accept: application/xml" https://user:password@www.assembla.com/spaces/:space_id/tickets/:ticket_number

cURL example:

curl -i -X DELETE -H "Accept: application/xml" -H "Content-type: application/xml" -d ":association_id" https://user:password@www.assembla.com/spaces/:space_id/tickets/17/api_remove_association

Create a ticket related time entry

To create a time entry related to a ticket send a POST request to https://www.assembla.com/spaces/:space_id/tickets/:ticket_number/update_time_data_invested

cURL example:

Use query string to send your data

curl -i -H "Accept: application/xml" -d "resolved_hours=3" https://user:password@www.assembla.com/spaces/:space_id/tickets/:ticket_number/update_time_data_invested

Use xml to send your data

curl -i -H "Accept: application/xml" -H "Content-type: application/xml" -d "<resolved_hours>3</resolved_hours>" https://user:password@www.assembla.com/spaces/:space_id/tickets/:ticket_number/update_time_data_invested

A result over a successful operation should be a list of tasks related to specified ticket.