Collection extra info

Overview

The main article provides Item methods for handling collections (contacts, products, observers). When you are searching API description, please refer to it. This article details on how these entities are handled in Item, some method specifics, particulars and nuances.

Working with collections is based on ORM. EntityObject, used inside Item has access to associated records via standard relations mechanism in ORM. In case of contacts - these are entries for associations and for product positions and observers - entries of corresponding tables (you can find more details on data in each corresponding section). Element table has the field OneToMany in description with necessary name (for example, Item::FIELD_NAME_CONTACT_BINDINGS for contacts and Item::FIELD_NAME_PRODUCTS for product positions), referring to a table. Item manages the data on which contacts are associated with an element.

The same is for contacts, product positions and observers: a multitude of methods remindActualContacts, unsetContactBindings, isChangedObservers are realized inside Item. Such methods are needed for correct operation of general methods Item::remindActual, Item::unset and etc.

Working with contacts

Multiple contacts in CRM are stored in a special manner. All associations between contacts and other CRM elements are stored in dedicated tables at the namespace \Bitrix\Crm\Binding.

Binding/association records have a special format, dictated by the methods of class \Bitrix\Crm\Binding\EntityBinding.

The ORM objects of contacts, retrieved using methods getContacts and etc. are uploaded inside Item based on binding records using [link=13976296]contact broker[/link]. This allows minimizing number of database queries upon frequent use of methods for getting and binding/unbinding contacts.

Algorithm of operation for bindContacts and unbindContacts

Method bindContacts binds contacts to an element. Passes arrays as качестве аргумента ему передаются массивы связи в формате, отдаваемом методами класса \Bitrix\Crm\Binding\EntityBinding.

Its operation algorithm can be described as follows:

1. Normalize bindings retrieved via argument.
2. Get records on presently binded contacts.
3. Compare retrieved binding arrays and current records. When required, update current records and create new ones.
4. Check for at least single binded contact to be marked as primary. When there is no primary contact or there are several of them, mark one of it as primary.

Use method unbindContacts for unbind already binded contacts from element. It receives binding arrays as an argument in the format \Bitrix\Crm\Binding\EntityBinding.

Algorithm for its operation is practically identical to the bindContacts. The only difference is when comparing the retrieved binding arrays, current records are deleted and not updated/created.

Abstract methods used when handling contacts

Several abstract methods are used to handle contacts. Due to different entity types using various tables for storing binding records, these methods incapsulate details of handled Item, with abovementioned binding field OneToMany(Item::FIELD_NAME_CONTACT_BINDINGS).

abstract protected function getContactBindingTableClassName(): string - method must return FQN for table class, storing records on element and contacts binding (for example, \Bitrix\Crm\Binding\EntityContactTable).

abstract protected function compilePrimaryForBinding(array $contactBinding): array - method must generate an associative array with primary key values based on the provided binding array. Returned array format with primary keys directly depends on employed binding table, returned in the method getContactBindingTableClassName.

Handling product positions

CRM element can have product positions, associated with it. They are stored in the table b_crm_product_row (table \Bitrix\Crm\ProductRowTable).

Details on setProductRows, addToProductRows

Because product positions database records have a complex structure with multiple fields, saving them requires a particular focus on data normalization. Specifically due to this, methods for adding/updating product positions return objects of class \Bitrix\Main\Result - they collect errors occurred during normalization process.

In case of errors during product position adding/updating and normalization process, such product positions are not added.

Abstract methods, used when handling product positions

protected function getItemReferenceFieldNameInProduct(): ?string - method must return field name, under which the table \Bitrix\Crm\ProductRowTable writes the field Reference, referring to table CoolEntityTypeTable. The ProductRowTable has the field new Reference('COOL_ENTITY_TYPE', CoolEntityTypeTable::class, ...). In this case, corresponding descendant Item of this entity type must return 'COOL_ENTITY_TYPE'.

Handling observers

From data standpoint, observers is an array with user IDs who observe a specific CRM elements. Separate table b_crm_observer is used for storing information on which observers monitor a specific element (\Bitrix\Crm\Observer\Entity\ObserverTable). In addition to links to CRM element and user, it stores sort fields and update dates, as well as recent observer updates.

Work algorithm for setObservers

1. Normailize input data.
2. Get data on which users are now observers.
3. Compare retrieved data with current data. If observer wasn't passed, unbind it. If a new observer was passed, create new record. If an already existing observer was passed, update time for the observer recent update.

Upon calling setObservers, observer sorting corresponds to sorting in a passed array., i. e. the ID that was first in the passed array will be saved with minimal sort number and etc.