Настройка импорта проектов из Jira
Настройки синхронизации Commits и Merge requests
Включение данной интеграции позволяет автоматически отображать информацию о коммитах и запросах на слияние из GitLab в карточках задач проекта.
Для запуска синхронизаций commits и merge request необходимо:
Создать в GitLab Access token. В профиле GitLab перейти в User settings -> Access tokens
При создании токена обязательно необходимо указать Select scopes - read_api
Далее скопировать созданный токен:
Перейти в Рабочее пространство «Раздел администратора» → Модель → Секреты и указать его в Секрете gitlab-access-token
Перейти в Рабочее пространство «Раздел администратора» → Модель → Конечные точки настроить конечную точку gitlab-domain-url:
указать URL GitLab – например, https://gitlab.yourcompany.ru
выбрать в Данных для аутентификации Токен доступа Gitlab
Перейти в Рабочее пространство «Раздел администратора» → Интеграция → Camel DSL, запустить gitlab-merge-requests-sync и gitlab-commits-sync:
Примечание
Синхронизация будет происходить по всем проектам в GitLab, к которым созданный токен имеет доступ
Маппинг коммитов и MR к задачам происходит по ключу задачи Project tracker, указанному в комментарии к commit или названии MR в GitLab. То есть, если ключ задачи в Project Tracker равен PT-1, то в комментарии к commit или названии MR в GitLab должно быть указано PT-1
Подробнее о действиях, доступных с Camel DSL.
Настройка импорта задач из Jira
Введение
Данный раздел описывает настройку синхронизации проектов из Jira в Citeck. Функциональность реализована с использованием Apache Camel DSL и позволяет настраивать гибкие сценарии импорта данных.
Основные возможности
Импорт задач (issues) из проекта Jira в Citeck;
Импорт комментариев к задачам;
Импорт затраченного времени (work logs);
Импорт компонентов (components);
Импорт тегов (tags/labels);
Импорт релизов (releases);
Импорт спринтов;
Импорт вложений (attachments);
Настраиваемое маппирование типов задач, статусов и приоритетов;
Настраиваемое преобразование атрибутов;
Импорт связей между задачами.
Пример конфигурации
- route:
# Пример импорта задач из Jira
# Проект должен быть создан в Citeck
id: jira-crm-import
from:
uri: "jira-issues:crm-import"
# Проверьте доступ к jira пользователя, под которым запускается импорт
parameters:
delay: 5000
jiraHost: '{{ecos-endpoint:jira-host/url}}'
jiraUser: '{{ecos-endpoint:jira-host/credentials/username}}'
jiraToken: '{{ecos-endpoint:jira-host/credentials/password}}'
projectKey: "ECOSCRM"
steps:
#- to: log:raw-jira-issues?level=INFO&showBody=true
# Указание workspace и проекта обязательно
- set-property:
name: jiraImportedRecordIdPrefix
constant: "imported-jira"
- set-property:
name: _workspace
constant: "ECOSCRM"
- set-property:
name: link-project:project
constant: "emodel/ept-project@eadfe69d-676a-42a5-b21f-2db7d5fc18bf"
- set-property:
name: "valuesMapping"
constant: >
{
"_type": {
"10000": "emodel/type@ept-issue-epic",
"10001": "emodel/type@ept-issue-story",
"10002": "emodel/type@ept-issue-task",
"10003": "emodel/type@ept-issue-subtask",
"10004": "emodel/type@ept-issue-bug",
"10501": "emodel/type@ept-issue-task",
"10500": "emodel/type@ept-issue-story",
"10503": "emodel/type@ept-issue-bug"
},
"priority": {
"1": "100_urgent",
"2": "200_high",
"3": "300_medium",
"4": "400_low"
},
"_status": {
"1": "backlog",
"10010": "backlog",
"3": "in-progress",
"10000": "to-do",
"10561": "to-do",
"10011": "to-do",
"10510": "review",
"10101": "waiting-for-qa",
"10100": "in-qa-review",
"10537": "in-qa-review",
"10565": "in-qa-review",
"10001": "done",
"10541": "done",
"10530": "on-hold",
"10006": "on-hold",
"10531": "on-hold"
},
"resolution": {
"10000": "emodel/ept-issue-resolution@done",
"10001": "emodel/ept-issue-resolution@wont-do",
"10002": "emodel/ept-issue-resolution@duplicate",
"10003": "emodel/ept-issue-resolution@cannot-reproduce",
"10400": "emodel/ept-issue-resolution@cannot-reproduce"
}
}
- set-property:
name: "valuesConverter"
constant: >
{
"description": "jiraRenderedFieldToTextArea",
"_created": "jiraDateToInstant",
"_modified": "jiraDateToInstant",
"endDate": "jiraDateToInstant",
"reporter": "emailToPersonRef",
"implementer": "emailToPersonRef",
"epicLink": "issueKeyToRef",
"remainingEstimateMills": "secondsToMills"
}
- set-property:
name: "attributesMapping"
# Json path to EPT field
constant: >
{
"fields.issuetype.id": "_type",
"fields.priority.id": "priority",
"fields.summary": "summary",
"fields.description": "description",
"fields.resolution.id": "resolution",
"fields.labels": "tags",
"fields.resolutiondate": "endDate",
"fields.status.id": "_status",
"fields.reporter.emailAddress": "reporter",
"fields.assignee.emailAddress": "implementer",
"fields.timetracking.originalEstimate": "estimatedWorks",
"fields.timetracking.remainingEstimateSeconds": "remainingEstimateMills",
"fields.created": "_created",
"fields.updated": "_modified",
"fields.customfield_10002": "epicLink"
}
- set-property:
name: "staticAttributes"
constant: >
{
"__disableAudit": true
}
- set-property:
name: "linksMapping"
constant: >
{
"10000": "issue-links:blocker",
"10001": "issue-links:clone",
"10002": "issue-links:duplicate",
"10300": "issue-links:problem",
"10003": "issue-links:relates"
}
- split:
expression:
simple: "${body}"
steps:
- set-property:
name: "originalIssue"
simple: "${body}"
# Трансформация метаданных jira в поля ept
- to:
uri: "transform-jira-issue:crm-import"
parameters:
jiraHost: '{{ecos-endpoint:jira-host/url}}'
jiraUser: '{{ecos-endpoint:jira-host/credentials/username}}'
jiraToken: '{{ecos-endpoint:jira-host/credentials/password}}'
- to: log:transformed-issue?level=INFO&showBody=true
# Создание ept задачи через records
- to: "ecos-records-mutate:?sourceId=emodel/ept-issue"
#- to: log:created-record?level=INFO&showHeaders=true
- set-header:
name: eptIssueRef
simple: "${header.recordsMutated[0]}"
- step:
id: import-comments
steps:
- set-body:
simple: "${exchangeProperty.originalIssue}"
- set-header:
name: commentLinkToRecord
simple: "${header.eptIssueRef}"
- to: "transform-jira-comment:crm-import"
- to: "ecos-records-mutate:?sourceId=emodel/comment"
#- to: log:importcomments?level=INFO&showBody=true
- step:
id: import-components
steps:
- set-body:
simple: "${exchangeProperty.originalIssue}"
- set-header:
name: eptIssueRef
simple: "${header.eptIssueRef}"
- to: "import-jira-component:crm-import"
#- to: log:importcomponents?level=INFO&showBody=true
- step:
id: import-jira-tags
steps:
- set-body:
simple: "${exchangeProperty.originalIssue}"
- set-header:
name: eptIssueRef
simple: "${header.eptIssueRef}"
- to: "import-jira-tags:crm-import"
#- to: log:importtags?level=INFO&showBody=true
- step:
id: import-releases
steps:
- set-body:
simple: "${exchangeProperty.originalIssue}"
- set-header:
name: eptIssueRef
simple: "${header.eptIssueRef}"
- to:
uri: "import-jira-releases:crm-import"
parameters:
jiraHost: "{{ecos-endpoint:jira-host/url}}"
jiraUser: "{{ecos-endpoint:jira-host/credentials/username}}"
jiraToken: "{{ecos-endpoint:jira-host/credentials/password}}"
#- to: log:importreleases?level=INFO&showBody=true
- step:
# Если настроен плагин 2FA для Jira, то в нем нужно отключить принудительный
# 2FA для url /secure/attachment
id: import-attachments
steps:
- set-body:
simple: "${exchangeProperty.originalIssue}"
- set-header:
name: eptIssueRef
simple: "${header.eptIssueRef}"
- to:
uri: "import-jira-attachment:crm-import"
parameters:
jiraHost: "{{ecos-endpoint:jira-host/url}}"
jiraUser: "{{ecos-endpoint:jira-host/credentials/username}}"
jiraToken: "{{ecos-endpoint:jira-host/credentials/password}}"
#- to: log:importattachments?level=INFO&showBody=true
- step:
id: import-sprint
steps:
- set-body:
simple: "${exchangeProperty.originalIssue}"
- set-header:
name: eptIssueRef
simple: "${header.eptIssueRef}"
- to:
uri: "import-jira-sprint:crm-import"
parameters:
# Поле в jira, в котором хранится спринт
sprintFieldId: "customfield_10006"
#- to: log:importsprint?level=INFO&showBody=true
- step:
id: import-work-logs
steps:
- set-body:
simple: "${exchangeProperty.originalIssue}"
- set-header:
name: worklogLinkToRecord
simple: "${header.eptIssueRef}"
- to: "transform-jira-worklog:crm-import"
#- to: log:transformworklog?level=INFO&showBody=true
- to: "ecos-records-mutate:?sourceId=emodel/ecos-time-tracking-type"
#- to: log:importworklogs?level=INFO&showBody=true
Быстрая настройка
Создайте проект в Citeck. После этого должно создаться рабочее пространство проекта.
В jira создайте пользователя для импорта задач, получите его токен или пароль.
В журнале Конечные точки (Рабочее пространство «Раздел администратора» → Модель) создайте конечную точку, заполните URL, данные для аутентификации с типом Basic.
В журнале Camel DSL (Рабочее пространство «Раздел администратора» → Интеграция ) создайте маршрут с контекстом на основе примера выше. Обязательно укажите параметры подключения к Jira,
_workspaceиlink-project:project.Логи импорта доступны в журнале Журнал синхронизаций (Рабочее пространство «Раздел администратора» → Интеграция).
Посмотреть состояние импорта, сбросить его можно в журнале Состояние синхронизации (Рабочее пространство «Раздел администратора» → Интеграция).
После того, как задачи импортированы, выключите маршрут.
Скорректируйте генератор счетчика задач. Для этого необходимо выполнить скрипт в консоли браузера:
const record = Records.get("emodel/num-template-action@");
record.att("type", "set-next-number");
record.att("args",
{
"templateRef": "emodel/num-template@ept-issue-num-template",
"counterKey": "emodel/ept-project@767a669f-8455-4cf3-b43f-75b66c6eeb8f",
"nextNumber": 39
})
record.save();
"nextNumber": 39- следующий номер задачи, который будет присвоен при создании новой задачи."counterKey": "emodel/ept-project@767a669f-8455-4cf3-b43f-75b66c6eeb8f"- recordRef проекта, аналогичный полюlink-project:projectв маршруте импорта.
Параметры настройки
Основные параметры
jiraHost - URL сервера Jira
jiraUser - Имя пользователя для подключения к Jira
jiraToken - Токен или пароль пользователя для подключения к Jira
projectKey - Ключ проекта в Jira для импорта
delay - Интервал проверки новых задач в миллисекундах
Указание рабочего пространства и проекта
Для корректной работы импорта обязательно необходимо указать рабочее пространство и проект в Citeck:
- set-property:
name: _workspace
constant: "ECOSCRM" # id рабочего пространства
- set-property:
name: link-project:project
constant: "emodel/ept-project@eadfe69d-676a-42a5-b21f-2db7d5fc18bf" # recordRef проекта, должен быть связан с рабочим пространством
Настройка маппинга значений
valuesMapping позволяет указать соответствие значений из Jira значениям в Citeck:
{
"_type": {
"10000": "emodel/type@ept-issue-epic",
"10001": "emodel/type@ept-issue-story",
"10002": "emodel/type@ept-issue-task",
"10003": "emodel/type@ept-issue-subtask",
"10004": "emodel/type@ept-issue-bug"
},
"priority": {
"1": "100_urgent",
"2": "200_high",
"3": "300_medium",
"4": "400_low"
},
"_status": {
"1": "backlog",
"10010": "backlog",
"3": "in-progress"
}
}
Конвертеры значений
valuesConverter определяет преобразование значений полей из формата Jira в формат Citeck:
{
"description": "jiraRenderedFieldToTextArea",
"_created": "jiraDateToInstant",
"_modified": "jiraDateToInstant",
"endDate": "jiraDateToInstant",
"reporter": "emailToPersonRef",
"implementer": "emailToPersonRef",
"epicLink": "issueKeyToRef",
"remainingEstimateMills": "secondsToMills"
}
Доступные конвертеры:
jiraRenderedFieldToTextArea - преобразует отрендеренное HTML-содержимое поля Jira в формат TextArea для Citeck, сохраняя форматирование и ссылки
jiraDateToInstant - преобразует дату из формата Jira в формат Instant для Citeck
emailToPersonRef - преобразует email-адрес пользователя Jira в ссылку на пользователя в Citeck
issueKeyToRef - преобразует ключ задачи Jira (например, ECOSCRM-123) в ссылку на соответствующую задачу в Citeck
secondsToMills - преобразует время в секундах в миллисекунды для корректного отображения в Citeck
Маппинг атрибутов
attributesMapping определяет соответствие полей Jira атрибутам сущностей в Citeck:
{
"fields.issuetype.id": "_type",
"fields.priority.id": "priority",
"fields.summary": "summary",
"fields.description": "description",
"fields.resolution.id": "resolution",
"fields.labels": "tags",
"fields.resolutiondate": "endDate",
"fields.status.id": "_status",
"fields.reporter.emailAddress": "reporter",
"fields.assignee.emailAddress": "implementer",
"fields.timetracking.originalEstimate": "estimatedWorks",
"fields.timetracking.remainingEstimateSeconds": "remainingEstimateMills",
"fields.created": "_created",
"fields.updated": "_modified",
"fields.customfield_10002": "epicLink"
}
Маппинг связей между задачами
linksMapping определяет соответствие типов связей между задачами в Jira типам связей в Citeck:
{
"10000": "issue-links:blocker",
"10001": "issue-links:clone",
"10002": "issue-links:duplicate",
"10300": "issue-links:problem",
"10003": "issue-links:relates"
}
Статические атрибуты
staticAttributes позволяет указать атрибуты, которые будут добавлены ко всем импортируемым сущностям:
{
"__disableAudit": true
}
Для корректного установления атрибутов _created, _modified и т.д. необходимо указать __disableAudit: true
Компоненты и этапы синхронизации
Импорт задач (Issues)
Основной компонент синхронизации, выполняет загрузку задач из Jira и их преобразование в сущности Citeck. Для работы использует JiraIssuesComponent и TransformJiraIssueComponent.
Импорт комментариев
Компонент TransformJiraCommentComponent импортирует комментарии к задачам из Jira в Citeck, сохраняя их как связанные записи с типом "emodel/type@ecos-comment".
Импорт затраченного времени
Компонент TransformJiraWorkLogComponent импортирует записи о затраченном времени (work logs) из Jira в Citeck, сохраняя их как сущности с типом "emodel/type@ecos-time-tracking-type".
Импорт компонентов
Компонент ImportJiraComponentComponent импортирует компоненты, присвоенные задачам в Jira.
Импорт тегов
Компонент ImportJiraTagsComponent импортирует метки (labels) из Jira, преобразуя их в теги Citeck.
Импорт релизов
Компонент ImportJiraReleasesComponent импортирует информацию о релизах (fixVersions и affectedVersions) из Jira в Citeck.
Импорт спринтов
Компонент ImportJiraSprintComponent импортирует информацию о спринтах, к которым отнесены задачи в Jira.
Импорт вложений
Компонент ImportJiraAttachmentComponent загружает вложения задач из Jira и импортирует их в Citeck.
Дополнительные возможности
Префикс идентификаторов
Для уникальной идентификации импортированных записей можно задать префикс через свойство jiraImportedRecordIdPrefix:
- set-property:
name: jiraImportedRecordIdPrefix
constant: "imported-jira"
Все созданные записи в рамках импорта будут использовать данные префикс, обратите внимание, если импорт будет выполняться несколько раз, то существующие записи будут обновлены, а новые созданы.
Если необходимо запустить импорт заново, то можно сбросить состояние импорта в журнале Состояние синхронизации (Рабочее пространство «Раздел администратора» → Интеграция).
Ограничения и рекомендации
Перед настройкой импорта убедитесь, что пользователь Jira имеет необходимые права доступа к проекту.
При использовании двухфакторной аутентификации в Jira необходимо использовать API-токен вместо пароля.
Для импорта вложений может потребоваться отключение принудительной 2FA для URL
/secure/attachmentв настройках Jira.Рекомендуется начинать с небольшого набора задач для проверки корректности импорта.
При импорте большого количества задач рекомендуется увеличить значение параметра
delay.Убедитесь, что корректно указаны
_workspaceиlink-project:project.
Устранение неполадок
Проблема: Задачи не импортируются.
Решение: Проверьте правильность указания
jiraHost,jiraUser,jiraTokenиprojectKey.Проблема: Не импортируются вложения.
Решение: Проверьте настройки двухфакторной аутентификации в Jira для URL
/secure/attachment.Проблема: Неверное маппирование типов/статусов.
Решение: Проверьте значения ID в Jira и обновите соответствующую секцию
valuesMapping.Проблема: Ошибка «Value mapping for field does not contain value».
Решение: Добавьте отсутствующее значение в соответствующую секцию
valuesMapping.