Mantis Issue Importer
=====================

Function:

Imports one or more issues from a text file into Mantis. Uses function bug_create in core/bug_api.php to create the issues.


Requirements:

Must be used with a version of Mantis that takes class BugData as a parameter to function bug_create in core/bug_api.php.
Tested on Mantis 0.19.0, 0.19.1, and 1.0.0a1.


Installation:

1. Unzip the distribution into a temporary folder.

2. Copy files into mantis root folder:
   - import_issues.php
   - import_issues_page.php
   
3. Edit custom_strings_inc.php located in the mantis root folder.
   If this file already exists, add the contents of custom_strings_inc.php from the distribution into the original and save.
   If this file does not exist, just copy custom_strings_inc.php from the distribution into the mantis root folder.

4. Edit custom_constant_inc.php located in the mantis root folder.
   If this file already exists, add the contents of custom_constant_inc.php from the distribution into the original and save.
   If this file does not exist, just copy custom_constant_inc.php from the distribution into the mantis root folder.

5. Edit core\html_api.php and find the print_manage_menu function. Files 
		print_manage_menu_0.19.x.txt and
		print_manage_menu_1.0.0ax.txt
   in the distribution have copies of this function with lines added to support the importing of issues.
   All added lines are marked with comments "# @@@ add this line for Mantis issue importer"
   Add these lines to the matching locations in function print_manage_menu in core\html_api.php.


Usage:

Note: You only can run the import as an administrator (under the manage menu)

1. Select Manage, then Import Issues. Review the fields that can be imported and their sequence, as well as the values used
   for field separators and line separators.

2. Prepare the text file to be used for import. The text file must contain the fields you wish to import in the same sequence
   as the list of fields on the Import Issues page. The fields must be separated with the specified separator (default ;),
   and the lines must be separated with the specified line separator (default \r\n).
   
3. Make a backup of your database before importing.
   
4. Switch to the project into which you want to import the issues. You must do this before starting the import, so that the
   appropriate defaults and choices for enumerations are available.
   
5. Select Manage, then Import Issues.

6. Select the text file to be imported. Windows users must change all occurrences of '\' in the file name to '/'.

7. For each field, choose one of:
	a) import the field
	b) use the default value for the field in each issue imported
	c) use a constant value for the field in each issue imported.
   The Summary field must always be imported, since its value identifies the nature of each issue.
   The Description field must either be imported or set to a constant value. The default empty string is not acceptable
   to the bug_create function.

8. Click the Start Import button.

9. Review the results to ensure they are as expected. If you remembered to take a backup you can try again!

Restrictions:

1. Several fields are not imported, because the bug_create function sets their values explicitly. These are:
	status			- set to assigned if there is an assignee, new otherwise
	resolution		- set to open
	duplicate_id	- set to 0
	projection		- set to 10
	eta				- set to 10
	date_submitted	- set to now
	last_updated	- set to now
	
2. Fields profile_id and sponsorship_total are not imported, because no meaningful equivalents are expected to
   be found in other bug trackers.
   
3. As indicated above, all issues are created in either new or assigned status. 
   If issues were in other states in your other bug tracker, 
   you will need to drive the workflow to achieve the desired state, e.g., for an assigned issue 
   that should be closed, resolve the issue then close it. In testing, I found it useful to import 
   a recognizable value in the Additional Information field to allow me to search for issues that 
   should be bulk migrated to a particular state.
   Also note that if the assignee name in any imported issue is not in the Mantis database, the 
   issue will be created in new status. 
   
4. At present, this facility only supports MySQL.
