Eventing for Microsoft Dynamics AX 2012

Events are a new concept within the Microsoft Dynamics AX 2012 development environment.   The premise is easy, you can create pre or post events on a method in order to “fire off” customized behavior.

Using events has three huge benefits:

• First, the ability to make business process requirements separate from method code.  An example is a method that calculates the cost price of a good.  The markup, or the increase above cost can be an event that is executed after (post) the method, that may be dependent on other factors such as customer (name) or customer group.
• Second, the potential of bypassing conflicts with method changes.  This works best in the case with several customizations, you avoid conflict when a customer uses different Independent Software Vendors (ISVs) that are possibly modifying the same objects.   Those modifications can still take place, however, the business logic or “triggers” for the event can exist outside of the core functionality.
• Third, there is the independence from code example.  The scenario is that Microsoft updates a specific system method during upgrade.  It may have a new table structure, class process, or normalized data structure that derives to the expected outcome.  This outcome is a product that is used by the events, and since they are outside of the method, are still in place and are not impacted by the system changes.

Introduction

This topic describes the concept of events and how they can be used in Microsoft Dynamics AX.

By removing business logic from primary methods, the method now acts as a base object with no other customized business functionality.  An example is a method that calculates the cost price of a good.  The markup, or the increase above cost can be an event that is executed after (post) the method, that may be dependent on other factors such as customer or customer group. In this way, if business processes change, the method or code does not need to change.

In the case of the bypassing customization, you are avoiding conflict when a customer uses several Independent Software Vendors (ISVs) that are possibly modifying the same objects.   Those modifications can still take place, however, the business logic or “triggers” for the event can exist outside of the method.

For the independence from code example, what if Microsoft updates a specific system method during upgrade.  It may have a new table structure, class processes, or  normalized data structure that derives to the expected outcome.  This outcome is a product that is used by the events, and since they are outside of the method, are still in place and are not impacted by the system changes.

Events

An event represents something that happens inside an object. Classic examples are posted, updated, or something tied to a business process such as purchased.

You can use events to support the following:

• Observation: Events can be used to look for exceptional behavior and generate alerts when such behavior occurs.

Information dissemination: Events can deliver the correct information to the appropriate consumers at the most suitable time. Information dissemination is supported by publishing an event to anyone that wants to react to it.

• Decoupling: Events produced by one part of the application can be consumed by a completely different part of the application. There is no need for the producer to be aware of the consumers, nor do the consumers have to know details about the producer. One producer’s event can be acted upon by any number of consumers. On the other hand, consumers can act upon any number of events from many producers.

An example of where this applies is in the business process of a credit hold placed on a customer account by the accounts receivable department.  The observation is that the account is now exceeding either a cap on gross dollars in the account exceeding a threshold value or an excess of time in payment on the account.  Information dissemination and decoupling comes in that once the trigger has occurred the event is available globally to the system, making it consumable by the finance department for the reduction in projected cash calculation, shipping for the stop on new goods shipments, and the notification to the sales department that they cannot sell any more items to the customer until this has been cleared.  The intelligence of the design is that these reactions to the event can be unlimited and are not dependent on the event itself sending the information to each handler.

Terminology

X ++ events in Microsoft Dynamics AX 2012 are modeled after .NET eventing concepts.  The following table lists the terms in Microsoft Dynamics AX 2012 related to events.

Example

In this example, Michael Shiermeyer quickly developed an event model that runs two pre-events, two post events, and also includes a runDelegate with sequential events.

Sample Event Model

Here is the infolog output when this is executed.

The first type of eventing is triggered immediately before or after a method is called.  These events can be added to any method and there can be multiple pre and post events on a single method.

Following is the setup for the PreEvent.

PreEvent Properties

The second type of eventing is called when a delegate method is called.  Delegate methods must be called from code and cannot contain any code.  The related events contain the code.  Similar to pre/post events, there can be any number of events tied to the delegate.  For all event types, the events are called by the kernel in the order they are listed in the AOT.

Delegate methods can be defined with any parameters.  They are illustrated above as the FirstEvent and SecondEvent objects.  Each related event method must have matching parameters.  When the delegate method is called, the same parameters are passed to each of the events.

Pre and post events can either be defined with no parameters or one parameter of type XppPrePostArgs.  The XppPrePostArgs will be populated by kernel and contains information useful in the method as seen in the example below.  If the parameters are not correct, a compile error should be thrown.  In the previous illustration, this is shown as the badDelegate. The method the event uses is defined on the properties of the event.  All event methods must be static.  The method can be in the current class or any other class in the system.

XppPrePostArgs Example

Tips for Events

When you consider working with events, do

• Define events the programmers customizing the behavior of the system should react to. You should identify natural customization points and use events to publish the relevant information to subscribers.
• Maintain the semantics implied by the event from one version to the next. Part of the usefulness of events comes from the preservation of the semantics of the events. As soon as an interface is defined, third parties will be able to leave their existing code unmodified if the semantics are left unchanged (even though the implementation behind might be modified).
• Document the events that you create well because this will help anyone who is performing the customization later.
• Favor defining events over creating pre and post events on methods. Events are strong interfaces, whereas methods are an implementation artifact—a method’s responsibilities and parameters can change over time, and they can disappear completely if the developer so decides.

When you consider working with events, do not

• Try to raise an event from outside the class in which the event is defined. The X++ compiler disallows raising events from outside the class by design.
• Make customizations that rely on the order in which event handlers are executed. No guarantees are made by the runtime environment about the order in which the event handlers are called.

Resources for Eventing

Microsoft has published a full white paper called Eventing.  You can download this whitepaper from the following location: http://technet.microsoft.com/EN-US/library/hh272875.  Information can also be found in the Development IV user guide on Customer Source.

Shaun McMikle