Development of custom CRM entity types for Bitrix24

Development of Custom CRM Entity Types in Bitrix24

In Bitrix24 CRM there is a fixed set of entities: leads, deals, contacts, companies. When a business process doesn't fit any of them — for example, real estate objects, repair requests, complaints — you start adapting deals for an alien task. Fields are named incorrectly for what they mean, pipeline stages describe something other than sales. Smart-processes solve this problem, but their default configuration covers 60% of cases. The remaining 40% require development.

Smart-Processes: What's Under the Hood

A Smart Process (Smart Process Automation, SPA) is a custom CRM entity type. Created via CRM → Settings → Automation → Smart-Processes. Each smart-process receives a numeric entityTypeId (starting from 128) and stores items in table b_crm_dynamic_items_{entityTypeId}.

Programmatically a smart-process is described by class \Bitrix\Crm\Service\Factory\Dynamic. The factory manages the lifecycle of items: creation, update, deletion, movement across stages. To get the factory:

$factory = \Bitrix\Crm\Service\Container::getInstance()
    ->getFactory($entityTypeId);

What's available out of the box:

• Custom fields (UF-fields) of any types — string, number, date, CRM entity binding, file
• Pipeline with stages and semantics (in process / success / failure)
• Robots and business processes on each stage
• Item card with configurable sections
• Kanban and list with filtering
• Timeline and change history
• Access rights through CRM roles

When Standard Smart-Process Isn't Enough

Three scenarios requiring development:

1. Entity relationships. A standard smart-process supports binding to a deal, contact, company. But if you need a many-to-many relationship between two smart-processes (e.g., "Object" and "Defect" — one object has many defects, one defect can belong to multiple objects), you'll need to create an intermediate entity or implement a relationship through REST handlers and custom fields of type crm_multifield.

2. Calculated fields. UF-fields don't support formulas. If the field "Profitability" = (Revenue - Cost) / Revenue * 100, its value needs to be recalculated by a handler on onAfterUpdate event. Handler registration:

$eventManager = \Bitrix\Main\EventManager::getInstance();
$eventManager->registerEventHandler(
    'crm',
    'onAfterCrmDynamicItemUpdate_128',
    'local',
    '\\Local\\Handler',
    'recalculateMargin'
);

3. Custom validation. Standard check — field requirement. If you need business validation (e.g., end date not earlier than start date, sum of items equals total sum), it's implemented through onBeforeCrmDynamicItemUpdate handler, which can cancel save and return an error.

Field and Stage Design

Before creating a smart-process, map your fields. Distinguish:

• Core fields — displayed in card and list, participate in filtering. Optimally 10–15 fields.
• Service fields — used by robots and handlers, hidden from interface via card settings.
• Archive fields — data for history, not indexed.

Pipeline stages are designed by irreversibility principle: an item moves left to right, return to previous stage — an exception, not norm. Each stage should mean a specific action: "Awaiting Legal Review", not "In Process".

Stage semantics are critical: STAGE_SEMANTIC_ID fields take values P (process), S (success), F (failure). CRM analytics are built on this semantics — conversion funnel, average cycle, forecast. Without semantics, reports will be empty.

Integration Through REST API

For external systems smart-processes are available via REST:

• crm.type.list — list of all entity types
• crm.item.add?entityTypeId=128 — create item
• crm.item.list?entityTypeId=128&filter[STAGE_ID]=DT128_1:NEW — filter by stage
• crm.item.update — update with automatic robot execution

Format STAGE_ID for smart-processes: DT{entityTypeId}_{categoryId}:{STATUS_CODE}. This is not obvious and often causes errors during integration — deal stages and smart-process stages are formatted differently.

Data Migration from "Workaround" Deals

If your business already misuses deals, migration to smart-process includes:

1. Create smart-process with similar fields
2. Map stages from old pipeline to new type stages
3. Batch data transfer via crm.item.add in loop (REST limit — 50 requests/sec, batch up to 50 commands)
4. Reconfigure robots and business processes
5. Switch integrations to new entityTypeId

What's Often Overlooked

Smart-processes don't support product items out of the box in the cloud version — only in the on-premise version through customization. If an item needs a tabular section (order items, list of works), implement it through linked items of another smart-process or through a custom JSON field (storage in UF_CRM_* string type with serialization).