Developing custom actions for Bitrix24 business processes

Developing Custom Business Process Actions for Bitrix24

Standard BP actions — send an email, modify a field, create a task — don't cover integration requirements. You need to query data from 1C inside an approval process, create a document in SharePoint, or send a message to a corporate Telegram bot. This is done through custom actions.

Architecture of Custom Actions

A custom BP action is a PHP class that extends CBPActivity (legacy API) or \Bitrix\Bizproc\Activity\BaseActivity (modern API). The class is registered as a handler for the OnBizProcActivityList event in the bizproc module.

Difference from custom CRM robots: custom actions are available throughout the entire business process editor, not just in CRM. They can be used in BP for lists, disk, CRM — everywhere.

Two ways to create a custom action:

1. REST API — the bizproc.activity.add method. Registers a webhook as an action. Works in both cloud and on-premise.
2. PHP module — a server-side class. Only for on-premise Bitrix24 with file system access.

Development via REST API

Registration via 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',  // async mode
    'PROPERTIES'   => [
        'article' => [
            'Name'     => ['en' => 'Product SKU'],
            'Type'     => 'string',
            'Required' => 'Y',
        ],
    ],
    'RETURN_PROPERTIES' => [
        'price' => [
            'Name' => ['en' => 'Price from 1C'],
            'Type' => 'double',
        ],
        'available' => [
            'Name' => ['en' => 'In stock'],
            'Type' => 'bool',
        ],
    ],
]);

USE_SUBSCRIPTION: Y is required for actions that run longer than 5 seconds. Bitrix24 calls the handler, which immediately responds 200 OK, performs the work asynchronously, then calls bizproc.event.send with the result.

Handler Structure

// Incoming request from Bitrix24
$event    = $_POST['event'];         // 'OnBpActivityExecute'
$data     = $_POST['data'];
$workflowId = $data['WORKFLOW_ID'];
$article    = $data['PROPERTIES']['article'];
$auth       = $data['auth'];

// Respond immediately with 200 OK
http_response_code(200);
echo json_encode(['status' => 'ok']);

// Work asynchronously (via queue or pcntl_fork)
$price = get_price_from_1c($article); // request to 1C

// Send result back to BP
$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,
    ],
]));

The event_token field is a one-time token that ties the callback to a specific BP instance. Without it Bitrix24 doesn't know which workflow to return the result to.

Developing a PHP Action for On-Premise Bitrix24

PHP class structure:

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

        // Request to 1C via SOAP or REST
        $result = \My1CConnector::getPrice($article);

        if ($result->isSuccess()) {
            $this->setResultValue('price',     $result->getPrice());
            $this->setResultValue('available', $result->getAvailable());
        } else {
            $this->writeToTrackingService(
                'Error querying 1C: ' . $result->getErrorMessage()
            );
        }

        return \CBPActivityExecutionStatus::Closed;
    }

    public static function getPropertiesDialog($params)
    {
        // Render the action settings form in the BP editor
    }
}

The writeToTrackingService method writes a message to the BP log — visible in the item's "History". Invaluable for debugging.

Real Case: Action for Querying a Credit Limit

Task: a distributor, shipment request approval process with deferred payment. During the process the credit limit and current debt of the counterparty must be retrieved from a CRM system, then either auto-approved or routed for manual approval by the CFO.

Solution: custom PHP action CheckCreditLimitActivity for on-premise Bitrix24. Takes parameters: company ID in CRM, request amount. Queries an internal financial system API over HTTP, receives JSON with the limit and debt. Returns to the BP variables available_limit (number) and approval_required (boolean).

After the action the BP has an "If-Then-Else": if approval_required = true — task for the CFO, otherwise — automatic approval and status update.

Complexity: the financial system was unavailable in 3–5% of cases due to scheduled maintenance. Retry logic was added: the action waits up to 30 minutes (via an agent), then if the system is still unreachable routes the request to manual approval with a reason notification.

Result: the approval cycle was reduced from 4 hours to 20 minutes for automatically approved requests (68% of total).

Common Development Mistakes

• Timeout without USE_SUBSCRIPTION — a synchronous handler runs longer than 5 seconds, Bitrix24 considers it hung. Always use async mode for external requests.
• Missing event_token — the result never reaches the BP, the workflow hangs in a waiting state. Check logs in b_bizproc_workflow_log.
• Forgotten error handling — an unhandled exception in a PHP action kills the entire workflow. Wrap external calls in try-catch.

Development Time

Developing a custom action end-to-end — 1–2 weeks depending on integration complexity and error-handling requirements.