ImpEx:JiraExport
From Cerberus Helpdesk Wiki
Contents |
Requirements
- You have an existing Jira installation.
- You've installed a fresh copy of Cerberus Helpdesk 4.0.
- You've installed the Cerb4 ImpEx tool.
This exporter was built and checked against Jira version 3.3.1 . It may also work for various other versions as well. We would appreciate any feedback on how it works on your version sent to development@webgroupmedia.com .
Jira has an option to view an XML feed version of any search result. Click the XML link above the search results and save the resulting output as an XML file. You will use this file as your input for the exporter.
Configuring the Jira Export
Inside the example-configs/ directory from the Cerb4-ImpEx files you'll find a jira.cfg template:
You should copy the jira.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 that is not enabled, 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.
- outputDir - This is where your export files will be written for this source.
- exportTickets - Set this to true to export ticket content from RT.
- jiraXmlFile - The name of the Jira export XML file which has the data you will be importing. This file should be placed in the same directory from which you are running the exporter.
- exportToGroup - This is the Cerb4 group that your Jira issues 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:Jira'. You can easily move tickets out of this imported group after importing from within Cerb4.
- messageFrom - The "message" of an imported ticket from jira is simply the summary and description of the jira issue. Choose any email address that the main issue messages will be FROM.
- messageTo - Choose any email address that the main issue messages will be TO
- requester - Choose an email address that will be considered the requester for this ticket.
- commentAuthor - All comments will be imported as FROM the email specified. It should be the email of one of your helpdesk workers.
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.
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.
