REST.js: Javascript-активити и конструктор роботов

Установить приложение на Маркете Битрикс24

REST.js позволяет создавать роботы, используя все возможности JavaScript и REST API Битрикс24.

Два варианта использования REST.js

Javascript-активити, устнавливаемое вместе с приложением

На вкладке "Javascript-активити" можно запустить готовые примеры или свой код, а затем поместить его в параметре активити

У Javascript-активити один опциональный параметр: inputText. Он используется для передачи строковых значений, а для чисел и дат используйте Вставку значения прямо в параметре "Javascript-код"

Конструктор роботов, для создания своих роботов "с нуля"

На вкладке "Конструктор роботов" можно добавлять роботов с любыми входными и выходными параметрами

Преимущество REST.js над php-скриптами, использующими вебхуки:

• более безопасно: используется протокол OAuth, а не статический секретный код в вебхуке
• моментальное внедрение: роботы доступны сразу после нажания кнопки "Установить" или "Сохранить"
• не нужно платить за хостинг: в рамках подписки доступно бесплатно 3000 вызовов робота

Примеры роботов

Робот в REST.js аналогичен облачной Javascript-функции. Он может иметь входные и выходные параметры.

Вот примеры роботов:

1. Удаление пробелов

   return inputText.trimStart().trimEnd();

2. Смена ответственного пользователя

   
   const userId = /* userId первого пользователя */;
   const newResponsibleId = /* userId второго пользователя */;
   
   const deals = bx24.fetchList('crm.deal.list', {
       filter: {
           ASSIGNED_BY_ID: userId
       }
   });
   
   const commands = [];
   for (const deal of deals) {
       commands.push(['crm.deal.update', {
           id: deal.ID,
           fields: { 'ASSIGNED_BY_ID': newResponsibleId }
       }]);
       if (commands.length === 50) {
           bx24.callBatch(commands);
           commands.length = 0; // Очистка массива команд
       }
   }
   
   if (commands.length > 0) {
       bx24.callBatch(commands);
   }
               

Больше примеров по ссылкам:

• Поиск по регулярному выражению
• Поиск сделок
• Добавить комментарий в таймлайн сделки
• Назначить компанию сделкам
• Форматирование имени контакта
• Поиск контактов по ответственному
• Добавление события календаря
• Сделки с незавершенными делами

Описание методов REST.js

Для обращения к Битрикс24 используется предопределенный объект bx24

1. Основной метод вызова API: bx24.callMethod(methodName, parameters)
   • callMethod возвращает поле result ответа Битрикс24, поэтому можно обращаться к данные напрямую, без необходимости указания ".result". Пример:

     
     const deal = bx24.callMethod('crm.deal.get', { id: dealId });
     return deal.ASSIGNED_BY_ID;
                         

2. Для получения списков элементов в bx24 имеется несколько методов. Эти методы являются функциями-генераторами, то есть возвращают итератор.
   • Для получения списков через старые методы (crm.deal.list и другие) используйте bx24.fetchList(method, parameters). Пример:

     
     const deals = bx24.fetchList('crm.deal.list', {
         filter: {
             ASSIGNED_BY_ID: userId
         }
     });
                         

   • Для получения списка через новые методы (crm.item.*) используйте bx24.fetchListCrm(method, parameters). Пример:

     
     const deals = bx24.fetchListCrm('crm.item.list', {
         entityTypeId: 2,
         filter: {
             '=assignedById': userId
         }
     });
                         

   • Для получения списка задач используйте bx24.fetchListTasks(). Пример:

     
     const tasks = bx24.fetchListTasks({
         filter: {
             '=RESPONSIBLE_ID': userId
         }
     });
                         

3. Пакетные запросы (батчи)

   Если надо обновить несколько элементов, то делать это можно с помощью метода bx24.callBatch(commands), где commands - список пар [метод, объект запроса])

   
   commands.push(['crm.deal.update', {
       id: deal.ID,
       fields: { 'ASSIGNED_BY_ID': newResponsibleId }
   }]);
   bx24.callBatch(commands);
               

   В одном батче должно быть не более 50 запросов.

4. console.log(message) - запись в журнал бизнес-процесса
5. stopWatch.getRemainingMillis() - возвращает оставшееся время выполнения активити в миллисекундах

Обработка ошибок

Каждый робот в REST.js содержит 2 выходных параметра для обработки ошибок: errorCode и errorMessage

• оба параметра заполнены только в случае ошибки
• errorCode: возможные значения - INVALID_PARAMETER, EXCEPTION, SYSTEM_ERROR, RUN_OUT_OF_TIME, TOO_MANY_REQUESTS, RESULT_TOO_LARGE
• errorMessage - произвольное сообщение об ошибке

Технические параметры и ограничения

Поддержка стандарта Javascript

REST.js полностью поддерживает ECMAScript 2023 (ES14). Подробнее см. в документации

Ограничение времени выполнения

• Время запуска робота ограничено 12 секундами серверного времени
• для проверки оставшегося времени в миллисекундах можно вызывать метод stopWatch.getRemainingMillis()
• в случае превышения лимита в выходной параметр errorCode будет иметь значение RUN_OUT_OF_TIME

Ограничение оперативной памяти (RAM)

Скрипт робота может использовать до 512 Мб оперативной памяти

Ограничение интенсивности запросов к API Битрикс24

REST.js следует требованиям Битрикс24 и ограничивает частоту запросов к API Битрикс24. Разрешенная максимальная частота - 2 запроса в секунду.

Стоимость

Приложение работает только на платных тарифах Битрикс24 с подпиской на Маркет. В рамках подписки доступны 3000 запросов на запуск роботов. Счетчик использования обнуляется 1-го числа каждого месяца

Цена дополнительных запросов - 500 рублей за 3000 запросов. Для приобретения обратитесь в службу поддержки приложения.