Настройка рабочего процесса Workflows с интеграцией с Yandex Tracker, YandexGPT API и Yandex Cloud Postbox

В данном руководстве вы создадите рабочие процессы Yandex Workflows и настроите их интеграцию с Yandex Tracker, YandexGPT API и Yandex Cloud Postbox.

Созданные рабочие процессы будут получать информацию о задачах в указанной очереди Tracker, с помощью YandexGPT анализировать проделанную в этих задачах работу, статусы задач и выставленные оценки. Результаты анализа и краткий отчет о проделанной работе будут сохраняться в комментарии к одной из задач в Tracker, а также дублироваться письмом на заданный адрес электронной почты с помощью сервиса Yandex Cloud Postbox.

Чтобы настроить рабочий процесс Workflows:

1. Подготовьте облако к работе.
2. Создайте сервисный аккаунт.
3. Подготовьте Tracker.
4. Настройте доступ рабочего процесса в Tracker.
5. Создайте адрес и пройдите проверку прав владения доменом в Yandex Cloud Postbox.
6. Создайте рабочий процесс Workflows.
7. Протестируйте рабочий процесс.

Если созданные ресурсы вам больше не нужны, удалите их.

Перед началом работыПеред началом работы

1. Войдите в ваш аккаунт на Яндексе. Если у вас еще нет аккаунта, создайте его.

2. Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

   1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
   2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

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

   Подробнее об облаках и каталогах.

3. Установите утилиту cURL, она понадобится для отправки запроса на получение OAuth-токена приложения Яндекс ID.

Необходимые платные ресурсыНеобходимые платные ресурсы

В стоимость поддержки создаваемой инфраструктуры входят:

• плата за хранение секрета и запросы к нему (см. тарифы Yandex Lockbox);
• плата за использование YandexGPT API (см. тарифы Yandex Foundation Models);
• плата за использование Yandex Tracker (см. тарифы Tracker);
• плата за использование Yandex Cloud Postbox (см. тарифы Yandex Cloud Postbox).

Создайте сервисный аккаунтСоздайте сервисный аккаунт

Подготовьте очередь и задачи в TrackerПодготовьте очередь и задачи в Tracker

Чтобы рабочие процессы, которые вы создадите в настоящем руководстве, работали корректно, настройте очередь в Yandex Tracker.

Настройте доступ для аутентификации рабочего процесса в TrackerНастройте доступ для аутентификации рабочего процесса в Tracker

Чтобы аутентифицировать рабочий процесс в Yandex Tracker, получите токен OAuth-приложения, у которого есть права на чтение и запись в Tracker.

Создайте OAuth-приложение в Яндекс IDСоздайте OAuth-приложение в Яндекс ID

Чтобы создать OAuth-приложение с правами доступа на чтение и запись в Tracker:

1. Перейдите в браузере на страницу создания OAuth-приложения. На открывшейся странице:

   1. В поле Название вашего сервиса введите название создаваемого OAuth-приложения: My Tracker Workflow.

   2. В блоке Платформы приложения выберите опцию Веб-сервисы и в появившемся поле задайте Redirect URI: https://oauth.yandex.ru/verification_code.

   3. В блоке Доступ к данным в поле Название доступа введите tracker:read и выберите доступ Чтение из трекера.

      Доступ Чтение из трекера появится ниже в списке доступов приложения.

      Аналогичным образом добавьте доступ tracker:write (Запись в трекер).

   4. В блоке Почта для связи укажите ваш адрес электронной почты для отправки уведомлений по создаваемому приложению.

   5. Нажмите кнопку Создать приложение.

На открывшейся странице созданного приложения скопируйте значения полей ClientID и Client secret. Они понадобятся на следующем этапе для получения OAuth-токена.

Получите OAuth-токен приложенияПолучите OAuth-токен приложения

1. Получите код подтверждения. Для этого вставьте в адресную строку браузера следующий адрес, указав в query-параметре client_id скопированное на предыдущем шаге значение:

   https://oauth.yandex.ru/authorize?response_type=code&client_id=<значение_ClientID>
   

   Подтвердите, что предоставляете доступ вашему OAuth-приложению к Tracker.

   В открывшемся окне скопируйте и сохраните полученный код подтверждения. Он понадобится для получения OAuth-токена.

2. Получите OAuth-токен приложения. Для этого в терминале выполните команду:

   curl \
     --request POST \
     --header "Content-type: application/x-www-form-urlencoded" \
     --data "grant_type=authorization_code&code=<код_подтверждения>&client_id=<значение_ClientID>&client_secret=<значение_Client_secret>" \
     https://oauth.yandex.ru/token
   

   Где:

   • code — полученный на предыдущем шаге код подтверждения.
   • client_id — полученное ранее значение ClientID вашего OAuth-приложения.
   • client_secret — полученное ранее значение Client secret вашего OAuth-приложения.

   Результат:

   {"access_token": "y0__wgBhMmiugUY4b40IJCda4YSeAfV5tAoPqy2tttkQsy********", "expires_in": 31536000, "refresh_token": "1:7WGrfpErRSTlkTJI:NGU-BJxhvhUdwDxDuez5ana4Befm63bXXhNpJFnbWDX1XJ_rJ3qh6DH_AItBhFJk********:ZZP-Pf0nxo4nil********", "token_type": "bearer"}%
   

   Сохраните полученное значение поля access_token — это OAuth-токен приложения, необходимый для доступа рабочего процесса к Tracker.

Создайте секрет Yandex LockboxСоздайте секрет Yandex Lockbox

Создайте секрет Yandex Lockbox для хранения OAuth-токена и назначьте сервисному аккаунту права доступа к созданному секрету.

Создайте адрес и пройдите проверку прав владения доменом в Yandex Cloud PostboxСоздайте адрес и пройдите проверку прав владения доменом в Yandex Cloud Postbox

Чтобы рабочий процесс мог отправлять письма, создайте адрес Yandex Cloud Postbox и подтвердите владение доменом, с которого будут отправляться письма.

Создайте адрес Yandex Cloud PostboxСоздайте адрес Yandex Cloud Postbox

1. Сгенерируйте ключ для создания DKIM-подписи. Для этого в терминале выполните команду:

   openssl genrsa -out privatekey.pem 2048
   

   Созданный ключ будет сохранен в файле privatekey.pem в текущей директории.

2. Создайте адрес:

   Консоль управления

   1. В консоли управления выберите каталог, в котором вы ранее создали сервисный аккаунт и секрет.

   2. В списке сервисов выберите Cloud Postbox.

   3. Нажмите кнопку Создать адрес.

   4. В поле Домен укажите домен, с которого будете отправлять письма. Например: example.com.

      Домен может быть любого уровня. У вас должны быть права на добавление ресурсных записей в публичную зону DNS указанного домена — это необходимо для подтверждения ваших прав на его использование.

   5. В поле Селектор укажите селектор. Например: tracker_workflow.

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

   6. В поле Приватный ключ скопируйте содержимое созданного ранее файла приватного ключа privatekey.pem.

   7. Нажмите кнопку Создать адрес.

   8. В появившемся списке адресов выберите созданный адрес и на открывшейся странице в блоке Подтверждение подписи скопируйте и сохраните значения полей Имя и Значение — они понадобятся для создания ресурсной записи TXT.

Пройдите проверку прав владения доменомПройдите проверку прав владения доменом

1. В публичной зоне DNS вашего домена создайте ресурсную запись TXT со следующими значениями:

   • Имя записи: скопированное на предыдущем шаге значение поля Имя.

     В Yandex Cloud DNS укажите часть имени, сгенерированного при создании адреса, без указания домена, в формате <селектор>._domainkey, например tracker_workflow._domainkey.

     Для других DNS-сервисов может потребоваться скопировать запись целиком. Итоговая запись должна иметь вид <селектор>._domainkey.<домен>., например tracker_workflow._domainkey.example.com..

   • Тип записи: TXT.

   • Значение записи: скопированное на предыдущем шаге значение поля Значение.

     Обратите внимание, что значение записи нужно взять в кавычки, например:

     "v=DKIM1;h=sha256;k=rsa;p=M1B...aCA8"
     

   Примечание

   Если ваш домен делегирован Yandex Cloud DNS, для создания ресурсной записи воспользуйтесь инструкцией. В остальных случаях воспользуйтесь личным кабинетом вашего регистратора доменных имен, при возникновении вопросов обратитесь к документации или в службу поддержки регистратора.

2. Выполните проверку прав на домен.

   Консоль управления

   1. В консоли управления выберите каталог, в котором находится созданный адрес.

   2. В списке сервисов выберите Cloud Postbox и выберите нужный адрес.

   3. Нажмите кнопку Проверить адрес. Если TXT-запись создана корректно, статус проверки на странице адреса изменится на Success.

      Ответы DNS-сервера кешируются, поэтому возможны задержки при обновлении ресурсной записи.

Создайте рабочий процесс WorkflowsСоздайте рабочий процесс Workflows

1. Выберите спецификацию, которую вы будете использовать для создания рабочего процесса. Обе приведенные спецификации используют интеграции с Yandex Tracker, YandexGPT API и Yandex Cloud Postbox, но по-разному анализируют исходные данные.

   Вариант 1

   Вариант 2

   Предлагаемый рабочий процесс анализирует задачи Tracker в указанной очереди, формирует и публикует отчет о прогрессе работы в этих задачах:

   1. Анализ задач с нужным тегом в заданной очереди Tracker:
      • общее количество задач;
      • общая суммарная оценка задач в единицах Story Point;
      • количество закрытых задач;
      • процентное соотношение количества закрытых задач к общему количеству задач;
      • суммарная оценка закрытых задач в единицах Story Point;
      • процентное соотношение суммарной оценки закрытых задач к общей суммарной оценке всех задач в единицах Story Point.
   2. Формирование отчета с результатами анализа.
   3. Публикация отчета в комментарии к заданной задаче Tracker, а также отправка отчета на заданный адрес электронной почты.

   Код спецификации:

   yawl: "0.1"
   start: fetch_tickets
   steps:
     fetch_tickets:
       tracker:
         organization:
           cloudOrganizationId: <идентификатор_организации>
         oauthToken: '\(lockboxPayload("<идентификатор_секрета>"; "oauth"))'
         listIssues:
           filter:
             issueProperties:
               queue: <ключ_очереди_в_Tracker>
               tags: "product"
         output: |-
           \({
             "sp_sum": [.[].storyPoints] | add,
             "closed_sp_sum": . | map(select(.status.key == "closed")) | map(.storyPoints) | add,
             "ticket_count": . | length,
             "closed_ticket_count": . | map(select(.status.key == "closed")) | length,
             "non_closed_ticket_texts": . | map(select(.status.key != "closed")) | map({
               "key": .key,
               "summary": .summary,
               "description": .description            
             })
           })
         next: summarize_texts
     summarize_texts:
       foundationModelsCall:
         next: create_report
         modelUrl: gpt://<идентификатор_каталога>/yandexgpt
         generate:
           maxTokens: 500
           temperature: 0.5
           messages:
             messages:
               - role: system
                 text: "Далее будут даны названия незавершенных задач в Tracker и их описание. Сформулируй как можно короче (не больше трех предложений), что осталось сделать"
               - role: user
                 text: |-
                   \("
                     \(.non_closed_ticket_texts | map(.summary + ": " + .description) | join(". "))
                   ")
         output: |-
           \({
             "summary": .alternatives.[0].message.text
           })
     create_report:
       noOp:
         output: |-
           \({
           "report_text": "**Количество работы всего:** \(.ticket_count) задач(а), \(.sp_sum) sp
           **Работы завершено:** \(.closed_ticket_count) (\(100 * .closed_ticket_count / .ticket_count | round)%) задач(а), \(.closed_sp_sum) (\(100 * .closed_sp_sum / .sp_sum | round)%) sp
   
           **Незавершенные задачи:**
             \(.non_closed_ticket_texts | map(.key) | join("\n"))
   
           **Сводка по тому, что осталось:**
             \(.summary)
           ",
           "report_text_html": "<b>Количество работы всего:</b> \(.ticket_count) задач(а), \(.sp_sum) sp<br>
           <b>Работы завершено:</b> \(.closed_ticket_count) (\(100 * .closed_ticket_count / .ticket_count | round)%) задач(а), \(.closed_sp_sum) (\(100 * .closed_sp_sum / .sp_sum | round)%) sp<br>
           <br>
           <b>Незавершенные задачи:</b><br>
             \(.non_closed_ticket_texts | map("<a href=https://tracker.yandex.ru/" + .key + ">" + .key + "</a>") | join("<br>"))<br>
           <br>
           <b>Сводка по тому, что осталось:</b><br>
             \(.summary | gsub("\\n"; "<br>"))
           "})
         next: deliver_report
     deliver_report:
       parallel:
         branches:
           tracker:
             start: write_report_to_tracker
             steps:
               write_report_to_tracker:
                 tracker:
                   organization:
                     cloudOrganizationId: <идентификатор_организации>
                   oauthToken: '\(lockboxPayload("<идентификатор_секрета>"; "oauth"))'
                   createComment:
                     key: <ключ_задачи_с_отчетом>
                     text: \(.report_text)
           postbox:
             start: send_report_via_postbox
             steps:
               send_report_via_postbox:
                 postbox:
                   simple:
                     subject:
                       data: "Dev progress report"
                       charset: UTF_8
                     body:
                       text:
                         data: \(.report_text)
                         charset: UTF_8
                       html:
                         data: \("<p>\(.report_text_html)</p>")
                         charset: UTF_8
                   fromAddress: tracker-robot@<ваш_домен>
                   destination:
                     toAddresses: <адрес_получателя>
   

   Где:

   • <идентификатор_организации> — идентификатор вашей организации Yandex Cloud Organization.
   • <идентификатор_секрета> — сохраненный ранее идентификатор секрета с OAuth-токеном приложения.
   • <ключ_очереди_в_Tracker> — ключ очереди Tracker, в которой вы создали тестовые задачи.
   • <идентификатор_каталога> — идентификатор каталога, в котором вы создаете рабочий процесс.
   • <ключ_задачи_с_отчетом> — ключ задачи Tracker, в комментарий к которой будет выгружена сводка по проанализированным тестовым задачам.
   • <ваш_домен> — домен, который вы указали при создании адреса Yandex Cloud Postbox. В качестве адреса отправителя fromAddress вы можете указать любой адрес на этом домене. Например: tracker-robot@example.com или noreply@example.com.
   • <адрес_получателя> — адрес электронной почты, на который рабочий процесс отправит письмо со сводкой по проанализированным тестовым задачам Tracker.

   Рабочий процесс включает в себя следующие шаги: fetch_tickets, summarize_texts, send_report_via_postbox и write_report_to_tracker.

   Предлагаемый рабочий процесс анализирует закрытые задачи Tracker за последнюю неделю, формирует и публикует отчет о проделанной в этих задачах работе:

   1. Анализ задач, закрытых за последнюю неделю:
      • выгрузка комментариев к задачам;
      • анализ и обобщение комментариев к каждой закрытой задаче.
   2. Формирование отчета с обобщением выполненной работы в каждой закрытой задаче.
   3. Публикация отчета в комментарии к заданной задаче Tracker, а также отправка отчета на заданный адрес электронной почты.

   Код спецификации:

   yawl: "0.1"
   start: fetch_tickets
   steps:
     fetch_tickets:
       tracker:
         organization:
           cloudOrganizationId: <идентификатор_организации>
         oauthToken: '\(lockboxPayload("<идентификатор_секрета>"; "oauth"))'
         listIssues:
           query: 'Status: changed(to: Closed date: >now()-2w)'
         output: |-
           \({
             "closed_tickets": . | map({"ticket_key": .key})
           })
         next: fetch_comments_fe
     fetch_comments_fe:
       foreach:
         input: \(.closed_tickets)
         do:
           start: fetch_comments
           steps:
             fetch_comments:
               tracker:
                 organization:
                   cloudOrganizationId: <идентификатор_организации>
                 oauthToken: '\(lockboxPayload("<идентификатор_секрета>"; "oauth"))'
                 listComments:
                   key: \(.ticket_key)
                 output: |-
                   \({
                     "comments": .
                   })
         output: |-
           \({
             "comment_text": map(.comments[].text) | join("\n")
           })
         next: summarize_texts
     summarize_texts:
       foundationModelsCall:
         modelUrl: gpt://<идентификатор_каталога>/yandexgpt
         generate:
           maxTokens: 500
           temperature: 0.5
           messages:
             messages:
               - role: system
                 text: "Далее будут даны комментарии завершенных задач в Tracker. Сформулируй как можно короче (не больше трех предложений), какая работа была проделана."
               - role: user
                 text: \(.comment_text)
         output: |-
           \({
             "summary": .alternatives.[0].message.text
           })
         next: create_report
     create_report:
       noOp:
         output: |-
           \({
             "report_text": "
               Завершенные задачи:
                 \(.closed_tickets | map(.ticket_key) | join("\n"))
               Сводка по закрытым задачам:
                 \(.summary)
             ",
             "report_text_html": "
               Завершенные задачи:<br>
                 \(.closed_tickets | map("<a href=https://tracker.yandex.ru/" + .ticket_key + ">" + .ticket_key + "</a>") | join("<br>"))<br>
   
               <br>
               Сводка по закрытым задачам:<br>
                 \(.summary | gsub("\\n"; "<br>")))
             "
           })
         next: deliver_report
     deliver_report:
       parallel:
         branches:
           tracker:
             start: write_report_to_tracker
             steps:
               write_report_to_tracker:
                 tracker:
                   organization:
                     cloudOrganizationId: <идентификатор_организации>
                   oauthToken: '\(lockboxPayload("<идентификатор_секрета>"; "oauth"))'
                   createComment:
                     key: <ключ_задачи_с_отчетом>
                     text: \(.report_text)
           postbox:
             start: send_report_via_postbox
             steps:
               send_report_via_postbox:
                 postbox:
                   simple:
                     subject:
                       data: "Dev progress report (closed issues)"
                       charset: UTF_8
                     body:
                       text:
                         data: \(.report_text)
                         charset: UTF_8
                       html:
                         data: \("<p>\(.report_text_html)</p>")
                         charset: UTF_8
                   fromAddress: tracker-robot@<ваш_домен>
                   destination:
                     toAddresses: <адрес_получателя>
   

   Где:

   • <идентификатор_организации> — идентификатор вашей организации Yandex Cloud Organization.
   • <идентификатор_секрета> — сохраненный ранее идентификатор секрета с OAuth-токеном приложения.
   • <идентификатор_каталога> — идентификатор каталога, в котором вы создаете рабочий процесс.
   • <ключ_задачи_с_отчетом> — ключ задачи Tracker, в комментарий к которой будет выгружена сводка по проанализированным тестовым задачам.
   • <ваш_домен> — домен, который вы указали при создании адреса Yandex Cloud Postbox. В качестве адреса отправителя fromAddress вы можете указать любой адрес на этом домене. Например: tracker-robot@example.com или noreply@example.com.
   • <адрес_получателя> — адрес электронной почты, на который рабочий процесс направит письмо со сводкой по проанализированным тестовым задачам Tracker.

   Рабочий процесс включает в себя следующие шаги: fetch_tickets, fetch_comments, summarize_texts, send_report_via_postbox и write_report_to_tracker.

2. Создайте рабочий процесс Workflows с использованием выбранной спецификации:

   Консоль управления

   1. В консоли управления выберите каталог, в котором находятся созданные ранее ресурсы — сервисный аккаунт, секрет и адрес Yandex Cloud Postbox.

   2. В списке сервисов выберите Serverless Integrations.

   3. На панели слева выберите Workflows.

   4. В правом верхнем углу нажмите кнопку Создать рабочий процесс и в открывшемся окне:

      1. В поле YaML-спецификация добавьте выбранную ранее спецификацию.
      2. Разверните блок Дополнительные параметры.
      3. В поле Имя введите имя рабочего процесса: my-tracker-workflow.
      4. В поле Сервисный аккаунт выберите созданный ранее сервисный аккаунт workflow-sa.

   5. Нажмите кнопку Создать.

Протестируйте рабочий процессПротестируйте рабочий процесс

Убедитесь, что процесс Workflows выполняется.

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

Как удалить созданные ресурсыКак удалить созданные ресурсы

Чтобы перестать платить за созданные ресурсы:

1. Удалите рабочий процесс:

   Консоль управления

   1. В консоли управления выберите каталог, в котором находятся созданные ресурсы.
   2. В списке сервисов выберите Serverless Integrations.
   3. На панели слева выберите Workflows.
   4. В строке с рабочим процессом my-tracker-workflow нажмите и выберите Удалить.
   5. Подтвердите удаление.

2. Удалите секрет.

3. Удалите задачи и очередь Tracker.

4. При необходимости удалите адрес Yandex Cloud Postbox:

   Консоль управления

   1. В консоли управления выберите каталог, в котором находится созданный адрес Yandex Cloud Postbox.
   2. В списке сервисов выберите Cloud Postbox.
   3. В строке с нужным адресом Yandex Cloud Postbox нажмите и выберите Удалить.
   4. Подтвердите удаление.