Package 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 Details

    • 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.