Начало работы

Введение

Исторически так сложилось, что манипуляция данными об элементах основных сущностей CRM осуществляется с помощью массивов.

У этого подхода есть ряд недостатков:

• Названия полей у разных сущностей отличаются, хотя имеют одинаковый смысл. Надо всегда помнить их названия.
• Нет autocomplete в IDE.
• Нет типизации и др.

С точки зрения публичного интерфейса доступа к данным об элементе сущности, особенных различий между элементами разных сущностей нет. Общего гораздо больше.

Чтобы унифицировать подход, закрыть перечисленные выше недостатки, в новом API был введён абстрактный класс Bitrix\Crm\Item.

Этот класс содержит в себе Bitrix\Main\ORM\Objectify\EntityObject и имитирует его поведение.

Каждый тип сущности имеет свою реализацию этого класса, где содержатся особенности этого типа.

Класс воспроизводит интерфейс \ArrayAccess, при обращении к объекту как к массиву, будут вызваны метод get и set.

Коды "общих" полей этого класса основаны на соответствующих кодах полей таблицы элементов смарт-процесса.

Именованные методы

Класс имеет набор именованных методов (по аналогии с EntityObject) для работы с состоянием и значениями полей.

Например, метод getStageId вернет строковый идентификатор стадии элемента. Даже если поле называется не STAGE_ID, а STATUS_ID, метод всё равно будет работать.

Аналогично будет работать метод setStageId - он запишет новое значение в поле для стадии, независимо от его кода в таблице элементов.

И так же будет работать метод isChangedStageId. Остальные кейсы, доступные в EntityObject, не реализованы.

Работа с именованными методами реализована через магический метод __call. Некоторые именованные методы реализованы в явном виде.

Вот полный набор методов, доступных для работы с полем "Заголовок" (TITLE):

• getTitle(): ?string - вернет текущее значение;
• setTItle(string $title): Item - запишет новое значение;
• isChangedTitle(): bool - вернет true, если значение поля было изменено.

Аналогичным образом можно обращаться к методам других полей. Код поля должен быть преобразован в UpperCamelCase нотацию.

Примеры:

• getCreatedTime(): ?DateTime
• getUpdatedTime(): ?DateTime
• getMovedTime(): ?DateTime
• getCreatedBy(): ?int
• getUpdatedBy(): ?int
• getMovedBy(): ?int
• getAssignedById(): ?int
• getOpened(): bool
• getBegindate(): ?DateTime
• getClosedate(): ?DateTime
• getCompanyId(): ?int
• getContactId(): ?int
• getStageId(): ?string
• getCategoryId(): ?int
• getOpportunity(): ?float
• getIsManualOpportunity(): bool
• getTaxValue(): float
• getCurrencyId(): ?string
• getOpportunityAccount(): ?float
• getTaxValueAccount(): ?float
• getAccountCurrencyId(): ?string
• getMycompanyId(): ?int
• getProductRows(): ?ProductRowCollection
• getClosed(): bool
• getSourceId(): ?string
• getSourceDescription(): ?string
• getWebformId(): ?int

Аналогичным образом можно работать с полями UTM-меток. Хотя значения этих полей не хранятся непосредственно в таблице элементов, к ним есть доступ аналогичным способом из этого класса.

• getUtmSource(): ?string
• getUtmMedium(): ?string
• getUtmCampaign(): ?string
• getUtmContent(): ?string
• getUtmTerm(): ?string

Общие методы

public function __construct(int $entityTypeId, EntityObject 
$entityObject, array $fieldsMap = [], array $disabledFieldNames = [])

public function hasField(string $fieldName): bool

public function getDefaultValue(string $fieldName)

public function get(string $fieldName)

public function set(string $fieldName, $value): self

public function reset(string $fieldName): self

public function unset(string $fieldName): self

public function remindActual(string $fieldName)

public function isChanged(string $fieldName): bool

public function getData(int $valuesType = Values::ALL): array

public function getCompatibleData
(int $valuesType = Values::ALL): array

public function getCompatibleData
(int $valuesType = Values::ALL): array

public function setFromCompatibleData(array $data): self

public function isNew(): bool

public function getId(): int

public function getEntityTypeId(): int

public function getTitlePlaceholder(): ?string

public function save(bool $isCheckUserFields = true): Result

public function delete(): Result

public function jsonSerialize(): array

public function getEntityFieldNameIfExists
(string $commonFieldName): ?string

public function isCategoriesSupported(): bool

public function isStagesEnabled(): bool

public function getCategoryIdForPermissions(): int

Работа с коллекциями

Все методы, изменяющие состояние привязанных коллекций, не производят запись изменений в базу данных. Они только изменяют состояние объекта (аналогично поведению методов get/ set).

Чтобы приведенные ниже методы работали корректно, из БД должны быть выбраны соответствующие данные: поля Item::FIELD_NAME_CONTACTS или Item::FIELD_NAME_CONTACT_BINDINGS для работы с контактами, поле Item::FIELD_NAME_OBSERVERS и поле Item::FIELD_NAME_PRODUCTS для товарных позиций.

Сделать это можно, передав в select метода Factory::getItems необходимые поля.

Если же необходимо получить один элемент, то можно воспользоваться методом Factory::getItem. Он вернет объект, для которого из БД получены все связанные записи.

Чтобы изменения были сохранены, необходимо вызвать метод save.

public function getPrimaryContact(): ?Contact

public function getContacts(): array

public function bindContacts(array $contactBindings): void

public function unbindContacts(array $contactBindings): void

public function getContactBindings(): array

public function getObservers(): array

public function setObservers($observerIds): Item

public function addToProductRows(ProductRow $product): Result

public function removeFromProductRows(ProductRow $product): void

public function setProductRowsFromArrays(array $productArrays): Result

public function setProductRows($products): Result

Пользовательские поля. Файловые поля

Для класса нет особенной разницы, с какими полями он работает - полями самой таблицы или пользовательскими. Главное, чтобы эти поля были доступны в EntityObject.

Есть некоторые особенности при обработке полей типа "Файл".

Особенности работы с файловыми полями

С точки зрения базы данных тип поля "Файл" - это число. Но в старом API файл перед сохранением можно было передать в виде массива с описанием загруженного файла (см. \CFile::MakeFileArray())

Чтобы этот способ работал, при передаче таких данных в метод setFromCompatibleData файл сразу сохраняется в таблицу b_file, а его ID записывается в поле EntityObject.

Загрузка производится через сервис загрузки файлов, который очистит файлы, которые не были сохранены.

Примеры

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

use Bitrix\Crm\Service;
use Bitrix\Crm\Item;

$factory = Service\Container::getInstance()->getFactory(\CCrmOwnerType::Quote);

$newFile = [
	'name' => 'document.docx',
	'size' => 145961,
	'type' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
	'description' => '', 
	'tmp_name' => '/tmp/d1gadg',
];

$fields = [
	'UF_CRM_FIELD' => 'some value',
	'UF_CRM_FILE' => $newFile,
];
$item = $factory->createItem([
	Item::FIELD_NAME_STAGE_ID => 'D128_3:CLIENT' ,
]);
$item->setFromCompatibleData($fields);

// here we can get new file identifier. But if item not saved, this file will be deleted.
$newFileId = $item->get('UF_CRM_FILE');

$result = $item->save();

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

use Bitrix\Crm\Service;
use Bitrix\Crm\Item;

$factory = Service\Container::getInstance()->getFactory(\CCrmOwnerType::Quote);

$item = $factory->getItem(1);
if ($item)
{
	$item->setStageId('SENT');
	$result = $item->save();
}

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

use Bitrix\Crm\Service;
use Bitrix\Crm\Item;

$factory = Service\Container::getInstance()->getFactory(\CCrmOwnerType::Quote);

$item = $factory->getItem(1);
if ($item)
{
	$result = $item->delete();
}

Изменение контактов

Представим, что у нас есть коммерческое предложение с id = 1, привязанное к двум контактам с id = 2 и id = 3. Мы хотим, чтобы оно было привязано к контактам 3 и 4.

use Bitrix\Crm\Binding\EntityBinding;
use Bitrix\Crm\Item;
use Bitrix\Crm\Service;


$factory = Service\Container::getInstance()->getFactory(\CCrmOwnerType::Quote);

$item = $factory->getItem(1);
if ($item)
{
	// add new contact with id = 4
	$item->bindContacts(EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [4]));
	// remove contact with id = 2
	$item->unbindContacts(EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [2]));
}

Преимущества и недостатки

Работа с этим классом имеет ряд преимуществ:

• Легко определить, было ли изменено значение поля (через метод isChanged).
• Прозрачный доступ к значениям полей, соответственно их смыслу, независимо от их кода в таблице.
• Типизация и autocomplete.
• Возможность работать с абстракцией.

При работе с этим классом есть ряд недостатков, связанных с особенностями поведения EntityObject:

• Значения полей приводятся к соответствующему типу. Из-за этого числовые поля с незаполненными значениями отдают 0. И нет никакой возможности определить, там записан 0 или поле не заполнено.
• При работе непосредственно с объектом нет возможности определить, было ли значение поля передано с фронта, или нет. Метод isChanged говорит только о том, изменено ли значение.

Эти недостатки известны, возможно, через некоторое время будут добавлены новые методы, позволяющие их нивелировать.