В этом разделе мы постарались собрать полезные примеры по работе с сущностью.
Table of Contents
Поиск по основным параметрам
Найти лиды, в названии которых есть буква “А”
В этой задаче мы хотим найти лиды, чье название начинается с буквы А, без учета текущих прав пользователя.
\Bitrix\Main\Loader::requireModule('crm');
$leadResult = \CCrmLead::GetListEx(
[],
[
'%TITLE' => 'А',
'CHECK_PERMISSIONS' => 'N'
],
false,
false,
[
'ID',
'TITLE'
]
);
while( $lead = $leadResult->fetch() )
{
/**
* [ 'ID' => ..., 'TITLE' => ... ]
* @var array
*/
var_dump($lead);
var_dump($lead['ID']);
}
Найти все лиды у которых есть телефон
Архитектурно множественные поля, такие как телефон, email или мессенджеры хранятся в отдельной таблице и чтобы не выполнять лишних запросов при операциях над такими контактами созданы поля-прослойки, которые отмечают факт наличия определенных связей.
HAS_PHONE
(Y/N
) - Y
в случае наличия хотя бы одного телефона
HAS_EMAIL
(Y/N
) - Y
в случае наличия хотя бы одной почты
HAS_IMOL
(Y/N
) - Y
в случае наличия хотя бы одного мессенджера
\Bitrix\Main\Loader::requireModule('crm');
$leadResult = \CCrmLead::GetListEx(
[],
[
'HAS_PHONE' => 'Y',
'CHECK_PERMISSIONS' => 'N'
],
false,
false,
[
'ID',
'TITLE'
]
);
while( $lead = $leadResult->fetch() )
{
/**
* [ 'ID' => ..., 'TITLE' => ... ]
* @var array
*/
var_dump($lead);
var_dump($lead['ID']);
}
Множественные поля
Мы уже описали что Битрикс24 хранит множественные поля отдельно и часто возникает вопрос как работать с такими полями. Наиболее удобным способом является работа от API множественных полей.
Получение всех телефонов контакта
Задача: найти все телефонные номера лида с ID:1
\Bitrix\Main\Loader::requireModule('crm');
$resFieldMulti = \CCrmFieldMulti::GetListEx(
[],
[
'ENTITY_ID' => \CCrmOwnerType::LeadName,
'ELEMENT_ID' => 1,
'TYPE_ID' => \CCrmFieldMulti::PHONE
]
);
while( $multifield = $resFieldMulti->fetch() )
{
/**
* $multifield = [
* "ID" => string(1) "6",
* "ENTITY_ID" => string(7) "LEAD",
* "ELEMENT_ID" => string(1) "1",
* "TYPE_ID" => string(5) "PHONE",
* "VALUE_TYPE" => string(4) "WORK",
* "COMPLEX_ID" => string(10) "PHONE_WORK"
* "VALUE" => string(9) "213 11 64"
* ];
*/
}
Найти лид по номеру телефона
Метод CCrmFieldMulti::GetListEx
выглядит удобным для поиска лида по телефонному номеру, однако это ошибочное мнение. Дело в том что таблица хранит в себе заданные пользователем значения as is
(как есть), т.е. один телефонный номер может быть записан в нескольких вариантах, например:
- 88002000600
- +7 800 2000 600
- 8 (800) 200-60-00
С точки зрения человека это один и тот же номер, но с точки зрения системы это совершенно разные строки.
Для данного метода поиск требует чтобы данные были проиндексированы менеджером дубликатов. В случае если поиск не производился или он устарел, данные будут некорректны.
Наиболее удобным является поиск по номеру телефона в системе дубликатов.
Найдем все контакты, которые имеют номер 2131164
:
\Bitrix\Main\Loader::requireModule('crm');
/**
* Телефон который будем искать
* @var string
*/
$phone = '2131164';
/**
* Список всех ID лидов с этим телефонным номером
* @var int[]
*/
$leadIds = [];
$adapter = \Bitrix\Crm\EntityAdapterFactory::create([
'FM' => [
'PHONE' => [
['VALUE' => $phone]
]
]
],
\CCrmOwnerType::Lead
);
$dups = (new \Bitrix\Crm\Integrity\ContactDuplicateChecker())
->findDuplicates(
$adapter,
new \Bitrix\Crm\Integrity\DuplicateSearchParams([
'FM.PHONE'
])
);
foreach($dups as &$dup)
{
if(!($dup instanceof \Bitrix\Crm\Integrity\Duplicate))
{
continue;
}
$entities = $dup->getEntities();
if(!(is_array($entities) && !empty($entities)))
{
continue;
}
//Each entity type limited by 50 items
foreach($entities as &$entity)
{
if(!($entity instanceof \Bitrix\Crm\Integrity\DuplicateEntity))
{
continue;
}
if ( $entity->getEntityTypeID() != \CCrmOwnerType::Lead)
{
continue;
}
$leadIds[] = $entity->getEntityID();
}
}
Телефонный номер в таблице дубликатов хранится в виде строки состоящей из чисел, поэтому предавая ее на поиск в менеджере дубликатов предварительно нужно очистить ненужные символы.
Дата рождения
Найти лиды, день рождения которых сегодня
Иногда необходимо найти лиды чье день рождения выпадает на определенное число или месяц. Так как не все СУБД поддерживают частичный поиск по полям с типом дата, разработчики использовали иной подход к подсистеме хранения даты рождения. При изменении даты рождения исходное значение сохраняется в поле BIRTHDATE
, в то время как на основании дня и месяца рождения вычисляется специальное число хранящееся в поле BIRTHDAY_SORT
.
Таким образом, чтобы найти пользователя у которого день рождения выпадает на определенно число нужно:
- Сгенерировать число для данной даты
- Выполнить поиск числа по ключу
BIRTHDAY_SORT
Для генерации сортировочного числа используется класс Bitrix\Crm\BirthdayReminder
:
\Bitrix\Main\Loader::requireModule('crm');
$birthDate = date('d.m.Y');
$sort = \Bitrix\Crm\BirthdayReminder::prepareSorting($birthDate);
/**
* Например при:
* $birthDate = 29.06.2021;
*
* Будет результат:
* $sort = 189;
*/
Остается только дополнить поиск:
$leadResult = \CCrmLead::GetListEx(
[],
[
'BIRTHDAY_SORT' => $sort,
'CHECK_PERMISSIONS' => 'N'
],
false,
false,
[
'ID',
'FULL_NAME'
]
);
while( $lead = $leadResult->fetch() )
{
/**
* [ 'ID' => ..., 'TITLE' => ... ]
* @var array
*/
var_dump($lead);
var_dump($lead['ID']);
}
Альтернативный вариант поиска контактов
Помимо изложенного выше пути существует и другой путь для поиска: через специальный метод getNearestEntities
класса Bitrix\Crm\BirthdayReminder
.
Сигнатура метода:
\Bitrix\Crm\BirthdayReminder::getNearestEntities(
$entityID,
$currentDate,
$startDate = '',
$responsibleID = 0,
$intervalInDays = 7,
$checkPermissions = true,
$limit = 5
);
-
$entityID
- тип сущности. Поддерживается\CCrmOwnerType::Lead
и\CCrmOwnerType::Contact
-
$currentDate
- текущая дата в формате сайта -
$startDate
- дата с которой нужно начинать поиск (в формате сайта) -
$responsibleID
- ID ответственного (если нужно), по-умолчанию - не учитывать -
$intervalInDays
- сколько дней от$startDate
нужно вычислять -
$checkPermissions
- проверять права на просмотр -
$limit
- количество возвращаемых элементов
\Bitrix\Main\Loader::requireModule('crm');
$leads = \Bitrix\Crm\BirthdayReminder::getNearestEntities(
\CCrmOwnerType::Lead,
date('d.m.Y'),
date('d.m.Y', strtotime('+1day')),
0,
7,
false,
5
);
var_dump($leads);
/**
* Example:
* [
* [
* "ID" => string(1) "9",
* "BIRTHDATE" => string(10) "29.06.2021",
* "BIRTHDAY_SORT" => int(189)
* "HONORIFIC" => NULL,
* "NAME" => string(16) "Светлана",
* "SECOND_NAME" => string(0) "",
* "LAST_NAME" => string(16) "Копылова",
* "PHOTO" => NULL,
* "ENTITY_TYPE_ID" => int(3),
* "IMAGE_ID" => int(0),
* "IS_BIRTHDAY" => bool(true)
* ]
* ]
*
*/