Как написать кастомную активити для бизнес-процесса для облачного Битрикс24
На зимней партнерской конференции 1C-Битрикс 2016г Олег Строкатый и Алексей Кирсанов показывали мастер-класс, в ходе которого разработали кастомную активити для бизнес-процесса под облачный Битрикс24. Информация по данной теме есть так же в курсе «Разработчик Bitrix Framework» (ссылки — в конце поста).
Изучив указанные материалы и опробовав их на своих проектах, мы составили для себя простую и подробную памятку действий по разработке активити для облачного Битрикс24, включающую в себя так же некоторые мелочи, которые в вышеуказанных источниках были недосказаны, видимо, в расчете на то, что у разработчика, изучающего их, уже есть определенный базис знаний. Этой памяткой я и хочу поделиться в данном посте.
Кастомная активити для облачного Битрикс24 реализуется как приложение так называемого «второго типа». То есть php-файл с обработчиком активити и с ее установщиком должен лежать где-то на внешнем web-сервере, а Битрикс24 будет обращаться к нему по определенному адресу, например,
Именно этот адрес и используется для добавления приложения в портал, и для публикации приложения в маркетплейс Битрикс24.
Для корректной работы такого приложения домен должен обладать SSL сертификатом (минимум Domain Validation (DV) Certificate). Вести разработку и тестирования приложения можно и без SSL сертификата, но он понадобится для реальной работы приложения, поэтому о нем стоит позаботиться заранее.
1.2 Структура приложения
В самом файле-приложении, прежде всего, необходимо сформировать скелет — структуру страницы приложения.
Данный скелет сразу можно подключить в тестовом портале как будет описано ниже и начать наращивать и отлаживать. Когда мы будем менять что-то в коде приложения на нашем сервере — переподключать приложение на стороне Битрикс24 не нужно — достаточно просто перезагрузить страницу приложения.
2 Какие данные мы получаем и как их проверить
Можно (и нужно) использовать и более сложные проверки с использованием регулярных выражений, но данный пост не о них.
3 Использование REST-api Битрикс24 на php
Далее нам понадобится php-функция, которая посредством curl будет посылать запросы к Битрикс24:
Если нам нужно будет вызвать rest-апи Битрикс24 из php-кода — мы далее можем использовать данную функцию:
4 Метод отладки приложения
Сразу встает вопрос: а как отлаживать наше приложение? Оно же выполняется у нас на сервере — значит мы можем смело все логировать в какой-то файл. Можно, например, использовать функции php fopen, fwrite, fclose. Ну а у нас на сервере тоже стоит Битрикс, поэтому нам нравится использовать функцию AddMessage2Log из битрикс-фреймворка (предварительно подключив заголовок).
5 Использование REST-api Битрикс24 на javascript
Мы можем вызывать rest-апи битрикс24 и через javascript. Следующим образом:
6 Создание и удаление простого активити
В частности нам нужны 2 javaскрипт обработчика для установки и удаления нашей активити (в данном примере мы создаем для облачного Битрикс24 активити, которая запрашивает идентификатор пользователя и возвращает бизнес-процессу его данные: телефон, skype и должность):
7 Логирование запросов и ответов на javascript
Если мы планируем размещать наше приложение в Маркетплейс Битрикс24, мы обязаны логировать все запросы и все ответы от Битрикс24 — не только те, которые посылаем из php-кода, но и те, которые мы посылаем из javascript
Если у нас на сервере тоже стоит Битрикс, можно использовать функции js библиотеки битрикс-фреймворка.
Скрипт-логгер, который мы дергаем по аяксу из нашего javascript может выглядеть так:
8 Не забыть вернуть ответ бизнес-процессу
Если объявляя активити, мы задали параметр ‘USE_SUBSCRIPTION’:’Y’ мы обязаны вернуть бизнес-процессу ответ, соответсвующий описанному для активити массиву выходных параметров RETURN_PROPERTIES. Для этого используем rest-api bizproc.event.send
9 Добавление приложения в портал
Чтобы добавить приложение в портал Битрикс24, его не обязательно публиковать в Маркетплейсе — можно добавить его только в свой портал — для использования только в этом портале. Для этого в левом меню облачного Битрикс24 выбираем пункт «Добавить приложение», далее выбираем «Для личного использования».
В открывшейся форме указываем название приложение, название пункта меню, указываем, права на доступ к каким подсистемам необходимы приложению. Если наше приложение добавляет активити в бизнес-процесс, то необходимо отмечать галку Бизнес-процессы. Указываем ссылку на файл приложения, лежащий на нашем сервере.
Добавленное приложение появляется в списке локальных приложений и в меню приложений.
На странице приложения в портале Битрикс24 у нас 2 кнопки, обработчики которых описаны в посте ранее. Одна кнопка устанавливает нашу кастомную активити, вторая — удаляет.
После установки активити появлется в редакторе бизнес-процесса.
Кастомную активити можно включить в бизнес-процесс, задать ей те входные параметры, которые мы определили, как входные, и она будет работать.
10 Что будет, если удалить кастомную активити, которая включена в бизнес-процесс?
В этом случае бизнес-процесс перестанет отрабатывать корректно, а в редакторе бизнес-процесса данная активити будет подсвечена красным цветом.
Создание приложения для Bitrix24 с нуля
Для расширения функциональности Bitrix24 удобно использовать приложения. В данной статье описано создание с нуля локального serverless приложения.
Для установки нашего приложения нам понадобится собственно портал bitrix24, в котором мы обладаем правами администратора или правом установки и редактирования приложений.
Если такого портала нет — создать его можно здесь.
| Заполняем следующие поля: | Название поля | Значение |
|---|---|---|
| Название приложения* | exampleApp | Или любое другое |
| Russian (ru) | Пример приложения | Также можно заполнить значения для других нужных языков |
| Пользователи (user) | отмечаем галочкой | Сейчас нам понадобится только это разрешения, но в дальнейшем разрешения для приложения можно будет корректировать |
Здесь нам нужно будет остановится, так как добавлять пока нечего. Оставим вкладку браузера открытой и приступим к созданию нашего приложения.
Официальная javascript-библиотека
Создадим папку с произвольным названием и в ней единственный пока файл index.html со следующим содержанием (исходный код):
Помещаем файл index.html в zip-архив и указываем этот архив в качестве значения поля Загрузите архив с вашим приложением (zip)* в диалоге создания приложения.
Затем нажимаем кнопку «Сохранить»
Посмотрим, что у нас получилось.
Кликаем по Перейти к приложению и видим… пустое место на месте нашего приложения.
Все необходимое для нас на данном этапе находится сейчас в консоли разработчика.
Мы видим, что наше приложение успешно получило данные необходимые для авторизации.
Официальная javascript-библиотека c promise
Использование callback-функций имеет свои преимущества, но не всем нравится или не всегда подходит к ситуации.
Поэтому попробуем получить тот же результат в promise-стиле. Для этого изменим наш index.html (исходный код)
Опять архивируем, опять обновляем наше приложение, опять смотрим, опять все работает.
Инструменты разработки
В папке нашего проекта инициализируем npm:
Установим необходимые пакеты:
Состояние проекта после всех изменений можно посмотреть здесь.
Создадим в корне нашего проекта файл server.js
Создадим папки src и public
В папку public перенесем index.html и изменим его содержимое на:
В папке src создадим файлы
Если package.json еще не создан, выполним:
Добавим скрипты в package.json :
Далее так как и команда start и команда watch не заканчиваются, их нужно запускать параллельно. Для этого в двух командных строках запускаем
Завершим настройку среды разработки редактированием нашего приложения в Bitrix24.
Перейдем в диалог редактирования нашего приложения и укажем в поле
Укажите ссылку* значение http://127.0.0.1:3000/
Перейдите к просмотру вашего приложения:
Вы должны увидеть приветствие с именем текущего пользователя:
Если использовать официальную библиотеку, то отличаться будут только два файла:
Итоговый код проекта для использования официальной библиотеки здесь.
Ознакомиться со всеми возможными методами и возможностями API можно здесь.
Исходный код можно увидеть здесь.
И последнее замечание. Описанные выше способы и методы не являются набором лучших практик. Это скорее предложение к конструктивному обсуждению.
UPD: желающих высказаться о 1С-Битрикс или Битрикс24 прошу сделать небольшое интеллектуальное усилие и осознать, что статья не о Битрикс24 и совсем не о 1С-Битрикс.
Это если в Питере прохожий объясняет другому, как пройти к Петропавловской крепости и тут третий вмешивается с репликой:
«Да тиран был ваш Петр I. Тиран и деспот. И усы у него дурацкие».
Если есть конструктивные замечания к коду в СТАТЬЕ или к подходам или к используемым паттернам — добро пожаловать.
Создаем лид в Битрикс24 через API
Введение
У Битрикс24 есть API, который позволяет делать определенные полезные штуки. Одна из них – отправка лида в CRM. Т.е. мы можем запрограммировать отправку данных из любой формы своего сайта в свой Битрикс24. Супер! Разберемся, как это сделать.
Создание вебхука
Прежде всего, в рамках Битрикс24 нужно создать вебхук, в который мы будем отправлять данные с сайта. В Битрикс24 в левом меню переходим в раздел Приложения, идем на вкладку Вебхуки, жмем кнопку Добавить вебхук, в подменю выбираем Входящий вебхук:
Открылась форма добавления вебхука. В поле Название вводим произвольное название, например Получение лидов с сайта. Поле Описание заполняем по своему желанию. В списке Права доступа отмечаем чекбокс CRM:
Больше ничего отмечать не нужно, нажимаем кнопку Сохранить (находится под списком прав доступа):
Перед нами открывается страница с кодом вебхука:
Сохраните этот код, он понадобится нам далее. Код никому не показывайте, это конфиденциальная информация.
Пример 1: передаем имя и телефон
Начнем с самого простого примера: передадим в CRM имя и номер телефона:
Комментарии добавил прямо в код, думаю вопросов быть не должно. Если запустим этот код — в Битрикс24 появится уведомление о создании нового лида:
В CRM зайдем в лид и увидим всю информацию, которую мы передали:
Супер! В примере мы заполнили только Название лида, Имя и Номер телефона. Но в CRM Б24 доступно намного больше полей. Их список можно посмотреть в документации по ссылке: https://dev.1c-bitrix.ru/rest_help/crm/leads/crm_lead_fields.php — обязательно ознакомьтесь с этой табличкой.
Пример 2: передаем пользовательские свойства
Немного дополним наш пример, передадим значения двух пользовательских полей. Предположим, что в CRM у нас есть поле Ждет звонка типа Да/Нет (содержит информацию о том, нужно ли перезвонить этому клиенту). И поле Дополнительное сообщение типа Строка, в котором мы передаем сообщение, оставленное пользователем:
Нам нужно получить коды этих свойств. Узнать их можно через просмотр кода элемента. Вот код нашего первого свойства:
Добавим их в наш код и получим следующее:
Как видим, пользовательские свойства передаются точно так же, как и обычные поля. Результат в CRM выглядит следующим образом:
Пользовательские поля корректно сохранились в Битрикс24.
Пример 3: передаем UTM-метки
Передача UTM-меток ничем не отличается от передачи обычных полей. Но я решил вынести этот пример в отдельный блок, т.к. в свое время сам не знал о существовании специальных полей для UTM-меток в CRM Битрикс24. А они есть, это следующие поля:
Дополним наш код исходя из этой информации: вытянем UTM-метки из урла и отправим их в лид:
Отправим лид со страницы со следующим набором значений в урле:
В итоге получим этот набор UTM-меток в соответствующих полях лида:
Пример сообщения об ошибке
У нас в коде есть блок, который отвечает за вывод ошибок, вот он:
Давайте попробуем получить какую-нибудь ошибку. Например, укажем несуществующего пользователя в переменной $b24UserID:
Запустив код с неправильным ID пользователя, мы получим следующее сообщение:
А в ячейке $result[‘error’] будет храниться код ошибки, в данном случае INVALID_CREDENTIALS.
Возможно, это поможет кому-то при дебаге.
Другие посты из этой же рубрики:
Copyright © 2015-2021, Алфавитка.ру – IT-блог разработчика.
Как быстро получить много данных от Битрикс24 через REST API
Например, вот сравнительные скорости выгрузки одного поля для разных типов полей:
Плюс, в силу того, что информация сервером выдается постранично, существует несколько стратегий для того, чтобы получить весь список, и некоторые из них позволяют ускорять процесс на порядки по сравнению с последовательными запросами.
Стратегии
Ниже мы описываем три стратегии, которые мы условно назвали «ID filter», «Start increment’ и «List + get».
Первые две стратегии («ID filter» и «Start increment») предложены в официальной документации Битрикс24, но мы ниже предлагаем их «докрутить».
ID filter
Запросы отправляются к серверу последовательно с параметром «order»: <"ID": "ASC">(сортировка по возрастанию ID), и в каждом последующем запросе используются результаты предыдущего (фильтрация по ID, где ID > максимального ID в результатах предыдущего запроса).
В потенциале для ускорения можно попытаться параллельно передвигаться по списку сущностей в два потока: с начала списка и с конца, продолжая получать страницы, пока ID в двух потоках не пересекутся. Такой способ, возможно, будет давать двукратное ускорение до тех пор, пока не будет исчерпан пул запросов к серверу и не потребуется включить throttling.
Start increment
После того, как мы получили первую страницу и увидели в ней общее количество элементов (поле total ), то дальнейшее ускорение запросов можно получить двумя нижеописанными способами.
Объединение запросов в батчи
Зная общее количество элементов, можно сразу создать запросы на все страницы и объединить их в батчи. (Битрикс поддерживает батчи в 50 запросов.) Использование батчей позволяет обойти ограничения на максимальную скорость запросов, так как один батч считается за один запрос при учете сервером количества получаемых запросов.
Параллельная отправка батчей к серверу
Примеры кода в официальной документации Битрикс24 REST API везде предлагают последовательную отправку запросов и описывают лишь ограничения на скорость отправки запросов. Но параллельная отправка запросов возможна и позволяет сильно ускорить обмен информацией с сервером.
Впрочем, таким образом достаточно просто перегрузить сервер, который даже при соблюдении скорости запросов начинает обрывать соединение и уходить в таймауты. Поэтому такой подход требует нахождения пределов нагрузки на сервер экспериментальным способом.
List + get
Чтобы проверить эффективность этих стратегий, мы провели тест (код теста).
Тест использует библиотеку fast_bitrix24 для автоматического контроля скорости запросов к серверу Битрикс24.
Тест проводим на 7-й версии REST API на списке в
Результаты теста
Выводы
В целом, стратегии, использующие батчи и параллельные запросы («Start increment» и «List + get»), показали себя лучше.
Однако при этом, к моему удивлению, стратегия «List + get» оказалась на порядок продуктивнее остальных, даже несмотря на то, что в ней приходится пробегаться по всему списку два раза. (Возможно, эту статью увидят разработчики Битрикс24 и объяснят этот феномен?)
Bitrix24 api php примеры
Bitrix24 API PHP Wrapper
Обертка на PHP7+ для работы с REST API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов и логированием в файл.
Разработчики на JavaScript могут воспользоваться классом-оберткой andrey-tech/bx24-wrapper-js.
Установка через composer:
в секцию require файла composer.json.
Базовые методы класса
Базовые методы находятся в классе \App\Bitrix24\Bitrix24API :
Дополнительные параметры настройки доступны через публичные статические и нестатические свойства класса \App\Bitrix24\Bitrix24API :
Методы для работы с сущностями Битрикс24
Методы работы со сделками
Методы для работы со сделками находятся в трейте \App\Bitrix24\Deal :
Методы для работы с контактами
Методы для работы с контактами находятся в трейте \App\Bitrix24\Contact :
Методы для работы с компаниями
Методы для работы с компаниями находятся в трейте \App\Bitrix24\Company :
Методы для работы с каталогами
Методы для работы с товарными каталогами находятся в трейте \App\Bitrix24\Catalog :
Методы для работы с товарами
Методы для работы с товарами находятся в трейте \App\Bitrix24\Product :
Методы работы с разделами товаров
Методы для работы с разделами товаров находятся в трейте \App\Bitrix24\ProductSection :
Методы работы с товарными позициями
Методы для работы с товарными позициями находятся в трейте \App\Bitrix24\ProductRow :
Методы для работы с пользователями
Методы для работы с пользователями находятся в трейте \App\Bitrix24\User :
Методы работы с задачами
Методы для работы с задачами находятся в трейте \App\Bitrix24\Task :
Методы для работы с делами
Методы для работы с делами (активностями) находятся в трейте \App\Bitrix24\Activity :
Методы для работы с диском
Методы для работы с Диском находятся в трейте \App\Bitrix24\Disk :
Методы для работы с лидами
Методы для работы с лидами находятся в трейте \App\Bitrix24\Lead :
Дополнительные параметры устанавливаются через публичные свойства объекта класса \App\HTTP\HTTP :
Примеры отладочных сообщений:
Дополнительные параметры устанавливаются через публичные свойства класса \App\DebugLogger\DebugLogger :
Пример результатов логирования:
Формат заголовков лога
Данная библиотека распространяется на условиях лицензии MIT.
About
Обертка на PHP7+ для работы с REST API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов к API и логированием в файл.