Overview

The CSV import to Assembla Tickets can be performed in the Tickets-Settings page of your Assembla workspace. This importer requires a comma-separated value (CSV) file (maximum size 500KB). If your CSV file is larger than 500KB, you should break it into individual files of 500KB or less. Note that some users report that a import of bigger files may take from 5 to 15 minutes depending on your location or time you upload files for import.

Header line

The first line of the CSV file must contain comma-separated reserved field keywords from this list. The field keywords must be separated by commas (,), and cannot be quoted. The field keywords must be all lowercase. The “summary” field keyword is the only required field.

• summary – Assembla one-line ticket summary (REQUIRED and must be the first column)
• reporter – Assembla “Reported by” field
• assigned_to- Assembla “Assigned to” field
• description – Assembla “Description” field
• status – Assembla “Status” field.
• state – state for Assembla “Status” field. Status ca have 2 states, OPENED and CLOSED
• priority – Assembla “Priority” field. If no priority is provided Normal will be used by default.
• milestone – Assembla “Milestone” field.
• component – Assembla “Component” field.
• number – Assembla number field that is shown to user, do not confuse it with ID.
• created_on – DateTime when ticket was created. Will be set to moment when ticket is imported if nothing is provided.
• updated_at – Last DateTime ticket was updated. If nothing is provided it will be set to time when ticket is imported.
• working_hours – Assembla working hours field, used to estimate time that will be spent on implementing the ticket.
• is_story – Assembla is_story field, that reflects if ticket is actually a story. False is used by default.
• importance – Assembla importance field that is used to allow custom ticket ordering used by agile planner. Null by default.
• story_importance – Assembla story_importance field that is used to allow custom story ordering used by agile planner. Null by default.
• custom fields – Any other field provided in CSV file will be imported as custom field. However if there are any custom fields provided you have to define custom field types in second row of the CSV file
  For any of the above field keywords that are missing, the corresponding field in the imported Assembla ticket will be blank or edfault value provided.

It is permitted to include other nonstandard keywords in the CSV file. For any nonstandard keywords that are specified, the imported ticket will contain an Assembla custom field.

Ticket lines

The remaining lines of the CSV file must contain comma-separated ticket data, one ticket per line. The ticket data must be in the same sequence as given in the first line.

• summary – Any one-line textual summary (REQUIRED)
• reporter – either login(username) used in assembla or user_id from assembla system. Note if provided login or user_id does not exist in assembla space owner of the space will be used as reporter.
• assigned_to – either login(username) used in assembla or user_id from assembla system. Note if provided login or user_id does not exist in assembla space no user will be used as assigned_to
• description – Any description provided or NULL
• status – The ticket data should be a status name from space’s tickets/settings (if it is necessary to create new statuses when importing, see state attribute). If state column/values are missing, the ticket will be imported with OPENED state. All tickets with unrecognized statuses, i.e. statuses that are not already defined on Tickets/Settings page as your custom statuses or are not known to assembla internal import rules(see internal statuses section for details) will still be imported but with OPENED status. You are advised to visit you Tickets/Settings page and check your statuses states after import. You can always change state of a status if it was imported wrongly by default.
• state – If state value is provided along with a status value that is not yet present in the ticket tool, we will create a new status with the given state. 1 – OPENED, 0 – CLOSED. If state is not provided for a given status and status is not defined in your custom statuses or is not known to assembla internal import rules(see internal statuses section for details), then OPENED state will be used as default.
• priority – The ticket data should be from this list of Assembla priority values (case insensitive): Highest, High, Normal, Low, Lowest. If this value is missing, the ticket will be imported as Normal. Any other priority value will be discarded and mapped to Normal.
• milestone – Any textual Milestone name is accepted. If the name does not correspond to an existing Milestone, a new one will automatically be created.
• component – Any textual Component name is accepted. If the name does not correspond to an existing Component, a new one will automatically be created.
• custom fields – Note that if any field other then ones from the list are added script will consider those as custom fields and thus will be looking for a second line in CSV file that defines custom field types. Following custom field types are supported:
  • Numeric or Integer – both integer and floating comma are supported if correct format is provided
  • String or Text – any text
  • Date – date shoud be provided in following format: YYYY/MM/DD, E.g: 2010/05/05, 2009/12/05, 1345/04/05. If another format is provided tickets will not be imported.
  • List – If you have a limiter number of items for a column that can be defined as a list.
  • TeamList – if you want custom field to take values from members in your Assembla space. The Assembla username must be provided, and the user must already be a member of the space, or the import will fail.
    For more details see the examples bellow.

Internal statuses rules

• ‘New’ => OPENED,
• ‘Created’ => OPENED,
• ‘Accepted’ => OPENED,
• ‘Assigned’ => OPENED,
• ‘Assign’ => OPENED,
• ‘Reopened’ => OPENED,
• ‘Reopen’ => OPENED,
• ‘Reviewed’ => OPENED,
• ‘Review’ => OPENED,
• ‘Test’ => OPENED,
• ‘Invalid’ => CLOSED,
• ‘Closed’ => CLOSED,
• ‘Close’ => CLOSED,
• ‘Fix’ => CLOSED,
• ‘Fixed’ => CLOSED

TODO: Update the list with other known stats => state rules.

Some other general guidelines:

First 2 rows of file – the header and custom field definition rows
All other row text data can be double-quoted.
Make sure you have first added the team members in the Team page of the space.
The Components should auto create, but you can create them first in the Tickets-Settings page.
The custom ticket fields should auto create, but you can create them first also.
File should have an empty line at the end of file

Examples

Example 1

Contains only one field – summary. There are no commas, because there is no need for separation.

summary
this is ticket 1
this is ticket 2
this is ticket 3

Example 2

Contains three columns – assigned_to,summary,description. In this example the first records does not have “assigned_to” and the field is left blank, the same goes for the second record – it does not have “description” and nothing is written after the comma, that comes after the second field.

assigned_to,summary,description
,this is test 1, description 1
na1,this is test 2,
na2,this is test 3, description 3

Example 3

Following example will illustrate how custom fields should be defined in order to be imported. Note that you do not have to provide data types for predefined fields but only custom fields.

reporter,summary,priority,Release Number,Project,Short Comment,Due Date,Tester
,,,numeric,list,text,date,teamlist
jack,summary for first ticket,High,111,Project1,bad ticket,2010/11/05,jack
jack,summary for second ticket,Low,112,Project2,very low priority ticket,2010/11/05,jack
jack,summary for third ticket,Normal,121,Project1,,,

Example 4

Following example will illustrate how to use status and state.

summary,reporter,assigned_to,description,status,priority,milestone,component,importance,story_importance,number,created_on,updated_at,notification_list,completed_date,working_hours,is_story,permission_type,state
This is the summary 100,jack,jack,This is the description,New,High,Two,Component X,,,,,,,,,,,1
This is the summary 200,jack,jack,This is the description,Created,High,Two,Component X,,,,,,,,,,,1
This is the summary 300,jack,jack,This is the description,fixed,High,Two,Component X,,,,,,,,,,,0
This is the summary 400,jack,jack,This is the description,Done,High,Two,Component X,,,,,,,,,,,0

If this would be imported on a default ticket tool, two additional statuses would be created – Created (OPENED) and Done (CLOSED). If no state values would have been provided, both Created and Done statuses would be imported with OPENED state.