TrackedObject

Method for data preparation

TrackedObject is an object used for preparing data for history entry. It's configured by [link=13981986]factory[/link] and depends on the entity type and specific element, provided by this object.

The class TrackedObject is an abstract class. Each element type has a descendant. It defines set of fields with enabled update history. They also can have different event messages redefined.

TrackedObject has handle only class objects EntityObject and \Bitrix\Crm\Item.

Data preparation for EventHistory is the main task of TrackedObject. For this purpose TrackedObject has a family of public methods prepare*EventData, passing the object EventHistoryData, filled with data for specific event. Data is generated based on the element passed in TrackedObject and with consideration of specifics for entity type (factory-created configuration).

Dependant objects

CRM element can have associated dependant entities (contacts, product items). When content for CRM element-associated entities is updated or when a specific fields of associated entity changes - this element history must reflect such changes. It is accomplished by the "dependent objects" mechanism.

TrackedObject can be made dependent using the method makeThisObjectDependant(string $ownerFieldName). After calling this method, the object will prepare data with consideration that such method is a dependant. This affects messages and fields, responsible for event associating with the element.

Parameter string $ownerFieldName shows which parent field has a dependant object. For example, contacts are stored in the field 'CONTACTS'. Accordingly, when calling makeThisObjectDependant we pass 'CONTACTS' as the argument.

To associate a dependant object TrackedObject to another TrackedObject, acting as a parent, use the method addDependantTrackedObject(TrackedObject $dependant).

Data preparation algorithm in the method prepareUpdateEventData

Because element update data preparation — is the most complex case in the operation of TrackedObject, it needs some clarification found below.

Upon calling the method, object scans all fields with all updates to be written into history. They are accumulated from the fields, specified in the descendant and fields with associated dependant objects, added via addDependantTrackedObject.

1. Collect data for specific field.
   • When field is standard and didn't change, prepare data about the update.
   • When field is dependant (i.e. a dependant TrackedObject), compare collections of associated objects before and after saving. Collect the discovered differences (added/deleted objects, updates in necessary fields).
2. When current object is a dependant (configured using makeThisObjectDependant), you need to modify the data additionally.