Designing Business Process Logic in Bitrix24

Designing Business Process Logic in Bitrix24

Business processes in Bitrix24 are one of those features that, when applied thoughtfully, save hours of daily manual work — and when implemented without proper planning, create chaos: hung instances, notifications that never arrive, and tasks that silently drop to an undefined step with no indication of why.

After years of designing BPs of varying complexity, we've arrived at a clear understanding: most problems don't appear at the implementation stage in the visual designer — they appear at the task definition stage, when the process logic hasn't been formally documented before the first click of a mouse.

BP Architecture in Bitrix24

The business process engine in Bitrix24 is based on the bizproc module. A process is described as a graph of activities (CBPActivity) with transitions between them. Each process instance is stored in the tables b_bp_workflow_instance, b_bp_workflow_state, and b_bp_task — these are the first places to look when diagnosing hung processes.

Activities are divided into:

• System activities — delay, condition, parallel activity, loop.
• Actions — send notification, create task, modify an entity field, call a REST method.
• User-defined activities (UDA) — custom activities written in PHP and registered via CBPActivity::RegisterActivity().

An important nuance: BPs in Bitrix24 can be attached to leads, deals, contacts, companies, tasks, live feed documents, and smart process items. Each entity type has its own variable context and its own available actions. This must be considered during design: a process written for a deal cannot be directly reused for a smart process without adaptation.

The Design Process

Step 1. Formalize the process in BPMN (or a simplified notation).

Before opening the BP designer — draw a flowchart. Required elements: start, end (there can be multiple), branches with conditions, the person responsible for each step, timers, and escalations. Pay particular attention to exception paths: what happens if the client doesn't respond for 3 days, if the responsible person is on vacation, if a payment is returned with an error.

Exception paths are the primary source of problems in implemented BPs. They get forgotten in the designer, and the process hangs waiting indefinitely with no signals.

Step 2. Variable inventory.

In Bitrix24, every process has: process variables (stored only within the instance scope), process parameters (input values at start), and constants. Additionally, the entity's own fields are accessible through Document.

Determine in advance: what data the process reads from the entity, what it creates on its own, and what should be written back to fields upon completion.

Step 3. Trigger definition.

Processes can be started manually, by an event (field change, stage change, entity creation), or on a schedule (via agents in the bizproc module). The trigger type determines the architecture: if a process starts when a deal stage changes, you must protect against repeated launches when returning to the same stage.

Step 4. Notification design.

Notifications in a BP are configured via the "Notification" activity, addressed by role (responsible person, author, specific user, group). A common mistake: a notification is sent to the "responsible person," but at the time that step executes, the "Responsible" field hasn't been filled in yet. The addressing chain must be explicitly defined for each step.

Case Study: Contract Approval Process

Client — a manufacturing company, 80 Bitrix24 users. The task: automate contract approval through the CRM. The contract is attached to a deal as a custom field of type "File." Approval participants: legal counsel, CFO, CEO — sequentially.

The client's initial attempt: three sequential tasks in the BP, each with "Approve/Reject." The problem: when rejected at any step, the process simply ended with no way to revise and resubmit.

The redesigned version included:

• A "submit → approve" cycle with the ability to return for revision at any stage, with a comment
• An escalation timer: if the legal counsel doesn't respond within 2 business days — notify the manager
• A parallel notification to the initiator about the current status at each step
• Writing the final approval status to a custom deal field for reporting
• Automatic creation of a task for the legal counsel with the contract file attached

Implementation took 8 business days, including testing in a test environment and deployment to production.

Limitations and Pitfalls

Versioning. Running process instances continue to operate under the old template version. If a process is modified but old instances haven't completed — two versions of the logic run simultaneously in the system. This must be considered when making changes: sometimes it is necessary to forcibly terminate old instances.

Performance. Heavy BPs with many parallel branches and REST calls can put load on cron. If the CBPSchedulerService::OnAgent agent runs every minute and there are several hundred active instances — this becomes noticeable. Design with load in mind.

REST activities. Calling external systems via REST from within a BP is done through the "Outgoing Webhook" activity or a custom UDA. Error handling must be built in: if the external service is unavailable, the process must not hang indefinitely.

Timeline

Designing a single linear process (5–8 steps, no parallel branches) takes 2–4 days. A complex process with branching, escalations, and integrations takes 1–3 weeks. The service includes: an approved process flowchart, implementation in the BP designer, variable documentation, testing, and handover.