Bindings

CRM entities can be associated/bound. Deal can have specific bound Contacts, with ongoing negotiations for example. Another example: a quote created or invoice issued from a deal. Practically any CRM entity can have a binding to another.

Entity bindings API is available from the update CRM 20.700.0.

Terminology

Terminology, used in documentation.

• Entity type (entity) - a CRM entity. For example, Deal, Lead, specific SPA type.
• Item - CRM entity item. It can be a specific deal (for example, deal with ID = 14), specific quote or specific SPA item.
• Binding type - if binding type exists between two CRM entity types, it means that theses entity elements can be bound between each other. For example, when binding type Deal - Quote exists, you can bind a specific deal to a specific quote.
• Binding - binding between specific entity items. For example, binding between a deal with ID = 14 and quote with ID = 62
• Parent entity - entity type, with binded descendant element.
• Descendant entity - entity type, with items bound to parent item.
• entityTypeId - \CCrmOwnerType class constant (for example, \CCrmOwnerType::Lead), identifies a specific entity type.
• entityId - Item ID. For example, specific deal ID.

Main concept

To organize handling of element bindings in a single format, use API from the namespace \Bitrix\Crm\Relation. Main idea is as follows:

\Bitrix\Crm\Relation\RelationManager - service, retrieved via container. It's "an entry" for the complete API. It can be used to check, if binding type exists between entities, or to create new binding type or to bind items.

\Bitrix\Crm\Relation object class is a specific binding type between entities, for example, Deal - Quote

\Bitrix\Crm\ItemIdentifier class object stores data for direct identification of specific item of any CRM entity

\Bitrix\Crm\RelationIdentifier class object, similar to ItemIdentifier, stores data used for direct identification of specific binding type between entities

\Bitrix\Crm\Service\ParentFieldManager - service object is written for familiarization; retrieved via container.

Examples

Snippets for standard API use variants.

Create new binding type:

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);

Bind two items:

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);

Check if items are bound

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);

Get all parent items, bound to an item

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

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

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

Get all binding types, where this entity is a parent:

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

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

Get all standard binding types for this entity:

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();