Entity event layer

Introduction

In Creatio version 7.12.4, we have enabled the development of object business logic without using event sub-processes.

To add the necessary actions to the handler of the needed object event (inheritor of the Entity class):

1. Create a class that inherits BaseEntityEventListener.
2. Decorate the class with the EntityEventListener attribute and specify the name of entity whose event subscription must be executed.
3. Override the handler method of the needed event.

Example:

// Event listener of the "Activity" entity.
[EntityEventListener(SchemaName = "Activity")] 
public class ActivityEntityEventListener : BaseEntityEventListener
{
    // Overriding the event handler of entity saving event.
    public override void OnSaved(object sender, EntityAfterEventArgs e) {
        //Calling the parent implementation.
        base.OnSaved(sender, e);
        //...
    }
}

Classes that form the Entity event layer mechanism:

The BaseEntityEventListener class

The BaseEntityEventListener class provides handler methods for different entity events (table 1).

Table 1. Entity event handler methods

Method parameters:

• sender – the link to the instance of entity generating the event. Parameter type – Object.
• e – event arguments. Depending on the execution time of the handler method (after or before the event), the argument type can be either EntityAfterEventArgs or EntityBeforeEventArgs.

The algorithm of calling event handler methods is provided in table 2.

Table 2. Algorithm of calling event handler methods

Obtaining UserConnection

You can obtain the UserConnection instance in the event handlers from sender parameter:

[EntityEventListener(SchemaName = "Activity")]
public class ActivityEntityEventListener : BaseEntityEventListener
{
    public override void OnSaved(object sender, EntityAfterEventArgs e) {
        base.OnSaved(sender, e);
        var entity = (Entity) sender;
        var userConnection = entity.UserConnection;
    }
}

The EntityAfterEventArgs class

The class provides properties with arguments of the handler method that is executed after the event occurs.

• ModifiedColumnValues – collection of modified columns.
• PrimaryColumnValue – record identifier.

The EntityBeforeEventArgs class

The class provides properties with arguments of the handler method that is executed before the event occurs.

• KeyValue – record identifier.
• IsCanceled – enables canceling the further event execution.
• AdditionalCondition – enables providing additional description of entity filter conditions before the action.

The EntityEventListener attribute

The EntityEventListener attribute (the EntityEventListenerAttribute class) is designed for listener registration. The listener can be connected with all objects (IsGlobal = true) or with a specific object (for example, SchemaName = “Contact”). One listener-class can be tagged with many attributes for defining the necessary “set” of “listened-to” entities.

Asynchronous operations in the Entity event layer

It is often a case when additional business logic of an object is time consuming and is executed consistently. Such an approach has its negative impact upon the efficiency of customer part, for example, when saving or modifying entities.

To eliminate such problems, we have developed a method of asynchronous execution of operations, based on the Entity event layer.

For example, when adding a new activity, you need to execute additional logic which can be executed asynchronously. For this, create a class, e.g., DoSomethingActivityAsyncOperation with implementation of the IEntityEventAsyncOperation interface (see below).

//Class implementing the asynchronous calling of operations.
public class DoSomethingActivityAsyncOperation: IEntityEventAsyncOperation
{
    // Start method of the class.
    public void Execute(UserConnection userConnection, EntityEventAsyncOperationArgs arguments) {
        // ...
    }
}

Receive the instance, implementing the IEntityEventAsyncExecutor interface in the handler-method of the activity object listener-class after saving the record via class factory, prepare parameters and pass the DoSomethingActivityAsyncOperation operation class to execution.

[EntityEventListener(SchemaName = "Activity")]
public class ActivityEntityEventListener : BaseEntityEventListener
{
    // Event handler method after saving the entity.
    public override void OnSaved(object sender, EntityAfterEventArgs e) {
        base.OnSaved(sender, e);
        // Class instance for asynchronous execution.
        var asyncExecutor = ClassFactory.Get<IEntityEventAsyncExecutor>();
        // Parameters for asynchronous execution. 
        var operationArgs = new EntityEventAsyncOperationArgs((Entity)sender, e);
        // Execution in asynchronous mode.
        asyncExecutor.ExecuteAsync<DoSomethingActivityAsyncOperation>(operationArgs);
    }
}

The IEntityEventAsyncExecutor interface

Provides method for asynchronous operation execution.

• void ExecuteAsync<TOperation>(object parameters) – the typed method for launching operations with parameters, where TOperation – is the configuration class implementing the IEntityEventAsyncOperation interface.

The IEntityEventAsyncOperation interface

Provides method for launch of an asynchronous operation.

• void Execute(UserConnection userConnection, EntityEventAsyncOperationArgs arguments) – launch method.

The EntityEventAsyncOperationArgs class

This class instances are used as arguments for passing to the asynchronous operation.

Properties.

• EntityId – record identifier.
• EntitySchemaName – name of the schema.
• EntityColumnValues – the glossary of current column values of an entity.
• OldEntityColumnValues – the glossary of old column values of an entity.