Инструкция по настройке интеграций с YouTrack
Сервис YouTrack является одним из самых популярных таск-менеджеров, который используется самыми разными компаниями вне зависимости от их численности и сферы деятельности.
В Albato доступны интеграции с сервисом, когда мы можете передавать в YouTrack данные из любых систем. Пока для сервиса доступно действие
- Новая задача
Кроме этого, доступны два триггера (действия), актуальные, когда сервис является источником данных.
- Задача создана
- Задача обновлена
Чтобы использовать таск-менеджер YouTrack в своих интеграциях, в первую очередь, следует сначала выполнить подключение сервиса к Albato.
Подключение YouTrack к Albato
Зайдите в верхнем меню интерфейса Albato в раздел “Подключения” и нажмите кнопку “Добавить подключение”.
Выберите из списка сервисов категорию “Другое” или воспользуйтесь поисковой строкой, чтобы быстрее найти YouTrack и нажмите “Добавить подключение”.
На следующем экране настройки полей нужно заполнить, используя данные из самого сервиса YouTrack.
Задайте уникальное название для сервиса и перейдите в настройки YouTrack. Настройки подключения Albato закрывать не нужно.
Скопируйте ID либо из адресной строки браузера, либо укажите название рабочей области, которое вы использовали при создании аккаунта. Перейдите в список пользователей системы, выберите пользователя, от которого будет идти доступ к интеграции и откройте у него вкладку “Аутентификация”:
Далее создаем новый токен и копируем его значения:
Переносим значение в Albato и завершаем настройку подключения:
Первая часть подключения готова. Для того, чтобы получать тикеты из YouTrack, нужно ещё создать два Workflow в YouTrack, прописать туда наши JS-коды и вставить в них вебхук из подключения.
Перейдите во вкладку Workflows:
Создайте новый Workflow:
Задайте ему название и выберите правило “При изменении” (on-change):
Вставьте полностью туда следующий код:
const albatoHook = '{{albatoHook}}';
const entities = require('@jetbrains/youtrack-scripting-api/entities');
const http = require('@jetbrains/youtrack-scripting-api/http');
const workflow = require('@jetbrains/youtrack-scripting-api/workflow');
function periodToHours(period) {
return period ? (
period.getMinutes() / 60 +
(
period.getHours() +
period.getDays() * 8 +
period.getWeeks() * 40
)
) : 0;
}
function formatValue(value) {
if (typeof value === 'object' && value !== null) {
switch (value.$$type) {
case 'User':
value = value.fullName;
break;
default:
if ('getPeriodType' in value) {
value = periodToHours(value);
} else if (value.constructor.name === 'ImmutableIterableWW') {
const array = value;
value = [];
array.forEach(item => value.push(item.name));
} else {
value = value.name;
}
}
}
return value === undefined ? null : value;
}
exports.rule = entities.Issue.onChange({
title: workflow.i18n('Send webhook to Albato'),
guard: function(ctx) {
return ctx.issue.becomesReported && ctx.issue.isReported;
},
action: function(ctx) {
const issue = ctx.issue;
const fields = {};
for (let field in issue.fields) {
fields[field] = formatValue(issue.fields[field]);
}
const tags = [];
issue.tags.forEach(nameTag => tags.push(nameTag.name));
const payload = {
'event': 'newTicket',
'ticketUrl': issue.url,
'tags': tags,
'id': issue.id,
'summary': issue.summary,
'description': issue.description,
'projectId': issue.project.key,
'project': issue.project.name,
'dateCreate': issue.created,
'dateUpdate': issue.updated,
'fields': fields,
};
console.log(issue.tags);
const connection = new http.Connection(albatoHook, null, 2000);
connection.addHeader('content-type', 'application/json');
const response = connection.postSync('', null, payload);
if (!response.isSuccess) {
console.warn('Failed to post webhook to Albato. Details: ' + response.toString());
}
},
});
Данный код ловит только создание задач, а следующий код, рассчитан на изменение задач. Вы можете работать в одном правиле или создать еще одно дополнительное и также вставить в него следующий код:
const albatoHook = '{{albatoHook}}';
const entities = require('@jetbrains/youtrack-scripting-api/entities');
const http = require('@jetbrains/youtrack-scripting-api/http');
const workflow = require('@jetbrains/youtrack-scripting-api/workflow');
function periodToHours(period) {
return period ? (
period.getMinutes() / 60 +
(
period.getHours() +
period.getDays() * 8 +
period.getWeeks() * 40
)
) : 0;
}
function formatValue(value) {
if (typeof value === 'object' && value !== null) {
switch (value.$$type) {
case 'User':
value = value.fullName;
break;
default:
if ('getPeriodType' in value) {
value = periodToHours(value);
} else if (value.constructor.name === 'ImmutableIterableWW') {
const array = value;
value = [];
array.forEach(item => value.push(item.name));
} else {
value = value.name;
}
}
}
return value === undefined ? null : value;
}
exports.rule = entities.Issue.onChange({
title: workflow.i18n('Send webhook to Albato'),
guard: function(ctx) {
return !ctx.issue.becomesReported && ctx.issue.isReported;
},
action: function(ctx) {
const issue = ctx.issue;
const fields = {};
for (let field in issue.fields) {
fields[field] = formatValue(issue.fields[field]);
}
const tags = [];
issue.tags.forEach(nameTag => tags.push(nameTag.name));
const payload = {
'event': 'changedTicket',
'ticketUrl': issue.url,
'tags': tags,
'id': issue.id,
'summary': issue.summary,
'description': issue.description,
'projectId': issue.project.key,
'project': issue.project.name,
'dateCreate': issue.created,
'dateUpdate': issue.updated,
'fields': fields,
};
console.log(issue.tags);
const connection = new http.Connection(albatoHook, null, 2000);
connection.addHeader('content-type', 'application/json');
const response = connection.postSync('', null, payload);
if (!response.isSuccess) {
console.warn('Failed to post webhook to Albato. Details: ' + response.toString());
}
},
});
Важный момент!
Теперь вам нужно в каждом правиле, куда вы вставили код, заменить в самой первой константе
«const albatoHook = ‘{{albatoHook}}’;», значение {{albatoHook}}, на реальный вебхук из созданного ранее подключения. Скопируйте вебхук, из вашего созданного подключения в Albato.
Вставьте вебхук в каждый созданный вами процесс:
Далее вам нужно привязать ваш Workflow к нужному вам проекту. Для этого вернитесь в список ваших Workflow, выделите созданный вами Workflow и привяжите его к нужным проектам:
Готово! Теперь вы можете использовать сервис в своих интеграциях.
Настройка связок с YouTrack
В Albato есть возможность передавать данные в YouTrack, чтобы сервис выполнял действие по постановке задач.
На первом этапе создания связки выберите сервис, из которого хотите получать данные, а на этапе выбора сервиса, куда передавать данные выберите YouTrack:
Выберите свое подключение сервиса. Далее откроется еще один блок, в котором нужно будет выбрать проект, куда будут вноситься новые задачи.
На следующим этапе вам для заполнения будут доступны несколько полей. Название, приоритет, тип и состояние являются обязательными из списка.
Для примера заполним таблицу значениями из Битрикс24:
- В поле “Название” мы установим название (заголовок) задачи из Битрикс24.
- В поле “Комментарий” мы можем поставить значение “Комментарий”, чтобы снабдить данными новую задачу в YouTrack.
- Значение приоритета можно выбрать из справочника. Для примера мы будем использовать нормальный уровень приоритетности задачи (96-2).
- В поле Type установим значение Task (96-9), тем самым укажем, что это обычная задача.
- В поле State укажем значение Open (98-1), то есть задача только появилась и она открыта.
- Subsystem заполняется значением, в котором будет передаваться размещение задачи.
- Поле Estimation нужно для оценки времени, которое уйдет на выполнение определенной задачи.
Пример заполненных полей:
Настройка исходящих данных
Теперь рассмотрим, как мы будем ловить поля для проекта. Создайте в Albato связку, выберите получать данные из YouTrack и нужное вам событие:
Если вы выбрали обновление, то на следующем шаге вы можете поставить галочку на «Загружать каждую задачу лишь единожды», если галочка стоит, то каждый тикет будет в одну связку попадать лишь один раз без повторного попадания.
На шаге «Ловец хуков», вам необходимо нажать кнопку «Ожидать вебхук», затем инициировать то событие, которое было выбрано (создание или изменение тикета) в YouTrack. После, вы получите все поля вашего проекта:
Дальше вы выбираете, куда отправлять данные, например, в Telegram.
Далее вы формируете текст вместе с кастомными полями, которые могут прийти из YouTrack.
Готово! Связка создана.
В каждой связке ловец хуков запоминает поля строго на одну свою связку. Вы можете создать несколько связок на каждый проект (если во всех проектах разный набор полей) и отфильтровать связку по проекту. Для этого откройте фильтр входящих данных у триггера:
Добавьте условие и выберите ID проекта, выберите условие «равно», а в правом поле, пропишите айди вашего проекта в YouTrack:
После этого нажмите сохранить. Такая связка будет работать только с одним проектом, а вы сможете разделить данные по проектам при помощи разных связок, создавая разные сценарии. Кроме этого, в фильтре можно задать статус задачи, что в комбинации с галочкой «Загружать каждую задачу лишь единожды», будет всегда запускаться определённый сценарий один раз, при попадании задачи в определённом статусе.
На этом настройка связки с YouTrack закончена.
Дополнительные параметры настройки
После основной настройки связки вы можете настроить дополнительные действия или инструменты. Для этого нажмите в “+” и выберите необходимый шаг, который необходимо совершить системе.
Вы также можете настроить фильтр входящих данных. О том, как он работает, можно подробно прочитать здесь.
