Расширение плагина импорта JIRA

Это руководство поможет вам расширить плагин JIRA Import с помощью Project Importer SPI. В настоящее время вы можете расширить плагин импортера JIRA, чтобы включить данные из ваших плагинов во время импорта проекта.

 

Обзор

Плагин JIRA Import используется для импорта проекта JIRA из файла резервной копии в экземпляр JIRA (см. документацию). Одним из ограничений плагина JIRA Import является то, что он не может обрабатывать данные плагина, а это значит, что вы не можете перемещать данные плагина между экземплярами JIRA. Исключением является пользовательские поля, но даже пользовательские поля имеют ограниченную поддержку, например, поле JIRA Agile sprint может передавать данные через указатель на спринт, но этот спринт не будет существовать в новом экземпляре JIRA.

Причина этого ограничения заключается в том, что плагин импорта JIRA не имеет ни малейшего представления о том, какие данные хранятся в плагинах или каковы значения и отношения с этими данными. Он не может определить, какие данные относятся к тем проектам или задачам или даже если данные связаны с проектом. Например, JIRA Agile не организована вокруг проектов, а использует JQL для определения быстрых досок и т. д.

Решение этого ограничения - позволить плагинам активно участвовать в процессе импорта. Прочтите следующие разделы для обзора процесса импорта проекта и того, как ваши плагины могут взаимодействовать с SPI Project Importer в каждой части процесса.

JIRA импортер проекта SPI

Процесс импорта проекта состоит из нескольких этапов. Project Importer SPI позволяет плагину участвовать в любом из этих шагов. Основной поток:

1. JIRA обрабатывает XML, извлекает информацию о проекте и задачи в резервном копировании, а также сопоставляет элементы конфигурации, например, идентификаторы типов  задач из исходной системы в значения в целевой системе.
2. JIRA обрабатывает XML снова, разделяя его на несколько файлов, по одному для каждого типа сущности, который должен быть импортирован, например. <jiraissue>, <customfieldvalue>, <jiraaction> и т. д.
3. JIRA создает проект, если требуется.
4. JIRA создает задачи и связанные с задачами данные, такие как комментарии и история изменений.

Существует ряд основных механизмов, с которыми должен взаимодействовать ваш плагин:

• Каждый тип (таблица) сущности данных может обрабатываться плагином, если он хочет предоставить обработчик для этого типа сущности.
• Существует коллекция Mappers, которую плагин может использовать и вносить в нее, чтобы определить, как данные сопоставляются между идентификаторами в источнике и идентификаторами в целевой системе.
• Плагин также может вносить результаты, которые будут отображаться в пользовательском интерфейсе, суммируя результаты импорта, добавляя результаты к объекту ProjectImportResult.
• Кроме того, для данных АО плагин может указать порядок, в котором объекты AO должны быть импортированы, чтобы они могли контролировать перестройку зависимостей между данными.

В этом документе мы ссылаемся на «JIRA Project Importer SPI» или просто на «SPI», поскольку мы в основном описываем набор интерфейсов, которые плагины должны реализовать, чтобы полностью участвовать в импорте проекта. Тем не менее, будут предоставлены и описаны обе точки SPI и API.

Добавление к валидации проекта

Плагины могут добавить к проверке(валидации), которая выполняется до того, как будет выполнен импорт.

Процесс довольно сложный, но по существу JIRA выполняет переход по резервной копии JIRA и собирает важную информацию для каждого проекта, такую как типы задач и используемые  пользовательские поля. Эта информация содержится в сессии. Когда пользователь выбирает проект для импорта, JIRA проверяет данные из резервной копии для этого проекта на текущее состояние системы.

Описанный здесь SPI позволяет плагинам присоединиться к этому процессу.

Интерфейс com.atlassian.jira.imports.project.ao.handler.PluggableOverviewAoEntityHandler

Определяет класс обработчика, который сможет собирать данные из резервной копии, которые затем могут использоваться для валидации или для других целей. Этот обработчик будет вызываться на начальных этапах импорта до того, как пользователю будет представлен список проектов, из которого они выбирают проект для импорта.

Точка плагина для этого обработчика: <project-import-ao-overview-handler>.

 

Краткое описание метода

• endTable (String tableName) - void.
  • Предоставляет реализации возможность выполнить некоторые действия, когда все строки таблицы были обработаны.
• endDocument () - void.
  • Предоставляет реализации возможность выполнить некоторые действия, когда документ закончил чтение.
• handleEntity (java.lang.String entityName, java.util.Map <java.lang.String, java.lang.Object>) - void.
  • Это основной метод реализации при использовании этого ImportEntityHandler. Этот метод предоставит имя сущности и полную карту ключей атрибутов /пар значений.  Атрибутами могут быть любые строковые, длинные, двойные, логические или данные.
• handlesEntity (java.lang.String entityName) - логическое.
  • Должен возвращать true, если пользователь хочет обработать этот объект.
• startDocument () - void.
  • Предоставляет возможность реализации некоторых действий, когда документ начинает считываться.
• setBackupOverviewBuilder (BackupOverviewBuilder backupOverviewBuilder) - void.
  • Устанавливает обзор резервного копирования. Плагины должны использовать BackupOverviewBuilder.addAdditionalData (String key, String projectId, Object data) для хранения критически важных данных резервного копирования для каждого проекта в резервной копии. К одному и тому же проекту и ключу могут добавляться несколько записей.

Поскольку это объект сеанса, это должно содержать только минимальные данные, необходимые для обеспечения возможности импорта для проекта.

Интерфейс com.atlassian.jira.imports.project.ao.PluggableValidator

Определяет класс, который будет вызываться для проверки того, что выбранный проект может быть импортирован.

Разработчикам плагинов необходимо понимать поток пользователей здесь:

1. Пользователь выбирает проект для импорта.
2. Затем JIRA проверяет, можно ли импортировать плагин. На этом этапе будут вызываться реализация PluggableValidator.
3. Затем пользователь может ответить на ошибки путем настройки элементов в JIRA.
4. Затем пользователь может повторить шаг валидации или выбрать другой проект для импорта.

Точка плагина для этого обработчика: <project-import-validator>.

 

Краткое описание метода

• validate (BackupProject backupProject, I18nHelper i18n) - ValidationMessage.
  • BackupProject будет содержать любые данные, предоставленные См. Collection<Object> BackupProject.getAdditionalData(String key).

Импорт данных

Интерфейс com.atlassian.jira.imports.project.ao.handler.PluggableImportAoEntityHandler

Определяет класс обработчика, который сможет выполнить некоторую операцию с учетом имени сущности AO и атрибутов сущностей.

Есть два плагина, которые используют этот обработчик, <ao-preimport-handler> и <ao-import-handler>:

• <ao-preimport-handler>, будет вызываться во время первого этапа импорта, когда activeobjects.xml разбивается на файлы для каждого типа сущности. Плагины могут собирать данные на этом этапе и хранить их, используя экземпляры AbstractMapper, для использования на фактическом этапе импорта.
• <ao-import-handler>, будет вызываться после того, как будут установлены данные OfBiz. Это время, когда плагины обычно импортируют необходимые данные в базу данных.

Краткое описание метода

• endTable (String tableName) - void.
  • Предоставляет реализации возможность выполнить некоторые действия, когда все строки таблицы были обработаны.
• endDocument () - void.
  • Предоставляет реализации возможность выполнить некоторые действия, когда документ закончил чтение.
• handleEntity (java.lang.String entityName, java.util.Map <java.lang.String, java.lang.Object>) - void.
  • Это основной метод реализации при использовании этого ImportEntityHandler. Этот метод предоставит имя сущности и полную карту пар значений/ ключей атрибутов. Атрибутами могут быть любые строки, длинные, двойные, логические или данные.
• handlesEntity (java.lang.String entityName) - логическое.
  • Должен возвращать true, если пользователь хочет обработать эту сущность.
• getEntityWeight (java.lang.String entityName) - long.
  • Возвращает вес для этой сущности. Если этот обработчик не обрабатывает сущность или не заботится о ее заказе, он должен возвращать com.atlassian.jira.imports.project.ao.handler.PluggableImportAoEntityHandler.WEIGHT_NONE. Это игнорируется (не вызывается) на этапе предварительного импорта, где объекты предоставляются в резервном XML-порядке.
• startDocument () - void.
  • Предоставляет возможность реализации некоторых действий, когда документ начинает считываться.
• setProjectImportMapper (ImportMapper projectImportMapper) - void.
  • Наборщик для ImportMapper. Это будет введено при создании экземпляра.
• setProjectImportResults (ProjectImportResults projectImportResults) - void.
  • Установщик для ProjectImportResults. Это будет введено при создании экземпляра.
• setBackupSystemInformation (BackupSystemInformation backupSystemInformation) - void.
  • Средство настройки для BackupSystemInformation. Это будет введено при создании экземпляра.
• setBackupProject (BackupProject backupProject) - void.
  • Средство настройкидля BackupProject. Это будет введено при создании экземпляра.

Интерфейс

com.atlassian.jira.imports.project.handler.PluggableImportOfBizEntityHandler

Определяет класс обработчика, который сможет выполнить некоторую операцию, учитывая имя сущности OfBiz и атрибуты сущностей.

Есть два плагина, которые используют этот обработчик, <ofbiz-preimport-handler> и <ofbiz-import-handler>:

• <ofbiz-preimport-handler> будет вызываться во время первого этапа импорта, когда entity.xml разбивается на файлы для каждого типа сущности. Плагины могут собирать данные на этом этапе и хранить их, используя экземпляры AbstractMapper, для использования на фактическом этапе импорта.
• <ofbiz-import-handler> будет вызываться, поскольку JIRA импортирует данные OfBiz. Плагинам может потребоваться импортировать некоторые данные на этом этапе, например, свойства сущности.

Краткое описание метода

• endDocument () - void.
  • Предоставляет реализации возможность выполнить некоторые действия, когда документ закончил чтение.
• handleEntity (java.lang.String entityName, java.util.Map <java.lang.String, java.lang.Object>) - void.
  • Это основной метод реализации при использовании этого ImportEntityHandler. Этот метод предоставит имя сущности и полную карту ключей атрибутов/ значений пар .
• handlesEntity (java.lang.String entityName) - логическое.
  • Должен возвращать true, если пользователь хочет обработать этот объект.
• startDocument () - void.
  • Предоставляет возможность реализации некоторых действий, когда документ начинает считываться.
• setProjectImportMapper (ImportMapper projectImportMapper) - void.
  • Средство настройки для ImportMapper. Это будет введено при создании экземпляра.
• setProjectImportResults (ProjectImportResults projectImportResults) - void.
  • Средство настройки для ProjectImportResults. Это будет введено при создании экземпляра.
• setBackupSystemInformation (BackupSystemInformation backupSystemInformation) - void.
  • Средство настройки для BackupSystemInformation. Это будет введено при создании экземпляра.
• setBackupProject (BackupProject backupProject) - void.
  • Средство настройки для BackupProject. Это будет введено при создании экземпляра.

Интерфейс com.atlassian.jira.imports.project.handler.PluggableImportOfBizEntityHandler

Определяет класс обработчика, который сможет выполнить некоторую операцию, учитывая имя сущности OfBiz и атрибуты сущностей.

Есть два плагина, которые используют этот обработчик, <ofbiz-preimport-handler> и <ofbiz-import-handler>:

• <ofbiz-preimport-handler> будет вызываться во время первого этапа импорта, когда entity.xml разбивается на файлы для каждого типа сущности. Плагины могут собирать данные на этом этапе и хранить их, используя экземпляры AbstractMapper, для использования на фактическом этапе импорта.
• <ofbiz-import-handler> будет вызываться, поскольку JIRA импортирует данные OfBiz. Плагинам может потребоваться импортировать некоторые данные на этом этапе, например, свойства объекта.

Краткое описание метода

• endDocument () - void.
  • Предоставляет реализации возможность выполнить некоторые действия, когда документ закончил чтение.
• handleEntity (java.lang.String entityName, java.util.Map <java.lang.String, java.lang.Object>) - void.
  • Это основной метод реализации при использовании этого ImportEntityHandler. Этот метод предоставит имя объекта и полную карту пар ключей / значений атрибутов.
• handlesEntity (java.lang.String entityName) - логическое.
  • Должен возвращать true, если пользователь хочет обработать эту сущность.
• startDocument () - void.
  • Предоставляет возможность реализации некоторых действий, когда документ начинает считываться.
• setProjectImportMapper (ImportMapper projectImportMapper) - void.
  • Средство настройки для ImportMapper. Это будет введено при создании экземпляра.
• setProjectImportResults (ProjectImportResults projectImportResults) - void.
  • Средство настройки для ProjectImportResults. Это будет введено при создании экземпляра.
• setBackupSystemInformation (BackupSystemInformation backupSystemInformation) - void.
  • Средство настройки для BackupSystemInformation. Это будет введено при создании экземпляра.
• setBackupProject (BackupProject backupProject) - void.
  • Средство настройки для BackupProject. Это будет введено при создании экземпляра.

Класс com.atlassian.jira.imports.project.mapper.AbstractMapper

Плагины должны обеспечивать конкретную реализацию этого класса, когда им нужно сопоставить старые значения из исходной системы с новыми значениями в целевом объекте и / или при необходимости отметить значения. Разумеется, они могут расширить его, чтобы предоставить любые дополнительные данные, необходимые для завершения процесса импорта. Главной целью сопоставителя, SimpleProjectImportIdMapperImpl, является предоставление для использования в тривиальных случаях.

Экземпляры сопоставителя доступны, вызывом getPluggableMapper (String mapperKey) в ImportMapper.

Краткое описание метода

• clearMappedValues () - void.
  • Это очистит любые сопоставленные данные, которые могут быть введены в сопоставители.
• flagValueAsRequired (java.lang.String oldId) - void.
  • Это внутренний метод использования Mappers, расширяющий AbstractMapper и он не должен вызываться из других классов.
• getAllMappedIds () - java.util.Collection <java.lang.String>.
  • Возвращает коллекцию всех новых идентификаторов, которые сопоставляются.
• getDisplayName (java.lang.String oldId) - java.lang.String.
  • Возвращает отображаемое имя для данного старого идентификатора.
• getKey (java.lang.String oldId) - java.lang.String.
  • Возвращает зарегистрированный «ключ» для данного старого идентификатора или null, если ни один из них не зарегистрирован.
• getMappedId (java.lang.String oldId) - java.lang.String.
  • Возвращает строку, соответствующую идентификатору в целевой системе JIRA, null, если ни один из них не был отображен.
• getRegisteredOldIds () - java.util.Collection <java.lang.String>.
  • Возвращает коллекцию идентификаторов как объектов String, идентифицирующих объекты из файла импорта, необходимые для импорта.
• getRequiredOldIds () - java.util.Collection <java.lang.String>.
  • Возвращает коллекцию идентификаторов как объектов String, идентифицирующих все объекты соответствующего типа, найденные в файле импорта.
• getValuesFromImport () - java.util.Collection <IdKeyPair>.
  • Устаревшее. Используйте getRegisteredOldIds ()
• mapValue (java.lang.String oldId, java.lang.String newId) - void.
  • Этот метод отображает значение из системы резервного копирования в действительное значение в целевой системе.
• registerOldValue (java.lang.String oldId, java.lang.String oldKey) - void.
  • Это внутренний метод использования Mappers, расширяющий AbstractMapper и не должен вызываться из других классов.

Интерфейс com.atlassian.jira.imports.project.handler.PluggableImportRunnable

Есть два плагина, которые используют этот обработчик, <preimport-handler> и <postimport-handler>:

• <preimport-handler> определяет класс обработчика, который будет вызываться после создания объекта проекта, но до того, как будут импортированы какие-либо данные конфигурации или задачи. Плагины могут использовать этот обработчик для проверки состояния целевой системы до начала импорта.
• <postimport-handler> определяет класс обработчика, который будет вызываться после того, как все данные будут импортированы в целевую систему.

Краткое описание метода

 

• run () - void.
  • Предоставляет возможность реализации некоторых действий.
• setImportMapper (ImportMapper projectImportMapper) - void.
  • Средство настройки для ImportMapper. Это будет введено при создании экземпляра.
• setProjectImportResults (ProjectImportResults projectImportResults) - void.
  • Средство настройки для ProjectImportResults. Это будет введено при создании экземпляра.
• setBackupSystemInformation (BackupSystemInformation backupSystemInformation) - void.
  • Средство настройки для BackupSystemInformation. Это будет введено при создании экземпляра.
• setBackupProject (BackupProject backupProject) - void.
  • Средство настройки для BackupProject. Это будет введено при создании экземпляра.

Типы пользовательских полей плагина

Интерфейс com.atlassian.jira.imports.project.customfield.ProjectImportableCustomField

Любые плагины, которые предоставляют пользовательские типы полей, которые необходимо перенести, должны реализовать интерфейс ProjectImportableCustomField.

Этот интерфейс требует, чтобы класс предоставил ProjectCustomFieldImporter, который будет следить за любым переводом данных, требуемым во время процесса архивации.

Краткое описание метода

• getProjectImporter () - ProjectCustomFieldImporter.
  • Возвращает объект, который будет выполнять фактические функции импорта проекта для пользовательского типа поля.

Интерфейс com.atlassian.jira.imports.project.customfield.ProjectCustomFieldImporter

Плагины также должны предоставлять или использовать текущую реализацию JIRA этого интерфейса для фактической карты импортированных данных по мере необходимости.

Краткое описание метода

• canMapImportValue (ProjectImportMapper projectImportMapper, ExternalCustomFieldValue customFieldValue, FieldConfig fieldConfig, I18nHelper i18n) - MessageSet.
  • Пользовательское поле должно определить, является ли допустимое значение пользовательского поля, которое может быть импортировано, предоставленным значением пользовательского поля в контексте конфигурации и сопоставителя импорта проекта являться валидным значением, которое может импортироваться.
• getMappedImportValue (ProjectImportMapper projectImportMapper, ExternalCustomFieldValue customFieldValue, FieldConfig fieldConfig) - ProjectCustomFieldImporter.MappedCustomFieldValue.
  • Пользовательское поле должно определить, какое «сопоставляемое» значение будет для предоставленного значения пользовательского поля и вернет это новое строковое представление значения.

Содействующие результаты

Каждому обработчику импорта вводится объект ProjectImportResults. Плагины могут добавлять к этому используя следующее:

ProjectImportResult

• void addResult (long count, String msgKey)

Добавляет результат импорта.

Этот метод предоставляется, чтобы плагины могли подсчитывать количество импортированных элементов.

Плагины должны пытаться отображать только небольшое количество наиболее релевантной информации, чтобы не перегружать пользователя и не захламлять результат

Средство настройки для BackupProject. Это будет введено при создании экземпляра.

Плагин XML

В этом разделе описываются ключевые элементы вашего дескриптора плагина, если вы используете SPI Project Importer. Ниже приведен пример XML-модуля плагина:

ЗОНА

Определение содержания этих элементов приведено ниже:

 

Заметки

• Данные набора Active Object(Активный объект) и Property (Свойство) импортируются после данных конфигурации JIRA и задач JIRA (сущность jiraissue).
• Данные набора свойств предварительно обрабатываются в объединенный формат, соединяются с данными <property-entry> и <property - ????>, то есть в записи <OSPropertyString> также будут атрибуты entityName и propertyKey.

 

По материалам Atlassian JIRA  Server Developer Extending the JIRA Import plugin