Creatio development guide
This documentation is valid for Creatio version 7.14.0. We recommend using the newest version of Creatio documentation.

Entity event layer

Glossary Item Box

Introduction

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

ATTENTION

The Entity event layer mechanism is triggered after executing the event subprocesses of an object.

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

OnDeleted(object sender, EntityAfterEventArgs e)

Event handler after deleting a record.

OnDeleting(object sender, EntityBeforeEventArgs e)

Event handler before deleting a record.

OnInserted(object sender, EntityAfterEventArgs e)

Event handler after adding a record.

OnInserting(object sender, EntityBeforeEventArgs e)

Event handler before adding a record.

OnSaved(object sender, EntityAfterEventArgs e)

Event handler after saving a record.

OnSaving(object sender, EntityBeforeEventArgs e)

Event handler before saving a record.

OnUpdated(object sender, EntityAfterEventArgs e)

Event handler after updating a record.

OnUpdating(object sender, EntityBeforeEventArgs e)

Event handler before updating a record.

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

Create Change Delete

OnSaving()

OnInserting()

OnInserted()

OnSaved()

OnSaving()

OnUpdating()

OnUpdated()

OnSaved()

OnDeleting()

OnDeleted()

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;
    }
}

ATTENTION

The approach to obtaining the UserConnection from HttpContext instance is not always correct. For example, the HttpContext instance may not exist at the time when event handlers are firing in the business processes or in the task scheduler.

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.

ATTENTION

We do not recommending describing the logic of changing the primary entity in the class implementing the IEntityEventAsyncOperation interface. Such use can lead to incorrect data creation. We do not recommend executing lightweight operations (for example, calculating a field value), since creating a separate flow might take more time than executing the operation itself.

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.
© bpm'online 2002-2019.

Did you find this information useful?

How can we improve it?