Task Queue Setup for 1C-Bitrix: Complete Guide

Task Queue Setup for 1C-Bitrix

Imagine: exchange with 1C fails due to timeout, an email campaign to 5000 subscribers blocks a hit, PDF generation for 20,000 products crashes the server. All these tasks share one thing: they cannot be executed in an HTTP request. A queue is needed—a mechanism that accepts a task, stores it, and executes it in the background via a separate process. We have been working with Bitrix for over 10 years and have set up such queues for 50+ projects—here's how it's done.

A task queue is a critical component for high-load projects. Without it, every long process blocks user requests, and timeouts lead to data loss. A properly designed queue solves three problems: guarantees execution, allows parallel processing of hundreds of tasks, and provides a retry mechanism for failed operations. In Bitrix, there are several approaches: from simple agents to external brokers like RabbitMQ.

Built-in Mechanisms: Agents

Agents (CAgent) are Bitrix's built-in deferred task system. An agent is a function called on a 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", // active "" // first run date ); 

Agents run in two ways:

• On hits (default)—on each request, Bitrix checks if there are agents due to run. Problem: if there's no traffic, agents don't run. If traffic is high, agent checks add load to every hit.
• On cron—the recommended mode. Add a crontab entry: */5 * * * * /usr/bin/php /var/www/bitrix/modules/main/tools/cron_events.php. Parameter in .settings.php:

'agents' => [ 'value' => [ 'use_crontab' => true ] ] 

Why Agents on Hits Are Bad

Agents on hits are the main cause of performance degradation on mid-sized projects. Every HTTP request spends up to 10% of its time checking and launching agents. With 10,000 visitors per day, that leads to an extra 20,000 calls to CAgent::CheckAgents() per hour. Moving to cron reduces server load by up to 70% and guarantees execution even with zero traffic.

When Agents Are Not Enough

Agents are single-threaded. One agent runs, others wait. If a data import agent takes 10 minutes, all other agents (email sending, cache recalculation, 1C exchange) are delayed. For projects with intensive background processing, a full queue is needed.

Queue Based on an HL-block

The 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 (retry count), UF_CREATED_AT, UF_PROCESSED_AT.
2. Task submission—QueueJobTable::add(['UF_HANDLER' => 'ImportHandler', 'UF_PAYLOAD' => json_encode($data), 'UF_STATUS' => 'pending']). Use D7 ORM—the standard for Bitrix.
3. Handler (cron script)—runs every minute, selects N tasks with status pending, changes to processing, executes, marks done or failed.

Advantages: retry (based on UF_ATTEMPTS), monitoring (SQL query to HL-block), priorities (add field UF_PRIORITY).

How to Set Up an HL-block Queue: Step-by-Step

1. Create an HL-block QueueJob with fields: UF_HANDLER (string), UF_PAYLOAD (text), UF_STATUS (list: pending, processing, done, failed), UF_ATTEMPTS (int), UF_CREATED_AT (datetime), UF_PROCESSED_AT (datetime).
2. Add an index on UF_STATUS for fast selection of pending tasks.
3. Write a handler class with method run($payload) that returns true/false.
4. Create a cron script that every minute selects up to 10 tasks with status pending, changes them to processing, calls the handler, and on success marks done, on failure marks failed with incremented attempts.
5. Protect the script from parallel execution using flock.

External Brokers: RabbitMQ, Redis

For high-load projects:

• RabbitMQ—connect via php-amqplib. Producer in Bitrix adds a task to the queue, Consumer—a separate PHP daemon that listens to the queue and executes tasks. Throughput: up to 10,000 tasks per minute.
• Redis—via LPUSH/BRPOP. Simpler than RabbitMQ, sufficient for most scenarios. Integration with Bitrix: producer is registered as an event handler (e.g., OnSalePayOrder), consumer runs via Supervisor.

Comparison: HL-block vs RabbitMQ vs Redis

According to our tests, an HL-block queue processes tasks 3-5 times faster than agents on hits, and RabbitMQ is 2 times faster than an HL-block.

What Is Included in Queue Setup

• Migration of agents from hits to cron with interval adjustments
• Design of HL-block or selection of external broker based on your load
• Development of queue handler with retry and logging
• Supervisor setup for RabbitMQ/Redis consumers
• Asynchronous launch of business processes (Bizproc) via queue
• Monitoring: alert when more than 50 unprocessed tasks accumulate
• Operation documentation and training for your team
• 30 days of post-release support

Why Us and How We Estimate the Project

Our engineers have worked with Bitrix since version 10, completed over 50 projects for background process optimization. We reduce server load by up to 70%, speed up task processing by 10 times. The cost of queue setup is determined after a load analysis. Source: official Bitrix documentation

Contact us for a consultation on your project. We will evaluate the load and propose the optimal solution—whether HL-block or RabbitMQ. Order a preliminary audit to get exact timelines and cost for your scenario. Get a detailed queue optimization plan—free on the introductory call.