Розробка кастомних процесів бізнес-процесів Бітрікс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'     => ['uk' => 'Артикул товару'],
            'Type'     => 'string',
            'Required' => 'Y',
        ],
    ],
    'RETURN_PROPERTIES' => [
        'price' => [
            'Name' => ['uk' => 'Ціна з 1С'],
            'Type' => 'double',
        ],
        'available' => [
            'Name' => ['uk' => 'В наявності'],
            '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 тижні залежно від складності інтеграції та вимог до обробки помилок.