com.atlassian.jira.imports.project

Interface ProjectImportManager

All Known Implementing Classes:

DefaultProjectImportManager

public interface ProjectImportManager

Performs project import tasks. This manager does not do any permission checks and throws exceptions if it is given invalid parameters.

Since:

v3.13

Method Summary

Modifier and Type	Method and Description
void	autoMapAndValidateCustomFields(ProjectImportData projectImportData, MappingResult mappingResult, BackupProject backupProject, I18nHelper i18nBean) Performs an automatic mapping of the custom fields from the backup system to the current systems custom field's and validates that all mappings are possible.
void	autoMapAndValidateIssueTypes(ProjectImportData projectImportData, MappingResult mappingResult, BackupProject backupProject, I18nHelper i18nBean) Performs an automatic mapping of the IssueTypes from the backup system to the current systems issue types and validates that all mappings are possible.
void	autoMapCustomFieldOptions(ProjectImportData projectImportData, BackupProject backupProject) Performs an automatic mapping of the custom field options from the backup system to the current systems values.
void	autoMapProjectRoles(ProjectImportData projectImportData) Performs an automatic mapping of the project roles from the backup system to the current systems values.
void	autoMapSystemFields(ProjectImportData projectImportData, BackupProject backupProject) Performs an automatic mapping of the system fields from the backup system to the current systems system field values The fields that are mapped are: Priority Resolution Status IssueLinkTypes Projects IssueSecurityLevels
void	createMissingUsers(UserMapper userMapper, ProjectImportResults projectImportResults, TaskProgressInterval taskProgressInterval) Creates all the Missing users that we have details for.
void	doImport(ProjectImportOptions projectImportOptions, ProjectImportData projectImportData, BackupProject backupProject, BackupSystemInformation backupSystemInformation, ProjectImportResults projectImportResults, TaskProgressInterval taskProgressInterval, I18nHelper i18n, ApplicationUser importAuthor) This will perform the project import based on the mappings provided.
List<ValidationMessage>	doPluginValidation(BackupProject backupProject, TaskProgressInterval taskProgressInterval, I18nHelper i18n) Call any plugin handlers that have registered to do validation
BackupOverview	getBackupOverview(String pathToBackupXml, TaskProgressSink taskProgressSink, I18nHelper i18n) Parses through the provided JIRA XML backup file and creates a BackupOverview.
ProjectImportData	getProjectImportData(ProjectImportOptions projectImportOptions, BackupProject backupProject, BackupSystemInformation backupSystemInformation, TaskProgressProcessor taskProgressProcessor) Parses through the provided JIRA XML backup file and creates a MappingResult.
void	importProject(ProjectImportOptions projectImportOptions, ProjectImportMapper projectImportMapper, BackupProject backupProject, ProjectImportResults projectImportResults, TaskProgressInterval taskProgressInterval) This will create or update a project and all its versions, components, and project role membership.
void	validateCustomFieldValues(ProjectImportData projectImportData, MappingResult mappingResult, BackupProject backupProject, TaskProgressProcessor taskProgressProcessor, I18nHelper i18nBean) Parses the partitioned custom field value XML and gets the custom fields to validate that they can handle the values.
void	validateFileAttachments(ProjectImportOptions projectImportOptions, ProjectImportData projectImportData, MappingResult mappingResult, BackupProject backupProject, BackupSystemInformation backupSystemInformation, TaskProgressProcessor taskProgressProcessor, I18nHelper i18n) Parses the partitioned file attachment XML and validates that the referenced file attachment exists in the user provided attachment directory.
void	validateSystemFields(ProjectImportData projectImportData, MappingResult mappingResult, ProjectImportOptions projectImportOptions, BackupProject backupProject, TaskProgressInterval taskProgressInterval, I18nHelper i18nBean) Validates that all mappings are possible.

Method Detail

getBackupOverview

BackupOverview getBackupOverview(String pathToBackupXml,
                                 TaskProgressSink taskProgressSink,
                                 I18nHelper i18n)
                          throws IOException,
                                 SAXException

Parses through the provided JIRA XML backup file and creates a BackupOverview.

If the optional parameter taskProgressSink is provided, then it is used to send information about the progress of this operation. This is used for the "Long Running Task" progress bar.

Parameters:

pathToBackupXml - must be a valid path, on disk, to a valid JIRA XML backup file.

taskProgressSink - Used to provide progress feedback, can be null.

i18n - used to internationalize the error messages

Returns:

a BackupOverview populated with the information gleaned from the JIRA XML backup.

Throws:

IOException - if there is a problem reading/finding the file

SAXException - if something goes wrong with processing the XML

getProjectImportData

ProjectImportData getProjectImportData(ProjectImportOptions projectImportOptions,
                                       BackupProject backupProject,
                                       BackupSystemInformation backupSystemInformation,
                                       TaskProgressProcessor taskProgressProcessor)
                                throws IOException,
                                       SAXException

Parses through the provided JIRA XML backup file and creates a MappingResult. The result will contain an initialProjectImportMapper and the paths to the partitioned XML files (created for the provided BackupProject).

Parameters:

projectImportOptions - User options for the project import, including the pathToBackupXML, attachmentPath, and "overwriteProjectDetails" flag.

backupProject - is the selected project that is used to inform creation of a mapper and a subset of XML data files.

backupSystemInformation - system-wide info from the backup file.

taskProgressProcessor - Used to provide progress feedback, can be null.

Returns:

ProjectImportData which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

Throws:

IOException - if something goes wrong handling the backup or partitioned XML files

SAXException - if something goes wrong with processing the XML

validateCustomFieldValues

void validateCustomFieldValues(ProjectImportData projectImportData,
                               MappingResult mappingResult,
                               BackupProject backupProject,
                               TaskProgressProcessor taskProgressProcessor,
                               I18nHelper i18nBean)
                        throws IOException,
                               SAXException

Parses the partitioned custom field value XML and gets the custom fields to validate that they can handle the values. Sets the map of custom field MessageSets in the MappingResult. This will also use the custom field options validator to validate the values of the custom fields that use the built in options.

Parameters:

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

mappingResult - this was the result containing the path to the partitioned XML files and the ProjectImportMapper

backupProject - the selected project to import

taskProgressProcessor - Used to provide progress feedback, can be null.

i18nBean - used to internationalize the error messages

Throws:

IOException - if something goes wrong handling the partitioned XML files

SAXException - if something goes wrong with processing the XML

validateFileAttachments

void validateFileAttachments(ProjectImportOptions projectImportOptions,
                             ProjectImportData projectImportData,
                             MappingResult mappingResult,
                             BackupProject backupProject,
                             BackupSystemInformation backupSystemInformation,
                             TaskProgressProcessor taskProgressProcessor,
                             I18nHelper i18n)
                      throws IOException,
                             SAXException

Parses the partitioned file attachment XML and validates that the referenced file attachment exists in the user provided attachment directory.

If any files do not exist a warning will be added to the file attachment message set in the mapping result.

NOTE: this validation only happens if ProjectImportOptions.getAttachmentPath() is non-null meaning that the user wants to restore attachments.

Parameters:

projectImportOptions - User options for the project import, including the pathToBackupXML, attachmentPath, and "overwriteProjectDetails" flag.

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

mappingResult - this was the result containing the path to the partitioned XML files and the ProjectImportMapper

backupProject - the selected project to import

backupSystemInformation - system-wide info from the backup file.

taskProgressProcessor - Used to provide progress feedback, can be null.

i18n - used to internationalize the error messages

Throws:

IOException - if something goes wrong handling the partitioned XML files

SAXException - if something goes wrong with processing the XML

autoMapAndValidateIssueTypes

void autoMapAndValidateIssueTypes(ProjectImportData projectImportData,
                                  MappingResult mappingResult,
                                  BackupProject backupProject,
                                  I18nHelper i18nBean)

Performs an automatic mapping of the IssueTypes from the backup system to the current systems issue types and validates that all mappings are possible. Any errors or warninigs will be reported through MappingResult.getIssueTypeMessageSet().

Parameters:

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

mappingResult - this was the result containing the path to the partitioned XML files,the ProjectImportMapper, and the MessageSets

backupProject - the selected project to import

i18nBean - used to internationalize the error messages

autoMapAndValidateCustomFields

void autoMapAndValidateCustomFields(ProjectImportData projectImportData,
                                    MappingResult mappingResult,
                                    BackupProject backupProject,
                                    I18nHelper i18nBean)

Performs an automatic mapping of the custom fields from the backup system to the current systems custom field's and validates that all mappings are possible. Any errors or warnings will be reported through the MappingResult.getCustomFieldMessageSet().

Parameters:

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

mappingResult - this was the result containing the path to the partitioned XML files,the ProjectImportMapper, and the MessageSets

backupProject - the selected project to import

i18nBean - used to internationalize the error messages

autoMapCustomFieldOptions

void autoMapCustomFieldOptions(ProjectImportData projectImportData,
                               BackupProject backupProject)

Performs an automatic mapping of the custom field options from the backup system to the current systems values. This should only ever happen if the custom fields have been mapped and validated.

Parameters:

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

backupProject - the selected project to import

autoMapProjectRoles

void autoMapProjectRoles(ProjectImportData projectImportData)

Performs an automatic mapping of the project roles from the backup system to the current systems values.

Parameters:

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

autoMapSystemFields

void autoMapSystemFields(ProjectImportData projectImportData,
                         BackupProject backupProject)

Performs an automatic mapping of the system fields from the backup system to the current systems system field values The fields that are mapped are:

• Priority
• Resolution
• Status
• IssueLinkTypes
• Projects
• IssueSecurityLevels

Parameters:

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

backupProject - the selected project to import

validateSystemFields

void validateSystemFields(ProjectImportData projectImportData,
                          MappingResult mappingResult,
                          ProjectImportOptions projectImportOptions,
                          BackupProject backupProject,
                          TaskProgressInterval taskProgressInterval,
                          I18nHelper i18nBean)

Validates that all mappings are possible. Any errors or warnings will be reported through the field's MessageSet on the MappingResult. The fields that are validated are:

• Priority
• Resolution
• Status
• Project Roles
• Project Roles Membership
• Groups
• IssueLinkTypes
• Users
• Description, Environment and Comment length

Parameters:

projectImportData - which holds the initial projectImportMapper and the partitioned XML file paths for the project XML data that was partitioned from the main XML backup.

mappingResult - this was the result containing the path to the partitioned XML files,the ProjectImportMapper, and the MessageSets

projectImportOptions - Contains user inputted options related to the project import.

backupProject - the selected project to import

taskProgressInterval - Used to provide progress feedback, can be null.

i18nBean - used to internationalize the error messages

doPluginValidation

List<ValidationMessage> doPluginValidation(BackupProject backupProject,
                                           TaskProgressInterval taskProgressInterval,
                                           I18nHelper i18n)

Call any plugin handlers that have registered to do validation

Parameters:

backupProject - the selected project to import

taskProgressInterval - Used to provide progress feedback, can be null.

i18n - used to internationalize the error messages

Returns:

A Set of Messages

importProject

void importProject(ProjectImportOptions projectImportOptions,
                   ProjectImportMapper projectImportMapper,
                   BackupProject backupProject,
                   ProjectImportResults projectImportResults,
                   TaskProgressInterval taskProgressInterval)
            throws AbortImportException

This will create or update a project and all its versions, components, and project role membership.

If the project does not exist then it will be created with default schemes and the details from the ExternalProject from the backup file.

If the project exists then the details will be updated to match that of the ExternalProject.

This will also have the side-effect of populating the ProjectImportMapper.getProjectMapper() and the ProjectImportMapper.getVersionMapper() and ProjectImportMapper.getComponentMapper().

Parameters:

projectImportOptions - Contains user inputted options related to the project import.

projectImportMapper - contains the project, version, and component mappers. If the external projects id is not mapped then this method will try to create the project.

backupProject - contains the project details used to clobber an existing project or as the details for the new project

projectImportResults - used to collect the statistics of what was created during the import, if it was a success, and any errors that may have occurred.

taskProgressInterval - used to show task progress to the user while this long running task is happening.

Throws:

AbortImportException - if the import is aborted due to errors.

doImport

void doImport(ProjectImportOptions projectImportOptions,
              ProjectImportData projectImportData,
              BackupProject backupProject,
              BackupSystemInformation backupSystemInformation,
              ProjectImportResults projectImportResults,
              TaskProgressInterval taskProgressInterval,
              I18nHelper i18n,
              ApplicationUser importAuthor)
       throws IOException,
              SAXException,
              IndexException

This will perform the project import based on the mappings provided. Calling this method will create a projects issues and all issue related data.

Parameters:

projectImportOptions - User options for the project import, including the pathToBackupXML, attachmentPath, and "overwriteProjectDetails" flag.

projectImportData - contains a projectImportMapper that has been through the automatic mapping and validation process and the paths, on disk, to the partitioned xml files.

backupProject - contains the import project details.

backupSystemInformation - system-wide info from the backup file.

projectImportResults - used to collect the statistics of what was created during the import, if it was a success, and any errors that may have occurred.

taskProgressInterval - used to show task progress to the user while this long running task is happening.

i18n - used to internationalize the error messages

importAuthor - the user who is performing the project import, this is used as the author of the change item marker for created issues @throws IOException if something goes wrong handling the partitioned XML files @throws SAXException if something goes wrong with processing the XML @throws IOException if something goes wrong handling the backup or partitioned XML files

Throws:

SAXException - if something goes wrong with processing the XML

IndexException - if there is a problem re-indexing JIRA.

IOException - IOException

createMissingUsers

void createMissingUsers(UserMapper userMapper,
                        ProjectImportResults projectImportResults,
                        TaskProgressInterval taskProgressInterval)
                 throws AbortImportException

Creates all the Missing users that we have details for. This

Parameters:

userMapper - The UserMapper which is used to determine missing users.

projectImportResults - used to collect the statistics of what was created during the import, if it was a success, and any errors that may have occurred.

taskProgressInterval - used to show task progress to the user while this long running task is happening.

Throws:

AbortImportException - if the import is aborted due to too many errors.