Developing Extension package NAV

Hi All,

Please refer my previous post on Extensions Overview.
https://nandeshgowda-navblog.blogspot.in/2016/11/extending-microsoft-dynamics-nav-using.html

Today we will discuss on how to develop & use Extensions.

We can build extension packages that add functionality to a Dynamics NAV deployment. Unlike the familiar development and deployment of Dynamics NAV functionality, building an extension relies on the exported version of an application to .TXT files.

We can export the application from the development environment, use the development environment commands, or use the Windows PowerShell cmdlet that is available in the Microsoft Dynamics NAV 2017 Development Shell, Export-NAVApplicationObjectLanguage.

I will create a new field on Customer table and put some validation on that field using Events.

Please refer my below post on how to implement Events
https://nandeshgowda-navblog.blogspot.in/2016/09/implementing-events-in-nav-2016.html


1) To start with please create a folder structure similar to below so that while creating a extension package we can use below path for Cmdlets for converting/merging and creating delta.



2)  The foundation for our extension is the exported .txt files of the objects we are modifying. We can export just the objects that we want to modify, or we can export the entire Dynamics NAV application. We can use  Export-NAVApplicationObjectLanguage cmdlet to export the objects.




3) Now we need to create a functionality using Events, In my example I have just added a field in Customer table and added a validation on onBeforeValidateEvent of new field created. I have used Events for the code changes.



4)  Write extension upgrade code for new or modified tables. This is needed as we may get error while building the Extensions. For time being you can just create upgrade codeunit and add the functions in it.

To write upgrade code for an extension

Create new codeunit.

Important

This must be a codeunit of type Normal, not an Upgrade codeunit.

Add upgrade functions to the codeunit. Make sure the function is declared as global so that the Local property is set to No.

Add the OnNavAppUpgradePerDatabase() function if the extension contains cross-company tables.

Add the OnNavAppUpgradePerCompany() function if the extension contains per-company tables.




5)  Now I will verify whether the changes are working from RTC Client.




6) Now Export the Modified objects in text format.




7) Our delta files must be one-to-one with the objects we have added or modified.

We cannot include a single merged delta file. If we output our export file as a single file use the Split-NAVAppplicationObjectFile cmdlet to create the individual files.

Go to  "Microsoft Dynamics NAV 2017 Development Shell" and type the command to split the file into individual objects





8) Create DELTA files using the Microsoft Dynamics NAV 2017 Development Shell cmdlets.

Extension packages are based on application object deltas. Again, we use the application merge utilities in the Microsoft Dynamics NAV 2017 Development Shell to distill the changes in the form of application object differences that are stored in DELTA files.

We use the Compare-NAVApplicationObject cmdlet to create these delta files.



If we will be adding Multilanguage translations for captions or constant. Use below cmdlet.

Compare-NAVAppApplicationObjectLanguage -OriginalPath MLORIGINAL -ModifiedPath MLMODIFIED -DeltaPath MLDELTA

9) Build Extension package.

Use the New-NAVAppManifest and New-NAVAppPackage cmdlets to build the manifest and package file.

The following is an example of how to create a new extension .NAVX package file with a new manifest.




10)  Signing a NAVxfile.

Code signing is a common practice for many applications. We must have a certificate on the computer (as a file or in the certificate store) that includes code signing for the intended purpose.

It is recommended that we use a certificate from a third party certificate authority. For testing purposes, it is acceptable to create a self-signed certificate using the New-SelfSignedCertificate cmdlet in PowerShell on Windows 10 or MakeCert.

I will Skip this process of Signing in this Demo. We will use unsigned extension package to Publish and Install.


11) Publish and Install extension :

We have packaged our extension so it is ready to be published and installed on a target server.

Please take a new & clean database without any customisations done to publish and install the extensions.

Use Publish-NAVApp cmdlet to publish the Extension for the service Instance



To Install we can use Install-NAVApp cmdlet

Install-NAVApp -ServerInstance YourDynamicsNAVServer -Name ”My Extension” –Tenant Tenant1, Tenant3

OR

We can install the same from RTC NAV Client

Go to Extension Management and install the published extension in our case FOCCustomer.



Now after installing we can verify whether our changes are reflecting on customer card.





NOTES :

1) Objects must be exported as .TXT files. We cannot build an extension based on a .FOB file.

2) DO NOT make C/AL code modifications.

3) DO use subscribing to events to execute code.

4) DO NOT change restricted page and table properties.

5) The packaging process adds a description of the extension to the manifest, such as whether it changes pages or adds tables. While not explicitly being enforced currently, this can be used to determine whether to install an extension, or not.

6) If we want to publish an unsigned extension package, we need explicitly state that by using the –SkipVerification parameter on the Publish-NAVApp cmdlet.

7) When we install an extension that includes changes to the menu suites, this does not take effect for any user until we sign out and then sign in again.



Please refer below MSDN links for Extensions

1) Developing Extensions for NAV 2017
https://msdn.microsoft.com/en-us/dynamics-nav/how-to--develop-an-extension

2) Create an Extension package for NAV 2017
https://msdn.microsoft.com/en-us/dynamics-nav/how-to--create-an-extension-package

3) Publish and Install Extension for NAV 2017
https://msdn.microsoft.com/en-us/dynamics-nav/how-to--publish-and-install-an-extension

4)  How to Write Extension Upgrade Code for NAV 2017
https://msdn.microsoft.com/en-us/dynamics-nav/extensions-upgrade-howto

5)  Extension Packages Capability Support Matrix for NAV 2017
https://msdn.microsoft.com/en-us/dynamics-nav/extension-packages-capability-support-matrix


Thanks & Regards,
Nandesh Gowda

Extending Microsoft Dynamics NAV Using Extension Packages

Hi All,

You can extend and customize a Dynamics NAV deployment without modifying the original application objects. With extension packages, you install, upgrade, and uninstall functionality in on-premises deployments or for select tenants in a multitenant deployment. Customers can easily add or remove horizontal or customized functionality to their solution that upgrade much easier than past solutions.

The main difference from classical development is that source code modifications are not allowed. Instead, you use C/AL events to extend and customize objects.

Extensions are delivered as .navx package files. A .navx package contains the various artifacts that deliver the new functionality to the Dynamics NAV deployment as well as a manifest that specifies the name, publisher, version, and other attributes of the extension. You manage .navx packages with a series of Windows PowerShell cmdlets that are available in the Microsoft Dynamics NAV 2017 Administration Shell. There are also cmdlets available to ISVs and developers in the Microsoft Dynamics NAV 2017 Development Shell that help create packages.


How Extensions Work

Extensions are in the simplest terms the runtime application of objects and object deltas for a specific combination of an extension package and a tenant. When an extension is published to a Dynamics NAV deployment, it compiles the objects in it against the current application database. Then, when the extension installs for a tenant, it stores the association and builds the relevant database schema. At runtime, Dynamics NAV simply loads the associated objects for that extension and tenant.

You can publish multiple extensions to a Dynamics NAV deployment and, in multitenant deployments, install any combination of published extensions for each tenant. For example, consider a scenario with a multitenant deployment with extensions A, B, C, and D published to it. Each tenant can have their own unique combination of extensions. So tenants 2, 3, and 4 can have the same extensions (extensions B and C) while tenants 1 and 5 only have one extension each, extension A and D, respectively. This provides for a great degree of customer functionality choice while at the same time maximizes the server hardware and administration workload.

In most cases, two extension packages can coexist and work independently of each other; however there is the possibility that two apps will try to modify the same object properties. In those cases, if the conflict cannot be resolved, the installation of the conflicting extension fails.

You can refer below MSDN Link for detailed explanation about Extensions.

https://msdn.microsoft.com/en-us/dynamics-nav/extending-microsoft-dynamics-nav-using-extension-packages


As per my understanding we will have a dilemma whether to go for extensions or use the traditional development methods.

We can have below consideration while choosing Extensions :

1) Is the database going to be heavily customized or not?

2) Is the development done can be easily maintained and monitored?

3) How frequently the changes will come in your existing extensions ?

4) What  level of IT hardware & Configuration needed for extension?

5) More the extensions used, more consideration to be given for Server hardware configuration as the extensions will be loaded by NAV at run time.

6) Upgrade Flexibility

7) Multi Tenant Environment Flexibility

8) Using extensions for third party App, ISV, etc.


Anyways we need to move forward and start using Extension packages for most of our developments.
.
I feel in future Extensions will be heavily concentrated on and improvements will come in this regard. As its obvious from NAV 2016 and NAV 2017 releases and changes w.r.t to Extensions.


Thanks & Regards,
Nandesh Gowda

Cannot add the Field Trigger or cannot add variable NAV Extensions

Hi All,

Cannot add the Field Trigger to.

Above error may come when creating Extension package using New-NAVAppPackage cmdlet.

The above error may come if you have written some code on Triggers of page or table for a field.

So please remove the code and use the Events to implement your code.

We have default trigger events available for table or page to write our code on when you subscribe to table/page object.

Cannot add variable to

Again this is similar kind of error, please remove the variable defined from the object and implement the logic using Events.

Thanks & Regards,
Nandesh Gowda

Publish-NAVApp : Merge Conflict: Could not update Codeunit NAV Extensions

Hi All,

Publish-NAVApp : Merge Conflict: Could not update Codeunit XXXX

Above error may come while using Publish-NAVApp cmdlet, if the customized objects which are added for development are already available in NAV Database.


Thanks & Regards,
Nandesh Gowda

Account Categories and Account Subcategories on Chart of Accounts NAV2017

Hi All,

New fields have been added on chart of accounts for categorization of Accounts.

To start with we will discuss G/L Account Category

NAV 2017 comes with five predefined Account Category.

You can add new Subcategories from G/L Account Category Page. Basically Account Subcategories are grouping under Account categories.

You can use Generate Account Schedules that will update predefined financial reports such as Balance Sheet, P&L, etc. ( through Account Schedules).




On Chart of Accounts you can see Account Category field with five predefined values

Account Category : 



Account Subcategory :

It's a variable on G/L Account Card.

It's value is picked from G/L Account Category based on the Account category selected.



Benefits of using Account Categories :

• Various Financial Reports (Balance Sheets, P&L, etc.) are readily available from Account Categories.
• We can group the G/L Accounts into Categories for better user understanding.
• We can see balances as per Categories and Subcategories.
• We can use the Categories for developing various kinds of Analysis reporting.

Thanks & Regards,
Nandesh Gowda

Notifications in UI NAV 2017

Hi All,

Notifications provide a programmatic way to send non-intrusive information to the user interface (UI) in the Dynamics NAV Web client. Notifications differ from messages initiated by the MESSAGE function. Messages are modal, which means users are typically required to address the message and take some form of corrective action before they continue working. On the other hand, notifications are non-modal. Their purpose is to give users information about a current situation, but do not require any immediate action or block users from continuing with their current task. For example, you could have a notification that a customer's credit limit is exceeded.


Notifications in the UI :

In the UI, notifications appear in the Notification bar (similar to validation errors) at the top of the page on which a user is currently working. The user can then choose to dismiss the notification, which clears it. Or if actions are defined on notification, the user can choose one of the actions.

• There can be multiple notifications. The notifications appear chronological order from top to bottom.
• Notifications remain for duration of the page instance or until the user dismisses them or takes action on them.
• Notifications that are defined on sub-pages, for example in parts and FactBoxes, appear in the same Notification bar.
• Validation errors on the page will be shown first.

Notifications in the development environment :

By using the Notification and NotificationScope data types and functions in C/AL, you can add code to send notifications to users. The following table provides an overview of the available functions. The sections that follow provide additional information about how to create notifications.

Function	Description
MESSAGE	Specifies the content of the notification that appears in the UI.
SCOPE	Specifies the scope in which the notification appears.
SEND	Sends the notification to be displayed by the client.
ADDACTION	Adds an action on the notification.
SETDATA	Sets a data property value for the notification
GETDATA	Gets a data property value from the notification.
RECALL	Recalls a sent notification.

Creating and sending a notification:

You create a notification by using the MESSAGE and SEND functions. The MESSAGE function defines the message part of the notification. When the SEND function is called, the notification is sent to the client and content of the message is displayed.

MyNotification.MESSAGE := 'This is a notification';
MyNotification.SEND;

The SEND function call should be the last statement in the notification code, after any ADDACTION or SETDATA function calls for the notification instance.

Defining the notification scope :

The scope is the realm in which a notification is broadcast in the client. There are two different scopes: LocalScope and GlobalScope.

• A LocalScope notification appears in context of the user's current task, that is, on the page the user is currently working on. LocalScope is the default.
• A GlobalScope notification is not directly related to the current task. Note:GlobalScope is currently not supported, so do not use it. This will be implemented in a future release.

The following code creates a notification in the LocalScope:

MyNotification.MESSAGE := 'This is a notification';
MyNotification.SCOPE := NOTIFICATIONSCOPE::LocalScope;
MyNotification.SEND;

Adding actions on a notification :

You add actions on notifications by using the ADDACTION function. This function provides a way for you to create interactive notifications. By default, users have the option to dismiss the notifications. However, there might be cases where you want to provide users with different actions that they can take to address the notification, like opening an associated page for modifying data.

Conceptually, a notification action calls a function in a specified codeunit, passing the notification object in the call. The function includes the business logic for handling the action.

MyNotification.MESSAGE := 'This is a notification';
MyNotification.SCOPE := NOTIFICATIONSCOPE::LocalScope;
MyNotification.ADDACTION('Action 1',CODEUNIT::"Action Handler",'RunAction1');
MyNotification.ADDACTION('Action 2',CODEUNIT::"Action Handler",'RunAction2');
MyNotification.SEND;

The basic steps for adding an action are as follows:

1. Create a global function in a new or existing codeunit. The function must have a Notification data type parameter for receiving the notification object.
2. Add C/AL code to the function for handling the action.
3. Specify the codeunit and function in the ADDACTION function call.

Important

You can have more than one action on a notification. A LocalScope notification can have up to 3 actions. A GlobalScope notification can have up to 2 actions.

Sending data with a notification :

You use the SETDATA and GETDATA functions to add data to a notification, which is typically needed when actions are invoked. The SETDATA function sets, or adds, data to the notification. The data is defined as text in a key-value pair. With the GETDATA function, you can then retrieve the data again.

The following code sets data for a notification:

MyNotification.MESSAGE := 'This is a notification';
MyNotification.SCOPE := NOTIFICATIONSCOPE::LocalScope;
MyNotification.SETDATA('Created',FORMAT(CURRENTDATETIME,0,9));
MyNotification.SETDATA('ID',FORMAT(CREATEGUID,0,9));
MyNotification.ADDACTION('Action 1',CODEUNIT::"Action Handler",'RunAction1');
MyNotification.ADDACTION('Action 2',CODEUNIT::"Action Handler",'RunAction2');
MyNotification.SEND;

The following code gets the data for a notification:

DataValue := MyNotification.GETDATA('Created');
DataValue := MyNotification.GETDATA('ID');

Example :

This simple example illustrates how notifications work and provides some insight into how you can use them. This example uses page 42 Sales Order of the CRONUS International Ltd. demonstration database according to the following.

• The code compares a customer's balance with their credit limit. If the balance exceeds the credit limit, a notification is sent to the client.
• The notification includes an action, which has the caption Change credit limit, that opens page 21 Customer Card. This enables the user to increase the credit limit.

To complete the example, follow these steps:

1. In C/AL code for page 42 Sales Order, add the following variables and text constants:

   Variable Name	Data Type	Subtype
   Customer	Record	Customer
   CreditBalanceNotification	Notification
   OpenCustomer	Text

   Text Constant Name	ConstValue
   Text003	The customer's current balance exceeds their credit limit.
   Text004	Change credit limit

2. Add the notification code on page 42 Sales Order.
   For this example, add the code on OnOpenPage tigger in C/AL .

   Customer.GET("Sell-to Customer No.");
   IF Customer."Balance (LCY)" > Customer."Credit Limit (LCY)" THEN
   BEGIN
    //Create the notification
    CreditBalanceNotification.MESSAGE(Text003);
    CreditBalanceNotification.SCOPE := NOTIFICATIONSCOPE::LocalScope;
    //Add a data property for the customer number
    CreditBalanceNotification.SETDATA('CustNumber', Customer."No.");
    //Add an action that calls the Action Handler codeunit, which you define in the next step.
    CreditBalanceNotification.ADDACTION('Text004', CODEUNIT::"Action Handler", OpenCustomer);
    //Send the notification to the client.
    CreditBalanceNotification.SEND;
   END
   

3. Create a codeunit, called Action Handler, for handling the notification action as follows:
   • Add a global function called OpenCustomer that has a Notification data type parameter called CreditBalanceNotification for receiving the Notification object.
   • Add the following C/AL variables to the codeunit:

     Variable Name	Data Type	Subtype
     CustNumber	Text
     CustNo	Text
     CustRec	Record	Customer
     CustPage	Page	Customer Card

   • Add the following code to the OpenCustomer function:

     //Get the customer number data from the SETDATA call.
     CustNo := CreditBalanceNotification.GETDATA(CustNumber);
     // Open the Customer Card page for the customer.
     IF CustRec.GET(CustNo) THEN BEGIN
      CustPage.SETRECORD(CustRec);
      CustPage.RUN;
     END ELSE BEGIN
       ERROR('Could not find Customer: ' + CustNo);
     END;

Thanks & Regards,
Nandesh Gowda