Setting up task queues in 1C-Bitrix

Setup of Task Queues on 1C-Bitrix

1C exchange dies on timeout, email broadcast to 5000 subscribers blocks a hit, PDF price generation for 20,000 products kills the server. All these tasks have one thing in common: they can't be executed in an HTTP request. You need a queue — a mechanism that accepts a task, stores it, and executes it in background via separate process.

Built-in Mechanism: Agents

Agents (CAgent) — built-in Bitrix deferred task system. Agent is a function called by schedule. Registration:

CAgent::AddAgent(
    "MyClass::processQueue();",  // PHP code to execute
    "main",                       // module
    "N",                          // non-periodic (N) or periodic (Y)
    300,                          // interval in seconds
    "",                           // first check date
    "Y",                          // activity
    ""                            // first run date
);

Agents execute in two ways:

• On page hits (default) — on each request, Bitrix checks if there are agents that should run. Problem: if no traffic — agents don't execute. If high traffic — agent check adds load to every hit.
• On cron — recommended mode. In crontab add a line: */5 * * * * /usr/bin/php /var/www/bitrix/modules/main/tools/cron_events.php. Parameter in .settings.php: 'agents' => ['use_crontab' => true].

When Agents Are Not Enough

Agents are single-threaded. One agent executes, others wait. If data import agent runs 10 minutes — all other agents (sending emails, cache recalculation, 1C exchange) are delayed.

For projects with intensive background processing — you need a full queue.

Queue Based on Highload-block

Simplest implementation without external dependencies:

1. HL-block QueueJob — fields: UF_HANDLER (handler class), UF_PAYLOAD (JSON with parameters), UF_STATUS (pending/processing/done/failed), UF_ATTEMPTS (attempt count), UF_CREATED_AT, UF_PROCESSED_AT.
2. Task submission — QueueJobTable::add(['UF_HANDLER' => 'ImportHandler', 'UF_PAYLOAD' => json_encode($data), 'UF_STATUS' => 'pending']).
3. Handler (cron script) — runs every minute, fetches N tasks with pending status, moves to processing, executes, marks done or failed.

Advantages: retry (repeated attempts via UF_ATTEMPTS), monitoring (SQL query to HL-block), priorities (add UF_PRIORITY field).

Queue via messagequeue Module (D7)

In the D7 core there's an experimental queue module: Bitrix\Main\Config\Queue. Supports drivers: file (file queue), database (DB table). Configuration in .settings.php:

'queue' => [
    'value' => [
        'default' => [
            'driver' => 'database',
            'table' => 'b_queue_message',
        ],
    ],
],

In practice, this module is rarely used — little documentation, limited functionality. For production, use either HL-block (simple and reliable) or external broker.

External Brokers: RabbitMQ, Redis

For high-load projects:

• RabbitMQ — connect via php-amqplib. Producer in Bitrix puts task in queue, Consumer — separate PHP daemon listening to queue and executing tasks.
• Redis — via LPUSH/BRPOP. Simpler than RabbitMQ, sufficient for most scenarios.

Bitrix integration: producer registers as event handler (e.g., OnSalePayOrder), consumer runs via Supervisor.

What We Configure

• Moving agents to cron (out of page hits)
• Designing task queue on HL-block with retry and monitoring
• Cron script for queue handler with parallel run protection (flock)
• Supervisor setup for PHP-consumer (with RabbitMQ/Redis)
• Monitoring: alert on growing unprocessed tasks
• Testing: task submission, processing, retry on error