Client in CRM

Client field exist in several types of CRM entities, allowing to bind Contact and Company to such entities. Depending on the implementation, you can bind up to several Contact and/or Companies to a single element.

Standard case - a single binding

In a simplest case, an individual element can have a single client entity bound. Company is used for this most often.

Connection is provided by writing cilent's entity ID into the column CONTACT_ID for Contacts and COMPANY_ID for Companies.

Example of such implementation - binding Company to a deal (table b_crm_deal).

Complex case - multiple binding

Several types of entities (Deal, Quote, Lead) can bind several Contacts. One of them can be the main, the rest - auxiliary.

From Database

The required connection M:N between elements of entities and Contacts is governed by a special table. Each entity has an individual table with the type name b_crm_entity_type_name_contacts (for example, b_crm_deal_contacts, b_crm_quote_contacts). The table has the following structure (with b_crm_deal_contacts as an example):

Field name	Description	Comment
DEAL_ID	INT(1) UNSIGNED NOT NULL	Link to entity ID
CONTACT_ID	INT(1) UNSIGNED NOT NULL	Contact ID
SORT	INT NOT NULL
ROLE_ID	TINYINT(1) NOT NULL
IS_PRIMARY	CHAR(1) NOT NULL	Is the main contact

Main contact ID (IS_PRIMARY === 'Y') also additionally is placed into the column CONTACT_ID of bound entity.

The order has a multiple binding for both Contacts and Companies. Table structure (b_crm_contact_company) and API is different in this specific case from the rest of CRM and is not overviewed in this article.

From API

CRM has an individual namespace Bitrix\Crm\Binding exists for handling the bound entities. Multiple binding with clients is implemented here as well. The namespace contains tables with intermediary tables (DealContactTable and etc.), and classes that process special arrays with bindings, reviewed below: EntityBinding and BindingHelper.

Array with bindings (bindings)

Information about bindings inside CRM is passed in the format of specialized structure arrays - binding arrays (bindings). They are generated and processed using the methods of class EntityBinding.

Array has the following structure:

$bindings = [
	[
		'CONTACT_ID' => 1, // Link to client entity. In case of Company, uses COMPANY_ID
		'SORT' => 10,
		'ROLE_ID' => 0,
		'IS_PRIMARY' => 'Y',
	], 
	// The array, as a minimum, has the fields CONTACT_ID (COMPANY_ID) and SORT
	[
		'CONTACT_ID' => 2,
		'SORT' => 20,
	],
];

How to add/delete a client

Client can be added/deleted when creating or updating entity using a corresponding class (CCrmDeal and etc.). Pass the following values in the parameter $arFields.

$deal = new \CCrmDeal();
$newDealId = $deal->Add([
	'COMPANY_ID' => 1,

	// Contact binding can be done in any keys below. When one parameter is passed, others are not needed
	'CONTACT_ID' => 12, // Binding a single contact
	'CONTACT_IDS' => [1, 2, 3], // Binding several contacts. First contact will be saved as the main contact
	'CONTACT_BINDINGS' => [ // Binding several contacts. Allows directly specifying the main contact, sorting and etc
		'CONTACT_ID' => 1, 
		'SORT' => 10, 
		'ROLE_ID' => 0,
		'IS_PRIMARY' => 'Y',
	],
	[
		'CONTACT_ID' => 2,
		'SORT' => 20,
	],
]);

When updating (CCrmDeal::Update), the parameter $arFields can pass the same keys and the new values will replace the old ones. No need to pass anything contact- or company-related when updating; current values will remain unchanged.

Also, the multiple contacts can be edited directly via corresponding intermediary table (DealContactTable ). However, such action is not recommended, because such updates won't be written into history, for last selected contacts and etc.