Walkthrough: Using Events in Microsoft Dynamics NAV - NAV2016 - Events Part 3

This walkthrough uses a simple example scenario to demonstrate how to program events in the application.

The walkthrough illustrates to the following tasks:

• Creating an event publisher function to publish an event.
• Adding code to application to raise the published event.
• Creating an event subscriber function to subscribe to a published event.
• Adding code to the event subscriber function to handle the raised event

 

Prerequisites

To complete this walkthrough, you will need:

• Microsoft Dynamics NAV 2016 with a developer license.
• CRONUS International Ltd. demonstration database.

When users change the address of a customer, you want to check that the address does not include invalid characters, which in this walkthrough is a plus sign (+).

To accomplish this, you will publish an event that is raised when the Address field on page 21 Customer Card is changed.

To handle the event when it is raised, you will add an event subscriber function that includes logic that checks the address value and returns a message to the user if it contains a plus sign.

 

Publishing the Event

To publish an event, you create a C/AL function that is set up to be an event publisher.

An event publisher function can be added in any object, such as a codeunit, page, or table.
This procedure will add the event publisher function to a new codeunit, in which you can potentially add more event publisher functions for other events later.
Because you might want to change this event implementation in the future, you decide to create an integration event type.
The event publisher requires a single text parameter for handling the address of the customer.

To create a new codeunit

1.    Open the development environment, and then connect to the CRONUS International Ltd. company.

2.    On the Tools menu, choose Object Designer, choose Codeunit, and then choose New.

The C/AL Editor opens.

3.    On the File menu, choose Save.

4.    On the Save window, enter 50000 in the ID field and enter My Publishers in the Name field.

5.    Make sure the Compiled check box is selected, and then choose the OK button.

The codeunit for the event publisher is created. Keep the C/AL editor open for the next task. You can now add the event publisher function to publish the event.

 

To create the event publisher function to publisher the event

1.    On the View menu, choose C/AL Globals.

2.    In the C/AL Globals window, choose the Functions tab.

3.    In a blank row, in the Name field, enter OnAddressLineChanged.

4.    To open the properties for the OnAddressLineChanged function, select the function, and then in the View menu, choose Properties. Set the properties as follows:

1.    Set the Local property to No.

2.    Set the Event property to Publisher. This makes the function an event publisher.

3.    Set the EventType property to Integration.

4.    Close the Properties window.

5.    Add a local parameter to the function for the address of the customer as described in the following steps:

1.    On the Functions tab, select the OnAddressLineChanged function, and then choose the Locals button.

The C/AL Locals window opens.

2.    On the Parameters tab, in the Name field, enter line.

3.    Set the DataType field to Text.

4.    Set the Length field to 100.

NOTE: An event publisher function cannot have a return value, variables, or text constants; otherwise you will not be able to compile the function.

5.    Close the C/AL Locals window.

6.    Close the C/AL Globals window.

The new function appears in the C/AL Editor with the following signature:

[IntegrationEvent] OnAddressLineChanged(line : Text[100])

You can now raise the event in the application.

Event Types - NAV2016 - Events Part 2

Microsoft Dynamics NAV supports different types of events for different purposes. This topic describes the different types.

Business Events

A business event is a custom event. It defines a formal contract that carries an implicit promise not to change in future releases. It is the expectation that business events are published by solution ISVs, including Microsoft.

Business events can be compared with publicly released APIs on which 3rd party solution provider develop integrations and additions. Therefore, the downstream cost of making changes to a business event implementation can be considerable for those who use the event in their applications. There may be some cases where changes are required; however, you should keep these to an absolute minimum.

Development considerations

A typical business event reflects changes in “state” with regards to a process. This makes them very well suited for workflow. An example of a business event could be when a sales order has been posted. It is important to note that business events should not be tied to the implementation-details, such as the tables or fields in which the data is stored. Preferably, the event publisher developer should be free to change the implementation, while still keeping the business event intact.

Documentation

Business events must be documented with the solution, including the before-state and after-state of the events.

Integration Events

An integration event is also a custom event, like a business event, except that it does not carry the same promise of not changing, nor does it have the restriction not to expose implementation details.

The main purpose of integration events is to enable the integration of other solutions with Microsoft Dynamics NAV without having to perform traditional code modifications.

Development considerations

An integration event can be changed to a business event later. At which time, it must adhere to the same implied contract and commitment as any business event. It can also simply be designed-in hook points for external add-ons.

Documentation

There are no formal requirements for integration events because they follow local partner best practices.

Trigger Events

Unlike business and integration events which must be programmed, trigger events are predefined events. Trigger events are raised by the system when it performs database table operations, such as deleting, inserting, modifying, and renaming a record. Trigger events are closely associated with the table triggers for database operations: OnDelete, OnInsert, OnModify, OnRename, and OnValidate (for fields).

Available Trigger Events

For each database operation, there is a "before" and "after" trigger event with a fixed signature. The following table describes the available trigger events:

Trigger event with signature	Description
OnBeforeDeleteEvent(VAR Rec: Record, RunTrigger: Boolean)	Executed before a record is deleted from a table.
OnAfterDeleteEvent(VAR Rec: Record, RunTrigger: Boolean)	Executed after a record is deleted from a table.
OnBeforeInsertEvent(VAR Rec: Record, RunTrigger: Boolean)	Executed before a record is inserted in a table.
OnAfterInsertEvent(VAR Rec: Record, RunTrigger: Boolean)	Executed after a record is inserted in a table.
OnBeforeModifyEvent(VAR Rec: Record, VAR xRec: Record, RunTrigger: Boolean)	Executed before a record is modified in a table.
OnAfterModifyEvent(VAR Rec: Record, VAR xRec: Record, RunTrigger: Boolean)	Executed after a record is modified in a table.
OnBeforeRenameEvent(VAR Rec: Record, VAR xRec: Record, RunTrigger: Boolean)	Executed before a record is renamed in a table.
OnAfterRenameEvent(VAR Rec: Record, VAR xRec: Record, RunTrigger: Boolean)	Executed after a record is renamed in a table.
OnBeforeValidateEvent(VAR Rec: Record, VAR xRec: Record, RunTrigger: Boolean; CurrentFieldNo: Integer)	Executed before a field is validated when its value has been changed.
OnAfterValidateEvent(VAR Rec: Record, VAR xRec: Record, RunTrigger: Boolean; CurrentFieldNo: Integer)	Executed after a field is validated when its value has been changed.

The following table describes the parameters of the trigger events:

Parameter	Type	Description
Rec	Record	The table that raises the event.
xRec	Record	The table that raises the event.
RunTrigger	Boolean	Specifies whether to execute the code in the event trigger when it i invoked. If this parameter is true, the code will be executed. If this parameter is false, then the code is not executed.
CurrentFieldNo	Integer	The number of the field that raises the event.

Development Considerations

Trigger events are published by the runtime and cannot be raised programmatically.

The relative order of execution of trigger events, table triggers, and database operations is as follows:

Order	Item	Example
1	Trigger event (before)	OnBeforeDeleteEvent
2	Table trigger	OnDelete
3	Global table trigger in codeunit 1	OnDatabaseDelete
4	Database operations	Delete the record
5	Trigger event (after)	OnAfterDeleteEvent

Trigger events do not appear in C/AL Editor from the Table Designer in the Microsoft Dynamics NAV Development Environment.

Subscriber functions cannot access the sender and or access global variables.

Introducing Events - NAV2016 - Events Part 1

We can use events to design the application to react to specific actions or behavior that occur. Events enable us to separate customized functionality from  the application business logic. By using events in the application where customizations are typically made, we can lower the cost of code modifications and upgrades to the original application.

• Code modifications to customized functionality can be made without having to modify the original application. 
• Changes to the original application code can be made with minimal impact on the customizations.

Events can be used for different purposes, such as generating notifications when certain behavior occurs or the state of an entity changes, distributing information, and integrating with external systems and applications. For example, in the CRONUS International Ltd. demonstration database, events are used for extensively for workflow and Microsoft Dynamics CRM integration.

How Events Work

The basic principal is that we program events in the application to run customized behavior when they occur. Events in Microsoft Dynamics NAV are modelled after Microsoft .NET Framework. There are three major participants involved in events: the event, a publisher and a subscriber.

• An event is the declaration of the occurrence or change in the application. An event is declared by a C/AL function, which is referred to as an event publisher function. An event publisher function is comprised of a signature only and does not execute any code.
• A publisher is the object that contains event publisher function that declares the event. The publisher exposes an event in the application to subscribers, essentially providing them with a hook-up point in the application.
  
  Publishing an event does not actually do anything in the application apart from making the event available for subscription. The event must be raised for subscribers to respond. An event is raised by adding logic to the application that calls into the publisher to invoke the event (the event publisher function).
  
  Partners or subsystems can then take advantage of the published event in their solutions. An ISV that delivers vertical solutions, and Microsoft itself, are the typical providers of published events.
  
  There are three different event types: business, integration, and trigger events. Business and integration type events must be explicitly declared and published, which means that we must create event publisher functions and add them to objects manually. On the other hand, trigger events, which occur on table and page operations, are published and raised implicitly by the Microsoft Dynamics NAV runtime. Therefore, no coding is required to publish them.
• A subscriber listens for and handles a published event. A subscriber is a C/AL function that subscribes to a specific event publisher function and includes the logic for handling the event. When an event is raised, the subscriber function is a called and it code is run. A subscriber enables partners to hook into the core Microsoft Dynamics NAV application functionality without having to do traditional code modifications. Any Microsoft Dynamics NAV solution provider, which also includes Microsoft, can use event subscribers.

There can by multiple subscribers to a single event publisher function. However, a publisher has no knowledge of subscribers, if any. Subscribers can reside in different parts of the application than publishers.

How to Implement Events

Implementing events in Microsoft Dynamics NAV consists of the following tasks:

1.    Publish the event.
For business and integration events, create and configure a function in an application object to be an event publisher function.

2.    Raise the event.
Add code that calls the event publisher function.

     3.    Subscribe to the event.
     At the consumer end, add one or more subscriber functions that subscribe to published events when they are raised. 

C/AL Editor Keyboard Shortcuts

The following table describes the keyboard shortcuts that are available from the C/AL Editor window.

Keystroke	Action
Ctrl+G	Open the C/AL Globals window to view and declare the global variables, text constants, and functions in the object.
Ctrl+L	Open C/AL Locals window to view and declare local variables and text constants for the current function or trigger.
Ctrl+Z	Undo the last action.
Ctrl+Y	Redo the last action.
Ctrl+J	List all members (as IntelliSense) for the local scope.
Ctrl+Space	List the members (as IntelliSense) for global scope.
Ctrl+W	Select the word.
Ctrl+U	Make the selected code lowercase.
Ctrl+Shift+U	Make the selected code uppercase.
Ctrl+Shift+N	Expand all collapsed code.
Ctrl+K+I	Display information about C/AL symbol (such as variable, functions, and parameter) in which the cursor is positioned. This displays the same text as when you point to the element.

Managing Language, Regional Settings, and Time Zone in the Microsoft Dynamics NAV Web Client

We change the language, the region, and the time zone in the Microsoft Dynamics NAV Web client by using the My Settings page located in the upper right corner under the user name that you are signed in with. 

The regional settings determine the format of data such as dates, times, numbers, currency, and so on. The time zone specifies the time zone that is applied to date and time data that a user views or enters in the Microsoft Dynamics NAV Web client. You need to sign out and sign in again for the change to take effect.

With the new My Settings page, it is now possible to dynamically switch the UI language, region, time zone, company, and work date of the Microsoft Dynamics NAV Web client, Microsoft Dynamics NAV Tablet client, and Microsoft Dynamics NAV Phone client. You need to sign out and sign in again to have the change take effect, except for changing work date that takes effect immediately.

The number of available languages is based on the installed language modules. All settings are based on the selection in My Settings.

NOTE: 

With the introduction of the My Settings page, the settings in the Web.config file for Company, Time Zone, Region, and Language have been removed. Using an old link that contains a specific company to open, for example, the Microsoft Dynamics NAV Web client will overwrite the choice in My Settings.

Posting Preview - NAV2016

On every document and journal that can be posted, you can choose the Preview Posting button to review the different types of entries that will be created when you post the document or journal.

To preview G/L entries that will result from posting a purchase invoice

 

1.     Create a purchase invoice.

2.     On the Actions tab, in the Posting group, choose Preview Posting.

3.     In the Posting Preview window, select G/L Entry, and then choose Show Related Entries.

The G/L Entries Preview window shows which entries will be created when you post the purchase invoice.

Redesigned C/AL Editor - NAV2016

The C/AL Editor in the Microsoft Dynamics NAV Development Environment has been redesigned to give you more coding capabilities.

Coding in the new C/AL editor is like before except you benefit from new features such as IntelliSense, name completion, change tracking, improved syntax highlighting and colorization.

The new design has a look-and-feel that resembles the Debugger regarding breakpoints.

And here it is

And if you start typing then it will start IntelliSense and you can press tab/enter to name completion.

Does it mean we cannot use old editor?

No, we can use the old version of the C/AL Editor by running the Microsoft Dynamics NAV Development Environment from a command prompt and setting the useoldeditor parameter

Ex: run the command prompt and add below string and enter

"C:\Program Files (x86)\Microsoft Dynamics NAV\90\RoleTailored Client\finsql.exe" useoldeditor=Yes

Or you can create a shortcut of the finsql and add useoldeditor=Yes in properties