The Zendesk Migration Utility supports the ability to import information about Tickets and Forums and associated items from a set of Comma separated Value (CSV) Files and associated attachments (see Running a Bulk CSV Import).
The files containing the CSV might have been generated as an interim set of files during a previous migration from another instance of Zendesk or alternative Help Desk application supported by the migration utility.
However, the files might also have originated from an alternative Help Desk application that supports the export of information in CSV format, or it might be necessary or desirable to create a set of CSV files from scratch using the templates provided as part of the migration utility for this purpose. This being the case it will first be necessary to ensure the structure and format of the CSV files complies with the requirements of the migration utility, as defined by the supplied templates, before the import can be successfully executed.
Resolve any Invalid Characters
** WARNING ** Since the nature of CSV is such that it identifies the values for each item property by recognizing a comma as the delimiter or separator, it is important to ensure that any commas included as part of the value for a property are not interpreted as a separator and this is achieved by enclosing the value within double quotes ("). The same is also true if your text fields that include line feeds or paragraph marks, in which case the text must also be enclosed within double quotes (").
However, this then introduces a further problem if the value also contains one or more double quotes. Under these circumstances each of the double quotes must be escaped using the backslash character (\).
For example, the following text contains both a comma and double quotes:
Hi, my name is "Fred"
In order to avoid interpretation of the comma as a separator, the value to be included in the CSV representing this text should be as follows:
"Hi, my name is \"Fred\""
The double quotes at the front and end of the text prevent the comma after the word Hi, being interpreted as a separator and the backslash characters escape the double quotes enclosing the word \"Fred\" to ensure that these double quotes are loaded as part of the property value.
Since the backslash (\) character is used to denote the presence of an escaped character, should any field contain a backslash that isn't being used to denote an escaped character and should be interpreted literally, then it is necessary to represent this within the CSV as a double backslash (\\), i.e. the backslash character must be escaped to avoid undesirable and invalid interpretation.
*Note: a number of issues have recently been experienced during attempts to run the Bulk CSV Importer due to the presence of a double quote character embedded within a field that has no commas or evident reason to enclose the value. This confuses the CSV parser into thinking that this is the start of a set of enclosing double quotes and thus destroys the integrity of the CSV structure.
As such it is the recommended approach that all string/text fields are enclosed between double quotes and any embedded double quote characters are always escaped as described above.
The following examples have been put together to clarify the format and structure of a CSV file and the rules pertaining to the presence and of commas, line breaks and double quotes embedded within text fields.
Basic Rules Pertaining to the stricture and format of CSV Files
A CSV File is constructed of one or more records (1) and the end of each record is identified through the presence of a line break (2). As such each new record starts on a new line.
Each record is composed of one or more fields (3), (4) and (5), each of which is separated by a delimiter (usually a comma) (6), to determine the start and end of a field.
The fist row of the CSV file usually contains a header (7) with a label for each field to help describe and clarify the structure and use of the records.
However, there are occasions in which commas and line breaks are present within the values for one or more fields that would confuse a CSV editor or interpreter about when a field or record starts and ends and without resolution will destroy the structure and integrity of the data, preventing use as a CSV file.
The following examples demonstrate when such situations occur and how to resolve them.
Example CSV Record with a Line Break in a Text Field
The above example shows a record in a comma separated value (CSV) file with a text field that includes a line break (2).
Each field is delimited using a comma (1) so that any CSV editor or interpreter knows when each filed in the record starts and ends.
In the example there is a line break (2) embedded within the third field of the record which is recognized by the presence of the second comma (3).
It is therefore necessary to enclose or encapsulate the entire third field using double quotes (4), otherwise the CSV editor will interpret the line break (2) as the end of the record and the text after the line break (5) will be treated as the first field in the next record, thus breaking the structure and format of the CSV.
Example CSV Record with a Comma and Double Quotes in a Text Field
As in the previous example in the above CSV record each field has been delimited using a comma (1).
However, in this example, in addition to line breaks, the third field includes a comma embedded within the text (2).
It is therefore necessary to enclose or encapsulate the entire third field using double quotes (3), otherwise the CSV editor will interpret the embedded comma (2) as the delimiter marking the end of the third field and the text following this embedded comma (4) will be interpreted as the start of the fourth field, thus breaking the structure and format of the CSV.
In this example, the introduction of the double quotes to enclose the text field would introduce an additional issue, since the text also includes embedded double quotes (5).
As demonstrated here it is necessary to "escape" these double quotes through the presence of a preceding back slash (\) character (6).
If these double quotes aren't "escaped" then they will otherwise be interpreted by the CSV editor as the end of the enclosing quotes (3), and thus break the format and structure of the CSV.
"Escaping" the double quotes will instruct the CSV editor to ignore them as enclosing quotes, but instead interpret them as characters embedded within the text.
Example CSV Record with a Comma in Two Fields
In the above example each filed in the record is delimited using a comma (1), however, both the second and third fields also include a comma embedded within the text (2) and (3).
Therefore, in order to avoid the CSV editor interpreting the embedded commas as field delimiters, it is necessary to enclose both the second and third fields using double quotes (4), (5), (6),and (7).
Refer to the Sample Data Files
A collection of sample data has been provided as part of the Zendesk Migration Utility with completed templates showing examples of how to prepare the CSV files for import.
It is recommended that these samples are used together with this documentation as a reference explaining how each template should be completed to achieve a successful bulk CSV import.
Prepare and Organize the CSV Files and Attachments
- Each Item to be loaded is represented by a separate CSV file, and templates with sample data are supplied as part of the migration utility for this purpose. These templates are best used within a spreadsheet that supports CSV formatted data, such as Microsoft Excel.
- Any attachments associated with an item must be held as separate files within the same folder as CSV files from within which the references are made.
Complete the Organizations Template
The Organizations Template maps to the Zendesk Organization item and properties as annotated in the above diagram.
2. and 3. The details and notes can contain HTML formatting, but be mindful of the rules pertaining to characters that could be misinterpreted by the translator (see step "Resolve any invalid Characters" above).
4. and 5. Control the settings that determine if users within the organization can view each others tickets and if so are able to make comments.
6. Optionally enter an email domain name that will be used to automatically assign users to the Organization.
Complete the Users Template
The Users Template maps to the Zendesk User item and properties as annotated in the above diagram.
3. The value of the initial password given to the User, this can be updated by the user once logged in.
6. The value in the Organization column must match on the name of an Organization in the Organizations.csv file (see also Making use of References ID's in the CSV Templates).
7. It is possible to associate multiple email addresses with users.
The email address column will accept a space separated list of email addresses.
The first email address is assumed to be the primary and any additional email addresses will be created as extra (non primary) identities.
Optionally it is possible to apply a Tag to each user (1) for the purposes of searching once loaded.
Also, it is possible to include two further optional properties to set the Details (2) and Notes (3) for each user.
*Note: when including these columns, the heaodn/name of the column must have the correct spelling and without spaces, but is not case sensitive.
Complete the Groups Template
The Groups Template maps to the Zendesk User item and properties as annotated in the above diagram.
2. The value in the Agents column must match on the name of a User in the Users.csv file, that assigned to the role of "Agent" (see also Making use of References ID's in the CSV Templates). Enter multiple rows using the same Group name to assign multiple Agents.
Complete the Forums Template
The Forums Template maps to the Zendesk User item and properties as annotated in the above diagram.
1. A check will be made to see if there is a matching Forum name in the target Zendesk account and if found this will be used for all Topics to be imported, otherwise a new Forum will be created.
2. The description of the Forum can contain HTML formatting, but be mindful of the rules pertaining to characters that could be misinterpreted by the translator (see step "Resolve any invalid Characters" above).
*Note: Forums support the use of HTML formatting and so it is recommended that some basic HTML markup is used to format the description to achieve an aesthetically pleasing and more readable result in the Zendesk browser.
3. Determines who can gain access to and view the Forum. The values can be either of:
"All" => Everybody
"Users" => Logged-in Users
"Agents" => Agents only
4. Determines who can create new Topics for the Forum. The values can be either of:
"No" => Logged-in Users
"Users" => Unrestricted agents and moderators only
5. If the value in the Category column matches on the name of a Category that already exists in the target Zendesk database then an association will be made accordingly, otherwise a new Category will be created
(see also Making use of References ID's in the CSV Templates).
6. Determines when the Forum will be visible and available based on the language setting for an user. The values can be either of the following:
*Note: Since an Agent can only use the English Language the setting of a locale for an "Agents Only" forum (see 3. above) cannot be achieved. As such if the CSV Import finds this combination of settings it will replace the setting in 3. above with "Users" to allow the locale of the forum to be instantiated upon import. However, a warning will be presented giving the option to proceed or cancel the import before this action is committed.
*Note: The locale will only work for those languages selected in addition to your default language in the "Localization" tab of your Zendesk "Account" settings.
"1" => English
"2" => Español
"8" => Deutsch
"19" => Português (Brasil)
"16" => Français
"1005" => Nederlands (Dutch)
"27" => Русский
"1000" => Dansk
"67" => (Japanese)
"22" => Italiano
"92" => Svenska
"1011" => Português (Europa)
"34" => Norsk
"13" => Polski (Polish)
"88" => Turkish
"84" => Suomi (Finnish)
"10" => (Simplified Chinese)
"78" => C(esky
"1009" => Magyar
"9" => (Traditional Chinese)
"66" => Arabic
"1003" => Slovak
"30" => (Hebrew)
"69" => ???
"23" => Romana
"1126" => Turkish (Turkish)
"93" => (Greek)
"1128" => Dutch (Dutch)
"77" => Indonesian
"81" => Thai (???)
"26" => Vietnamese
"59" => Japanese
"1075" => Català (Catalan)
"94" => Bulgarian
"24" => Íslenska
"74" => Hrvatski
"1092" => Lietuviu; kalba
"101" => Eesti keel (Estonian)
"72" => Slovenian
"1016" => Persian (?????)
"1150" => Srpski
"90" => Informal German
"47" => Filipino
"1008" => Bosnian
"1101" => Latvian
Complete the Topics Template
The Topics Template maps to the Zendesk Topic item and properties as annotated in the above diagram.
1. The value in the Topic # column must be a unique identifier within the Topics.csv file and will be referenced from within other files.
3. The body of the Topic can contain HTML formatting, but be mindful of the rules pertaining to characters that could be misinterpreted by the translator (see step "Resolve any invalid Characters" above).
*Note: Topics support the use of HTML formatting and so it is recommended that some basic HTML markup is used to format the body to achieve an aesthetically pleasing and more readable result in the Zendesk browser.
4. See Working with Date Definitions in the CSV Templates for full details on the rules for capturing date and time information within CSV templates.
6. *Note: Although the API indicates the presence of this property, there is no equivalent in the Zendesk Administration browser. As such although this column remains in the CSV for now, setting a value will have no effect on the visibility and access of Topics, since this is controlled using the appropriate settings at the Forums level (see "Complete the Forums Template" above).
8. Set this field to "yes" to prevent users adding comments to the Topic, otherwise use "no" to allow the recording of comments.
9. The value in the Forum column must match on the name of a Forum in the Forums.csv file (see also Making use of References ID's in the CSV Templates).
Complete the Topic Attachments Template
The Topic Attachments Template maps to the Zendesk Topic Attachments and properties as annotated in the above diagram.
1. The value in the Topic# column must match on the unique number of a Topic in the Topics.csv file. Enter multiple rows using the same unique number to assign multiple attachments (see also Dealing with Attachments that have Duplicate File Names).
Complete the Posts Template
The Posts Template maps to the Zendesk Post item and properties as annotated in the above diagram.
1. The value in the Post# column must be a unique identifier within the Posts.csv file and will be referenced from within other files.
2. The value in the Topic# column must match on the unique number of a Topic in the Topics.csv file.
3. The body of the Post can contain HTML formatting, but be mindful of the rules pertaining to characters that could be misinterpreted by the translator (see step "Resolve any invalid Characters" above).
4. See Working with Date Definitions in the CSV Templates for full details on the rules for capturing date and time information within CSV templates.
5. The value in the Submitter column must match on the name of a User in the Users.csv file (see also Making use of References ID's in the CSV Templates).
Complete the Post Attachments Template
The Post Attachments Template maps to the Zendesk Posts Attachments and properties as annotated in the above diagram.
1. The value in the Post # column must match on the unique number of a Post in the Posts.csv file. Enter multiple rows using the same unique number to assign multiple attachments (see also Dealing with Attachments that have Duplicate File Names).
Complete the Tickets Template
The Tickets Template maps to the Zendesk Ticket item and properties as annotated in the above diagram.
1. The value in the Ticket # column must be a unique identifier within the Tickets.csv file and will be referenced from within other files.
3. The description of the Ticket can contain HTML formatting, but be mindful of the rules pertaining to characters that could be misinterpreted by the translator (see step "Resolve any invalid Characters" above).
*Note: Tickets do not support the use of HTML formatting and so it is recommended that where possible any HTML markup is removed from the description and replaced with simple "rich text" formatting (i.e. line breaks) to ensure the most aesthetically please and readable results in the Zendesk browser.
4. See Working with Date Definitions in the CSV Templates for full details on the rules for capturing date and time information within CSV templates.
5. The same rules apply as per the creation date, but a Closure Date should only be specified for a Ticket that has a status of "Solved".
6. The value in the Requester column must match on the name of a User in the Users.csv file (see also Making use of References ID's in the CSV Templates).
7. The value in the Group column must match on the name of a Group in the Groups.csv file (see also Making use of References ID's in the CSV Templates).
8. The value in the Assignee column must match on the name of a User in the Users.csv file and the assignee must be a member of the group specified in 7. above (see also Making use of References ID's in the CSV Templates).
9 thru 10. The values in these columns must match one those available in the corresponding combo box in the Zendesk form.
1. If required it is possible to specify the submitter of a ticket, otherwise the submitter will be set as the ticket requester.
*Note: the submitter must be a valid agent specified within the Users.csv file included as part of the migration (see also Making use of References ID's in the CSV Templates).
2. It is possible to specify values for each of the custom ticket fields (see Working with Custom Fields in the CSV Templates for full details).
Complete Ticket Attachments Template
The Ticket Attachments Template maps to the Zendesk Ticket Attachments and properties as annotated in the above diagram.
1. The value in the Ticket # column must match on the unique number of a Ticket in the Tickets.csv file. Enter multiple rows using the same unique number to assign multiple attachments (see also Dealing with Attachments that have Duplicate File Names).
Complete Ticket Comments Template
The Posts Template maps to the Zendesk Post item and properties as annotated in the above diagram.
1. The value in the Ticket # column must match on the unique number of a Ticket in the Tickets.csv file.
2. The value in the Ticket Comment# column must be a unique identifier within the Tickets Comments.csv file and will be referenced from within other files.
3. The comment can contain HTML formatting, but be mindful of the rules pertaining to characters that could be misinterpreted by the translator (see step "Resolve any invalid Characters" above).
*Note: Ticket Comments do not support the use of HTML formatting and so it is recommended that where possible any HTML markup is removed from the comment and replaced with simple "rich text" formatting (i.e. line breaks) to ensure the most aesthetically please and readable results in the Zendesk browser.
4. See Working with Date Definitions in the CSV Templates for full details on the rules for capturing date and time information within CSV templates.
5. The value in the Author column must match on the name of a User in the Users.csv file (see also Making use of References ID's in the CSV Templates).
6. Set the value of this column to "TRUE" if the comment should be visible to the general public, otherwise set to "FALSE" to restrict access to authorized users.
Complete Ticket Comment Attachment Templates
The Ticket Comment Attachments Template maps to the Zendesk Ticket Comment Attachments and properties as annotated in the above diagram.
1. The value in the Ticket Comment # column must match on the unique number of a Ticket Comment in the Ticket Comments.csv file. Enter multiple rows using the same unique number to assign multiple attachments (see also Dealing with Attachments that have Duplicate File Names).
Zip up the Files Ready for Import
- Package up the folder containing the populated CSV template files and all associated attachment files into a .zip file ready for import.
Run the Import Operation
Use the Zendesk Migration Utility to import the information into your target Zendesk environment (see Running a Bulk CSV Import).
Comments
0 comments
Please sign in to leave a comment.