Работа с элементами

Работа с элементами

• Класс для работы с элементом любого типа сущности - \Bitrix\Crm\Item
• Получение объектов осуществляется через методы фабрики \Bitrix\Crm\Service\Factory
• Выполнение действий (создание / изменение / удаление и другие) оборачивается в операции \Bitrix\Crm\Service\Operation
• Особенности работы с коллекциями элемента раскрыты в отдельной статье
• Немного про структуру данных с привязками

Создание элемента

$entityTypeId = \CCrmOwnerType::Deal;

$factory = \Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
if (!$factory)
{
	echo 'factory not found';
	return;
}

// пустой элемент, у которого заполнены значения полей по умолчанию. В том числе направление, стадия, кем создан и т.д.
$item = $factory->createItem();

// метод вернет данные об элементе в виде массива, идентичного по структуре "старому" API 
// $item->getCompatibleData();

// теперь надо записать новые значения полей
$item
	->setAssignedById($newAssigned)
	->setMycompanyId($newMycompanyId)
;

// можно данные записать массивом, аналогичным по структуре "старому" API

$item->setFromCompatibleData([
	\Bitrix\Crm\Item::FIELD_NAME_ASSIGNED => $newAssigned,
	\Bitrix\Crm\Item::FIELD_NAME_MYCOMPANY_ID => $newMycompanyId,
])

// данные нигде не сохранены, они только хранятся внутри $item 
// чтобы сохранить изменения в БД без выполнения всех связанных действий, достаточно вызвать
// $item->save();
// НО ДЕЛАТЬ ТАК НЕ РЕКОМЕНДУЕТСЯ.
// Все связанные действия, часто обеспечивающие работоспособность функционала crm будут пропущены (обновления счетчиков,
// прав доступа, поисковых индексов, т.д.)

// если необходимо переопределить контекст выполнения, это надо сделать в явном виде
$context = new \Bitrix\Crm\Service\Context();
$context->setUserId($userId);

// операция производится от пользователя $userId с выполнением всех проверок
$operation = $factory->getAddOperation($item, $context);
$result = $operation->launch();

Изменение элемента

Например, мы хотим изменить состав связанных с элементом контактов, без учёта всех проверок.

$entityTypeId = \CCrmOwnerType::Deal;
$entityId = 261;

$factory = \Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
// нет смысла выполнять код дальше, если у сущности нет поля "Клиент"
if (!$factory || !$factory->isClientEnabled())
{
	echo 'factory not found';
	return;
}

$item = $factory->getItem($entityId);
if (!$item)
{
	echo 'item not found';
	return;
}

// $item->getContacts() вернет массив orm-объектов из таблицы b_crm_contact, привязанных к этому элементу
// он может быть полезен, когда необходимо прочитать данные привязанных контактов.

// здесь хранится простой массив с данными о привязках к контактам
//$existingBindings = $item->getContactBindings();

// добавить связь с контактом с ид = 4
$item->bindContacts(\Bitrix\Crm\Binding\EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [4]));
// удалить связь с контактом с ид = 3
$item->unBindContacts(\Bitrix\Crm\Binding\EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [3]));

// данные о новых привязках ещё нигде не сохранены, они только хранятся внутри $item 
// чтобы сохранить изменения в БД без выполнения всех связанных действий, достаточно вызвать
// $item->save();
// НО ДЕЛАТЬ ТАК НЕ РЕКОМЕНДУЕТСЯ.
// Все связанные действия, часто обеспечивающие работоспособность функционала crm будут пропущены (обновления счетчиков,
// прав доступа, поисковых индексов, т.д.)

// если необходимо переопределить контекст выполнения, это надо сделать в явном виде
// $context = new \Bitrix\Crm\Service\Context();
// $context->setUserId($userId);

$operation = $factory->getUpdateOperation($item);
$operation->disableAllChecks();

$result = $operation->launch();

Удаление элемента

$entityTypeId = \CCrmOwnerType::Deal;
$entityId = 260;

$factory = \Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
if (!$factory)
{
	echo 'factory not found';
	return;
}

$item = $factory->getItem($entityId);
if (!$item)
{
	echo 'item not found';
	return;
}

// удалить элемент без выполнения дополнительных проверок и действий можно через
// $item->delete();
// НО ТАК ДЕЛАТЬ НЕ РЕКОМЕНДУЕТСЯ!
// В таблицах останутся лишние записи (индексы, связи и т.д.)

$result = $factory->getDeleteOperation($item)->launch();