ImpEx:Cerb3Export
From Cerberus Helpdesk Wiki
These steps will work for exporting from Cerb2 or Cerb3 to Cerb5. For brevity, the instructions will refer to Cerb3 as the source.
Contents |
Requirements
- You have an existing Cerb2 (2.7) or Cerb3 (3.6) installation. Upgrade to the latest release for your version if necessary.
- You've installed a fresh copy of Cerberus Helpdesk 5.x.
- You've installed the Cerb5 ImpEx tool.
Configuring the Cerb2/Cerb3 Export
Inside the example-configs/ directory from the Cerb4-ImpEx files you'll find a cerb2.cfg and cerb3.cfg template:
You should copy the cerb3.cfg template to a new file if you're going to be performing multiple imports.
Options that are 'commented out' will use their defaults. The default behavior is to export nothing.
- 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.
- Line 4: 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.
- Line 5: fixMagicQuotes - If your Cerb3 webserver has magic_quotes_gpc enabled in php.ini then you'll want to set this option to true. If you aren't sure, you can create a new phpinfo.php file in your web-path with the following content and open it in your browser:
- Line 8: dbConnection - The server connection details to your existing Cerb3 database in JDBC format. Make sure the hostname, port and database name are properly set. Usually you'll only need to change the database name (which is cerb3 in the example file).
- Line 9: dbUser - Your database login (found in your Cerb3 config.php file).
- Line 10: dbPassword - Your database password (found in your Cerb3 config.php file).
- Line 13: exportTickets - Set this to true to export ticket content from Cerb3.
- Line 14: exportToGroup - This is the name of the Cerb4 group that your Cerb3 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:Cerb3', which you'll want to change if you're importing from multiple sources. After you run ImpEx and import your tickets into Cerb4, your tickets will be sorted into categories named for your Cerb3 mailboxes (or queues). These categories will be nested within the group you specified for exportToGroup. From that point you can easily use the Cerb4 Pile Sorter to sort your tickets into other groups or categories (see example video at http://www.cerberusweb.com/videos ).
- Line 15: exportMaskPrefix - If any of your Cerb3 tickets don't have masks then one will be generated using this prefix. The default is 'CERB3', which will give an ID of 500 a mask of CERB3-000500. This allows you to still find old helpdesk content in Cerb4, even though the ticket will be assigned a new internal ID.
- Line 16: exportTicketExcludeOpen - Enable this option to NOT export open Cerb3 tickets.
- Line 17: exportTicketExcludeClosed - Enable this option to NOT export closed Cerb3 tickets.
- Line 20: exportWorkers - Enable this option to export Cerb3 workers.
- Line 23: exportOrgs - Enable this option to export organizations from the Cerb3 address book.
- Line 26: exportContacts - Enable this option to export contacts from the Cerb3 address book.
- Line 29: exportKb - Enable this option to export articles and categories from the Cerb3 knowledgebase.
- Line 30: exportKbRoot - This option specifies where you would like your Cerb3 articles to be merged with your Cerb4 knowledgebase categories. You can enter a new category name here and it will be created. You can enter the name of an existing Cerb4 top-level category and the imported articles will be merged with your existing content. It's usually a good idea to import your KB articles to a new top-level category per import source -- then you can purposefully organize your knowledgebase content using Cerb4's philosophies. You may wish to ignore this advice if you have thousands of articles to import. (Disable this option if you want to place the imported categories at the top level in Cerb4.)
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 include 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 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 or click the "run now" link next to the Background Importing and Synchronization job. (Note: if you get an error about your IP not being authorized, add the listed IP to the IP Security box on Helpdesk Setup -> System.
You can change the value of the &reload= parameter to a number of seconds to wait after finishing an import before starting another batch.
We intentionally export data from Cerb3 in descending chronological order, so large helpdesks will have access to their most recent content first and the oldest items in a several year old archive will be imported last (as older content is increasingly less likely to be needed over the course of a few hour import).
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.
Earlier versions of Cerberus Helpdesk didn't enforce validation as much as they should have, so most failures are likely malformed e-mail addresses from spam.
