Event Handlers

Introduction

Event handlers define microflows that handle certain events related to the entity. Depending on the chosen moment and type, a microflow is executed before or after creating, committing, deleting, or rolling back an object.

Event handlers should be used moderately, as they will be triggered every time the corresponding event occurs, so they must be for things you want always to happen. If you only want something to happen on a certain page, you can use a microflow there (for example, on a customized Save button).

For example, say your Customer entity has a Postcode attribute and you want to check that this is always valid. If there are multiple places where this can be changed, you can add a Before Commit event which calls a microflow BCo_Customer_Postcode which checks that the postcode is valid every time a Customer object is committed and prevents the object being committed if the postcode is invalid.

For more information on using event handlers for data validation, see How To Set Up Data Validation.

Properties

You can add and edit event handlers for an entity from the entity dialog box.

An example of the event handler properties is represented in the image below:

Event handler properties consist of the following sections:

• When
• What

When Section

Moment

Moment specifies whether the microflow is executed Before or After the specified event occurs.

Event

Event specifies the event that triggers execution of the microflow.

Value	Description
Create	The microflow is executed when an object of this entity is created. This happens when the user clicks Create on a grid or when an object is created in a microflow. In a create action in a microflow, an after create action is executed after the object is initialized with the attributes’ default values, but before any change items specified in the action are applied.
Commit	The microflow is executed when an object of this entity is committed. This happens when the user clicks Save on a page or when an object is committed in a microflow.
Delete	The microflow is executed when an object of this entity is deleted. This happens when a user clicks Delete in a grid or when an object is deleted in a microflow.
Rollback	The microflow is executed when an object of this entity is rolled back. This happens when a user clicks Cancel on a page or when an object is rolled back in a microflow.

What Section

Pass Event Object

This option specifies whether the microflow (see Microflow below) set for this event will have the object associated with the event as a parameter. This is useful, for example, if you want to do some validation checks in your event handler on an object being committed.

If you set this to No, you can only specify a microflow with no parameters.

Microflow

This property defines the microflow that is executed for the specified event. The microflow must have parameter and return types consistent with the moment and event of the event handler:

• Microflows of all event handlers except Before Create can get the object on which the event occurs as parameter.
• Microflows that are executed before the event should return a Boolean value that specifies whether the event should continue (true) or be cancelled (false). When multiple microflows handle the same event, it is cancelled immediately when one of the microflows returns false. In that case, some microflows might not be executed at all. You can use this feature, for example, to cancel committing an object when a certain condition is not met.

Moment	Event	Can Get Object as Parameter	Returns a Boolean Value
Before	Create	No	Yes
After	Create	Yes	No
Before	Commit	Yes	Yes
After	Commit	Yes	No
Before	Delete	Yes	Yes
After	Delete	Yes	No
Before	Rollback	Yes	Yes
After	Rollback	Yes	No

Raise an Error When the Microflow Returns False

This is only relevant if the Moment is set as Before.

If this option is enabled, the event handler raises an error when the microflow returns false. You can then use error handling to detect whether the event handler returned false.

For example, this makes it possible to use Before Commit event handlers in the same way as native validation. If this option is set to No, a Before Commit event handler can stop the commit from happening but the rest of the microflow will still be executed.

Default: Yes

Read More

• How to Denormalize Data to Improve Performance
• How To Set Up Data Validation