CCrmEvent::GetList: работа с историей событий в CRM Битрикс24

13 июля 2026

Полезное

Введение

При разработке на «коробочной» версии Битрикс24 часто возникает задача программного получения истории изменений различных сущностей CRM — лидов, сделок, контактов и компаний. Универсальным инструментом для этого является метод CCrmEvent::GetList. Он предоставляет доступ к таблице b_crm_event, где хранится вся история событий: изменения полей, создание звонков, добавление связей, просмотры и другие действия пользователей.

Область применения и ключевые сущности

Метод используется для получения истории событий в следующих контекстах:

Изменение полей сущностей — отслеживание изменений значений полей лидов, сделок, контактов, компаний. Например, изменение ответственного (ASSIGNED_BY_ID), статуса, стадии, названия и других полей.
История коммуникаций — созданные звонки, письма, встречи, задачи, связанные с сущностью CRM.
Действия пользователей — просмотры карточек, добавление комментариев, изменение связей между сущностями.
Бизнес-процессы и роботы — события, генерируемые бизнес-процессами при переходе между стадиями или выполнении действий.
Связи и привязки — добавление или удаление связей между лидами, контактами, компаниями и сделками.

Параметры метода

Метод имеет следующую сигнатуру:

php

public static function GetList($arOrder = array(), $arFilter = array(), $arGroupBy = false, $arNavStartParams = false, $arSelectFields = array())

Параметр `$arOrder` (сортировка)

Определяет порядок сортировки записей. Представляет собой ассоциативный массив, где ключ — поле сортировки, значение — направление (ASC или DESC). Поддерживаемые ключи:

ID — уникальный идентификатор записи
DATE_CREATE — дата и время создания события (используется чаще всего)
EVENT_TYPE — тип события
CREATED_BY_ID — идентификатор пользователя, создавшего событие

Пример:

php

$arOrder = array('DATE_CREATE' => 'ASC'); // от старых к новым

Параметр `$arFilter` (фильтрация)

Позволяет отфильтровать результаты по одному или нескольким критериям. Основные поддерживаемые ключи:

ID — фильтр по уникальному идентификатору события
ENTITY_TYPE — тип сущности (LEAD, DEAL, CONTACT, COMPANY)
ENTITY_ID — идентификатор сущности
EVENT_TYPE — тип события (1 — изменение поля, 2 — другие действия)
EVENT_NAME — название события (полный текст или с использованием % для поиска по шаблону)
CREATED_BY_ID — идентификатор пользователя, создавшего событие
ASSOCIATED_ENTITY_TYPE — тип ассоциированной сущности (для событий связи)ASS
OCIATED_ENTITY_ID — идентификатор ассоциированной сущности
Важно: Поля EVENT_TEXT_1 и EVENT_TEXT_2 нельзя использовать в фильтре через API — они доступны только при переборе результатов.

Параметр `$arGroupBy` (группировка)

Позволяет группировать результаты по указанным полям. Обычно не используется при работе с историей событий. По умолчанию false.

Параметр `$arNavStartParams` (постраничная навигация)

Позволяет ограничить количество получаемых записей. Используется для оптимизации производительности при большом количестве событий.

Примеры:

php

// Получить только первые 50 записей
$arNavStartParams = array('nTopCount' => 50);

// Получить с постраничной навигацией
$arNavStartParams = array('nPageSize' => 20);

Параметр `$arSelectFields` (выбираемые поля)

Определяет, какие поля будут возвращены в результате. Если не указан, возвращаются все поля. Основные поля:

ID — идентификатор события
DATE_CREATE — дата и время создания
CREATED_BY_ID — ID пользователя, создавшего событие
EVENT_NAME — название события
EVENT_TEXT_1 — первое текстовое поле события (например, старое значение)
EVENT_TEXT_2 — второе текстовое поле события (например, новое значение)
EVENT_TYPE — тип события (1, 2 и др.)
FILES — идентификаторы прикрепленных файлов

Возвращаемое значение

Метод возвращает объект результата запроса CDBResult, который содержит записи таблицы b_crm_event. Перебор результатов осуществляется через метод fetch() в цикле while.

Практические примеры

Пример 1. Получение всей истории событий лида

php

// Подключаем модуль CRM
if (\Bitrix\Main\Loader::includeModule('crm')) {
    $leadId = 12345;
    $events = array();
    
    $dbResult = CCrmEvent::GetList(
        array('DATE_CREATE' => 'ASC'),        // сортировка по дате
        array(
            'ENTITY_TYPE' => 'LEAD',           // тип сущности
            'ENTITY_ID' => $leadId             // ID сущности
        ),
        false,
        false,
        array('*')
    );
    
    while ($event = $dbResult->fetch()) {
        $events[] = array(
            'ID' => $event['ID'],
            'DATE_CREATE' => $event['DATE_CREATE'],
            'EVENT_NAME' => $event['EVENT_NAME'],
            'EVENT_TEXT_1' => $event['EVENT_TEXT_1'],
            'EVENT_TEXT_2' => $event['EVENT_TEXT_2'],
            'CREATED_BY_ID' => $event['CREATED_BY_ID']
        );
    }
}

Пример 2. Получение только событий изменения ответственного

php

$dbResult = CCrmEvent::GetList(
    array('DATE_CREATE' => 'ASC'),
    array(
        'ENTITY_TYPE' => 'LEAD',
        'ENTITY_ID' => $leadId,
        'EVENT_NAME' => 'Значение поля "Ответственный" было изменено'
    ),
    false,
    false,
    array('*')
);

while ($event = $dbResult->fetch()) {
    $oldResponsible = $event['EVENT_TEXT_1']; // кто был
    $newResponsible = $event['EVENT_TEXT_2']; // кто стал
}

Пример 3. Поиск первого назначения ответственного

php

$responsibleId = 1347; // ID текущего ответственного

// Получаем ФИО ответственного
$rsUser = CUser::GetByID($responsibleId);
$arUser = $rsUser->Fetch();
$responsibleName = trim($arUser['LAST_NAME'] . ' ' . $arUser['NAME']);

// Получаем все события изменения ответственного
$dbResult = CCrmEvent::GetList(
    array('DATE_CREATE' => 'ASC'),
    array(
        'ENTITY_TYPE' => 'LEAD',
        'ENTITY_ID' => $leadId,
        'EVENT_NAME' => 'Значение поля "Ответственный" было изменено'
    ),
    false,
    false,
    array('*')
);

$firstAssignmentDate = null;
while ($event = $dbResult->fetch()) {
    // Ищем первое появление текущего ответственного
    if (strpos($event['EVENT_TEXT_2'], $responsibleName) !== false) {
        $firstAssignmentDate = $event['DATE_CREATE'];
        break; // первое назначение найдено
    }
}

Пример 4. Получение последних событий с ограничением

php

$dbResult = CCrmEvent::GetList(
    array('DATE_CREATE' => 'DESC'),        // сначала новые
    array(
        'ENTITY_TYPE' => 'DEAL',
        'ENTITY_ID' => $dealId
    ),
    false,
    array('nTopCount' => 10),              // только 10 записей
    array('*')
);

while ($event = $dbResult->fetch()) {
    // Обработка последних 10 событий
}

Пример 5. Фильтрация по типу события

php

$dbResult = CCrmEvent::GetList(
    array('DATE_CREATE' => 'ASC'),
    array(
        'ENTITY_TYPE' => 'LEAD',
        'ENTITY_ID' => $leadId,
        'EVENT_TYPE' => 1                     // только изменения полей
    ),
    false,
    false,
    array('*')
);

Пример 6. Поиск событий по тексту (поисковая фильтрация)

php

// Поиск всех событий, содержащих слово "звонок"
$dbResult = CCrmEvent::GetList(
    array('DATE_CREATE' => 'DESC'),
    array(
        'ENTITY_TYPE' => 'LEAD',
        'ENTITY_ID' => $leadId,
        'EVENT_NAME' => '%звонок%'            // LIKE поиск
    ),
    false,
    false,
    array('*')
);

Пример 7. Получение истории для всех сущностей пользователя

php

$userId = 1347;
$dbResult = CCrmEvent::GetList(
    array('DATE_CREATE' => 'DESC'),
    array(
        'CREATED_BY_ID' => $userId            // события, созданные пользователем
    ),
    false,
    array('nTopCount' => 100),
    array('*')
);

while ($event = $dbResult->fetch()) {
    // История действий пользователя
}

Альтернативные методы

Для работы с историей событий также доступны:

CCrmLead::GetListEx() — для получения списка лидов с возможностью сортировки и фильтрации
CCrmDeal::GetListEx() — аналогично для сделок
CCrmEvent::GetListInfo() — упрощенный метод для получения событий без дополнительных параметров

Особенности и рекомендации

Обязательное подключение модуля: Перед вызовом любого метода CRM необходимо подключить модуль через CModule::IncludeModule('crm') или \Bitrix\Main\Loader::includeModule('crm').
Структура таблицы b_crm_event: Основные поля: ID, DATE_CREATE, CREATED_BY_ID, EVENT_NAME, EVENT_TEXT_1, EVENT_TEXT_2, EVENT_TYPE, FILES. Поля EVENT_TEXT_1 и EVENT_TEXT_2 хранят текстовую информацию в зависимости от типа события.
Фильтрация по EVENT_NAME: EVENT_NAME хранит полный текст названия события. Для поиска используйте % для LIKE-запросов. Для точного совпадения указывайте полное название.
Производительность: При получении истории с большим количеством событий обязательно используйте $arNavStartParams для ограничения количества записей. Рекомендуется также использовать индексы полей ENTITY_TYPE и ENTITY_ID.
Событие "Изменение ответственного": Название события для изменения поля "Ответственный" выглядит как Значение поля "Ответственный" было изменено. При разработке учитывайте, что это значение зависит от локализации системы.
События звонков: Создание звонка генерирует событие с названием Создан звонок, а в EVENT_TEXT_1 сохраняется тема звонка.
События стадий: Изменение стадии создает событие Стадия изменена, где в EVENT_TEXT_1 хранится старое значение, а в EVENT_TEXT_2 — новое.
Логирование: Для отладки рекомендуется выводить структуру событий, чтобы понять, в каких полях хранится нужная информация для конкретного типа события.
Привязка к сущности: События привязываются к сущности через комбинацию полей ENTITY_TYPE и ENTITY_ID. ENTITY_TYPE может принимать значения LEAD, DEAL, CONTACT, COMPANY.

Заключение

CCrmEvent::GetList — это основной инструмент для программного доступа к истории событий CRM в коробочной версии Битрикс24. Он обеспечивает гибкую фильтрацию и сортировку, позволяя получать любые события: от изменений полей до коммуникаций и действий пользователей. Понимание этого метода необходимо каждому разработчику, работающему с CRM-модулем Битрикс, особенно при реализации отчетов, аудита и аналитики.

Начните сотрудничество с индивидуальной консультации по подбору инструментов и услуг.

Заказать услугу

Комментарии

Загрузка комментариев...

Назад к списку