Доступность: Jira 4.1 и более поздние.
На этой странице представлены концепции и методы работы с задачами Jira в приложении.
IssueService
Jira 4.1 представил объект уровня API, называемый IssueService. Этот класс службы используется для выполнения операций создания, обновления, удаления и перехода в Jira с задачей. Эти методы служб гарантируют, что при решении задач все бизнес-правила Jira будут соблюдены. Это означает, что будут проверены разрешения и проверка данных, будут запущены соответствующие события и будут активированы уведомления.
Разработчики приложений, которые хотят выполнить какую-либо из этих операций, должны использовать IssueService, поскольку он абстрагирует обычно сложные операции с задачами в чем-то более простым и гарантирует, что вы не поместите поврежденные данные в Jira.
Общий формат службы состоит в том, что для каждой операции есть два метода - валидация и метод «делать». Метод проверки генерирует объект результата, который используется как параметр для следующего метода «делать». Если валидация не прошла, в объекте результата есть интернационализированное сообщение об ошибке, которое объясняет, что не так, и вы не можете вызвать метод do с этим параметром.
Методы «do» также возвращают объект результата, который содержит новое состояние задачи, если операция успешна, и ошибки, если что-то пойдет не так во время действия.
Получение экземпляра IssueService
Вы можете получить объект IssueService либо путем инъекции конструктора с помощью Atlassian Spring Scanner, либо явно через вызов getIssueService, например:
IssueService issueService = ComponentAccessor.getInstance().getIssueService();
Получение задачи
Задачи можно получить с помощью службы IssueService по ID или ключу:
IssueService.IssueResult issueResult = issueService.getIssue(applicationUser, 10000L);
MutableIssue mutableIssue = issueResult.getIssue();
//OR
IssueService.IssueResult issueResult = issueService.getIssue(null, "JRA-1234");
MutableIssue mutableIssue = issueResult.getIssue();
IssueInputParameters - построитель, который задает значения задачи
Чтобы выполнить операцию над задачей, вам нужно использовать экземпляр com.atlassian.jira.issue.IssueInputParameters в качестве строителя, который позволяет вам рассказать Jira, как вы хотите, чтобы задача выглядела.
Вот пример использования объекта-строителя:
IssueInputParameters issueInputParameters = issueService.newIssueInputParameters();
issueInputParameters.setProjectId(12345L)
.setIssueTypeId("2");
.setSummary("This is a summary");
.setReporterId("joeuser");
.setAssigneeId("otheruser");
.setDescription("I am a description");
.setEnvironment("I am an environment");
.setStatusId("2");
.setPriorityId("2");
.setResolutionId("2");
.setSecurityLevelId(10000L);
.setFixVersionIds(10000L, 10001L);
Иногда вам может потребоваться установить поле, отсутствующее на экранах создания или обновления, create и update. Для этого вам необходимо использовать следующий метод: issueInputParameters.setSkipScreenCheck (true);
Это используется при создании, обновлении и переходах, чтобы указать новые или обновленные значения.
Этот строитель может использоваться для добавления комментариев (с ограничениями или без ограничений) к задаче и для установки пользовательских значений полей. Подробные сведения см. в разделе javadoc о IssueInputParameters, упомянутом ранее.
IssueInputParameters - пользовательские поля
Значения настраиваемых полей могут быть добавлены с помощью методов com.atlassian.jira.issue.IssueInputParameters.addCustomFieldValue.
Здесь представлен некоторый контент, описывающий, как строки values (значения) должны быть отформатированы для разных типов полей.
IssueInputParameters issueInputParameters = issueService.newIssueInputParameters();
issueInputParameters
.addCustomFieldValue(myNumberField.getId(), "3")
.addCustomFieldValue(myDateField.getId(), "3/Jan/2012")
.addCustomFieldValue(myDateTime.getId(), "30/Jan/13 10:53 PM")
.addCustomFieldValue(mySelectList.getId(), "1234") // 1234 is option id as string
.addCustomFieldValue(myMultiSelectList.getId(), "1234, 5678") // 1234 and 5678 are option id's as strings
.addCustomFieldValue(myMultiSelectUserList.getId(), "uname1, uname2")
.addCustomFieldValue(myCascadingSelectList.getId(), )
.addCustomFieldValue(myCascadingSelectList.getId() + ":1", );
Создание новой задачи
После того, как вы настроите строитель задач так, как вам хотелось бы, вам нужно получить экземпляр службы задачи.
Чтобы проверить, что ваша задача может быть создана, как указано, вы должны вызвать метод validateCreate. Если есть какие-либо ошибки (например, недостаточные разрешения, отсутствующие обязательные поля, ссылки на значения, которые не существуют, и т. д.), в возвращаемом объекте результата будут отображаться сообщения i18n'ed.
Когда у вас есть действительный (валидный) CreateValidationResult, вы можете передать этот объект методу службы задачи create. Это создаст задачу и выполнит все связанные задачи (tasks)(публикация событий, индексирование задачи и т. д.). Результат создания будет иметь ошибки только в том случае, если с Jira существует серьезная проблема (например, не удается связаться с базой данных, рабочий процесс изменился с тех пор, как вы вызвали проверку и т. д.).
Для получения полной информации см. Javadoc.
Ниже приведен пример того, как вызвать службу для создания задачи, которую мы установили выше:
IssueService issueService = ComponentAccessor.getInstance().getIssueService();
CreateValidationResult createValidationResult = issueService.validateCreate(user, issueInputParameters);
if (createValidationResult.isValid())
{
IssueResult createResult = issueService.create(user, createValidationResult);
if (!createResult.isValid())
{
// Do something
}
}
Редактирование существующей задачи
Редактирование существующей задачи очень похоже на создание задачи. Вам нужно использовать тот же com.atlassian.jira.issue.IssueInputParameters, что и строитель, который позволяет вам рассказать Jira, что вы хотите изменить в задаче.
Вы должны вызвать метод validateUpdate с идентификатором задачи, который вы хотите обновить, и параметром IssueInputParameters, который содержит изменения, которые вы хотите применить. Это приведет к обновлению UpdateValidationResult, которое вы можете предоставить методу update.
Если есть какие-либо ошибки (например, недостаточные разрешения, отсутствующие обязательные поля, ссылки на значения, которые не существуют, и т. д.), в возвращаемом объекте результата будут отображаться сообщения i18n'ed.
Если у вас есть действующий (валидный) UpdateValidationResult, вы можете передать этот объект методу обновления службы задач. Это обновит задачу и выполнит все связанные задачи(tasks) (публикация событий, индексирование выпуска и т. д.). Результат обновления будет иметь ошибки только в том случае, если существует серьезная проблема с Jira (например, не удается связаться с базой данных, рабочий процесс изменился с тех пор, как вы вызвали валидацию и т. д.).
Для получения полной информации см. Javadoc.
Ниже приведен пример вызова службы для обновления резюме задачи с идентификатором 12345:
IssueInputParameters issueInputParameters = issueService.newIssueInputParameters();
issueInputParameters.setSummary("I am a new summary");
IssueService issueService = ComponentAccessor.getInstance().getIssueService();
UpdateValidationResult updateValidationResult = issueService.validateUpdate(user, 12345L, issueInputParameters);
if (updateValidationResult.isValid())
{
IssueResult updateResult = issueService.update(user, updateValidationResult);
if (!updateResult.isValid())
{
// Do something
}
}
Переход существующей задачи
Переход задачи очень похож на редактирование задачи. Вам нужно указать дополнительный параметр - идентификатор действия перехода, который идентифицирует переход, который должна сделать задача, вместе с объектом IssueInputParameters, определяющим любые значения, которые вы хотите установить при переходе. Вы должны вызвать метод validateTransition в службе задач для создания TransitionValidationResult.
Если есть какие-либо ошибки (например, недостаточные разрешения, отсутствующие обязательные поля, ссылки на значения, которые не существуют, и т. д.), тогда в возвращаемом объекте результата будут сообщения i18n'ed.
Когда у вас есть действительный (валидный) TransitionValidationResult, вы можете передать этот объект методу перехода службы задачи. Это переместит задачу и выполнит все связанные с ней задачи (tasks) (публикация событий, индексация заданий, функции почты рабочего процесса и т. д.). Результат перехода будет иметь ошибки только в том случае, если существует серьезная проблема с Jira (например,она не может связываться с базой данных, рабочий процесс изменился с момента вызова проверки и т. д.).
Для получения полной информации см. Javadoc.
Ниже приведен пример того, как вызвать службу для перехода задачи с идентификатором 12345 на идентификатор 10000, а также установить правопреемника:
IssueInputParameters issueInputParameters = issueService.newIssueInputParameters();
issueInputParameters.setAssigneeId("newdude");
IssueService issueService = ComponentAccessor.getInstance().getIssueService();
TransitionValidationResult transitionValidationResult = issueService.validateTransition(user, 12345L, 10000L, issueInputParameters);
if (transitionValidationResult.isValid())
{
IssueResult transitionResult = issueService.transition(user, transitionValidationResult);
if (!transitionResult.isValid())
{
// Do something
}
}
Удалить существующую задачу
Чтобы удалить задачу, вам необходимо предоставить службе задачи
идентификатор задачи, которую вы хотите удалить. Вы должны вызвать метод validateDelete, и он будет генерировать DeleteValidationResult. Это можно использовать для вызова метода delete.
Если есть какие-либо ошибки (например, недостаточные разрешения, проблема больше не существует и т. д.), тогда в возвращаемом объекте результата будут сообщения i18n'ed.
Когда у вас есть действительный (валидный) DeleteValidationResult, вы можете передать этот объект службы задачи delete method. Это удалит задачу и выполнит все связанные задачи (tasks)(удалите связанные вложения, комментарии, рабочие журналы и т. д.). Результат удаления будет иметь ошибки, только если есть серьезная проблема с Jira.
Для получения полной информации см. Javadoc.
Ниже приведен пример вызова службы для удаления проблемы с идентификатором 12345:
IssueService issueService = ComponentAccessor.getInstance().getIssueService();
DeleteValidationResult deleteValidationResult = issueService.validateDelete(user, 12345L);
if (deleteValidationResult.isValid())
{
ErrorCollection deleteErrors = issueService.delete(user, deleteValidationResult);
if (deleteResult.hasAnyErrors())
{
// Do something
}
}
Выполнение операций без валидации
Если по какой-то причине вы не хотите использовать класс IssueService, вы должны посмотреть на javadoc для класса IssueManager для создания, удаления и обновления, а также на WorkflowManager для перехода.
Тем не менее, мы настоятельно рекомендуем использовать класс IssueService для этих операций, так как существует много бизнес-логики, связанной с операциями задач.
Получение ссылок на задачи
Следующий пример повторяется по списку задач, и для каждой задачи возникают связанные задачи. Этот код может быть полезен, если вы создаете пользовательский отчет, который показывает связанные задачи.
Помните, что каждая ссылка имеет направление и тип. Поэтому задачи в Link Collection (сборке ссылок) сгруппированы по типу и направлению ссылки.
// A list of Issues representing issues
List issues = ...
for (Issue issue: issues ) {
// Retrieve a collection of all linked issues and their link types
LinkCollection linkCollection = issueLinkManager.getLinkCollection(issue, authenticationContext.getLoggedInUser());
Set linkTypes = linkCollection.getLinkTypes();
if (linkTypes != null) {
// For each link type
for (IssueLinkType linkType : linkTypes) {
// Get the outward linked issues
List outwardIssues = linkCollection.getOutwardIssues(linkType.getName());
if (outwardIssues != null) {
for (Issue outwardIssue : outwardIssues) {
System.out.println("outwardIssue = " + outwardIssue);
}
}
// And the inward linked issues
List inwardIssues = linkCollection.getInwardIssues(linkType.getName());
if (inwardIssues != null) {
for (Issue inwardIssue : inwardIssues) {
System.out.println("inwardIssue = " + inwardIssue);
}
}
}
}
}
Одним из способов получения списка задач является создание и запуск запроса(Search Request) на поиск.
Обратите внимание, что приведенный выше код использует JiraAuthenticationContext для извлечения пользователя приложения. Самый простой способ получить доступ к экземпляру JiraAuthenticationContext - объявить его как зависимость в конструкторе вашего класса.
@Named
public class ExampleClass {
@JiraImport
private JiraAuthenticationContext authenticationContext;
@Inject
public ExampleClass(JiraAuthenticationContext authenticationContext) {
this.authenticationContext = authenticationContext;
}
}
Следующие шаги
Также читайте о создании сервлета задач CRUD и поиске задач.
По материалам Atlassian JIRA Server Developer Performing issue operations