Разработка кастомных действий бизнес-процессов Битрикс24

Разработка кастомных действий бизнес-процессов Битрикс24

Стандартные действия БП — отправить письмо, изменить поле, создать задачу — не покрывают интеграционные задачи. Нужно внутри процесса согласования запросить данные из 1С, создать документ в SharePoint или отправить сообщение в корпоративный Telegram-бот. Это делается через кастомные действия.

Архитектура кастомных действий

Кастомное действие БП — это PHP-класс, наследующий CBPActivity (устаревший API) или \Bitrix\Bizproc\Activity\BaseActivity (современный API). Класс регистрируется как обработчик события OnBizProcActivityList в модуле bizproc.

Отличие от кастомных роботов CRM: кастомные действия доступны во всём редакторе бизнес-процессов, не только в CRM. Их можно использовать в БП для списков, диска, CRM — везде.

Два способа создать кастомное действие:

1. REST API — метод bizproc.activity.add. Регистрирует вебхук как действие. Работает в облаке и коробке.
2. PHP-модуль — класс на сервере. Только коробочный Битрикс24 с доступом к файловой системе.

Разработка через REST API

Регистрация через bizproc.activity.add:

$client->call('bizproc.activity.add', [
    'CODE'         => 'GET_1C_PRICE',
    'HANDLER'      => 'https://my-server.com/bp-activity-handler',
    'AUTH_USER_ID' => 1,
    'NAME'         => [
        'ru' => 'Получить цену из 1С',
        'en' => 'Get price from 1C',
    ],
    'USE_SUBSCRIPTION' => 'Y',  // асинхронный режим
    'PROPERTIES'   => [
        'article' => [
            'Name'     => ['ru' => 'Артикул товара'],
            'Type'     => 'string',
            'Required' => 'Y',
        ],
    ],
    'RETURN_PROPERTIES' => [
        'price' => [
            'Name' => ['ru' => 'Цена из 1С'],
            'Type' => 'double',
        ],
        'available' => [
            'Name' => ['ru' => 'В наличии'],
            'Type' => 'bool',
        ],
    ],
]);

USE_SUBSCRIPTION: Y — обязательно для действий, которые работают дольше 5 секунд. Битрикс24 вызывает обработчик, тот сразу отвечает 200 OK, выполняет работу асинхронно, затем вызывает bizproc.event.send с результатом.

Структура обработчика

// Входящий запрос от Битрикс24
$event    = $_POST['event'];         // 'OnBpActivityExecute'
$data     = $_POST['data'];
$workflowId = $data['WORKFLOW_ID'];
$article    = $data['PROPERTIES']['article'];
$auth       = $data['auth'];

// Немедленно ответить 200 OK
http_response_code(200);
echo json_encode(['status' => 'ok']);

// Работаем асинхронно (через очередь или pcntl_fork)
$price = get_price_from_1c($article); // запрос к 1С

// Отправляем результат обратно в БП
$callbackUrl = 'https://' . $auth['domain'] . '/rest/bizproc.event.send.json';
file_get_contents($callbackUrl . '?' . http_build_query([
    'auth'        => $auth['access_token'],
    'event_token' => $data['event_token'],
    'return_values' => [
        'price'     => $price,
        'available' => $price > 0,
    ],
]));

Поле event_token — одноразовый токен для привязки колбэка к конкретному экземпляру БП. Без него Битрикс24 не знает, в какой воркфлоу вернуть результат.

Разработка PHP-действия для коробочного Битрикс24

Структура PHP-класса:

class My1CPriceActivity extends \Bitrix\Bizproc\Activity\BaseActivity
{
    protected function execute(array &$arProperties)
    {
        $article = $this->getFieldValue('article');

        // Запрос к 1С через SOAP или REST
        $result = \My1CConnector::getPrice($article);

        if ($result->isSuccess()) {
            $this->setResultValue('price',     $result->getPrice());
            $this->setResultValue('available', $result->getAvailable());
        } else {
            $this->writeToTrackingService(
                'Ошибка запроса к 1С: ' . $result->getErrorMessage()
            );
        }

        return \CBPActivityExecutionStatus::Closed;
    }

    public static function getPropertiesDialog($params)
    {
        // Рендер формы настройки действия в редакторе БП
    }
}

Метод writeToTrackingService записывает сообщение в журнал БП — видно в «Истории» элемента. Незаменимо для отладки.

Реальный кейс: действие для запроса лимита кредитования

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

Решение: кастомное PHP-действие CheckCreditLimitActivity для коробочного Битрикс24. Принимает параметры: ID компании в CRM, сумму заявки. Запрашивает внутренний API финансовой системы по HTTP, получает JSON с лимитом и задолженностью. Возвращает в БП переменные available_limit (число) и approval_required (булево).

После действия в БП стоит «Если-то-иначе»: если approval_required = true — задание финансовому директору, иначе — автоматическое одобрение и изменение статуса заявки.

Сложность: финансовая система была недоступна в 3–5% случаев из-за регламентных работ. Добавили логику повтора: действие ждёт до 30 минут (через агент), затем при недоступности системы переводит заявку на ручное согласование с уведомлением о причине.

Итог: цикл согласования сократился с 4 часов до 20 минут для автоматически одобряемых заявок (68% от общего числа).

Типичные ошибки при разработке

• Таймаут без USE_SUBSCRIPTION — синхронный обработчик работает дольше 5 секунд, Битрикс24 считает его зависшим. Всегда используйте асинхронный режим для внешних запросов.
• Не передаётся event_token — результат не доходит до БП, воркфлоу зависает в состоянии ожидания. Проверяйте логи в b_bizproc_workflow_log.
• Забытая обработка ошибок — необработанное исключение в PHP-действии роняет весь воркфлоу. Оборачивайте внешние вызовы в try-catch.

Сроки разработки

Разработка кастомного действия «под ключ» — 1–2 недели в зависимости от сложности интеграции и требований к обработке ошибок.