Инструкция по настройке интеграций с 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 закончена.

Дополнительные параметры настройки

После основной настройки связки вы можете настроить дополнительные действия или инструменты. Для этого нажмите в «+» и выберите необходимый шаг, который необходимо совершить системе.

Вы также можете настроить фильтр входящих данных. О том, как он работает, можно подробно прочитать здесь.