Мониторинг создания порталов Битрикс24

Активити (робот) "Мониторинг создания порталов Битрикс24" предназначено для использования в роботах и может быть полезно в следующих сценариях:

Автоматическое отслеживание создания новых порталов в партнерском кабинете Битрикс24;
Реагирование на события создания порталов в бизнес-процессах;
Автоматизация процессов при создании новых порталов клиентами;
Мониторинг новых клиентов через партнерский API;
Интеграция с внешними системами на основе событий создания порталов;
Автоматическое уведомление о создании новых порталов;
Отслеживание регистрации новых клиентов;
Автоматическое выполнение действий при создании портала;
Сбор информации о новых порталах для аналитики;
Синхронизация данных о новых порталах с внешними системами.

Как работает активити (робот):
- Активити (робот) подписывается на события создания порталов через партнерский API Битрикс24 (partners.1c-bitrix.ru);
- При запуске проверяется наличие действующего обработчика через метод get.callback.list;
- Если обработчик существует и запись в events совпадает с текущим workflow_id, робот просто ждёт событий;
- Если обработчик существует, но запись в events не совпадает, запись обновляется;
- Если обработчика нет, создаётся новый через метод add.callback.add.bitrix24.partner.portal;
- При получении события создания портала от партнерского API робот возвращает данные о новом портале;
- Активити (робот) работает через систему callback от внешнего ресурса, а не через события Битрикс24;
- Поддерживается опция принудительного удаления существующих обработчиков перед созданием нового.

Описание параметров активити (робота)

Название поля	Описание и примеры использования
Идентификатор партнера	В данном поле указывается идентификатор партнера в партнерском кабинете Битрикс24. Это обязательный параметр. Примеры: - 1092905 - числовой идентификатор партнера; - {=Variable:PARTNER_ID} - использовать идентификатор из переменной предыдущего активити (робота); - {=Document:ID} - использовать ID из документа (если ID документа совпадает с идентификатором партнера). Важно: Идентификатор партнера можно получить в партнерском кабинете Битрикс24. Убедитесь, что указанный идентификатор корректен.
Секретный ключ партнера	В данном поле указывается секретный ключ партнера, который был указан в партнерской карточке. Это обязательный параметр. Используется для формирования подписи запросов к партнерскому API. Примеры: - 1234567 - секретный ключ партнера; - {=Variable:PARTNER_CORE} - использовать ключ из переменной предыдущего активити (робота). Важно: Секретный ключ партнера должен совпадать с ключом, указанным в партнерской карточке. Ключ используется для авторизации запросов к партнерскому API.
Удалить обработчик	В данном поле указывается, нужно ли удалять существующие обработчики перед созданием нового. Это необязательный параметр типа булево (да/нет). Варианты выбора: - Нет (false) - не удалять существующие обработчики, использовать существующий если он есть; - Да (true) - удалять все существующие обработчики перед созданием нового. Примеры использования: - Нет - использовать существующий обработчик если он есть, создавать новый только если его нет; - Да - всегда удалять существующие обработчики и создавать новый при каждом запуске робота. Когда использовать: - Для принудительного обновления обработчика при каждом запуске; - Для очистки старых обработчиков перед созданием нового; - Для обеспечения единственности обработчика на портал.
Запускать от имени	Данное поле необходимо для того, чтобы установить сотрудника, с правами которого выполнять действие данного активити (робота). Если у сотрудника не будет прав на выполнение действия, то активити (робот) не сработает. Рекомендуем выбирать всегда сотрудника с правами администратора системы.
Устанавливать текст статуса	Данное поле позволяет включать возможность установки статуса бизнес-процесса. Это необходимо для того, чтобы во время работы активити (робота) информировать пользователя в истории о том, что бизнес-процесс остановился на конкретном шаге. Это особенно важно в момент отладки и выяснения причин неполадок в работе механизма.
Текст статуса	В данном поле указывается текстовый вариант статуса, который Вы можете изменять. Используется только при включённом параметре "Устанавливать текст статуса".
Ожидать ответа	Данное поле Вами не управляется. Оно необходимо для того, чтобы определить, нужно ли ожидать реакции от нашего активити (робота) после запуска.
Период ожидания. Время ожидания ответа от приложения	Указывается в секундах, минутах, часах, днях, но не менее 5 минут и желательно не более 1 часа. Это поле нужно для аварийного завершения активити (робота), и если ответ не получен в течении того количества времени, то активити (робот) завершается.

Примеры использования активити (робота)

Описание примера	Решение
Отслеживание создания порталов для конкретного партнера	Параметры: Идентификатор партнера - 1092905, Секретный ключ партнера - 1234567, Удалить обработчик - Нет. Активити (робот) подпишется на события создания порталов и будет ожидать callback от партнерского API.
Принудительное обновление обработчика при каждом запуске	Параметры: Идентификатор партнера - {=Variable:PARTNER_ID}, Секретный ключ партнера - {=Variable:PARTNER_CORE}, Удалить обработчик - Да. Активити (робот) удалит все существующие обработчики и создаст новый при каждом запуске.
Использование параметров из переменных	Параметры: Идентификатор партнера - {=Variable:PARTNER_ID}, Секретный ключ партнера - {=Variable:PARTNER_CORE}, Удалить обработчик - Нет. Активити (робот) использует данные из переменных предыдущих активити (роботов) для настройки мониторинга.
Мониторинг создания порталов с автоматическим удалением обработчика	Параметры: Идентификатор партнера - 1092905, Секретный ключ партнера - 1234567, Удалить обработчик - Да. Активити (робот) удалит существующие обработчики, создаст новый и будет ожидать события создания порталов.
Использование существующего обработчика	Параметры: Идентификатор партнера - 1092905, Секретный ключ партнера - 1234567, Удалить обработчик - Нет. Если обработчик уже существует и запись в events совпадает с текущим workflow_id, активити (робот) просто будет ожидать событий без создания нового обработчика.
Обновление записи при несовпадении workflow_id	Параметры: Идентификатор партнера - 1092905, Секретный ключ партнера - 1234567, Удалить обработчик - Нет. Если обработчик существует, но запись в events не совпадает с текущим workflow_id, активити (робот) обновит запись в events для корректной работы.
Создание нового обработчика при отсутствии существующего	Параметры: Идентификатор партнера - 1092905, Секретный ключ партнера - 1234567, Удалить обработчик - Нет. Если обработчика нет в списке, активити (робот) создаст новый через метод add.callback.add.bitrix24.partner.portal.
Мониторинг создания порталов с использованием данных из документа	Параметры: Идентификатор партнера - {=Document:ID}, Секретный ключ партнера - {=Variable:PARTNER_CORE}, Удалить обработчик - Нет. Активити (робот) использует ID документа как идентификатор партнера и ключ из переменной.
Ожидание события создания портала	Параметры: Идентификатор партнера - 1092905, Секретный ключ партнера - 1234567, Удалить обработчик - Нет. Активити (робот) настроит подписку и будет ожидать события создания портала от партнерского API. При получении события вернёт данные о новом портале.
Автоматическое удаление обработчика после получения события	Параметры: Идентификатор партнера - 1092905, Секретный ключ партнера - 1234567, Удалить обработчик - Нет. После получения события создания портала в файле partner_callback.php обработчик автоматически удаляется через метод delete.callback.add.bitrix24.partner.portal перед отправкой результата в бизнес-процесс, а запись из events также удаляется.

Возвращаемые параметры данного активити (робота):
- ID обработчика (callback_id) - числовой идентификатор обработчика callback, созданного для отслеживания создания порталов. Используется для идентификации обработчика в системе.
- Тип обработчика (callback_type) - тип события, на который подписан обработчик. Всегда равен "ADD_BITRIX24_PARTNER_PORTAL" для данного активити (робота).
- Адрес портала (b24_portal) - адрес портала Битрикс24, который был создан.
- Внешний код портала (portal_external_id) - внешний код портала (например CP_111111 или B24_33333), который был создан.
- Email контакта (contact_email) - email контакта, связанного с созданным порталом.
- Данные контакта (contact_name) - данные контакта, связанного с созданным порталом.
- Реферер (referrer) - информация о реферере, откуда пришёл клиент.
- Тариф (tariff) - тариф, выбранный при создании портала.
- all_conditions (math_search_results) - строка, указывающая результат выполнения активити (робота). Всегда равен "Y" при успешном получении события.

Примеры использования возвращаемых параметров:
- Использовать данные о новом портале для создания записи в CRM;
- Сохранить информацию о новом портале в переменные для дальнейшей обработки;
- Отправить уведомление о создании портала с использованием данных contact_email и contact_name;
- Использовать portal_external_id для идентификации портала в внешних системах;
- Использовать referrer для аналитики источников клиентов;
- Сохранить информацию о тарифе для дальнейшего анализа;
- Создать задачу или дело при создании портала с использованием данных о контакте;
- Использовать callback_id для логирования или отладки.

Важно о возвращаемых параметрах: Параметры возвращаются только при получении события создания портала от партнерского API. Если событие не получено в течение периода ожидания, активити (робот) завершится по таймауту. Всегда проверяйте наличие значения параметра math_search_results перед использованием возвращаемых данных в дальнейших шагах бизнес-процесса.

Важно! Ограничения и рекомендации:

Обязательные параметры:
Для успешной настройки мониторинга обязательно должны быть заполнены следующие параметры:
- Идентификатор партнера;
- Секретный ключ партнера.

Работа с партнерским API:
Активити (робот) работает через партнерский API Битрикс24 (partners.1c-bitrix.ru), а не через стандартные события Битрикс24. Callback приходит напрямую от партнерского API на специальный endpoint partner_callback.php. События срабатывают асинхронно, поэтому бизнес-процесс может продолжить выполнение через некоторое время после настройки мониторинга.

Проверка существующего обработчика:
При запуске активити (робот) проверяет наличие действующего обработчика через метод get.callback.list. Если обработчик существует и запись в events совпадает с текущим workflow_id, робот просто ждёт событий без создания нового обработчика. Это позволяет избежать дублирования обработчиков.

Обновление записи в events:
Если обработчик существует, но запись в events не совпадает с текущим workflow_id, активити (робот) обновит запись в events для корректной работы. Это обеспечивает правильную привязку обработчика к текущему бизнес-процессу.

Автоматическое удаление обработчика:
После получения события создания портала в файле partner_callback.php обработчик автоматически удаляется через метод delete.callback.add.bitrix24.partner.portal перед отправкой результата в бизнес-процесс через bizproc.event.send, а запись из events также удаляется. Это предотвращает накопление неиспользуемых обработчиков.

Параметр "Удалить обработчик":
Если параметр "Удалить обработчик" установлен в "Да", активити (робот) удалит все существующие обработчики перед созданием нового.

Ограничение на количество обработчиков:
Партнерский API позволяет создать только один обработчик на портал. Если попытаться создать второй обработчик для того же портала, будет возвращена ошибка CALLBACK_ALREADY_EXISTS. Активити (робот) автоматически обрабатывает эту ситуацию и использует существующий обработчик или удаляет его перед созданием нового в зависимости от параметра "Удалить обработчик".

Права доступа:
Убедитесь, что пользователь, указанный в поле "Запускать от имени", имеет права на работу с партнерским API. Рекомендуется использовать пользователя с правами администратора системы.

Удаление отслеживания:
При удалении активити (робота) автоматически удаляются подписки на события и записи в events, настроенные для данного активити (робота). Это предотвращает накопление неиспользуемых подписок на события.

Производительность:
Мониторинг создания порталов создаёт подписки на события через партнерский API, которые могут увеличить нагрузку на систему при большом количестве отслеживаемых порталов. Рекомендуется использовать мониторинг только для действительно необходимых случаев и удалять неиспользуемые активити (роботы) мониторинга.

Ваша корзина пуста

Мониторинг создания порталов Битрикс24