ImpEx:ZendeskExport
From Cerberus Helpdesk Wiki
These steps will work for exporting from Zendesk to Cerb4.
Contents |
Requirements
- You have an existing Zendesk installation.
- You've installed a fresh copy of Cerberus Helpdesk 4.0.
- You've installed the Cerb4 ImpEx tool.
Configuring the Zendesk Export
Inside the example-configs/ directory from the Cerb4-ImpEx files you'll find a zendesk.cfg template:
You should copy the zendesk.cfg template to a new file if you're going to be performing multiple imports.
Options that are 'commented out' will use their defaults.
- To enable an option, uncomment it by removing the leading # character on the line. Then choose the appropriate value for the option.
- To disable an option, comment it out by adding a leading # character to the front of the line.
Below are some notes on the most common configuration options.
- exportEncoding - Zendesk data is encoded UTF-8 so this should be set to "UTF-8". Ideally, your Cerb4 framework.config.php LANG_CHARSET_CODE and DB_CHARSET_CODE should match as well as your cerb4 MySQL database charset.
- outputDir - This is where your export files will be written for this source. If you're exporting from multiple sources you should give them each a unique outputDir.
- zendeskURL - The main url of your zendesk helpdesk
- zendeskUser - The login email for your zendesk helpdesk
- zendeskPassword - The password for you zendesk account
- maxHttpConnections - The exporter uses Zendesk's web api which means it makes several HTTP connections to download your data. This setting controls the maximum number of HTTP connections that you will allow at once. Higher numbers than this default can make the export complete faster on desks with large amounts of tickets.
- exportTickets - Set this to true to export ticket content from Zendesk.
- zenTicketViewId Tickets are imported from the Zendesk 'view' of your choice. Login to your Zendesk helpdesk and browse to the view that contains the tickets you want to import. Look at the url in your browser and it should look something like:
http://yourhelpdesk.zendesk.com/rules/123456 in this case, the value you would enter for zenTicketViewId would be 123456.
- exportToGroup - This is the Cerb4 group that your Zendesk tickets will be imported into. This value can be set to anything and the group will be created if it doesn't already exist. The default is 'Import:Zendesk', which you'll want to change if you're importing from multiple sources.
- exportMaskPrefix - A mask prefix that will be appended to the Zendesk ticket ID. The default is 'ZEN', which will give an ID of 500 a mask of ZEN-000500. This allows you to still find old helpdesk content in Cerb4, even though the ticket will be assigned a new internal ID.
- zendeskEmailAddress - Tickets that were submitted via the Zendesk web interface instead of by email do not have a TO address in Zendesk. Specify a default helpdesk address to apply for these tickets.
- exportWorkers - Enable this option to export Zendesk workers.
- initialWorkerPassword All imported workers will have their Cerb4 password initialized to this value. They should change it after they log in.
- exportContacts - Enable this to export contacts. The zendesk api does not allow us to pull the passwords for contacts, so contacts will have to sign up directly in cerberus if they want to login to the support center and access their ticket history.
Running the Export
You can start the export with the following command:
You'll be given feedback about the current progress. When the export is complete, you should have several subdirectories inside your outputDir directory.
Should you happen to run into "out of memory" errors while exporting, you can tell the Java VM to use more memory with the -Xmx argument, like so:
Importing the output into Cerb4
You need to move the subdirectories from your outputDir directory into the /cerb4/storage/import/new directory of your new Cerb4 installation. Only includes the contents of outputDir and not the top-level output directory itself. Also be sure to change the owner of the files to your webserver's user, or otherwise alter the permissions since the importer needs to delete the import files as it imports them.
The final step to begin your automatic import is to enable the Background Importing and Synchronization job in Cerb4 -> Helpdesk Setup-> Scheduler. You should set the Run Every option to something reasonable -- not too slow that it takes a week to import your data, but not so fast that you bombard your database with queries. It's difficult to provide a universal default since the right settings depends on many factors: how powerful your server is, what other services your server is providing, if you need to be considerate to other users on the machine, how much data you're importing, etc. There's no harm in beginning the import manually to find an ideal setting before leaving it unattended.
To manually run the import process, open your browser to: /cerb4/cron/cron.import?loglevel=6&reload=0
You can change the value of the &reload= parameter to a number of seconds to wait after finishing an import before starting another batch.
Dealing with import failures
Occasionally, the Cerb4 import process may reject one of your import items. These files will show up in Cerb4's /cerb4/storage/import/fail/ directory under their original export subdirectory. Once your import is finished, you can move these files into the /cerb4/storage/import/new/ directory and run the import process manually to see detailed error messages.
