Та я вирішив додати свої п’ять копійок у цей нескінченний некролог і пропоную подивитися у майбутнє.

Код як нова грамотність

Давайте відразу: винесемо за дужки прогнози про те, що скоро код писатиме лише нейромережа, а ми будемо просто вирощувати органічну моркву. Будемо вважати, що програмування — це все ще актуальна навичка, принаймні для того, щоб виступати диригентом для зграї ШІ-агентів. Тож завдання на зараз — навчити цієї грамотності. Яка це буде мова програмування? Один з багатьох варіантів — звісно, PHP.

Які ще мови програмування можна розглянути для базової навички програмування? Python, так, але будь ласка, ніякого JavaScript.

PHP no.1

Це новий маніфест. Я навіть пропоную зробити це офіційним логотипом майбутніх змін.

— Ей, ми ж програмісти, відлік починається з нуля!
— Згоден. Тому титул «no.0» ми з повагою залишимо для «C».

А зміни будуть потрібні, саме тому що я не хотів би навчати дітей та студентів чомусь, що виглядає як пошук голки в стозі сіна. Але про це трохи згодом.

Програмування для всіх

Головна моя теза — для розвитку будь-якої мови програмування потрібні нові та молоді розробники. Тож далі я буду намагатися розвити думку з приводу того, як можна привабити нових людей до програмування, та до програмування на PHP у нашому випадку.

Перше — треба рухатись у напрямку продавати програмування як базовий скіл будь-якого інженера, а можливо, не лише інженера. Це прям повинно стати метою всього цього руху з навчанням.

Друге — треба звернути увагу на програмування для шкіл, причому комплексно, щоб це не було якесь програмування на рівні циклів та роботи з консоллю. Потрібно навчати з прикладної точки зору, тож розвивати прикладне програмування — це повинно зацікавити дітей. Треба йти не від «ось PHP, на ньому будемо робити ось це», а «хочете зробити сайт — давайте візьмемо найпопулярнішу мову програмування для сайтів». Ось там і HTML, і CSS, і база JavaScript зайде, і робота з базами даних — і так, вже в школі.

Чому я так вважаю, що треба змінити підхід і йти від зацікавленості? В мене був негативний досвід співпраці з ВНЗ Харкова, коли ми намагалися розробити програму навчання з PHP, яка включала б і лекції, і практики. Але ми отримали конфлікт з викладачами ВНЗ та витратили свій час даремно, бо «неможна розповідати про HTTP — це програма курсу мережевих протоколів», «ми не розповідаємо про бази даних, то буде окремий курс», «звісно, ми HTML та CSS вже пройшли, але ви не можете…», і так далі.

Що треба, щоб стати мовою програмування «no.1» у школах?

Контент повинен бути доступним для школярів:

• Готові програми навчання, коли викладач може сам легко все зрозуміти та відтворити, бо впровадження — це основна з перепон нових методів навчання.
• Готові рішення, які можна скачати чи придбати. Це може бути, наприклад, міні-сервер на Raspberry Pi з розгорнутим LAMP та доступом, щоб можна було програмувати прямо в браузері чи легко деплоїти на сервер (SFTP-конект прямо з IDE).
• Цікаво також надати можливість використовувати PHP на Arduino.
• Якісь забавки для розумного будинку.
• Якісь готові агенти, які можуть зацікавити дітей.
• Може, навіть буде потрібен TikTok-канал (знов-таки, в першу чергу це про програмування, в другу — що приклади будуть на PHP).
• Уроки на GitHub, щоб школярі могли свій профайл прокачувати теж (але тут питання, чи можуть вони мати свій профіль за правилами GitHub).
• IDE для школярів на основі PHPStorm, але прибрати все зайве (можливо за прихованими пунктами меню), спростити максимально, може відразу вбудувати доступ до GitHub-уроків. Вбудувати AI з препромптами, що пояснювати треба школярам.
• Переробити нарешті той мануал, щоб він був написаний для людей, щоб батьки дитини, коли сіли розбиратися, могли прочитати та все пояснити дитині.
• Мануал повинен мати інтерактивні приклади.
• Додати в мануал шлях вивчення мови.

І вже після шкіл можна переходити до ВНЗів.

Згадав кейс з LeetCode, коли одне з завдань я зробив на PHP та опинився в топ-1 зі своїм рішенням. Та це не про мене і моє рішення, а про те, що ніхто не розв’язує задачі на PHP на LeetCode :(

PHP X

Я вже казав, щоб заходити до шкіл та ВНЗів — PHP потрібні зміни.
Скоріш за все, вже є затверджені плани на зміни у PHP 9, але я дивлюся трохи далі.
Цей пункт складний, але він обов’язково потрібен для успішної реалізації попереднього розділу, тож, можливо, його треба робити навіть раніше.
PHP X — це повинна бути мова, в якій не буде місця $needle та $haystack, asort, strstr, str_replace і так далі. Я маю на увазі — мова повинна бути консистентна, оці всі хвороби неймінгу функцій, класів та методів — їх треба буде залишити в минулому. Не треба дітей навчати цим «особливостям» мови. Цей смітник треба буде розгрібти, і якщо комусь для сумісності потрібна буде нова версія PHP — то хай ставить собі екстеншен для цього, за замовчуванням цього не треба.

Насправді буде багато холіварів. Наприклад, є речі, які я б сам змінив:

• Конкатенація строк — використовувати «+» було б логічно.
• Синтаксис масиву як [ "a" : 42 ].
• Є й інші питання синтаксису.

Тож тут головне — створити PHP X саме мовою no.1 для навчання, яка реально буде допомагати, навіть якщо потім будеш переходити на іншу мову програмування.

Можливо, PHP 9 та PHP X будуть співіснувати одночасно та розвиватися разом як дві паралельні гілки.

Чесно про конкурентів

Перш ніж говорити про стратегію, варто визнати очевидне: Python уже виграв гонку за місце в освіті. І виграв не через технічну перевагу, а через екосистему навчання — Jupyter Notebooks, Google Colab, інтерактивність «з коробки», тисячі безкоштовних курсів. Коли школяр відкриває Colab, він пише код у браузері через 10 секунд. Коли школяр хоче спробувати PHP — йому треба піднімати сервер.

Це не привід здаватися, це привід розуміти, з чим ми конкуруємо. PHP має свою нішу — веб, і ця ніша величезна. Але щоб зайти в освіту, треба дати порівнянний досвід «від нуля до результату за хвилину». Все, що нижче — це просто програма для мотивованих, а не для всіх.

Стратегія і тактика

На що треба звернути увагу:

Cloud presence

Було б вагомою перемогою, щоб PHP став однією з мов програмування, доступних для Lambda в AWS. Це прям топ-топ — зв’язатися з Amazon та спитати, що їм для цього потрібно від PHP. Можливо, не лише з Amazon.

Lambda — це лише частина картини. Cloudflare Workers, Vercel, Fly.io — всі ці платформи зараз формують уявлення про те, які мови «сучасні». PHP там або відсутній, або на задвірках. Cloud presence загалом — це системна задача, не разовий запит до одного вендора.

Інфраструктура для навчання

Колаборація з якимось Linux-дістрибутивом для швидкого сетапу лаптопу, готового для навчання стеку PHP (може, до DHH з цим запитом зайти — в нього є Omarchy Linux, який нормально працює на слабкому залізі, що ок для навчання).

Спільнота та амбасадори

Контент і інструменти — це добре, але хтось має це все нести в школи та ВНЗ. Python зріс в освіті багато в чому завдяки PSF Education Initiative — програмі, де ентузіасти приходили у школи, проводили воркшопи, організовували хакатони. PHP Foundation міг би запустити щось подібне: програму амбасадорів, менторів, які готові витратити кілька годин на місяць на живі заходи. Один воркшоп у школі дає більше, ніж сто банерів на сайтах.

Сертифікація та портфоліо

Для школярів і студентів важливо мати щось «відчутне» після навчання. Бейджі, сертифікати, рівні — геймифікація шляху вивчення мови. Це добре лягає до пункту про GitHub-уроки, але заслуговує окремої уваги: програма рівнів на кшталт freeCodeCamp, де кожен етап завершується мікропроєктом, який можна показати. «Я зробив свій перший сайт на PHP» з бейджем у профілі — це мотивація, яка працює.

Showcase: «Built with PHP»

Треба банери, що щось розроблено на PHP, намагатися просувати це де можливо, просити авторів відповідних сайтів додати на їхні сайти, навіть без посилань.

Але можна піти далі — зробити окремий ресурс «Built with PHP» з реальними кейсами: від WordPress і Laravel до конкретних стартапів та сервісів. Діти та студенти мотивуються не абстрактною мовою, а тим, що на ній зроблено щось, чим вони користуються щодня. «Цей сайт, яким ти користуєшся — він на PHP» — це працює краще за будь-який маніфест.

Інтеграція з AI-екосистемою

Я на початку казав про «диригента для зграї ШІ-агентів» — і ось тут PHP поки програє. Немає офіційного SDK OpenAI для PHP, а SDK Anthropic для PHP ніяк не вийде з beta, та має лише 130+ зірочок на GitHub. Якщо PHP хоче бути мовою «no.1», треба лобіювати появу першокласних AI SDK, або хоча б офіційних прикладів інтеграції. Для навчання це теж критично — дітям цікавіше зробити свого чат-бота чи AI-агента, ніж черговий CRUD. А якщо для цього треба перейти на Python — вони перейдуть і не повернуться.

Ринки, що зростають

Арабський та африканський ринок — вони починають зростати, відстають років на 15, та зараз швидко намагаються надолужити все. Тож туди можна принести вже готову програму навчання та підсадити на PHP.

Але «принести програму» — це не просто перекласти README. Це локалізація документації, приклади з місцевим контекстом, партнерство з місцевими освітніми ініціативами. І до речі, якщо вже говоримо про школи в Україні — мануал українською мовою був би логічним першим кроком. Важко продавати PHP як мову «для всіх», якщо мануал існує лише англійською.

Замість висновку

Звісно, я тут прописав кроки для розвитку PHP, але хто буде першим — питання досі відкрите. Це не план дій для одного розробника і не wish-list у порожнечу. Це текст для тих, хто приймає рішення — і в першу чергу для PHP Foundation. Саме у них зараз є ресурс, авторитет і можливість перетворити задум у реальність, щоб PHP став no.1.

Та конкуренція велика, а вікно можливостей не безкінечне. Python не чекає, Rust заходить у нові ніші, а нове покоління розробників обирає мову не за потужність ядра, а за перший досвід — і цей досвід формується прямо зараз. Тож не можна зволікати.

Але давайте подивимось правді в очі: за статистикою W3Techs, jQuery досі використовується на 70% всіх сайтів в інтернеті. Сімдесят. Відсотків. Тобто десь три з чотирьох сайтів, які ви відвідуєте щодня, тягнуть за собою цю «застарілу» бібліотеку. WordPress, Shopify, Bootstrap хоч і не останній, та всі вони досі на jQuery. Ваш улюблений інтернет-банкінг — теж, скоріш за все.

Тож поки розробники сперечаються, яка з наявних LLM зараз рулить у генерації коду, решта світу продовжує тихенько писати $('.button').click() і воно просто працює. Та мені здалося, Claude теж не без гріха.

Що нового

Підручник «jQuery для початківців» отримав оновлення до версії 2.0.0:

• Переклад українською — повний переклад всіх 77 файлів підручника. Тепер можна вивчати jQuery рідною мовою, а не продиратись крізь російський текст.
• Переклад англійською — для тих, хто хоче поділитись підручником з колегами з-за кордону, або просто звик до англомовної документації.
• Виправлено 50+ помилок — друкарські помилки, баги в прикладах коду, некоректні технічні твердження. Так, навіть у підручнику про jQuery бувають баги. Ніхто не ідеальний.
• Оновлено інформацію про jQuery 4.0 — додано детальний список видалених shorthand-методів та застарілих утиліт. Бо jQuery теж розвивається. Хто б міг подумати.
• Виправлено приклади коду — у супутньому репозиторії з прикладами знайдено та виправлено критичні помилки, які не давали коду працювати.

Посилання

• Підручник українською: gitbook — uk
• Підручник англійською: gitbook — en
• Підручник російською: gitbook — ru
• Приклади коду: anton.shevchuk.name/book/code
• Вихідний код прикладів: GitHub
• Вихідний код підручника: GitHub

Для кого цей підручник

Для всіх, хто стикається з jQuery у реальних проєктах. А це, як ми з’ясували, майже всі. Ви можете скільки завгодно писати у резюме «React, TypeScript, Next.js», але на першому ж проєкті підтримки вас зустріне $(document).ready() та legacy-код, якому років більше, ніж деяким фронтенд-фреймворкам, та часом навіть більше ніж років деяким фронтенд-розробникам.

jQuery is dead. Long live jQuery.

Перед тим як я продовжу, хочу зазначити, що всі мої судження суб’єктивні та можуть відрізнятися від вашого досвіду. Я працював з процесами, які починали розробляти на Talend 10 років тому, та зараз вони можуть здаватися спадщиною «кривавого Enterprise», тож не дивуйтесь, що мій досвід скоріш негативний.

Середовище розробника

Перше, з чим стикається розробник, — це робоче середовище.

Talend пропонує Talend Studio, яка зібрана на базі Eclipse. Рішення універсальне, та не скажу, що зручне. Можливо, це в мене посттравматичне з минулого досвіду роботи з Eclipse, але мені не зайшло, бо все працювало, м’яко кажучи, нешвидко:

Boomi Platform — це сучасне рішення для iPaaS. Для розробки вам достатньо браузера, нічого додатково встановлювати не треба, не треба інструкцій, ліцензій тощо. Все зроблено добре, у мене майже немає нарікань на роботу їхньої платформи.

Версійність «коду»

Talend використовує Git «під капотом», і усі процеси ви зберігаєте у репозиторії. Ви маєте можливість віддати процес штучному інтелекту, він розбере його та зможе в подальшому відповідати на питання стосовно того, що та як робить цей процес. Це дуже допомагає, особливо коли відсутні вимоги, та процес міграції перетворюється на такий собі реверс-інженіринг.

Boomi теж має версійність, вона вбудована в платформу. Ви можете швидко перейти до попередньої версії процесу або навіть компонента, можете завантажити XML вашого процесу. Це, звісно, зручно, та ось доступу до репозиторію, як у Talend, ви не маєте. Додайте сюди ще відсутність блокування процесу під час редагування, і потенційно ви матимете клопіт під час одночасного редагування процесів.

⚠️ Обидві системи мають можливість створювати гілки, та моя вам порада: не користуйтесь цією можливістю без нагальної потреби та тримайтесь однієї гілки (або створіть гілку на процес). Інакше розгрібати конфлікти в цих системах — це ще той виклик. Дотримуйтесь простого правила — одночасно над процесом повинен працювати лише один розробник.

Робота з базами даних

Обидві системи в мене працювали з MSSQL, обидві системи для цього використовували один і той самий Microsoft JDBC Driver. Для Talend ця можливість їде «з коробки», для Boomi слід було завантажувати драйвер як JAR файл на Runtime.

Та далі я розкажу про особливості, з якими стикнувся вже у Boomi, бо у Talend я бачив реалізацію, та не знаю, які були виклики перед розробниками і чому вони реалізовували те або інше рішення.

Boomi на даний момент має два конектори до баз даних.

Перший — це «Database (Legacy)». Він досить гнучкий та універсальний, та він має одну ваду: він оперує документами, які використовують профіль особливого формату. Вони фактично описують не документ, а саме запит до бази даних. Це незручно, коли ви будуєте процес: вам треба створювати потім окремий профіль для документів та мапінг для перетворення з одного в інший.

Цю проблему вирішує конектор «Database V2». Він вже працює з універсальним профілем документів у форматі JSON, та і запит до БД перенесли до «операцій», що виглядає більш логічно:

Але цей конектор, на мій погляд, вже не такий гнучкий, як попередня версія, та можу навіть сказати, що він трохи «сирий», бо має дитячі вади з валідацією синтаксису запитів.

Також у Boomi є обмеження щодо роботи з temporary tables. Оскільки такі таблиці існують в межах одного з’єднання (connection), то працювати з ними можна лише в межах одного шейпу процесу. Boomi не гарантує, що два окремих шейпи з викликом до БД будуть відбуватися в межах одного і того ж з’єднання, а не іншого з пулу конектів.

Та що для мене було важливо — це те, що зрозумілим та знайомим виявився механізм роботи з транзакціями та блоком try-catch, і це майже в кожному процесі доводилось робити:

Виглядає це дуже примітивно, та тим не менш працює ефективно та зрозуміло будь-якому розробнику.

Mapping

Talend має можливість мульти-мапінгу — це коли фактично ми зливаємо декілька документів в один або перетворюємо в декілька.

Скріни взяті з офіційного мануалу компанії QlikTech International AB.

В Boomi важче злити два документи до одного. Для цього треба додавати мапінг-функцію на всі поля, або робити кастомний скрипт, який буде це робити, та ще, можливо, слід буде городити додатковий кеш до цього всього:

Наче Boomi-варіант менш гнучкий, та реалізація в Talend має великий недолік: подібний мапінг погіршує читабельність (readability) процесу. Додайте до цього відсутність пошуку полів, і перевага Talend дуже швидко перетворюється на суцільний головний біль.

На мою думку, мапінг в Boomi більш зрозумілий, використання функцій для мапінгу дисциплінує та дозволяє зручно перевикористовувати код (я про це ще розповім).

Мій досвід з мапінгом в Talend я б назвав травматичним, бо кожного разу він виглядав для мене як зустріч з Демогоргоном:

Динамічна конфігурація

Те, чого концептуально неможливо зробити в Boomi, — це конфігурувати з’єднання під час виконання процесу. Не можна змінити connection string до бази даних під час виконання процесу; не можна підставити іншу конфігурацію SFTP після запуску. Ці та інші налаштування ви повинні встановлювати для процесу перед початком виконання.

З одного боку, це звісно «хард» обмеження, та це зроблено навмисно, бо фактично це є фундамент для ваших розрахунків з Boomi (ліцензування конекторів). Але з іншого боку, гарно спроєктований процес буде знати заздалегідь всі можливі конекти ще на початку своєї роботи.

Зрештою, процеси, які потребували подібного підходу, були реалізовані, та це потребувало додаткового часу на конфігурацію.

Перевикористання «коду»

І Talend, і Boomi дають можливість створювати саб-процеси та використовувати їх у основному процесі.

Можу зазначити, що виклик саб-процесів у Talend зроблено зручніше, бо налаштування запуску конфігуруються безпосередньо у властивостях елемента, який викликає саб-процес. В Boomi для цього доводиться використовувати окремий додатковий елемент «Set Properties»:

Наче й не складно, та все ж таки варіант, який пропонує Talend, мені здається більш логічним. А варіант від Boomi у випадку виклику саб-процесу декілька разів потребує додаткової уваги, щоб не наробити помилок.

Кастомний код

Talend дозволяє вставити Java код майже в кожне поле. Це виглядає гнучко як концепція, але моя робота дуже часто виглядала як оцей мем з розслідуванням:

Також в Talend є можливість створювати та додавати кастомні Java бібліотеки, щоб потім використовувати їх. Угу, викликати Java-бібліотеку можна майже з будь-якого поля, тут вже інший мем…

При роботі з Boomi ви теж можете використовувати кастомні Java-бібліотеки, такі як iText чи jsoup, або написати свою власну. Але розробляти та компілювати ви будете поза Boomi, а на платформу завантажуватимете вже готові JAR-файли.

Використання кастомного коду в Boomi обмежено Process Script та Map Script, їх завжди легко знайти серед компонентів:

Для використання кастомних бібліотек ви все одно будете використовувати JavaScript або Groovy. Як я зазначав у попередній статті, в мене виникають питання лише з приводу версій, які підтримує Boomi: код слід писати як 10 років тому, наче й не проблема, та все одно трохи дратує.

Переваги Boomi

Є у Boomi один великий плюс — це можливість перевикористовувати майже усі компоненти: екшени, профілі, мапінги та скрипти без того, щоб оформляти їх як Java-бібліотеки. Це прям сильно спрощує життя розробникам. Головне — оці загальні компоненти оформлювати, документувати та шерити знання про них серед команди.

Як я вже зазначив вище, реалізація транзакцій та робота з try-catch реалізована зручно та передбачувано.

Були й інші моменти, коли я радів функціоналу Boomi, якого не було в Talend (чи, можливо, розробники просто не використовували той функціонал, бо він з’явився пізніше за створення процесу).

Як приклад — PGP Encrypt/Decrypt. В Boomi ви завантажуєте сертифікат через інтерфейс та використовуєте його в Data Process шейпі:

Як бачите, є робота з Base64 через UI, а не з коду; те саме з Zip архівацією.

Дуже просунуте логування, яке дозволяє легко дебажити процеси, аналізувати перформанс та знаходити проблемні місця:

Додам, що Boomi має ще одну велику перевагу — він має вбудований функціонал з AI, який вміє документувати процеси (і це не єдине, що він вміє). Робить він це, не сказати, що прям добре — я б оцінив на 3 з 5 зірочок. Мені особисто не вистачає можливості, щоб AI розумів саб-процеси та переходив по ним.

Можу відзначити також значний прогрес їхнього AI для побудови процесів: він стає розумнішим, та, на мою думку, йому ще зарано будувати процеси самостійно. Можливо, за пів року або рік це стане дійсно корисним інструментом.

Недоліки Boomi

Головний недолік, на який я вже скаржився в попередній статті, — це те, що логування, яке я нахвалював раніше, дуже сильно впливає на швидкодію. Вимкнути його для процесів, які виконуються за розкладом, неможливо, і як результат — різниця в часі виконання між Talend та Boomi одного і того ж процесу у 3-4 рази.

Окремо існує проблема: коли у вас велика кількість документів (мільйони), то не варто намагатися їх порахувати в Boomi, це сильно впливає на швидкодію. Ось так не робіть:

Що можна покращити в Boomi?

Це нотатка скоріш для розробників Boomi, і сподіваюсь вона дістанеться свого адресата.

Робота з Dynamic Process Properties (DPP) та Dynamic Document Properties (DDP) вимагає постійно «пам’ятати» назви цих Properties. Використовуєш їх постійно, доводиться копіювати назви, а це незручно і викликає помилки. Було б добре, щоб система відслідковувала DPP та DDP під час розробки та давала можливість обирати з попередньо створених. Також під час виконання процесу у Test Mode хотілось би мати можливість бачити, що у тих Properties відбувається, щоб не робити це за допомогою окремих елементів.

Роботу з профілями документів теж можна покращити — коли перший елемент процесу повертає якийсь профіль, та ми додаємо наступний елемент, такий як Map, то було б зручно, якби він автоматично розумів контекст та брав відповідний профіль. Наразі система не підказує, який профіль обрати, що призводить до помилок, які доволі часто трапляються під час розробки, хоча і діагностуються теж легко.

Що треба знати? Або чому Low-Code не означає No-Knowledge

Якщо ви думаєте, що робота з Boomi — це лише перетягування іконок, мушу вас розчарувати. Щоб будувати серйозні рішення, вам знадобиться комплексний технічний бекграунд, і ось чому.

Почнемо з програмування. Так, Boomi дозволяє багато зробити візуально, але як тільки логіка стає нестандартною, вам доведеться писати скрипти. Тут панує JavaScript, але є нюанс: це старий добрий ECMAScript 5, тому забудьте про модні фішки сучасного JS. А оскільки платформа працює на Java-машині, то знання Java або Groovy стає вашим секретним козирем для вирішення задач, які не під силу звичайному JS. Ну і, звісно, розуміння структур даних та вміння писати тести ніхто не скасовував.

Далі — робота з даними, адже інтеграція — це, по суті, перекладання даних з однієї кишені в іншу. Ви маєте вільно почуватися з базами даних, і мова не про прості SELECT-запити. Реальні кейси вимагають роботи зі збереженими процедурами (Stored Procedures) та транзакціями, особливо в MSSQL. Крім того, вашими постійними супутниками стануть JSON та XML. І якщо JSON — це стандарт сучасного світу, то XML та вміння писати для нього XSLT-трансформації — це сувора реальність Enterprise-систем, яку треба прийняти.

Щодо зв’язку систем, то тут ви маєте бути поліглотом. REST API — це ваша база: ви повинні розуміти, як працюють HTTP-методи та авторизація. Але Enterprise не був би Enterprise’ом без SOAP-сервісів, тож доведеться навчитися «дружити» і з ними. А для побудови сучасних асинхронних архітектур вам знадобиться досвід роботи з чергами повідомлень, зокрема з Apache Kafka, щоб ваші системи могли обмінюватися даними миттєво і надійно.

І наостанок — інфраструктура та безпека. Ваш процес не висить у вакуумі. Ви повинні розуміти хмарне середовище: що таке балансувальники навантаження, як працює автоскейлінг та як моніторити здоров’я системи. І, звісно, безпека: розібратися в OAuth, SSL сертифікатах та інших методах автентифікації — це не опція, а необхідність, щоб ваші інтеграції не стали діркою в безпеці компанії.

Boomi. Такий шлях

Ця стаття не претендує на хайповий заголовок Boomi VS Talend, бо в першу чергу я хотів поділитися своїм досвідом та мав за ціль підкреслити один факт: міграція з Talend до Boomi можлива. Та чи потрібна вона вам і вашій компанії? Ось тут я не зможу відповісти, я лише намагався трошки надати вам аргументів, якщо перед вами постане таке питання. Для однозначної відповіді вам треба зважити дуже багато факторів, серед яких буде і ціна рішення, і ціна міграції, і ціна навчання нової системи.

З останнім я вам підкажу трохи. На мою думку, щоб навчитися працювати з Boomi, слід орієнтуватися на 1 місяць інтенсивного навчання. Перші два тижні потрібні, щоб пройти Integration Developer Path та декілька супутніх топіків. Після цього можна буде починати брати перші прості інтеграційні процеси до роботи. Наступні 2 тижні — це буде занурення до прикладів реалізації, до мануалів, напрацювання best practice, та в залежності від ваших вимог та потреб можливо слід буде пройти курс Associate Event Streams та Professional API Design. Загалом, за місяць перекваліфікуватися до System Integration Engineer можливо, але за умови, що вже є базові знання.

P.S.

Якщо ви теж проходили цей шлях міграції або маєте свої «милиці» та лайфхаки для Boomi — діліться в коментарях, цікаво почути про ваш досвід. І окремо буду щиро вдячний, якщо хтось підкаже елегантний спосіб обійти проблему з гальмуванням логів. Бо поки що це виглядає як вибір без вибору, і мене це гризе.

P.P.S.

Під час міграції жоден Talend-розробник не постраждав…

Та перед тим як перейти безпосередньо до історії Boomi, я б хотів почати свою розповідь з передумов появи такої системи, та можливе це розставить все відразу на свої місця, і все стане зрозуміло без додаткових пояснень.

Ця стаття написана для техлідів, архітекторів та менеджерів Enterprise-проєктів. Вона містить багато спрощень, та я гадаю, це допоможе у розумінні матеріалу. У будь-якому разі, я буду радий почути фідбек від кожного.

Prequel «Enterprise»

Рано чи пізно, але більшість IT спеціалістів стикається з розробкою різноманітних систем для Enterprise, це може бути як внутрішня розробка компанії, так і розробка для замовника. Потрапивши сюди, ви не залишитесь таким як були раніше, можливо вам буде подобатися робота в такому середовище, можливо ні, але з часом ви точно не пожалкуєте про свій досвід.

— Що то таке Enterprise, та як він з’являється?

Enterprise — це комплексна система яка забезпечує роботу критичних для бізнесу процесів, які проходять крізь різні підрозділи компанії, та можуть поєднувати в собі багато окремих підсистем.

— Тож виглядає так, що якщо в вас маленька outsource компанія на 10 людей, яка користується одночасно CRM/HRM/Jira/GitHub/etc то вже є Enterprise?

І так, і ні.

Тут важлива різниця в підході до процесів:

— Якщо ваші процеси не автоматизовані та здебільшого виглядають як чек-листи для людей. Схоже, ваші процеси ще не зрілі та мають «поспіти».

— Якщо подія у компанії (наприклад, вихід нового співробітника) автоматично запускає декілька паралельних процесів та організовує взаємодію людей і систем — оце вже ознака Enterprise.

Enterprise-системи значною мірою складаються саме з таких процесів — з багатьох таких процесів.

Скільки процесів має бути, щоб впевнено сказати: «А ось це Enterprise»? Ніхто не дасть точної відповіді — можливо 100, можливо 1000. Але рано чи пізно зростаюча компанія подолає цей бар’єр і постане перед новими викликами.

Як це буде відбуватися? Тут може бути декілька шляхів:

• Еволюційний
• Революційний
• Або мікс обох у різній пропорції.

Enterprise Еволюція

Це класична історія успішного стартапу або маленької компанії. Зміни відбуваються поступово, «під тиском» нових вимог, коли старі рішення перестають працювати.

Давайте розглянемо декілька прикладів.

Етап I. MVP що затягнувся

Компанія має один або декілька ключових сервісів, навколо яких зав’язаний увесь бізнес. Можливо, є й інші сервіси (наприклад, за підпискою), та вони майже не пов’язані один з одним.

Взаємодія здебільшого відбувається через комунікацію людей, які користуються різними системами (“Human middleware”).

З часом бізнес зростає, координація забирає забагато часу. Компанія змушена наймати людей, які фактично займаються лише супроводом цих процесів.

Етап II. Зоопарк сервісів та Point-to-Point

Компанія зростає, з’являється відповідальний за інфраструктуру. Він намагається зібрати команду з різних відділів, але наштовхується на вічну проблему — у всіх “немає часу”.

Сценаріїв розвитку безліч: від розпилу монолітів на мікросервіси та купівлі SaaS (Salesforce, Zendesk) до повного хаосу, коли все це впроваджується одночасно й неконтрольовано.

Результатом такого хаосу стає Point-to-Point взаємодія. Система перетворюється на клубок зв’язків: сервіси тісно зчіплені (tight coupling) та знають забагато один про одного. Як наслідок — підтримка ускладнюється, а вартість будь-яких змін зростає в геометричній прогресії.

Етап III. Middleware зрілість

З часом стає зрозумілим, що одна людина вже фізично не спроможна встигати за розвитком системи, тому компанія формує окремий підрозділ, який займатиметься інфраструктурою.

Хтось із нового відділу бере на себе роль Enterprise Architect’а та доходить висновку, що подальше зростання та зміни потребують впровадження middleware. Що зміниться:

• Розробників познайомлять з Enterprise Service Bus
• З’явиться поняття Canonical Data Model (єдиний формат даних для всієї компанії)
• Заборонять прямі виклики сервісів один до одного, усі будуть спілкуватися через брокер/шину
• Застосують патерн Strangler Fig (фікус-душитель): старий легасі-код поступово замінють новими сервісами, не вимикаючи систему.

Як альтернативу або доповнення починають розглядати Integration Platform (однією з яких є Boomi, але про неї згодом).

Еволюція — це про рефакторинг та стандартизацію. Це про поступове введення правил гри (API-контракти, події), які зменшують ентропію (хаос).

Enterprise Революція

Це стрес-тест для архітектури. Це відбувається, коли велика компанія купує іншу або коли два гіганти зливаються (M&A). Тут немає часу на повільний рефакторинг — бізнес вимагає результату «на вчора».

Тут немає етапів — тут є виклики, які треба вирішувати негайно.

Уявіть ситуацію: Банк А купує Фінтех Б. Перед Enterprise Architect постає ряд завдань.

Виклик 1. Дублювання функцій

Ситуація:

• У Банку А є своя CRM («Самописна, стара, але надійна»).
• У Фінтеха Б є своя CRM («Модна, у хмарі»).

CTO приймає вольове рішення — «Rip and Replace». Протягом 6 місяців Фінтех Б зобов’язаний викинути свою систему і мігрувати в CRM Банку (чи були сумніви, хто залишиться?).

Що буде відбуватися далі? Зануритись у пекло міграційних скриптів, мапінгу полів і втрати даних? Ні. Тут критично потрібні ETL-інструменти (Extract, Transform, Load), щоб коректно «перекачати» дані з однієї структури в іншу.

Виклик другий. Ізоляція даних (Data Silos)

Ситуація:

• Ви маєте інформацію про клієнтів в двох різних системах, вони між собою не зв’язані, та не сінхронізуються.

Наслідки:

• Суперечливість даних (Inconsistency), дублювання зусиль та некоректна аналітика.

Що робити? Тут слід впровадити MDM (Master Data Management). Це технологія, процеси та політики, що дозволяють створити «Золотий запис» (Golden Record) та отримати Єдине Джерело Істини (Single Source of Truth).

Виклик третій. «Федерація»

Що відбувається:

• Іноді об’єднати системи неможливо швидко, але треба забезпечити їх одночасну роботу вже зараз.

Що буде відбуватися далі? Ми будуємо «Фасад» — спільний API, який приймає запит, а всередині «під капотом» вирішує, куди його направити: в стару систему Банку чи нову систему Фінтеху. Для користувача це виглядає як одна система, хоча всередині це «Франкенштейн».

Революція — це про інтеграцію та міграцію. Це про поєднання чужорідних систем, про адаптери, шини даних та жорсткі адміністративні рішення («ми вимикаємо цей сервер 1-го числа»).

Boomi. Пролог

Настав час розповісти безпосередньо про Boomi.

Boomi — це iPaaS (Integration Platform as a Service). Інструмент для реалізації бекенд-логіки без хардкорного кодингу (тут сумний смайлик).

Архітектурно Boomi складається з двох частин:

1. Boomi Platform (The Build)

Це безпосередньо “Visual IDE” у вашому браузері, де ми розробляємо та налаштовуємо процеси. Замість написання функцій ми перетягуємо іконки:

• HTTP Client Connector
• Map Shape
• Database Connector
• та інші…

Ми поєднуємо їх стрілочками у єдиний flow.

Тут також відбуваються адміністративні дії: перегляд логів, керування налаштуваннями, формування розкладів запусків.

Все це працює у хмарі — швидко та передбачувано. Хіба що автоматичне вирівнювання на складних процесах може викликати нарікання, а так все достатньо «гладенько»:

2. The Runtime (The Execution)
Друга складова — це Runtime. Фактично, це Java-додаток (JVM), який виконує той «код», що згенерувала платформа.

Як це працює: Коли ви натискаєте “Deploy” на платформі, Boomi компілює ваш візуальний процес у пакет і відправляє його на Runtime для виконання.

Важливий момент: Існує декілька типів Runtime:

• Basic Runtime
• Runtime Cluster
• Runtime Cloud (Private або Public)

Чим вони відрізняються, коли та що обирати я про це ще розповім.

Boomi. Епізод I

Надалі я буду намагатися йти «шляхом» розвитку Enterprise та розповім де та як можна застосувати Boomi, та який Runtime краще обрати.

Почнемо з першого сценарію, коли нам треба зв’язати між собою сервіси які живуть своє життя:

Уявимо, що це маленька компанія, яка використовує сервіси за підпискою, та ці сервіси не вміють в інтеграцію один з одним. Процеси раніше підтримували люди: там статус на борді змінити, десь файли завантажити, комусь рахунок виписати.

В такому випадку нам підійде Boomi Runtime Cloud – це хмарний runtime, який хоститься і керується самою компанією Boomi, це мінімум додаткових зусиль, лише розробити процес, залити та користуватися:

Реалтайм нам не потрібен, тож для кожного процеса можемо створити свій розклад для запуску. Процеси будуть бігати Point-to-Point між сервісами. Подібну схему можно достатньо швидко реалізувати, бо Boomi підтримує більше 1000 конекторів з коробки — https://boomi.com/connectors/ (та треба пам’ятати, що платити треба буде саме за підключені конектори):

Фактично для цього вигаданого сценарію, це виглядає як сервіс IFTTT на максималках.

Давайте розглянемо альтернативну компанію, яка має сервіси у себе в локальній мережі, чи VPC, у такому випадку Boomi Runtime Cloud не буде мати можливість співпрацювати з сервісами компанії, варіант налаштувати firewall, щоб Boomi міг стукатись до всіх внутрішніх сервісів виглядає не секьюрно. Тож ми підемо іншим шляхом, і будемо піднімати свій Runtime вже за firewall’ом:

З точки зору розробки процесів, тут не буде ніяких змін, та будуть зміни в деплойменті, та відповідальність за інфраструктуру буде лягати вже на плечі DevOps’ів, тепер це їх клопіт як інстанц підняти та як його моніторити. Про те який інстанц потрібно обрати можна дізнатися з навчальних матеріалів, приведу тут лише табличку щоб було уявлення про вимоги:

Якщо чесно, що саме вклали в цю «кількість транзакцій на день», мені важко сказати, будемо вважати, що одна «транзакція», це один простий процесс, який обробляє один документ <100Кб.

Boomi. Епізод II

Поїхали далі, наш наступний приклад, це Enterprise з зоопарком Point-to-Point сервісів.
Ми не будемо прибирати цей безлад, ми опановуємо його. В цьому вигаданому сценарії ми будемо переносити процеси до Boomi, та оскільки процесів багато і вони життєво важливі для роботи компанії то нам слід буде забезпечити безвідмовну роботу нашої системи під постійним навантаженням. У Boomi для цього передбачено використання Runtime Cluster, який забезпечить як high availability так і scalability системи за рахунок часу вашої DevOps команди та можливостей Cloud провайдерів:

У кластері Boomi є ряд особливістей.
Перша особливість, це використання Shared File System, усі ноди монтують папку, яка відповідає за зберігання конфігів, логів та черг повідомлень, все лежить в одному місці.

Будь ласка обережно використовуйте Shared File System для зберігання тимчасових файлів якщо вам такі будуть потрібні під час виконання процесу, це може мати негативний вплив на швидкість роботи таких процесів.

Друга особливість, про яку слід пам’ятати, це те, що кількість нод в нас обмежена через Network Chatter, рекомендуєме обмеження, це 10 нод. Якщо цього вам не вистачить, то слід будувати новий кластер, і тоді треба буде розподіляти процеси по цим кластерам, що додасть клопоту усім.

Якщо що, то я трохи погуглив, та ось вам декілька статей, про сетап Cluster’а:

• High Availability AWS Integration Runtime
• Integration Runtime Installation – runtime cluster on AWS ECS
• Runtime cluster Kubernetes Azure Quick Start

Ще пів року назад, Boomi використовували неймінг Atom (Runtime) та Molecula (Cluster), тож час від часу ви будете зустрічати цю термінологію у документації.

Інформація по рекомендованому розміру кластера також є в навчальних матеріалах:

Boomi. Епізод III

Настав час розповісти про організацію EDA (Event Driven Architecture) на базі Boomi.
Коли ваша Enterprise система починає використовувати шину для обміну повідомленнями ваша робота концентрується на розробці адаптерів для сервісів:

Саме такі адаптери будуть відповідати за бізнес-логіку, яка зв’язує шину подій та API сервісів. І звісно реалізацію таких сервісів ви можете покласти на Boomi:

А ось з приводу яку шину вибрати якщо в вас її ще немає, то тут є декілька опцій.

Перша — використовувати вбудований до Runtime механізм черг – Boomi Atom Queue. Він живе на вашому Runtime або Runtime Cluster. Ця шина має дуже вагоме обмеження — взаємодіяти з нею можна лише з Boomi, тож ніякі зовнішні сервіси не будуть мати доступ до черги без участі Boomi. Ну і використання файлової системи (мережової для кластеру) для зберігання теж накладає обмеження на швидкодію, та і надійнійсність, це буде ваш клопіт. Моніторинг такої черги вкрай обмежений.

Boomi Atom Queue вже кличуть Legacy, та все рівно будуть підтримувати

Друга опція — Boomi Event Streams, це вже окремий SaaS сервіс від Boomi. За інфраструктуру відповідає Boomi. За допомоги API до такої шини вже можна звертатися ззовні та відправляти повідомлення до черги, а ось слухати зась. Для моніторінгу є дашборд в інтерфейсі Boomi Platform. Тут вже сплачуємо гроші за об’єм даних.

Третя опція — використовувати Kafka чи RabbitMQ, чи будь який інший брокер повідомлень. Ніяких обмежень на використання, та вся відповідальність за роботу лягає вже на вас, надійність та моніторинг – все це ваша зона відповідальності. З мого досвіду, Boomi чудово працює з Kafka, та звісно у такому випадку конектор до зовнішньої системи буде враховуватися до вашого чеку за Boomi.

Boomi. Епізод IV

Перейдемо до революційних змін Enterprise. Як ми можемо використати Boomi, коли часу в нас обмаль, а від нас вимагають результату «на вчора»?

Boomi спроєктовано таким чином, щоб ви як найшвидше пройшли шлях від вимог, розробки, та тестування та отримали результат на production.

І якщо буде потрібно швидко розробити ETL (Extract, Transform, Load) процес, то Boomi вам підійде, бо має багато вбудованих інструментів для його організації, а якщо їх вам не вистачить, то тоді вже можна і код написати для обробки документів. Boomi підтримує як JavaScript так і Groovy.

Попередній параграф був як з рекламного буклету? Ну добре, перейдемо до специфіки системи.

Почнемо з коду який ми можемо додавати до процесів.

Перша доступна опція, це може бути JavaScript, та підтримується лише ECMAScript 5, чому? Бо там не NodeJs виконує JavaScript, це робить Java машина, вона має свій власний рушій для виконання JavaScript. З плюсів – ви можете викликати вбудовані Java-класи, та навіть більше – ви можете завантажити JAR файл до вашого Runtime, та викликати його.

Друга опція, це Groovy, ми можемо використовувати версію 1.5 або 2.4. Я звісно не Groovy-розробник, але щось мені підказує, ще це доволі старі версії 🙁

Окремо варто зазначити, що прикладів коду не так багато, і це має побічну дію, що ШІ не може коректно генерувати більшість скриптів, отакої.

Що є ще? Перформанс. Тут я можу порівнювати як працює Boomi та Talend, бо ми мігрували багато процесів з одною системи до іншої, і я побачив що реалізація процесу у Boomi працює повільніше, та в мене є думка чому так відбувається – Boomi для процесів які виконуються за розкладом використовує так званий General Process Mode, у цьому режимі Boomi логує все, кожен крок, кожен документ, кожну трансформацію, все це потребує багато часу, та багато місця для логів. Чи можна обрати інший режим запуску? Так, є режим Low Latency але він не буде працювати для процесів за розкладом.

Тож який висновок? Якщо ви обрали Boomi у якості iPaaS для вашої компанії, то його можливостей скоріш за все вистачить і для побудови ETL процесів які будуть обробляти гігабайти даних. Можливо це не буде так швидко, як з рішеннями від конкурентів, та я сподіваюсь це питання розробники вирішать.

Boomi. Епізод V

Для реалізації Master Data Management в Boomi є інструмент який називається Boomi DataHub, за його допомогою ви можете вирішити проблему ізоляції даних. Ну принаймні це слідує з опису цього сервісу, бо в мене не було досвіду роботи з ним.

Отакої, коротенький епізод вийшов…

Boomi. Епізод VI

Так, а що у Boomi з можливостями по реалізації API для нашої вигаданої історії?

Boomi має 2 інструмента для цього, перший, це API Management — тут ми можемо налаштовувати доступ, генерувати ключі, встановлювати квоти. Та тут також доступний Swagger «з коробки» та Developer Portal за потреби.

Другий інструмент, це безпосередньо Integration, ви будуєте процеси, які будуть спрацьовувати за запитом зовні на відповідні endpoint’и, і далі вже можете за якимось правилами викликати той чи інший внутрішній сервіс:

Boomi. Епілог

Щось моя розповідь затягнулась, та я сподіваюсь я допоміг вам трохи розібратися що то таке Boomi, та у яких випадках цей інструмент підійде саме вам.

Додам ще трохи матеріалів.

По перше, Boomi має досить непогані навчальні матеріали, вони доступні безкоштовно, єдина умова – для реєстрації на порталі вам слід використовувати робочу пошту, gmail не підійде. З усіх матеріалів, якщо ми кажемо про розробку інтеграцій, то я рекомендую йти шляхом розробника, та через пару тижнів вже зможете показувати перші результати своєї роботи.

Багато практичних статей ви зможете знайти на сторінці Boomi Blueprint.

Статті від ком’юніті, траплялось що відповіді я знаходив лише там – https://community.boomi.com/s/

Ну і звісно офіційний мануал, хоч і не самий інформативний, та все ж таки досить корисний.

Я не буду детально зупинятися на розробці бота у цій статті, і я вважаю що він у вас вже є, та працює як слід, тож залишається зробити лише останній крок до маркету.

Почнемо нашу роботу, для початку нам треба підключити Google Workspace Marketplace SDK до нашого проєкту:

Далі нам слід перейти до налаштувань Google Workspace Marketplace SDK та обрати потрібні пункти.

App Configuration

Почнемо з «App Visibility», бот буде публічним, та його можна буде знайти у пошуку:

Встановлювати його зможуть усі бажаючі:

І так, це лише додаток до чату:

Для роботи будуть потрібні лише базові scopes, які не потребують додаткових дозволів:

Трохи про себе:

Store Listing

Розділ «Store Listing» також треба уважно заповнити, почнемо з детального опису, я розписав бота на англійський та українській мовах, але здається мені, що опис англійською то буде обов’язковим пунктом:

Підготуйте іконки та банери:

Красиві скріншоти, треба лише впевнитись, що на них немає нічого сенсетивного:

І тепер дуже важлива частина, ви повинні підготувати Terms та Privacy сторінки та додати посилання на ці сторінки:

Як бачите, в мене усі посилання ведуть на github:

• Privacy Policy
• Terms of Service
• Support Page
• User Manual

Після цього, ви зможете відправити вашого бота на модерацію до Google Workspace Marketplace, але в мене не вийшло з першого разу пройти модерацію, та і з другого разу не вийшло:

Як бачите, я отримав 3 рази відповідь — Rejected, і кожного разу з тим самим текстом:

1. Links for Privacy Policy, Terms of Service and Support are provided and point to the correct information.
You can check additional info about this requirement here (https://developers.google.com/workspace/marketplace/create-listing#support_links).
All provided links work and point to the correct information. For example, a link provided for a privacy policy points to a page describing the privacy policy.

2. Functionality – There are no obvious bugs and all visible actions are fully functional.
You must ensure the Add-on is operational and functions in accordance with the description of the Add-on. You should thoroughly test all the add-ons you create before publishing using the available test options.

Я вже не знав, що робити, бо посилання були, але здається модератору не подобалось, що текст розміщений на GitHub, та він просто ігнорив посилання на нього. Тому коли я в 4-ий раз отримав листа від Google Workspace Marketplace Reviews Team що вони почали працювати над перевіркою, то я у відповідь розписав їм, що це за додаток, навіщо він створений, та чому усі посилання ведуть на GitHub.

Не пропустіть того листа, я отримував його у проміжок часу від 12:00 до 15:00 за Київом, а вже за 2-3 години отпримував вже відмову.

І далі була тиша, rejected-відповіді я отримував впродовж дня, а тут відповідь затягнулась, схоже мій запит пройшов першу лінію модерації, та перейшов на інший рівень, де вже було прийнято рішення про Approved:

Все, тепер мій бот Bender 2.0 доступний у Google Workspace Market, встановлюйте, тестуйте, залишайте відгуки.

Якщо у вас також вийшло опублікувати вашого бота, залишайте посилання у коментарях :)

І так, ось є офіційна документація, беріть та користуйтесь, а статтю залиште у обраному, щоб якщо що було в кого перепитати ;)

Для початку, а що то таке типографська розкладка, звідкіля вона з’явилась, та як нею користуватися?

Перша типографська розкладка з якою я познайомився була типографська розкладки Іллі Бірмана, вона була і є лише для російської та англійської мов. Але мені була потрібна розкладка для українскої мови, і серед можливих варіантів я обрав шлях створення своєї на основі розкладки від Іллі.

— Навіщо потрібні всі ці «типографічні» розкладки?
— Як раз для того, щоб написати цей діалог не використовуючи нічого окрім української розкладки…

Так, типографічні розкладки створюють як раз для того, щоб швидко друкувати такі елементи як лапки «, », та оте довге тире —, а не якісь дефіс. І це не все, давайте ще приведу приклади використання:

• спеціальні сімволи: ©, ®, та ™
• символ градусів — °, дивіться як гарно виглядає +24°C
• математичні символи: 1¹+2²+3³≠30, ¹⁄₂+¹⁄₃+¹⁄₄≈1, та 2×2=4, зі справжнім знаком множення, а не літерою x
• звісно валюти: жміть ⌥ + р отримаєте ₴ (тому що латинкою то h — hrivnya), £, ¥, €, $, та ¢
• стрілочки ←, →, ↑, та ↓
• скажи Ющенко ✓так

Насправді ще багато чого, подивіться самі на це різноманіття символів, і так, багато з чого я дійсно використовую:

— А що то за незрозуміле Ы у розкладці, навіщо воно треба?
— То треба, щоб видалити російську розкладку з обігу, тож навіть якщо є потреба надрукувати оті Ы та Э вам не треба більше ставити ще одну розкладку, або шукати ці символи у інтернеті.

Заголом, я намагався додати можливість друкувати будь які літери кирилиці:

А	Б	В	Г	Ґ	Д	Ѓ
Ђ	Е	Ѐ	Є	Ё	Ж	З
З́	 Ѕ	 И	 Ѝ	 І	 Ї	 Й
Ј	К	Л	Љ	М	Н	Њ
О	П	Р	С	С́	 Т	 Ћ
Ќ	У	Ў	Ф	Х	Ц	Ч
Џ	Ш	Щ	Ъ	Ы	Ь	Э
Ю	Я

Але все не так просто, бо для більшості символів з модифікаторами накшталт акцентів (ў), наголосів (а́), умлаутів (ä) слід використовувати так звані «мертві клавіші». Ось декілька прикладів:

• нажміть одночасно ⌥ + ⌃ + ˘, а потім вже у отримаєте ў;
• нажміть одночасно ⌥ + ⌃ + ¨, а потім вже ж отримаєте ӝ.

Хоча я ще не все реалізував з кирилиці, мені ще є над чим працювати:

Ђ	Ѕ	Ј	Љ	Њ	Ћ	Џ

Але давайте повернемось до того, що вже зроблено:

Тут для нас все досить звично, для тих хто користувався Windows то розташування максимально знайоме, з особливостей відмічу:

• для вводу літери ґ слід використовувати комбінацію ⌥ + г
• для вводу символа ₴ слід використовувати комбінацію ⌥ + р

А ось у останньому оновленні в мене змінилась концепція щодо символів, які ховаються за shift ⇧:

Така зміна пов’язана з тим, що я вже багато років використовую MacBook лише з англійською розкладкою, тож в мене на клавіатурі немає інших символів ¯\_(ツ)_/¯. Так, я друкую українською «наосліп», і виходячи з цього я намагався побудувати розкладку яка використовувала би максимально сумісний вигляд з нативною англійською розкладкою:

• верхній рядок символів над цифрами повністю сумісний з англійською версією: ! @ # $ % ^ & * ( ) _ +
• символи які ховаються за option ⌥: ? < > : [ ]
• символи які ховаються за сполученням клавіш option ⌥ + shift ⇧: … { } ; { }

Як встановити?

Перейдіть на сторінку проєкту на GitHub та завантажте з останнього релізу файл ukrainian-typography.dmg. Далі дабл-клік по файлу:

Тепер запустіть Keyboard Installer (MacOS буде попереджати про те, що цей файл завантажено з інтернету), а потім перетягніть до вікна інсталера файл ukrainian-typography.bundle:

Далі оберіть встановлення до поточного користувача. Все, тепер вам потрібно лише перейти до налаштувань клавіатури:

System Settings > Keyboard > Text Input: Input Sources > Edit та обрати 🇺🇦 Ukrainian - Typography

Насолоджуйтесь :)

Варіанти?

На поточний час, у вас є можливість обрати серед чисельних інших розкладок:

• Моя попередня версія 1.5.0, більш звична для користувачів;
• Ukrainian Typographic Keyboard від Дениса Довганя;
• Українсько-російська типографська розкладка від Олександра Колодько;
• Сумісні українські типографічні розкладки для Windows/Mac/Ubuntu від Олександра Швеца;
• Версія від GaGadget.

Або навіть обрати свій шлях, та створити свою розкладку за допомоги утіліти ukelele.

Почнемо з початку, з редактору коду. Але знаєте що? Мене редагування коду у браузері трохи бісить, тому будемо налаштовувати робочий енвайронмент здорової людини локально на робочому комп’ютері. Для цього нам знадобиться git, ваша улюблена IDE та eslint для перевірки що у вас все добре. Все це звучить досить знайомо, тож так ми будемо розробляти код локально, перевіряти кодестайл за допомоги eslint, а за версіонування коду в нас буде відповідати git з усіма його можливостями.

Подивіться як виглядає package.json мого проєкту:

{
  "name": "bender-2.0",
  "version": "7.0.0",
  "description": "The Bender bot for Google Workspace",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/AntonShevchuk/bender-2.0.git"
  },
  "keywords": [
    "Google Workspace",
    "Google Chat API",
    "Apps Script"
  ],
  "author": "Anton Shevchuk",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/AntonShevchuk/bender-2.0/issues"
  },
  "homepage": "https://github.com/AntonShevchuk/bender-2.0#readme",
  "devDependencies": {
    "@eslint/js": "^9.2.0",
    "eslint": "^9.2.0",
    "eslint-plugin-googleappsscript": "^1.0.5",
    "eslint-plugin-jsdoc": "^48.2.3",
    "globals": "^15.1.0"
  }
}

Нічого зайвого, запускай npm install та працюй з кодом…

— Але ж код у нас на Apps Script, його ж не треба ручками буде постійно копіювати?
— Ні, не треба, для цього є консольна утиліта clasp, яка нам як раз допоможе тягати код туди-сюди.

The Apps Script CLI

Далі вас чекає невеличкий переказ офіційної документації, можете відразу по мануалу робити, або навіть пройти відповідну лабу. Тож вибір за вами :)

Почнемо з того, що нам буде потрібно буде встановити nodejs, і вже потім встановлювати clasp глобально:

npm i @google/clasp -g

Якщо все добре, то наступна команда повинна вам вивести перелік доступних команд:

clasp -h

Я особисто ніяк не можу звикнути до назви цієї тулзи, постійно набираю claps ¯\_(ツ)_/¯

Тепер нам треба авторизуватися, виконайте команду login:

clasp login

Далі вам слід буде авторизуватися використовуючи ваш gmail акаунт, та надати доступи до нього. Вам також слід буде ввімкнути Google Apps Script API на сторінці налаштувань:

Після цього можна буде подивитися на перелік ваших проєктів:

clasp list

Тепер щоб стягнути код до себе використовуйте команду clasp clone та ID вашого проєкту:

clasp clone <scriptID>

Все, тепер ваш код у вас є локально, але з ним відбулись деякі зміни:

# було
actions/actionEditCard.gs
actions/actionEditNotes.gs
commands/slashBender.gs
commands/slashWhisky.gs

# стало
actions/
  |-- actionEditCard.js
  `-- actionEditNotes.js
commands/
  |-- slashBender.js
  `-- slashWhisky.js

Насправді, з теками стало набагато зручніше!

Тепер ви можете вносити зміни до коду, комітити їх до git, а потім заливати в одну команду на script.google.com:

clasp push

А тепер прочитайте дуже уважно, та запам’ятайте:

• коли ви використовуєте команду clasp pull, то всі локальні файли будут замінені на файли з script.google.com
• коли ви використовуєте команду clasp push, то всі локальні файли будут відправлені до script.google.com, та перетруть всі зміни там

Тож, робимо висновок, що щоб потім не жалітися, то слід редагувати або локально, або безпосередньо на сайті script.google.com, але не треба одночасно і тут, і там вносити зміни, закінчиться тим, що ви щось та загубите.

І ще один момент, до сайту script.google.com будуть залиті лише js-файли та файл appsscript.json, усі інші файли залишаються на вашій відповідальності, тож не забувайте змінити заливати до git.

Підключаємо eslint

Для того щоб перевірити ваш код слід до теки з проєктом додати package.json який я приводив на самому початку та запустити команду npm install:

Тепер додайте конфігураційний файл самого eslint:

import globals from 'globals';
import pluginJs from '@eslint/js';
import jsdoc from 'eslint-plugin-jsdoc';
import appsScript from 'eslint-plugin-googleappsscript';

export default [
  pluginJs.configs.recommended,
  {
    files: ['**/*.js'],
    plugins: {
      jsdoc,
      googleappsscript: appsScript,
    },
    languageOptions: {
      globals: {
        ...globals.browser,
      },
    },
    rules: {
      'comma-dangle': ['error', 'never'],
      'max-len': ['error', { code: 120, 'ignoreTrailingComments': true  }],
      'camelcase': [
        'error',
        {
          ignoreDestructuring: true,
          ignoreImports: true,
          allow: ['access_type', 'redirect_uris'],
        },
      ],
      'guard-for-in': 'off',
      'no-var': 'off',
      'no-unused-vars': 'off', // Functions aren't used.
      'no-undef': 'off', // Ignore undefined errors for global variables
    },
  }
];

Тепер можна запустити перевірку коде-стайлу вашого коду:

npx eslint

Сподіваюсь, ви не побачити ніяких помилок:

З іншого боку, у цій конфігурації досить лайтові перевірки, тож якщо маєте хист, то відправлйте pull request до мого репозіторію ;)

Структура проєкта

Як я вже писав раніше, в мене в розробці декілька проєктів, тож я намагаюсь розробити зручну структуру для розробки функціоналу. В мене поки виходить наступна структура проєкта:

Така структура дає можливість швидко найти потрібну частину коду. Далі я буду приводити приклади за алфавітом з поясненнями.

Усі екшени потрапили до відповідної теки actions, це те що відбувається коли ви клікаєте по кнопках на картці, там де прописано onClick => action:

actions/
  |-- actionEditCard.js
  |-- ...
  `-- actionEditNotes.js

Усі картки, які ми відправляємо до чату оформлюємо у окремі функції, всі ці функції до окремої теки:

cards/
  |-- cardHome.js
  `-- cardPoll.js

Насправді, бот Bender 2.0 в нас має 5 окремих карток, але деякі з них я не виносив до окремих функцій, хоча можливо це слід було зробити.

Для кожної slash-команди окрема функція, в окремому файлі у теку з усіма іншими slash-командами:

commands/
  |-- slashBender.js
  |-- ...
  `-- slashWhisky.js

Всякі різні допоміжні класи та функції, загалом то тут теж ще слід наводити лад:

components/
  |-- FormInputHandler.js
  |-- ...
  `-- Response.js

Діалоги для взаємодії з користувачами, один файл — один діалог:

dialogs/
  |-- dialogCard.js
  `-- dialogPoll.js

Події, саме тут в нас будуть жити такі важливі функції як onCardClick(), onMessage() та інші:

events/
  |-- onCardClick.js
  |-- ...
  `-- onMessage.js

Допоміжні функції:

helpers/
  `-- htmlEntities.js

Функції, для створення віджетів:

widgets/
  |-- widgetDecoratedText.js
  |-- ...
  `-- widgetTextParagraph.js

Звісно, після того як ви використовуєте команду clasp push, то вся ця структура на script.google.com перетвориться на «плоску» тека/файл.gs, але то вже не так важливо, бо ви вже майже не будете використовувати редагування у браузері.

Source Code

Код бота доступний на GitHub, реліз 7.0.0 відповідає коду з цієї статті.

P.S. Функціонал бота навмисно спрощено відносно релізу 6.0.0, це зроблено задля підготовки до публікації у Google Workspace Market.

За моїм задумом, у випадку оновлення issue (редагування або зміни статусу) ми будемо відправляти до треду оновленні дані та оновлювати картку.

Але почнемо з далеку, з далекого далеку: нам треба зробити так, щоб повідомлення до чату було відправлено не від імені користувача, а від самого бота, бо інакше ми потім не зможемо оновити картку без участі користувача.

Для цього нам треба буде зробити сервісний акаунт.

Підготовка сервісного акаунту

Для створення сервісного акаунту вам слід перейти до сторінки налаштувань вашого проєкту, а потім тицнути «Create Service Account»:

Далі, перейдіть до налаштувань цього акаунту, та створіть новий JSON ключ:

Після цього, ви отримаєте відповідний JSON файл, який буде виглядати наступним чином:

{
  "type": "service_account",
  "project_id": "bender-20",
  "private_key_id": "-----",
  "private_key": "-----BEGIN PRIVATE KEY-----\nAAAAAA\n-----END PRIVATE KEY-----\n",
  "client_email": "-----@-----.iam.gserviceaccount.com",
  "client_id": "-----",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/-----%40-----.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

Вам потрібно буде перенести до Properties вашого бота декілька полів:

Все, сервісний акаунт створено та ключі додано. Поїхали далі.

Доречі, ви можете використовувати створений акаунт якщо вам потрібно буде надати дозвіл на будь який ресурс у межах Google документів. Це так, на майбутнє.

OAuth

Наступний крок — створення OAuth Consent Screen:

Якщо ви розробляєте для Google Workspace, то у вас буде можливість обрати опцію Internal, таким чином ви обмежити використання вашого додатку та він буде «лише для своїх»

Додайте всю необхідну інформацію:

На кроці додавання скоупів, я додав лише наступні:

Після цього нас чекають ще трошки «напрягів» — для того, щоб відправити повідомлення до чату слід використовувати наступну нотацію для виклику метода Chat.Spaces.Messages.create():

Chat.Spaces.Messages.create(
  {'text': 'Hello world!'},
  event.space.name,
  {},
  {'Authorization': `Bearer ${serviceToken}`}
);

Але щоб отримати отой serviceToken нам слід підключити бібліотеку OAuth до нашого чату використовуючи ідентифікатор:

1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Створимо функцію getServiceAccessToken():

/**
 * Get Access Token by service credentials
 *
 * Examples of usage:
 * 
 *  getServiceAccessToken('messages', ['https://www.googleapis.com/auth/chat.messages.create']);
 *  getServiceAccessToken('spaces', ['https://www.googleapis.com/auth/chat.spaces.readonly']);
 */
function getServiceAccessToken(serviceName = 'messages', scopes = []) {
  const scriptProperties = PropertiesService.getScriptProperties()

  const service = OAuth2.createService(serviceName)
    .setTokenUrl('https://oauth2.googleapis.com/token')
    .setPrivateKey(scriptProperties.getProperty('PRIVATE_KEY').replace(/\\n/g, '\n')) // lifehack ^_^
    .setIssuer(scriptProperties.getProperty('CLIENT_EMAIL'))
    .setPropertyStore(scriptProperties)
    .setScope(scopes.join(' '));

  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return null;
  }

  return service.getAccessToken();
}

Все, збираємо до кучі:

const serviceToken = getServiceAccessToken('messages', ['https://www.googleapis.com/auth/chat.messages.create']);

Chat.Spaces.Messages.create(
  {'text': 'Hello world!'},
  event.space.name,
  {},
  {'Authorization': `Bearer ${serviceToken}`}
);

Результат:

Повертаємось до редагування actionNewIssue.gs, та замінимо створення повідомлення вже використовуючи сервісний токен:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionNewIssue(event) {
  //
  // ... the code was cropped
  // 

  try {
    const card = cardIssue(event, issue)
    const serviceToken = getServiceAccessToken('messages', ['https://www.googleapis.com/auth/chat.messages']);
    const message = Chat.Spaces.Messages.create(
      card, 
      event.space.name,
      {},
      {'Authorization': `Bearer ${serviceToken}`}
    );

    // Extracting the thread name from the response
    // Assuming ID is spaces/AAAAAAAA/threads/BBBBBBBB
    const [ , spaceId, , threadAndMessageId] = message.thread.name.split('/');

    const threadUrl = `https://chat.google.com/room/${spaceId}/${threadAndMessageId}/${threadAndMessageId}`;

    Logger.log(`New thread ${threadUrl}`)

    let updateData = {
      "fields": {}
    }

    updateData.fields[jiraApi.customField] = threadUrl

    jiraApi.updateIssue(response.key, updateData)
  } catch (err) {
    Logger.log('Failed to create message with error %s', err.message);
  }

  return OK()
}

На цьому ми завершили роботу по створенню issue

Web Application

Далі, нам треба додати можливість викликати нашого бота з зовні, для цього слід створити новий Deployment:

Після цього у вас з’явиться Web app URL, ви можете навіть спробувати відкрити посилання, але вас буде чекати помилка:

Так, нас чекають нові методи для обробки запитів ззовні, зустрічайте doGet() та doPost():

/**
 * GET request to Web app URL
 */
function doGet(event) {
  Logger.log(`WebHook doGet()`)

  return HtmlService.createHtmlOutput("GET request processed");
}

/**
 * POST request to Web app URL
 */
function doPost(event) {
  Logger.log(`WebHook doPost()`)

  return HtmlService.createHtmlOutput("POST request processed");
}

Спробуйте тепер постукати до того Web URL, ви отримаєте відповідь від вашого бота. Але нас цікавить саме URL, скопіюйте його, він нам знадобиться.

Автоматизація в Jira

Настав час повернутися до Jira та налаштувати автоматизацію, для цього у вас повинні бути адмінські права до проєкту. Перейдіть до Automation та створіть правила які будуть виконуватися під час роботи над issue у Jira. Я додав 3 простих правила:

• коли хтось ассайнить issue
• коли змінюється статус
• коли редагують Summary або Description

Для цього нам якраз стане у нагоді URL до Web Application, але ми трошки змінемо його відповідно до призначення кожного правила:

Так, так, ми додали параметр action до URL, і тепер можемо побудувати логіку виходячи з нього:

/**
 * POST request to Web app URL
 */
function doPost(event) {
  const action = event.parameter.action ? event.parameter.action : null

  Logger.log(`WebHook doPost("${action}")`)

  if (!event.postData || !event.postData.contents) {
    Logger.log(`POST data is empty`)
  }

  const data = JSON.parse(event.postData.contents);

  if (!data) {
    Logger.log(`POST data is invalid`)
  }

  try {
    // You can now call your bot method based on event type
    switch (action) {
      case 'assigned':
        // ...
        break;
      case 'updated':
        // ...
        break;
      case 'transitioned':
        // ...
        break;
      default:
        Logger.log("Invalid action")
        break;
    }
  } catch (e) {
    return HtmlService.createHtmlOutput(`POST request processed with error: ${e}`);
  }

  return HtmlService.createHtmlOutput("POST request processed");
}

Звірніть увагу, що я також вказав значення «Webhook body» як «Issue Data»!

Відправка відповіді у тред

Тепер починається саме цікаве — нам треба відправити повідомлення як відповідь до початкового повідомлення, посилання на яке ми зберегли у Custom Field. Почнемо звісно з того, що дістанеме те посилання, та отримаємо з нього ідентифікатор потрібного треда (цей код я додам до doPost.gs):

const scriptProperties = PropertiesService.getScriptProperties();

// JIRA threadUrl
const threadUrl = data.fields[scriptProperties.getProperty('JIRA_CUSTOM_FIELD')]

const parts = threadUrl.split('/'); // Split the URL into parts by '/'
const spaceId = parts[4]; // The space ID is expected to be the fifth part
const threadId = parts[5]; // The thread ID is expected to be the sixth part

Давайте зробимо окрему функцію, яка буде відправляти повідомлення до треду:

/**
 * @param {String} spaceId the ID of the space
 * @param {String} threadId the ID of the thread
 * @param {Object} issue the issue data from JIRA
 */
function hookAssigned(spaceId, threadId, issue) {

  Logger.log(`Send update message to space "${spaceId}" to thread "${threadId}"`)

  const space = `spaces/${spaceId}`
  const thread = `spaces/${spaceId}/threads/${threadId}`

  let message = {
    "text": "Assigned",
    "thread": {
      "name": thread
    }
  }

  const serviceToken = getServiceAccessToken('messages', ['https://www.googleapis.com/auth/chat.messages']);

  return Chat.Spaces.Messages.create(
    message,
    space,
    { "messageReplyOption": "REPLY_MESSAGE_OR_FAIL" },
    { "Authorization": `Bearer ${serviceToken}` }
  );
}

Зверніть увагу на рядок 16, таким чином слід вказати до якого треду треба відправити відповідь, а також на рядок 25, бо без цього параметру до треду теж не дістатися. Додамо виклик цієї функції до doPost.gs та спробуємо заасайнити таск на себе:

У коді бота буде цікавіше приклад відповіді у тред, але то вже самі подивитесь

Оновлення картки

Тепер нам треба ще оновити безпосередньо саму картку яку ми відправляли до спейсу, для цього не так багато треба — взяти дані з Jira, знову згенерувати оновлену картку, та відправити її назад до чату:

/**
 * @param {String} spaceId the ID of the space
 * @param {String} threadId the ID of the thread
 * @param {Object} issue the issue data from JIRA
 */
function hookUpdated(spaceId, threadId, issue) {

  Logger.log(`Update the card relative to issue "${issue.key}"`)

  const serviceToken = getServiceAccessToken('messages', ['https://www.googleapis.com/auth/chat.messages']);

  const name = `spaces/${spaceId}/messages/${threadId}.${threadId}`

  let message = Chat.Spaces.Messages.get(name, {}, { "Authorization": `Bearer ${serviceToken}` })

  message = Object.assign({}, message, cardIssue(false, issue))

  return Chat.Spaces.Messages.update(message, name, { "updateMask": "cardsV2" }, { "Authorization": `Bearer ${serviceToken}` })
}

Невеличке пояснення, у рядку 14 ми отримуємо всю-всю картку зі спейсу, у 16 рядку — генеруємо оновлену картку по новим даним з Jira, у рядку 18 — оновлюємо картку, обов’язково вказавши потрібну нам updateMask = cardsV2.

Аналогічно треба буде зробити для редагування та зміни статусу issue, в мене в результаті вийшов ось такий doPost.gs:

/**
 * POST request to Web app URL
 */
function doPost(event) {
  const action = event.parameter.action ? event.parameter.action : null

  Logger.log(`WebHook doPost("${action}")`)

  if (!event.postData || !event.postData.contents) {
    Logger.log(`POST data is empty`)
  }

  const data = JSON.parse(event.postData.contents);

  if (!data) {
    Logger.log(`POST data is invalid`)
  }

  const scriptProperties = PropertiesService.getScriptProperties();

  // JIRA threadUrl
  const threadUrl = data.fields[scriptProperties.getProperty('JIRA_CUSTOM_FIELD')]

  if (!threadUrl || threadUrl.length === 0) {
    Logger.log(`Invalid thread URL for issue "${data.key}"`)
    return HtmlService.createHtmlOutput(`POST request processed: Invalid thread URL`);
  }

  try {
    const parts = threadUrl.split('/'); // Split the URL into parts by '/'
    const spaceId = parts[4]; // The space ID is expected to be the fifth part
    const threadId = parts[5]; // The thread ID is expected to be the sixth part

    // You can now call your bot method based on event type
    switch (action) {
      case 'assigned':
        hookUpdated(spaceId, threadId, data)
        hookAssigned(spaceId, threadId, data)
        break;
      case 'updated':
        hookUpdated(spaceId, threadId, data)
        break;
      case 'transitioned':
        hookUpdated(spaceId, threadId, data)
        hookTransitioned(spaceId, threadId, data)
        break;
      default:
        Logger.log("Invalid action")
        break;
    }
  } catch (e) {
    return HtmlService.createHtmlOutput(`POST request processed with error: ${e}`);
  }

  return HtmlService.createHtmlOutput("POST request processed");
}

Діаграма послідовності

#
# https://sequencediagram.org/
#
title Google Chat + Jira 
 
actor "User" as U
materialdesignicons F0822 "Chat" as C
materialdesignicons F167A "Apps Script" as S
materialdesignicons F0303 "JIRA" as J
actor "Developer" as D

U->C:run /issue
activate C
C->S:call slashIssue()
activate S
S->C:return dialogIssue() 
deactivate S
note over U,C: [ Summary ]\n\n[ Description ]\n\n    [  Send  ]
deactivate C

space -3
C->S:call actionNewIssue()
activate S
S->J: create issue
activate J
J->S: issue key
deactivate J
S->J: get issue
activate J
J->S: issue data
deactivate J
S->C: call create()
deactivate S
 
note over U,C: Summary\n\nDescription...\n\n[ JIRA ]

space -3
C->S: link to thread
space -3
S->J: update issue

space -10
create D

D->J: — assign\n— update\n— comment\n— change status

J->S: issue data to webhook

space -3
S->C: message to thread
space -2
S->C: update card

Домашнє завдання

Розібратися як створити web-hook для того, щоб додавати коментарі з Jira до треду у Google Chat.

Я лише дам підказку, що для автоматизації краще використовувати «custom data» з можливостями «smart values»:

{
  "key": "{{issue.key}}",
  "fields": {
    "summary": "{{issue.fields.summary.jsonEncode}}",
    "description": "{{issue.fields.description.jsonEncode}}",
    "customfield_14033": "{{issue.fields.customfield_14033}}"
  },
  "comment": {
    "body": "{{issue.comments.last.body.jsonEncode}}",
    "author": {
      "displayName": "{{issue.comments.last.author.displayName}}",
      "name": "{{issue.comments.last.author.name}}"
    }
  }
}

Source Code

Код бота доступний на GitHub, реліз 6.0.0 відповідає коду з цієї статті.

З початку розповім свій задум: я хочу додати до бота можливість створення тасків та репорту помилок до обраного проєкту у Jira, усі апдейти з Jira повинні прилітати назад до нашого чату, бо користувачі повинні бачити що відбувається з issue у Jira.

Як це буде працювати:

1. користувач нашого бота викликає slash-команду /task
2. заповнює форму для таска у Jira
3. данні з форми летять до Jira, де ми створюємо відповідний issue
4. до чату відправляємо картку з посиланням на Jira issue
5. отримавши посилання на тред у чаті, додаємо його до Jira issue

Діалог

Все знов починається з додавання slash-команди до нашого боту, нагадую, що для цього нам треба перейти до налаштувань Google Chat API.

Ми вже створювали діалоги, тож не забудьте поставити позначку ✅ Opens a dialog.

Зміни до onMessage() теж не складні, нам треба лише піймати нову команду з ID 12:

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    // Checks for the presence of event.message.slashCommand
    // The ID for your slash command
    switch (event.message.slashCommand.commandId) {
      case 1:
        return slashHelp(event)
      case 10:
        return slashBender(event)
      case 11:
        return slashWhisky(event)
      case 12:
        return slashTask(event)
      case 20:
        return slashCard(event)
      case 21:
        return slashNotes(event)
      case 22:
        return slashPoll(event)
    }
  } else {
    // If the Chat app doesn't detect a slash command
    // ...
  }
}

Створимо функцію slashTask() у відповідному файлі:

/**
 * Opens a dialog in Google Chat.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function slashTask(event) {
  // nothing for now
  return dialogIssue(event)
}

Тут лише виклик dialogIssue(), тож перейдемо до відповідного dialogIssue.gs. Я відразу приведу код з обробкою помилок, бо у попередній частині ми вже детально розбирали як те робиться, а повторюватися мені ліньки:

/**
 * Create a dialog for Google Chat.
 *
 * @param {Object} event the event object from Chat API.
 * @param {Object} request the data from the form or from parameters.
 * @param {String} type the type of issue
 * @return {object} open a Dialog in Google Chat.
 */
function dialogIssue(event, request = null, type = "Task") {
  let card = {
    "action_response": {
      "type": RESPONSE_TYPE_DIALOG,
      "dialog_action": {
        "dialog": {
          "body": {
            "sections": [
              {
                "widgets": []
              }
            ],
            "name": `New ${type}`,
            "fixedFooter": {
              "primaryButton": {
                "text": "Create",
                "onClick": {
                  "action": {
                    "function": "actionNewIssue",
                    "parameters": [
                      {
                        "key": "type",
                        "value": type
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  }

  if (request && !request.summary) {
    card.action_response.dialog_action.dialog.body.sections[0].widgets.push({
        "textParagraph": {
          "text": "<font color='#c1121f'>The summary is required</font>"
        }
      }
    )
  }

  card.action_response.dialog_action.dialog.body.sections[0].widgets.push(
    {
      "textInput": {
        "label": "Summary*",
        "type": "SINGLE_LINE",
        "name": "summary",
        "hintText": "",
        "value": request ? request.summary : ""
      }
    }
  )

  if (request && !request.description) {
    card.action_response.dialog_action.dialog.body.sections[0].widgets.push({
        "textParagraph": {
          "text": "<font color='#c1121f'>The description is required</font>"
        }
      }
    )
  }

  card.action_response.dialog_action.dialog.body.sections[0].widgets.push(
    {
      "textInput": {
        "label": "Description*",
        "type": "MULTIPLE_LINE",
        "name": "description",
        "hintText": "",
        "value": request ? request.description : ""
      }
    }
  )

  card.action_response.dialog_action.dialog.body.sections[0].widgets.push({
      "textParagraph": {
        "text": "<font color='#c1121f'>*</font> - all fields are required."
      }
    }
  )

  return card
}

Тут я додав ще аргумент type, бо ми не тільки таски будемо створювати, а й репортити про помилки.

Після цього ви вже можете користуватися командою /task, та отримаєте наступний діалог:

Відправка ще не буде працювати, треба додати до onCardClick() підтримку нового action actionNewIssue:

/**
 * Responds to a CARD_CLICKED event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onCardClick(event) {
  switch (event.common.invokedFunction) {
    // 
    // ... the code was cropped
    // 
    // - /task
    case 'actionNewIssue':
      return actionNewIssue(event)
  }
}

Відповідний функціонал actionNewIssue.gs ми будемо роздивлятися по частинам.

Частина перша — валідація даних:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionNewIssue(event) {

  const parameters = event.common.parameters
  const formHandler = new FormInputHandler(event)

  const summary = formHandler.getTextValue('summary')
  const description = formHandler.getTextValue('description')
  const type = parameters.type

  // validation
  if (!summary.length || !description.length) {
    return dialogIssue(event, { summary, description })
  }

  //
  // ... the code was cropped
  // 
}

Тут в нас лише перевірка на те що поля не пусті, та у випадку помилки, ми повертаємо картку з dialogIssue() з текстом помилок:

Ви можете додати більш складні перевірки до коду, дійте на свій розсуд

Далі нам вже треба працювати з Jira, але вона ще не готова :)

Підготовка Jira проєкту

Для початку, нам потрібен JIRA проєкт, та краще окремий користувач для нашого бота, у проєкті йому треба буде надати адмінські права:

А ще треба створити персональний Access Token для вашого користувача:

Access Token який ви отримаєте слід зберегти у Properties вашого бота, туди також слід додати посилання на Jira та ключ вашого проєкту:

А тепер увага, для того, щоб у вашому issue зберігалось посилання на відповідне повідомлення у Google Chat слід додати Custom Field, типу URL до потрібних Screens у вашому проєкті. Якщо ви не розумієте про що мова — попросіть вашого адміністратора Jira зробити це. Screen мого проєкту у Jira виглядає наступним чином:

Ідентифікатор новоствореного Custom Field я також додаю до Properties:

Створення Issue

Так, Jira готова, додамо класс для взаємодією з нею, та створимо той issue:

/**
 * Class for working with JIRA API v2
 *
 * @link https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/
 */
class JiraAPI {
  constructor() {
    const scriptProperties = PropertiesService.getScriptProperties();
    this.baseUrl = scriptProperties.getProperty('JIRA_URL');
    this.token = scriptProperties.getProperty('JIRA_TOKEN');
    this.project = scriptProperties.getProperty('JIRA_PROJECT');
    this.customField = scriptProperties.getProperty('JIRA_CUSTOM_FIELD');
    this.options = {
      headers: {
        "Authorization": "Bearer " + this.token,
        "Content-Type": "application/json"
      },
      muteHttpExceptions: true // Set to false to throw exceptions for HTTP errors
    }
  }

  /**
   * Makes a HTTP request to the JIRA API with error handling.
   *
   * @param {String} endpoint - The API endpoint.
   * @param {Object} options - The options for the fetch call, including method, headers, and payload.
   * @return {Object} The JSON response from the JIRA API.
   */
  fetch(endpoint, options) {
    const url = `${this.baseUrl}${endpoint}`;

    Logger.log(url)
    Logger.log(options)

    try {
      const response = UrlFetchApp.fetch(url, Object.assign({}, options, this.options));
      const responseCode = response.getResponseCode()
      const contentText = response.getContentText()
      const contentType = response.getHeaders()['Content-Type']

      Logger.log(`Response code: ${responseCode}`)
      Logger.log(`Content type: ${contentType}`)

      if (responseCode >= 200 && responseCode < 300) {
        // it strange, FIXME
        if (contentText.length && contentType.search('application/json') !== -1) {
          return JSON.parse(contentText)
        } else {
          return response.getResponseCode()
        }
      } else {
        console.error(`JIRA API request to ${endpoint} failed with code: ${responseCode}, response: ${contentText}`);
        throw new Error(`Request failed with code: ${responseCode}`);
      }
    } catch (e) {
      console.error(`Error making request to JIRA API: ${e}`);
      throw e; // Rethrow the error after logging
    }
  }

  /**
   * Retrieves details of an issue from JIRA.
   *
   * @param {String} issueIdOrKey - The ID or key of the issue
   */
  getIssue(issueIdOrKey) {
    return this.fetch(`/rest/api/2/issue/${issueIdOrKey}`, {
      "method": "get"
    });
  }

  /**
   * Creates a new issue in JIRA.
   *
   * @param {Object} issueData
   */
  createIssue(issueData) {
    return this.fetch("/rest/api/2/issue", {
      "method": "post",
      "payload": JSON.stringify(issueData)
    });
  }

  /**
   * Updates an issue in JIRA.
   *
   * @param {String} issueIdOrKey - The ID or key of the issue
   * @param {Object} issueData
   */
  updateIssue(issueIdOrKey, issueData) {
    return this.fetch(`/rest/api/2/issue/${issueIdOrKey}`, {
      "method": "put",
      "payload": JSON.stringify(issueData)
    });
  }
}

Цей клас вміє не так багато, але нам цього вистачить:

• getIssue() — отримати issue по ключу або ідентифікатору
• createIssue() — створити issue
• updateIssue() — оновити issue по ключу або ідентифікатору

⚠️ Після додавання цього коду, ваш бот буде питати користувачів дозвіл на відправку запитів на сторонні ресурси:

Давайте продовжимо роботу над actionNewIssue.gs. Додамо другу частину до нашого пазлу — створення issue:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionNewIssue(event) {
  //
  // ... the code was cropped
  // 

  Logger.log(`New Issue: ${summary}`)

  const jiraApi = new JiraAPI()

  let issueData = {
    "fields": {
      "project": { "key": jiraApi.project },
      "summary": summary,
      "description": googleChatToJira(description),
      "issuetype": { "name": type },
      "reporter": { "name": event.user.email },
      "assignee": null,
    }
  };

  const response = jiraApi.createIssue(issueData);

  Logger.log(`The Issue Key is "${response.key}"`)

  const issue = jiraApi.getIssue(response.key)

  //
  // ... the code was cropped
  // 
}

Коли ми створюємо іssue (рядок 24), то Jira повертає не весь issue у відповідь, тому щоб отримати все що нам потрібно ми робимо ще один запит до Jira API (рядок 28).

Наш наступний крок — то сформувати картку та відправити її до чату. За формування картки буде відповідати функція cardIssue():

/**
 * Create a card for Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @param {Object} issue the JIRA issue
 *
 * @return {Object} the card object
 */
function cardIssue(event, issue) {

  const scriptProperties = PropertiesService.getScriptProperties();
  const jiraUrl = scriptProperties.getProperty('JIRA_URL')
  const jiraIssueUrl = `${jiraUrl}/browse/${issue.key}`

  Logger.log(`The URL to Issue is ${jiraIssueUrl}`)

  let card = {
    "cardsV2": [
      {
        "cardId": "presale-request",
        "card": {
          "sections": [
            {
              "widgets": [
                {
                  "decoratedText": {
                    "icon": {
                      // "iconUrl": issue.fields.issuetype.iconUrl
                      "materialIcon": {
                        "name": issue.fields.issuetype.name === "Task" ? "task" : "bug_report"
                      }
                    },
                    "text": issue.fields.summary,
                  }
                },
                {
                  "textParagraph": {
                    "text": jiraToGoogleChat(issue.fields.description)
                  }
                }
              ]
            },
            {
              "widgets": [
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "JIRA",
                        "color": {
                          "red": 0.75,
                          "green": 0.85,
                          "blue": 0.95,
                          "alpha": 1
                        },
                        "icon": {
                          "materialIcon": {
                            "name": "task"
                          }
                        },
                        "onClick": {
                          "openLink": {
                            "url": jiraIssueUrl
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            },
            {
              "widgets": [
                {
                  "columns": {
                    "columnItems": [
                      {
                        "widgets": [
                          {
                            "decoratedText": {
                              "icon": {
                                "iconUrl": issue.fields.status.iconUrl
                              },
                              "topLabel": "Status",
                              "text": issue.fields.status.name,
                              "bottomLabel": "",
                            }
                          }

                        ]
                      },
                      {
                        "widgets": [
                          {
                            "decoratedText": {
                              "icon": {
                                "knownIcon": "PERSON"
                                // "iconUrl": issue.fields.assignee.avatarUrls["48x48"]
                              },
                              "topLabel": "Assigned",
                              "text": issue.fields.assignee ? issue.fields.assignee.displayName : 'Unassigned',
                              "bottomLabel": issue.fields.assignee ? issue.fields.assignee.emailAddress : '',
                            }
                          }
                        ]
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }

  // we have the event if a user works with chat
  if (event) {
    card.cardsV2[0].card["header"] = {
      "title": event.user.displayName,
      "subtitle": event.user.email,
      "imageUrl": event.user.avatarUrl,
      "imageType": "CIRCLE"
    }

    card.cardsV2[0].card["sections"].push(
      {
        "widgets": [
          {
            "decoratedText": {
              "icon": {
                "knownIcon": "CLOCK"
              },
              "text": new Date().toLocaleString(),
            }
          }
        ]
      }
    )
  }

  return card
}

Далі буде ще складніше, нам треба відправити підготовлену картку до чату за допомоги API, бо таким чином, ми можемо отримати ідентифікатор повідомлення та зберегти його до issue у Jira (так, до того custom field). Але це не так просто зробити.

Chat API

Нашим наступним кроком буде додавання до проєкту сервіса Chats API, тож поверніться до нашого редактора коду, та жміть «+» напроти Services:

Оберіть та додайте Google Chat API (документація до API доступна на сторінці https://developers.google.com/apps-script/advanced/chat).

Тепер в нас з’явиться можливість відправляти до чату повідомлення:

Chat.Spaces.Messages.create(
  {'text': 'Hello world!'},
  event.space.name
);

Хоча, ні, ви отримаєте помилку:

GoogleJsonResponseException: API call to chat.spaces.messages.create failed with error: Request had insufficient authentication scopes.

Треба ще додати відповідний скоуп до appssript.json:

{
  "oauthScopes": ["https://www.googleapis.com/auth/chat.messages.create"], 
}

Тепер все буде працювати, звісно у користувача бот запитає потрібні дозволи, щоб писати щось у чат, та все ж таки результат буде:

У коді, ви отримаєте відповідь від API:

{ 
  name: 'spaces/AAAABBBB/messages/QWERTY.QWERTY',
  argumentText: 'Hello world!',
  text: 'Hello world!',
  sender: { type: 'HUMAN', name: 'users/111111234567890000000' },
  createTime: '2024-04-27T21:58:02.427887Z',
  space: { name: 'spaces/AAAABBBB' },
  formattedText: 'Hello world!',
  thread: { name: 'spaces/AAAABBBB/threads/QWERTY' }
}

Тож вже можна посилання на тред закинути до Jira. Повертаємось до редагування actionNewIssue.gs:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionNewIssue(event) {
  //
  // ... the code was cropped
  // 

  try {
    const card = cardIssue(event, issue)

    const message = Chat.Spaces.Messages.create(card, event.space.name);

    // Extracting the thread name from the response
    // Assuming ID is spaces/AAAAAAAA/threads/BBBBBBBB
    const [ , spaceId, , threadAndMessageId] = message.thread.name.split('/');

    const threadUrl = `https://chat.google.com/room/${spaceId}/${threadAndMessageId}/${threadAndMessageId}`;

    Logger.log(`New thread ${threadUrl}`)

    let updateData = {
      "fields": {}
    }

    updateData.fields[jiraApi.customField] = threadUrl

    jiraApi.updateIssue(response.key, updateData)
  } catch (err) {
    Logger.log('Failed to create message with error %s', err.message);
  }

  return OK()
}

Спробуємо створити таск використовуючи команду /task та отримаємо у чаті наступну картку:

В Jira буде створено відповідний issue:

І це вже непоганий результат. Мені подобається що в нас виходить.

Діаграма послідовності

Приведу ще діаграму послідовності, вона наче не складна вийшла:

#
# https://sequencediagram.org/
#
title Dialogs
 
actor "User" as U
materialdesignicons F0822 "Chat" as C
materialdesignicons F167A "Apps Script" as S
materialdesignicons F0303 "JIRA" as J

U->C:run /issue
activate C
C->S:call slashIssue()
activate S
S->C:return dialogIssue() 
deactivate S
note over U,C: [ Summary ]\n\n[ Description ]\n\n    [  Send  ]
deactivate C

space -3
C->S:call actionNewIssue()
activate S
S->J: create issue
activate J
J->S: issue key
deactivate J
S->J: get issue
activate J
J->S: issue data
deactivate J
S->C: call create()
deactivate S
 
note over U,C: Summary\n\nDescription...\n\n[ JIRA ]

space -3
C->S: link to thread
space -3
S->J: update issue

Тож на цьому першу частину я вважаю можна завершувати, але це ще не весь функціонал який я хотів реалізувати, але можливо вам його вистачить.

Діалог

Почнемо знов з додавання slash-команди до нашого боту, нагадую, що для цього нам треба перейти до налаштувань Google Chat API.

Ми вже створювали діалоги, тож не забудьте поставити позначку ✅ Opens a dialog.

Зміни до Code.gs теж не складні, нам треба лише піймати нову команду з ID 22:

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    // Checks for the presence of event.message.slashCommand
    // The ID for your slash command
    switch (event.message.slashCommand.commandId) {
      case 1:
        return slashHelp(event)
      case 10:
        return slashBender(event)
      case 11:
        return slashWhisky(event)
      case 20:
        return slashCard(event)
      case 21:
        return slashNotes(event)
      case 22:
        return slashPoll(event)
    }
  } else {
    // If the Chat app doesn't detect a slash command
    // ...
  }
}

Створимо функцію slashPoll() у відповідному файлі:

/**
 * Opens a dialog in Google Chat.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function slashPoll(event) {
  // nothing for now
  return dialogPoll(event)
}

Тут в нас буде лише виклик dialogPoll(), так зроблено для подальшого розширення функціоналу, наразі у dialogPoll.gs буде лише створення діалогу:

/**
 * Opens a dialog in Google Chat.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function dialogPoll(event) {
  return {
    "action_response": {
      "type": "DIALOG",
      "dialog_action": {
        "dialog": {
          "body": {
            "sections": [
              {
                "header": "Create New Poll",
                "collapsible": true,
                "uncollapsibleWidgetsCount": 4,
                "widgets": [
                  {
                    "textParagraph": {
                      "text": "Enter the poll topic and up to 10 choices in the poll. Blank options will be omitted."
                    }
                  },
                  {
                    "textInput": {
                      "name": "question",
                      "label": "Ask a question*",
                    }
                  },
                  {
                    "textInput": {
                      "name": "option1",
                      "label": "1️⃣ Option*",
                    }
                  },
                  {
                    "textInput": {
                      "name": "option2",
                      "label": "2️⃣ Option*",
                    }
                  },
                  /* Options 3, 4, 5 .. 9 */
                  {
                    "textInput": {
                      "name": "option10",
                      "label": " Option",
                    }
                  }
                ]
              },
              {
                "header": "Options",
                "collapsible": false,
                "widgets": [
                  {
                    "decoratedText": {
                      "text": "Multiple Answers",
                      "bottomLabel": "If this checked the voters can choose more than option",
                      "switchControl": {
                        "name": "multi",
                        "selected": true,
                        "controlType": "SWITCH"
                      }
                    }
                  }
                ]
              }
            ],
            "fixedFooter": {
              "primaryButton": {
                "icon": {
                  "materialIcon": {
                    "name": "send"
                  }
                },
                "text": "Send",
                "onClick": {
                  "action": {
                    "function": "actionNewPoll"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Нагадую, що для створення діалогів та карток зручно використовувати сервіс Card Builder

Після цього ви вже можете користуватися командою /poll, та навіть зможете отримати наступний діалог:

Тепер слід додати обробку onclick-функції з попереднього лістингу кода, для цього внесіть зміни до onCardClick(event):

/**
 * Responds to a CARD_CLICKED event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onCardClick(event) {
  switch (event.common.invokedFunction) {
 
    //
    // ... the code was cropped
    //

    // - /poll
    case 'actionNewPoll':
      return actionNewPoll(event)
  }
}

Знов створимо нову функцію actionNewPoll() у новому файлі actionNewPoll.gs:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionNewPoll(event) {

  const formHandler = new FormInputHandler(event)

  formHandler.getTextValue('question')
  formHandler.getBooleanValue('multi')
  formHandler.getTextValue('option1')
  // ...
  formHandler.getTextValue('option10')

  //
  // ... the code was cropped
  //

}

Тут трохи треба призупинитися, та нагадати, що клас FormInputHandler ми створювали раніше, та він відповідає за отримання даних з форми, а зараз ми лише додали новий метод getBooleanValue(), та я гадаю з ним не виникне непорозумінь.

Але я не просто хочу отримати дані, я хочу зробити валідацію, щоб можна було внести зміни у форму у випадку, якщо виникла помилка.
Для цього я додам декілька перевірок, і у випадку невдачі буду повертати попередню форму з текстом помилки:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionNewPoll(event) {

  const formHandler = new FormInputHandler(event)

  let data = {
    question: formHandler.getTextValue('question'),
    multi: formHandler.getBooleanValue('multi'),
    options: []
  }

  for (let i = 1; i <= 10; i++) {
    let option = formHandler.getTextValue(`option${i}`)
    if (option.length) {
      data.options.push(option)
    }
  }

  if (!data.question.length) {
    return dialogPoll(event, data)
  }

  if (data.options.length < 2) {
    return dialogPoll(event, data)
  }

  //
  // ... the code was cropped
  //

}

У цьомі коді я формую об’єкт data, щоб було зручніше працювати з даними з форми, та роблю усього дві перевірки — що в нас є питання і що варіантів відповідей не менше двох. Коли виникає помилка я повертаю знов діалог, який ми додали до функції dialogPoll(). Нам лише треба внести зміни, щоб на формі зберігались попередньо внесені дані та відображався текст помилки:

/**
 * Opens a dialog in Google Chat.
 *
 * @param {Object} event the event object from Chat API.
 * @param {Object} data the data from a form.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function dialogPoll(event, data = null) {

  let card = {
    'action_response': {
      'type': 'DIALOG',
      'dialog_action': {
        'dialog': {
          'body': {
            'sections': [
              {
                'header': 'Create New Poll',
                'collapsible': true,
                'uncollapsibleWidgetsCount': 4,
                'widgets': [
                  {
                    "textParagraph": {
                      "text": "Enter the poll topic and up to 10 choices in the poll. Blank options will be omitted."
                    }
                  },
                  {
                    'textInput': {
                      'name': 'question',
                      'label': 'Ask a question*',
                      'value': data && data.question ? data.question : ''
                    }
                  },
                  {
                    'textInput': {
                      'name': 'option1',
                      'label': '1️⃣ Option*',
                      'value': data && data.options && data.options[0] ? data.options[0] : ''
                    }
                  }
                  /* Options 2, 3, 4, 5 .. 10 */
                ]
              },
              {
                "header": "Options",
                "collapsible": false,
                "widgets": [
                  {
                    "decoratedText": {
                      "text": "Multiple Answers",
                      "bottomLabel": "If this checked the voters can choose more than option",
                      "switchControl": {
                        "name": "multi",
                        "selected": (data && data.multi) ? data.multi : true,
                        "controlType": "SWITCH"
                      }
                    }
                  }
                ]
              }
            ],
            'fixedFooter': { /* ... */ }
          }
        }
      }
    }
  }

  if (data) {
    let section = {
      'widgets': [
        {
          "textParagraph": {
            "text": "<b><font color='#ff0000'>Please fill in all required data, including the question and two or more options.</font></b>"
          }
        }
      ]
    }

    card.action_response.dialog_action.dialog.body.sections.unshift(section)
  }

  return card;
}

У такий спосіб ми повернемо користувачу форму редагування голосування, та не загубимо його дані (зверніть увагу на рядки 9,32,39 та 55). Для більшої інформативності додаємо текст помилки, щоб користувач не розгубився, що наразі відбувається (рядок 81).

Картка для голосування

Перевірки всі зроблені, настав час створити картку для голосування та відправити її до чату. Відразу продемонструю дизайн картки, і потім приведу відповідний код до неї:

Повернемось на попередній крок, та додамо до функції actionNewPoll() виклик іншої функції — cardPoll():

/**
 * @param {Object} event the event object from Google Chat
 */
function actionNewPoll(event) {
  const formHandler = new FormInputHandler(event)

  let data = {
    question: formHandler.getTextValue('question'),
    multi: formHandler.getBooleanValue('multi'),
    options: []
  }

  //
  // ... the code was cropped
  //

  return cardPoll(event, data)
}

Звісно реалізація cardPoll() буде у відповідному файлі:

/**
 * @param {Object} event the event object from Google Chat
 * @param {Object} data the data from the request
 * 
 * @return {Object} the card object
 */
function cardPoll(event, data) {
  let card = {
    'actionResponse': {
      'type': 'NEW_MESSAGE',
    },
    "cardsV2": [
      {
        "cardId": "poll",
        "card": {
          "header": {
            "title": event.user.displayName,
            "subtitle": event.user.email,
            "imageUrl": event.user.avatarUrl,
            "imageType": "CIRCLE"
          },
          "sections": []
        }
      }
    ]
  }

  let sections = [];

  sections.push({
    "widgets": [
      {
        "decoratedText": {
          "text": data.question,
          "endIcon": {
            "materialIcon": {
              "name": data.multi ? "checklist_rtl" : "rule"
            }
          }
        }
      }
    ]
  })

  for (let i = 0; i < data.options.length; i++) {
    sections.push({
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "decoratedText": {
            "startIcon": {
              "materialIcon": {
                "name": "arrow_right"
              }
            },
            "topLabel": data.options[i],
            "text": "⬜️⬜️⬜️⬜️⬜️⬜️⬜️⬜️⬜️⬜️",
            "bottomLabel": "0%",
            "button": {
              "text": "vote",
              "icon": {
                "materialIcon": {
                  "name": "add"
                }
              },
              "altText": "Vote",
              "onClick": {
                "action": {
                  "function": "actionVotePoll",
                  "parameters": [
                    {
                      "key": "option",
                      "value": `${i+1}`
                    }
                  ]
                }
              }
            }
          }
        }
      ]
    })
  }

  card.cardsV2[0].card.sections = sections

  return card
}

Тут з основного — додано виклик функції actionVotePoll() у action кнопки, і про неї розповім далі.

Оновлення картки

Для початку звісно знов повернемося до onCardClick(), та додамо підтримку та виклик функції actionVotePoll():

/**
 * Responds to a CARD_CLICKED event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onCardClick(event) {
  switch (event.common.invokedFunction) {
 
    //
    // ... the code was cropped
    //

    // - /poll
    case 'actionNewPoll':
      return actionNewPoll(event)
    case 'actionVotePoll':
      return actionVotePoll(event)
  }
}

Далі будемо створювати вже саму функцію у файлі actionVotePoll.gs:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionVotePoll(event) {

  let parameters = event.common.parameters

  let card = event.message.cardsV2[0]

  //
  // ... the code was cropped
  //


}

Давайте поступово — окрім параметрів функції (рядок 6) нас загалом цікавить уся картка яка в нас є у чаті (рядок 8).

А тепер ключовий момент — ми можемо оновити картку у чаті після того як користувач буде взаємодіяти з нею:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionVotePoll(event) {

  let parameters = event.common.parameters

  let card = event.message.cardsV2[0]

  //
  // ... the code was cropped
  //

  return {
    "actionResponse": {
      "type": "UPDATE_MESSAGE",
    },
    "cardsV2": [ card ]
  }
}

Використовуючи цю можливість можна зберігати голоси користувачів як частину картки:

Cards are usually displayed below the text body of a Chat message, but can situationally appear other places, such as dialogs. Each card can have a maximum size of 32 KB.

Тож залишилось лише реалізувати цю логіку:

/**
 * @param {Object} event the event object from Google Chat
 */
function actionVotePoll(event) {

  let parameters = event.common.parameters

  let sections = event.message.cardsV2[0].card.sections

  let multi = sections[0].widgets[0].decoratedText.endIcon.materialIcon.name === "checklist_rtl"

  let option = parseInt(parameters.option)

  let user = event.user.displayName
  let avatar = event.user.avatarUrl

  let widget = {
    "decoratedText": {
      "startIcon": {
        "iconUrl": avatar
      },
      "text": user,
    }
  }

  let votes = []

  for (let i = 1; i < sections.length; i++) {
    let widgets = sections[i].widgets
    let people = []

    if (widgets.length > 1) {
      for (let j = 1; j < widgets.length; j++) {
        people.push(
          widgets[j].decoratedText.text
        )
      }
    }

    votes[i] = people.filter(n => n)

    Logger.log(`Votes for "${i}": ${votes[i].length}`, votes[i])
  }

  // update votes
  let index = votes[option].indexOf(user)
  if (index === -1) {
    Logger.log(`+1 vote for ${option}`)
    votes[option].push(user)
    sections[option].widgets.push(widget)
  } else {
    Logger.log(`-1 vote for ${option}, index is ${index}`)
    votes[option].splice(index, 1);
    sections[option].widgets.splice(index + 1, 1)
  }

  // for non-multi voting poll
  // remove user votes for another options
  if (!multi) {
    for (let i = 1; i < sections.length; i++) {
      if (i === option) {
        continue
      }
      let index = votes[i].indexOf(user)
      if (index !== -1) {
        Logger.log(`-1 vote for ${i}, index is ${index}`)
        votes[i].splice(index, 1)
        sections[i].widgets.splice(index + 1, 1)
      }
    }
  }

  Logger.log(`Vote for "${option}": ${votes[option].length}`, votes[option])

  // removed empty value from position 0
  votes.shift()

  let percentages = calculatePercentages(votes)

  Logger.log(`%:`, percentages)

  for (let i = 1; i < sections.length; i++) {
    sections[i].widgets[0].decoratedText.text = fillProgressBar(percentages[i - 1])
    sections[i].widgets[0].decoratedText.bottomLabel = `${percentages[i - 1]}%`
  }

  return {
    "actionResponse": {
      "type": "UPDATE_MESSAGE",
    },
    "cardsV2": [
      {
        "cardId": "poll",
        "card": {
          "header": event.message.cardsV2[0].card.header,
          "sections": sections
        }
      }
    ]
  }
}

/**
 * @param {Array} data
 */
function calculatePercentages(data) {
  // Flatten the array by concatenating all sub-arrays
  let flattenedArray = [].concat.apply([], data);

  // Calculate total number of items across all sub-arrays
  let totalItems = flattenedArray.length

  // Filter out duplicates by using a temporary object where properties represent the unique items found so far
  let uniqueItems = flattenedArray.filter(function(item, index, self) {
    return self.indexOf(item) === index;
  });

  let totalUniqueItems = uniqueItems.length;

  // Calculate the percentage of each subarray based on the total items
  return data.map(function (sublist) {
    return totalUniqueItems ? Math.round(sublist.length / totalUniqueItems * 100) : 0;
  });
}

/**
 * @param {Number} percentage
 */
function fillProgressBar(percentage) {
  let totalBoxes = 10; // Total number of boxes in the text
  let filledBoxes = Math.round(percentage / 10); // Calculate number of filled boxes (each box represents 10%)
  let progressBar = ""; // Initialize an empty string for the progress bar

  // Build the progress bar string
  for (let i = 0; i < totalBoxes; i++) {
    if (i < filledBoxes) {
      progressBar += ""; // Add a filled box for each 10% completed
    } else {
      progressBar += "⬜️"; // Fill the rest with empty boxes
    }
  }

  return progressBar;
}

У цьому коді для зберігання голосів використовуються віджети, тож кожна опція — це окрема секція, кожен голос — окремий віджет. Коли користувач голосує, то ми отримуємо всю картку, розібравши її на частинки можна відновити результати голосування та внести зміни.

Діаграма послідовності

Хотів привести діаграму послідовності, можливо вона допоможе вам краще розібратися у функціоналі:

title The Poll

actor User

materialdesignicons F0822 "Chat" as C


participantgroup Apps Script
participant slashPoll()
participant dialogPoll()
participant actionNewPoll()
participant cardPoll()
participant actionVotePoll()
end

User->C: /poll


create slashPoll()

C->slashPoll(): onMessage()
activate slashPoll()
space -6
create dialogPoll()
slashPoll()->dialogPoll(): 
activate dialogPoll()
dialogPoll()->slashPoll(): The Form Card
deactivate dialogPoll()
slashPoll()->C: The Form Card
deactivate slashPoll()

space -2
box over C:\n\n[  Question Input ]\n\n[  Answers 1..10 ]\n\n[  Options  ]\n\n[ Send ]

space -7
create actionNewPoll()
C->actionNewPoll(): The Form Data
activate actionNewPoll()
actionNewPoll()-->dialogPoll(): The Form Data\nValidation Error
space -4
dialogPoll()-->C: The Form Card\nWith Data and Error

space -10
create cardPoll()
actionNewPoll()->cardPoll(): Build the Poll Card
activate cardPoll()
cardPoll()->actionNewPoll(): The Poll Card
deactivate cardPoll()

actionNewPoll()->C: The Poll Card

deactivate actionNewPoll()

space -2
box over C:\n\n  Question  \n\n  Answers 1  [+ vote ]\n\n  Answers 2  [+ vote ]\n

space -8
create actionVotePoll()

C->actionVotePoll(): Vote for Options
activate actionVotePoll()
actionVotePoll()->C: The Poll Card + data
deactivate actionVotePoll()


space -2
box over C:\n\n  Question  \n\n  Answers 1  [+ vote ]\n\n  Answers 2  [+ vote ]\n\n  data as part of card

Source Code

Код бота доступний на GitHub, реліз 5.1.0 відповідає коду з цієї статті.

P.S.

З початку був реліз 5.0.0, але я потім подивився на той код, та вирішив навести в ньому лад, саме тому краще дивитися версію 5.1.0 :)