Set of changes

Copy the link to the article

Copied

Points to consider when working with a set of changes:

Object changeSet (type Change\EntityChangeSet) represents the interface for receiving information about changes when editing objects (for example, order or customer). In the reference book of objects, you can see the available methods for this object.

In order to find out which of the actions is currently being performed with the object (creation, modification, deletion), the corresponding methods are provided in changeSet:

changeSet.isCreate() # creation
changeSet.isUpdate() # change
changeSet.isDelete() # deletion

For example, when creating a trigger or validation for an order, specifying the changeSet.isCreate() parameter, the condition will be fulfilled at the time the order is created.

The most commonly used methods are hasChangedField(), oldValue and newValue. With hasChangedField() you can determine whether the field has changed, and oldValue and newValue allow you to retreive the old and new value of the field, respectively.

changeSet.hasChangedField("status") and changeSet.newValue("status").code == "complete" # The order status has changed and its new value is "Completed"

These methods take as a parameter the service name of the field in the underscore format. The service names of the fields available for use can be viewed in the reference book of objects. If we refer to a nested field, then the nesting is specified via a dot.

changeSet.hasChangedField("status") and changeSet.newValue("status").group.code == "complete" # The order status has changed and its new value is from the status group  "Completed"

In this example, a request is made to the object group nested in status, in this object the "code" field is nested, respectively, this check will be performed if the order status is changed to a status that is in the group "Completed".

It is important to understand the difference between check:

changeSet.hasChangedField("delivery_type") and changeSet.newValue("delivery_type").code == "russian-post" # delivery type has changed and its new value is "Russian Post"

from

order.deliveryType.code == "russian-post" # delivery type in the order is "Russian Post"

The first condition will be triggered only at the moment when we change the delivery type to "Russian Post". The second will work at the moment of changing the type of delivery to "Russian Post", as well as with all subsequent changes to the order, until we change the type of delivery to something else.

changeSet.hasChangedField ("status") # Determine if the Order status field has changed
changeSet.oldValue ("delivery_cost") # Get the previous value of the Delivery cost field
changeSet.newValue ("delivery_address.city") # Get the new value of the Delivery city field
changeSet.hasChangedField ("delivery_type") and changeSet.newValue ("delivery_type"). code == "russian-post" # The delivery type has changed and its new value is "Russian Post"

In these examples, we look at the field changes:

order.status # order status
order.deliveryCost # delivery cost
order.deliveryAddress.city # delivery city
order.deliveryType # delivery type

Changing custom fields

Changes to custom fields are stored with the custom_ prefix. For example, to determine if there is a change in the custom field transaction_id, write:

changeSet.hasChangedField("custom_transaction_id") 

Important!

If changes are tracked using the newValue or oldValue methods in custom fields with the "Number" and "Integer" types, the field values ​​will be in numeric format, all other types of the custom fields store the values ​​in text format.

For different types of custom fields, it is necessary to provide a check corresponding to the type of field, examples of such checks are available in the article "How to use a set of changes for different types of fields".

Getting the author of the change:

Sometimes it is necessary to get a manager who made a change in a certain field, for example, it is possible to assign a manager responsible for an order if he changed its details.

In order to find out which manager has changed this or that field, use the authorOfChange function, which returns the manager who made the change (User) or null if the change was made by the system itself, via API or in a trigger.

changeSet.authorOfChange("status")

If the order status is changed by the system user, the above-mentioned example will return the User object.

To check for a change in a specific field, you can use the sourceOfChange function, which returns the symbolic code of the change source:

api # API
user # Manager
rule # Trigger
code # System
combine # Combining with another object
copy # Copying objects

This check will be executed if the order status is changed by API or by trigger:

changeSet.sourceOfChange("status") in ["api", "rule"]

You can also check for any changes from a specific source using the hasChangesWithSource function, specifying the symbolic code corresponding to the source of changes in the function parameters:

changeSet.hasChangesWithSource("api")

This check will be executed if the change is initiated via API.

Tracking changes using pipe filters:

The system provides filters that allow you to work with data arrays, so they can be used to track changes in the changeSet object. You can familiarize yourself with the available filters in the article "Language of expressions".

For example, you can check the change in the status of a product in an order:

changeSet | contains (product =>product.fieldName == 'order_product.status' and product.oldValue.code == 'new' and product.newValue.code == 'otklonen')

This check will be executed if there is a change in the status of at least one product from the order details.