Version: 8.3

Track changes in collection data

Level: advanced

note

This functionality is available for Creatio 8.3.2 and later.

When building dynamic pages and custom apps in Creatio, collections often drive user interaction. The UI must remain consistent and responsive on data changes at runtime. For example, counters should stay accurate, validation rules should react immediately, and users should see meaningful feedback when items are added, removed, or updated.

Typical scenarios include:

keeping record counters in sync with the actual number of items
displaying activity indicators when collection content changes
reacting to data updates without reloading the entire page

Previously, collection change listeners could only report that a change occurred, without details. This made it difficult to understand what exactly changed without implementing manual snapshots and comparisons.

Since version 8.3.2, Creatio introduces a dedicated collection change tracking API through the BaseViewModelCollection class. This API provides detailed, event-based information about changes at both the collection and item levels, allowing apps to respond precisely and efficiently to runtime data updates. Learn more: BaseViewModelCollection class.

The API supports the following conceptual scenarios:

tracking structural changes in a collection, such as adding, removing, moving, or reloading items
detecting attribute-level changes inside existing collection items
synchronizing UI state and view model logic with actual data changes
avoiding manual comparison logic and temporary state storage

Collection changes fall into the following categories:

Collection structure changes, where the composition or order of items changes
Item attribute changes, where existing items remain in place but their data is updated

The table below maps common business goals to the appropriate API methods. Learn more about the full API reference: BaseViewModelCollection class.

Business goal	Method to use	Use cases
Track collection changes	registerOnCollectionChangeCallback()	Track when items are added to the collection Track when items are removed from the collection Track when items are moved within the collection Track when the collection is reloaded with new items Listen for all collection change actions or only for a specific action type
Track item attribute changes in the collection	registerOnItemAttributesChangesCallback()	Track when any attribute value changes within an existing collection item Update UI or trigger validation when item data changes React to changes that do not modify the collection structure
Stop tracking collection changes	unregisterOnCollectionChangeCallback()	Clean up subscriptions when the component is destroyed Prevent memory leaks Stop listening for all actions or for a specific action type
Stop tracking item attribute changes in the collection	unregisterOnItemAttributesChangesCallback()	Clean up item-level subscriptions when they are no longer needed Prevent memory leaks Stop reacting to item attribute updates

When working with view model collections, follow these recommendations:

/* Register callbacks on "ViewModel" initialization. */
collection.registerOnCollectionChangeCallback((changes) => {
    /* Implement custom business logic. */
});

Keep references to callback functions so they can be cleanly unregistered later.

/* Store callback reference. */
const handler = (changes) => {
    /* Implement custom business logic. */
};

/* Register the callback. */
collection.registerOnCollectionChangeCallback(handler);

/* If needed, unregister the callback later. */
collection.unregisterOnCollectionChangeCallback(handler);

Subscribe only to specific action types when full change tracking is unnecessary.

/* Listen only for item additions. */
collection.registerOnCollectionChangeCallback(
    handler,
    ViewModelCollectionActionType.Add
);

Always unregister callbacks when a component is destroyed to avoid memory leaks.

ngOnDestroy() {
    collection.unregisterOnCollectionChangeCallback(handler);
    collection.unregisterOnItemAttributesChangesCallback(attributeChangeHandler);
}

Detailed example: Display live contact list statistics.

See also​

See also