Інтеграція Google Apps Script з API Kommo CRM – як ми вирішили проблему та автоматизували процеси

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

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

У цій статті ми розглянемо, як саме Google Apps Script допоміг трансформувати процеси та вирішити проблему з інтеграцією.

#1. Make не допоміг

OAuth (скорочення від англ. Open Authorization) — це відкритий стандарт авторизації, який дозволяє користувачам відкривати доступ до своїх приватних даних (фотографії, відео, списки контактів), що зберігаються на одному сайті, іншому сайту, без необхідності вводу імені користувача та паролю. OAuth 2.0 фокусується на простоті розробки клієнтської частини, забезпечуючи спеціальні потоки дозволу для вебзастосунків, настільних застосунків, мобільних телефонів.

У нас була проблема: не могли зрозуміти, як правильно зробити OAuth інтеграцію. Навіть доходило до такого, що у нас з іншим розробником два абсолютно однакових рішення, тільки одне працює а інше – ні, бо десь там в запиті зайву літеру поставили. Щодо доступу, просто при будь-якій спробі писало: «У доступі відмовлено», без будь-якого пояснення. Треба було правильно створити Kommo інтеграцію та правильно її підключити в Make.

Спроба вирішити цю проблему через сервіс Make не принесла бажаного результату через його обмеження. Тому ми вирішили звернутися до Google Apps Script, що в кінці кінців стало нашим рішенням. Влад, один із членів нашої команди, знайшов спосіб розібратися з авторизацією, і це стало переломним моментом у нашій роботі.

Як ми дійшли до вирішення питання

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

Перше, до чого ми дійшли, це розуміння того, що інструменти, які надає сервіс Make, можуть бути адаптовані під наші потреби за допомогою додаткової автоматизації. Наприклад, ми можемо генерувати API-ключ (APK), створювати за його допомогою запити і отримувати доступ до необхідної інформації.

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

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

Ефективна розробка: використання існуючих методів бібліотеки для адаптації під специфічні завдання

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

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

#2. Як виглядає код

 function getKOMMOAuthToken() {
 var projectID = "someId";
 var datasetID = "someDataSetId";
 var clientId = "someClientId";
 var clientSecret = "someClientSecret";
 var redirectUris = "someRedirectUris";
 var authorizationCode = getRefreshToken_(projectID);
 var url = "someUrl";
 // Define the token request parameters
 var payload = {
 "client_id": clientId,
 "client_secret": clientSecret,
 "grant_type": 'refresh_token',
 "refresh_token": authorizationCode,
 "redirect_uri": redirectUris
 };
 // Make the token request
 var data = {
 method: "POST",
 headers:{
 "Content-Type": "application/json"
 },
 payload: JSON.stringify(payload)
 };
 var response = UrlFetchApp.fetch(url, data);
 var tokenData;
 var refreshToken;
 var accessToken;
 if (response.getResponseCode() === 200) {
 tokenData = JSON.parse(response.getContentText());
 Logger.log(JSON.parse(response.getContentText()));
 accessToken = tokenData.access_token;
 refreshToken = tokenData.refresh_token;
 } else {
 Logger.log("Error: " + JSON.parse(response.getContentText()));
 }
 setRefreshToken_(projectID, refreshToken);
 setAccessToken_(projectID, accessToken);
}
function setRefreshToken_(projectID ,refreshToken) {
 //var ss = SpreadsheetApp.getActiveSpreadsheet(); // Get the active spreadsheet
 // var sheet = refreshTokenSS_.getSheetByName('refresh_token'); // Get the "refresh_token" sheet
 // sheet.getRange('A1').setValue(refresh_token); // Set the value in cell A1
 var refreshTokenTableID = "customname.refresh_token";
 var sqlQuery_PutRefreshToken = `INSERT INTO ${refreshTokenTableID} (refresh_token, timestamp) VALUES ("${refreshToken}", CURRENT_TIMESTAMP())`;
 var refreshTokenRequest = {
 query: sqlQuery_PutRefreshToken,
 useLegacySql: false
 }
 var queryResults = BigQuery.Jobs.query(refreshTokenRequest, projectID);
 Logger.log(`QUERY to set refresh token\n\nQUERY RESULT: ${queryResults.jobComplete}`);
}
function getRefreshToken_(projectID) {
 //var ss = SpreadsheetApp.getActiveSpreadsheet(); // Get the active spreadsheet
 // var sheet = refreshTokenSS_.getSheetByName('refresh_token'); // Get the "refresh_token" sheet
 // var refresh_token = sheet.getRange('A1').getValue(); // Get the value from cell A1
 var refreshTokenTableID = "customname.refresh_token";
 var refreshTokenTableID = "customname.refresh_token";
 var sqlQuery_GetRefreshToken = `SELECT * FROM ${refreshTokenTableID} ORDER BY timestamp DESC LIMIT 1`;
 var refreshTokenRequest = {
 query: sqlQuery_GetRefreshToken,
 useLegacySql: false
 }
 var queryResults = BigQuery.Jobs.query(refreshTokenRequest, projectID);
 Logger.log(`QUERY to get refresh token\n\nQUERY RESULT: ${queryResults.jobComplete}`);
 var refreshToken = queryResults.getRows()[0].f[0].getV();
 return refreshToken;
}
function getAccessToken() {
 //var ss = SpreadsheetApp.getActiveSpreadsheet(); // Get the active spreadsheet
 // var sheet = refreshTokenSS_.getSheetByName('access_token'); // Get the "access_token" sheet
 // var access_token = sheet.getRange('A1').getValue(); // Get the value from cell A1
 // return access_token;
 var projectID = "customname";
 var accessTokenTableID = "customname.access_token";
 var sqlQuery_GetAccessToken = `SELECT * FROM ${accessTokenTableID} ORDER BY timestamp DESC LIMIT 1`;
 var accessTokenRequest = {
 query: sqlQuery_GetAccessToken,
 useLegacySql: false
 }
 var queryResults = BigQuery.Jobs.query(accessTokenRequest, projectID);
 Logger.log(`QUERY to get access token\n\nQUERY RESULT: ${queryResults.jobComplete}`);
 var accessToken = queryResults.getRows()[0].f[0].getV();
 return accessToken;
}
function setAccessToken_(projectID, accessToken) {
 //var ss = SpreadsheetApp.getActiveSpreadsheet(); // Get the active spreadsheet
 // var sheet = refreshTokenSS_.getSheetByName('access_token'); // Get the "access_token" sheet
 // sheet.getRange('A1').setValue(access_token); // Set the value in cell A1
 var accessTokenTableID = "customname.access_token";
 var sqlQuery_PutAccessToken = `INSERT INTO ${accessTokenTableID} (access_token, timestamp) VALUES ("${accessToken}", CURRENT_TIMESTAMP())`;
 var accessTokenRequest = {
 query: sqlQuery_PutAccessToken,
 useLegacySql: false
 }
 var queryResults = BigQuery.Jobs.query(accessTokenRequest, projectID);
 Logger.log(`QUERY to set access token table\n\nQUERY RESULT: ${queryResults.jobComplete}`);
}
function test() {
 Logger.log(getAccessToken());
}

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

Чому саме Apps Script? Порівняння із Make

Вибір на користь Apps Script обумовлений багатьма факторами, серед яких важливе місце займає легкість інтеграції з продуктами Google, можливість використовувати JavaScript для автоматизації завдань та відсутність потреби в хостингу. Також цей інструмент дозволяв ефективно логувати процеси та легше інтегруватися з різноманітними API.

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

Як почати працювати з AppScript

1. Quickstart
2. Google Apps Script: A Beginner’s Guide
3. З чого почати вивчення Google Apps Script?
4. Скрипти Google Apps Script у документах, таблицях та презентаціях
5. The Beginner’s Guide to Google Sheets and App Script-1

Як працює логування скриптів на Appscript у Google Cloud

Використання Google Apps Script значно спрощує роботу з внутрішніми API Google. У Google є широкий спектр API для різноманітних задач, і Apps Script дозволяє легко інтегруватися з ними, не залежно від мови програмування, чи то Python або інша. Для цього вам просто потрібно додати необхідний API до вашого проекту через консоль розробника, і ви зможете відразу почати його використовувати у своїх скриптах з використанням спеціалізованих методів Apps Script.

Ось декілька корисних посилань, які допоможуть розібратись із цим:

1. The Сloud Logging
2. Cloud Logging documentation
3. Logging query language

Якщо ви хочете вирішити проблему з отриманням лідів, використовуючи Google Apps Script та інтеграцію з Коммо, найефективніший спосіб – це поєднання вивчення документації та практичного застосування. Перш за все, ознайомтеся з офіційною документацією Google Apps Script та документацією API Комо, щоб зрозуміти основні принципи роботи з цими інструментами. Навіть якщо ви маєте базові знання JavaScript, це буде достатньо для старту.

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

1. Apps Script samples overview – тут ви знайдете різноманітні зразки скриптів, які можна адаптувати під свої завдання.
2. Google Developers Codelabs – інтерактивні практичні лабораторії, які крок за кроком проведуть вас через процес створення різноманітних застосунків і скриптів.
3. Expand capabilities with API –знайомтеся з прикладами використання API для інтеграції з системою Комо.

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

#3. Виклики, з якими ми зустрілись при інтеграції

Під час розробки нашої бібліотеки на Google Apps Script ми зіткнулися з певними технічними обмеженнями та викликами, які вимагали від нас креативних рішень та глибшого розуміння інструментів, що ми використовували.

Обмеження API та їх обхід

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

function getLeadsByCreateDate(pipelineId, dateFrom, dateTo) {
let accessToken = getAccessToken();
let page = 1;
let collectedData = [];
do{
let responseData = makeGETRequestToKOMMOLeadsCreateDate_(accessToken, pipelineId, dateFrom, dateTo, page);
if(responseData == null) break;
page++;
collectedData = [...collectedData, ...responseData._embedded.leads];
} while(true);
Logger.log(collectedData.length + " Leads")
return collectedData;
}

Ось, як ми вирішили це питання!

Іншим важливим обмеженням був 6-хвилинний ліміт на виконання скриптів в Google Apps Script. На відміну від проблеми з кількістю записів, це обмеження ми не намагалися обійти, оскільки воно було фіксованою частиною платформи.

Робота зі сторонніми бібліотеками та синтаксисом

На відміну від деяких мов програмування, де для роботи з криптографією чи обробкою даних потрібно підключати сторонні бібліотеки, в Google Apps Script багато необхідних інструментів вже вбудовано. Це спростило нам роботу, але вимагало додаткового часу на вивчення відповідних методів і документації.

Utilities Service – одна з бібліотек, яка вам знадобиться у роботі.

#4. Структура проєкту та неймінг файлів

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

Правила і поради щодо неймінгу

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

Правила та поради щодо неймінгу у файлах:

1. Нотации в программировании: правила именования
2. Именование файлов в JavaScript
3. БЕМ
4. The Art of Naming: Best Practices for File Naming
5. Understanding The JavaScript Filename Naming Convention: A Comprehensive Guide

Чіткий та зрозумілий неймінг файлів та методів є ключовим для ефективної роботи з кодом. Наприклад, коли ви відкриваєте файл, назва якого відповідає певній функції, ви одразу розумієте, що в ньому містяться методи для роботи з лідами з системи Комо за допомогою ID. Така організація дозволяє легко знайти потрібну функціональність і розібратися в коді, особливо коли використовуються коментарі для додаткових пояснень.

#5. П’ять порад для роботи з великим масивом коду

1. Модульність коду. Організуйте код у модулі або пакети, що відповідають за певні функції системи. Це не тільки спростить розуміння архітектури проекту новими розробниками, але й дозволить легше вносити зміни та оновлення.

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

3. Документація. Ретельна документація та коментарі у коді необхідні для швидкого орієнтування в проекті. Важливо оновлювати документацію у відповідності до змін у коді, щоб уникнути плутанини.

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

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

#6. Процес тестування та відлагодження коду

Одним із найбільш часозатратних і складних етапів у розробці нашої бібліотеки на Google Apps Script стало тестування. Часто ми стикалися з ситуаціями, коли неправильно поставлений символ у запиті, наприклад, знак питання замість потрібного знаку, міг призводити до повного збою програми. Такі дрібні помилки викликали значні труднощі, оскільки система не завжди надавала чітке пояснення причин збою. Це змушувало нас витрачати багато часу на детальний аналіз та перевірку коду, щоб виявити і виправити помилку.

Під час тестування ми використовували декілька методів. Один із них – це робота з інтеграційною платформою Make (раніше відомою як Integromat), яка дозволила нам візуалізувати процеси та легше ідентифікувати моменти збоїв. Розширення для Make, Integromat DevTools, зокрема, стало незамінним інструментом, що допомагало нам наочно відстежувати всі процеси та помилки.

Крім того, велику роль у процесі відлагодження відіграла консоль у самому Google Apps Script. Вона дозволяла безпосередньо у проекті переглядати помилки та виводити дані для аналізу. Це було особливо корисно для детального розуміння того, де саме і чому виникали проблеми. Більш того, глобальна консоль проєкту надавала можливість детальніше аналізувати поведінку скрипта і ефективніше знаходити помилки.

Хоча тестування було складним і вимагало багато часу, воно стало ключовим етапом, який дозволив нам забезпечити високу якість та надійність нашої бібліотеки.

Використання комбінованого підходу з використанням інструментів відлагодження та активного аналізу коду допомогло нам ефективно вирішити виявлені проблеми.

Використання бібліотеки в EdTech компанії

Одним із важливих аспектів нашої роботи стала можливість використовувати створену бібліотеку для спрощення роботи інших команд. Наприклад, метод для додавання нотаток до ліда значно полегшував рутинні завдання і зменшував кількість помилок.

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

Завдяки цьому досвіду ми не лише вирішили конкретну задачу, але й збагатили свої знання та навички у сфері програмування і автоматизації процесів. Вивчення Google Apps Script відкрило перед нами нові можливості для розвитку та оптимізації робочих процесів.

Висновок

Розробка бібліотеки на Google Apps Script була цікавим викликом, який дозволив нам глибше зануритися в можливості цієї платформи. Попри деякі технічні обмеження та складнощі, ми змогли адаптувати наш підхід та знайти ефективні рішення для автоматизації процесів роботи з даними.