Связи

Терминология

Термины, используемые в документации.

• Тип сущности (сущность) - сущность CRM. Например, Сделка, Лид, конкретный тип Смарт-процесса.
• Элемент - элемент сущности CRM. Это может быть конкретная сделка (например, сделка с ID = 14), конкретное коммерческое предложение или конкретный элемент смарт-процесса.
• Тип связи - если существует тип связи между двумя типами сущностей CRM, то это значает, что элементы этих сущностей можно связать между собой. Например, если существует тип связи Сделка - Предложение, то мы можем привязать конкретную сделку к конкретному предложению.
• Связь - связь между конкретными элементами сущностями. Например, связь между сделкой с ID = 14 и предложением с ID = 62
• Родительская сущность - тип сущности, к элементам которого привязывается элемент-потомок.
• Сущность-потомок - тип сущности, элементы которого привязываются к элементу-родителю.
• entityTypeId - константа класса \CCrmOwnerType (например, \CCrmOwnerType::Lead), которая однозначно идентифицирует какой-то тип сущности.
• entityId - ID элемента. Например, ID конкретной сделки.

Основной концепт

Чтобы организовать работу со связями между сущностями в едином формате используется API из пространства имён \Bitrix\Crm\Relation. Основная идея заключается в следующем:

\Bitrix\Crm\Relation\RelationManager - сервис, получаемый через контейнер. Он является "точкой входа" всего API. Через него можно проверить, есть ли тип связи между сущностями, создать новый тип связи или связать элементы.

Объект класса \Bitrix\Crm\Relation представляет собой конкретный тип связи между сущностями, например, Сделка — Предложение

Объект класса \Bitrix\Crm\ItemIdentifier хранит данные, по которым можно однозначно идентифицировать конкретный элемент любой сущности CRM

Объект класса \Bitrix\Crm\RelationIdentifier, по аналогии с ItemIdentifier, хранит данные, по которым можно однозначно идентифицировать конкретный тип связи между сущностями

Для ознакомления описан \Bitrix\Crm\Service\ParentFieldManager - объект-сервис, получаемый через контейнер.

Примеры использования

Сниппеты для типовых вариантов использования API.

Создать новый тип связи:

use Bitrix\Crm\Relation;
use Bitrix\Crm\Service\Container;

$newRelation = Relation::create(\CCrmOwnerType::Deal, \CCrmOwnerType::Activity);

/** @var Bitrix\Main\Result $result */
$result = Container::getInstance()->getRelationManager()->bindTypes($newRelation);

Связать два элемента:

use Bitrix\Crm\ItemIdentifier;
use Bitrix\Crm\Service\Container;

$parent = new ItemIdentifier(\CCrmOwnerType::Deal, 1);
$child = new ItemIdentifier(\CCrmOwnerType::Activity, 1);

/** @var Bitrix\Main\Result $result */
$result = Container::getInstance()->getRelationManager()->bindItems($parent, $child);

Проверить, связаны ли элементы

use Bitrix\Crm\ItemIdentifier;
use Bitrix\Crm\Service\Container;

$parent = new ItemIdentifier(\CCrmOwnerType::Deal, 1);
$child = new ItemIdentifier(\CCrmOwnerType::Activity, 1);

/** @var bool $result */
$result = Container::getInstance()->getRelationManager()->areItemsBound($parent, $child);

Получить все родительские элементы, привязанные к элементу

use Bitrix\Crm\ItemIdentifier;
use Bitrix\Crm\Service\Container;

$child = new ItemIdentifier(\CCrmOwnerType::Activity, 1);

/** @var ItemIdentifier[] $parents */
$parents = Container::getInstance()->getRelationManager()->getParentElements($child);

Получить все типы связей, где данная сущность является родителем:

use Bitrix\Crm\Relation;
use Bitrix\Crm\Service\Container;

/** @var Relation\Collection $childRelations */
$childRelations = Container::getInstance()->getRelationManager()->getChildRelations(\CCrmOwnerType::Deal);

Получить все стандартные типы связи для данной сущности:

use Bitrix\Crm\Relation;
use Bitrix\Crm\Service\Container;

/** @var Relation\Collection $relations */
$relations = Container::getInstance()->getRelationManager()->getRelations(\CCrmOwnerType::Deal);
/** @var Relation\Collection $predefinedRelations */
$predefinedRelations = $relations->filterOutCustomRelations();