Extending Microsoft Dynamics NAV 2016 Cookbook Make the most of your NAV deployment by extending and customizing it with a variety of expert tools Alexander Drogin BIRMINGHAM - MUMBAI Extending Microsoft Dynamics NAV 2016 Cookbook Copyright © 2017 Packt Publishing All rights reserved No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews Every effort has been made in the preparation of this book to ensure the accuracy of the information presented However, the information contained in this book is sold without warranty, either express or implied Neither the author, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals However, Packt Publishing cannot guarantee the accuracy of this information First published: January 2017 Production reference: 1130117 Published by Packt Publishing Ltd Livery Place 35 Livery Street Birmingham B3 2PB, UK ISBN 978-1-78646-060-8 www.packtpub.com Credits Author Copy Editor Alexander Drogin Safis Editing Reviewer Project Coordinator Oleg Romashkov Vaidehi Sawant Commissioning Editor Proofreader Aaron Lazar Safis Editing Acquisition Editor Indexer Sonali Vernekar Mariammal Chettiyar Content Development Editor Production Coordinator Siddhi Chavan Arvindkumar Gupta Technical Editors Dhiraj Chandanshive Bhavin Savalia About the Author Alexander Drogin started working with Navision Attain version 3.01 in 2002 as a software developer at a consulting company After years of development, he shifted his focus to end-user support In 2012, he joined the Microsoft Russia development team as a software engineer in testing, and worked on NAV test automation Currently, he leads the sustained engineering team in the Supply Chain Management area at Microsoft I would like to thank my colleagues who helped me in my work on this book Oleg Romashkov, for reviewing the book and testing the code samples, whose valuable feedback on the content helped improve the quality of the book; and Sergey Iazovskiy, who helped me in designing numerous NET examples and solving issues with NET Interoperability About the Reviewer Oleg Romashkov has been a NAV developer since 2001 He worked for eight years with Microsoft by developing new features and country localizations for NAV 4.00 – NAV 2015 Also he spent years working for a few MS partners where he implemented NAV for more than 20 customer projects www.PacktPub.com For support files and downloads related to your book, please visit www.PacktPub.com Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub.com and as a print book customer, you are entitled to a discount on the eBook copy Get in touch with us at service@packtpub.com for more details At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks https://www.packtpub.com/mapt Get the most in-demand software skills with Mapt Mapt gives you full access to all Packt books and video courses, as well as industry-leading tools to help you plan your personal development and advance your career Why subscribe? Fully searchable across every book published by Packt Copy and paste, print, and bookmark content On demand and accessible via a web browser Customer Feedback Thank you for purchasing this Packt book We take our commitment to improving our content and products to meet your needs seriously—that's why your feedback is so valuable Whatever your feelings about your purchase, please consider leaving a review on this book's Amazon page Not only will this help us, more importantly it will also help others in the community to make an informed decision about the resources that they invest in to learn You can also review for us on a regular basis by joining our reviewers' club If you're interested in joining, or would like to learn more about the benefits we offer, please contact us: customerreviews@packtpub.com Table of Contents Preface Chapter 1: Writing Basic C/AL Code Introduction Installing NAV Development Environment Getting ready How to it… How it works… Application object triggers How to it… How it works… NAV Development Environment – C/SIDE How to it… How it works… Compiling objects and error handling How to it… How it works… Importing and exporting application objects How to it… How it works… Basic C/AL programming How to it… How it works… Accessing the database in C/AL How to it… How it works… Configuring NAV Server Getting ready How to it… How it works… Creating a NAV user account Generating a self-signed certificate Obtaining the certificate thumbprint Changing the server configuration Configuring web server Getting ready 8 9 12 12 13 14 15 15 17 18 18 19 20 20 23 23 23 26 27 28 29 31 31 31 35 35 35 35 36 36 36 How to it… How it works… There's more… See also 37 41 42 44 Chapter 2: Advanced C/AL Development Introduction Creating custom tables How to it… How it works… Understanding database triggers How to it… How it works… Implementing a user interface with pages How to it… How it works… Linking datasources in subpages How to it… How it works… Working with page triggers How to it… How it works… Presenting related data in FactBoxes How to it… How it works… Designing reusable code How to it… How it works… See also Accessing temporary tables How to it… How it works… See also Role-Tailored client and role centers How to it… How it works… Assigning role centers to user profiles Getting ready How to it… How it works… [ ii ] 45 46 46 46 50 54 55 56 58 58 66 67 68 69 71 71 73 74 74 77 77 78 80 81 81 81 83 84 85 85 94 97 97 97 99 PowerShell How it works… Parameters for the cmdlet New-NAVServerInstance in Step are given on the assumption that the NAV demo database is hosted on the default instance of SQL Server If a named instance is used instead, include a parameter -DatabaseInstance The full list of parameters will be as follows: New-NAVServerInstance -ServerInstance "NAVShellTest" ` -DatabaseServer localhost ` -DatabaseInstance "NAVDEMO" ` -DatabaseName "Demo Database NAV (9-0)" ` -ManagementServicesPort 7065 ` -ClientServicesPort 7066 ` -SOAPServicesPort 7067 ` -ODataServicesPort 7068 This cmdlet has five mandatory parameters: the name of the new server instance and four ports for external connections Other parameters are optional, and can be configured via Microsoft Management Console or directly in the server configuration file CustomSettings.config Optional parameters not specified in the command, are initialized with default values, and the example of the preceding command is sufficient to create a workable server instance Handling application objects In previous examples of this chapter, we used PowerShell cmdlets available via the NAV Administration shell These are commands intended to automate administration tasks Another set of cmdlets is accessible in the NAV 2016 Development Shell and aimed for application developers to help them in their routine work with application objects In the current recipe, we will illustrate several basic scripts for application objects manipulation How to it… In this recipe, you will learn how to export, import, compile, and run application objects from the PowerShell command line Start Dynamics NAV 2016 Development Shell To it, open the Start menu and start typing the application name [ 417 ] PowerShell One of the typical tasks for a NAV application developer is to export application objects from C/SIDE and store them in separate text files in a source control system This is easily done in NAV Development Shell Export custom application objects into a text file: Export-NAVApplicationObject -DatabaseServer "localhost" ` -DatabaseName "Demo Database NAV (9-0)" ` -Filter "Type=Codeunit|Table;Id=50000 59999" ` -Path "NavObjects.txt" This command will export all tables and codeunits with IDs between 50000 and 59999 The full file path must be provided in the parameter -Path The default path is the same as for the administrator shell, C:\Windows\System32 Create a NavObjects folder where the object files will be stored Split the file into separate objects: Split-NAVApplicationObjectFile ` -Source "NavObjects.txt" ` -Destination "NavObjects" Object files can be imported from a source code storage via a PowerShell cmdlet Import the codeunit 50000 from a text file Codeunit 50000 was introduced in the recipe, Basic C/AL programming, in Chapter 1, Writing Basic C/AL Code You can copy it from the book's source files To import the object to the database, run the following command: Import-NAVApplicationObject ` -Path "NavObjects\COD50000.txt" ` -DatabaseServer "localhost" ` -DatabaseName "Demo Database NAV (9-0)" ` -ImportAction Overwrite -SynchronizeSchemaChanges Force In the next step, we will illustrate error reporting when compiling an object from the command line Let's introduce an error to the object code to see the error report Open the codeunit 50000 in the object designer and change the first line from IF VerifyCheckSum(79927398712.0) THEN to IF VerifyCheckSum('79927398712.0') THEN [ 418 ] PowerShell Apostrophes around the number in the function parameter present it as a text constant rather than the expected big integer number This is a compiler error Save the object without compiling (remove the checkmark Compiled in the Save As dialog) Now compile all uncompiled objects in the database: Compile-NAVApplicationObject -DatabaseServer "localhost" -DatabaseName "Demo Database NAV (9-0)" -Filter "Compiled=No" The result of the compilation will be displayed in the Development Shell console: To fix the error, return to the object designer and remove the erroneous apostrophes in the codeunit 50000 The first line in the OnRun trigger should be as follows: IF VerifyCheckSum(79927398712.0) THEN [ 419 ] PowerShell Now compile the codeunit again with the following command: Compile-NAVApplicationObject ` -DatabaseServer "localhost" ` -DatabaseName "Demo Database NAV (9-0)" ` -Filter "Type=Codeunit;ID=50000" With PowerShell cmdlets, you can even invoke NAV code units or codeunit methods Run object from NAV Administration Shell: Invoke-NAVCodeunit ` -ServerInstance DynamicsNAV90 -CodeunitId 50000 Invoke-NAVCodeunit in the preceding example calls the codeunit's OnRun method Any UI messages raised by the codeunit will be posted in the console 10 With the same cmdlet, any global function in a codeunit can be called To demonstrate this, let's invoke the codeunit 50800 from Chapter 8, Web Services Import the codeunit and open it in the object designer Replace the EXIT in the last line of the GetCityByPostCode method with a MESSAGE: MESSAGE(PostCodeCatalog.City); 11 Save and compile the modified codeunit 12 Now run the Invoke-NAVCodeunit cmdlet with the following parameters: Invoke-NAVCodeunit ` -ServerInstance DynamicsNAV90 ` -CodeunitId 50800 ` -MethodName GetCityByPostCode ` -Argument "ES-46007" ` -CompanyName "CRONUS International Ltd." The GetCityByPostCode method name is passed as a parameter to the cmdlet This function returns the city name by the post code that is received in a parameter The method receives the post code parameter in the cmdlet parameter -Argument As a result of the execution, the message text Valencia will be posted to the PowerShell window [ 420 ] PowerShell How it works… The second step of the recipe illustrates the export of application objects into a text file The database server and database where the objects must be exported from, are specified in parameters -DatabaseServer, and -DatabaseName, respectively If the database is located on a default SQL Server instance, it is sufficient to specify the NetBIOS name of the server (for example, localhost) where the service is running In case of a named instance, the name of the instance is specified after the computer name, separated with a backslash (for example, localhost\NAVDEMO): Export-NAVApplicationObject ` -DatabaseServer "localhost\NAVDEMO" ` -DatabaseName "Demo Database NAV (9-0)" ` -Filter "Type=Codeunit|Table;Id=50000 59999" ` -Path "NavObjects.txt" The -Filter parameter specifies the filters that will be applied to the list objects The filter structure is similar to the filters used in NAV user interface The filter begins with a field name which you want the filter to be applied on, followed by the filtered values To specify several values, separate them with a vertical bar (Type=Codeunit|Table) A range of values is defined with two dots (Id=50000 59999) Several filters that must be applied to different fields are divided with a semicolon Step shows how to import objects from a text file into the development environment with the Import-NAVApplicationObject cmdlet You specify the file name where the object is stored, and the server and the database to import the objects to Two parameters to pay special attention to are ImportAction and SynchronizeSchemaChanges The first one, ImportAction, defines the cmdlet behavior if an object being imported already exists in the database It accepts one of the values Default, Overwrite, Skip Default: Object is not imported, and the error is logged Overwrite: Object in the database is replaced with the new one Skip: Conflicting object is skipped The SynchronizeSchemaChanges parameter can take one of three values: Force, No, Yes This parameter manages the schema synchronization for imported tables if there are any among the imported objects For a detailed description of database schema synchronization, refer to the recipe Creating custom tables in Chapter 1, Writing Basic C/AL Code [ 421 ] PowerShell In Step 5, the imported objects are compiled with the compilation log dumped on the screen This way of reporting compilation errors may be extremely inconvenient, so it would be a good idea to include a LogFile parameter to the cmdlet to duplicate its output into a text file: Compile-NAVApplicationObject ` -DatabaseServer "localhost" ` -DatabaseName "Demo Database NAV (9-0)" ` -Filter "Compiled=No" ` -LogPath "NavObjects" The value of the LogPath parameter is a folder where the two resulting files are generated: The navcommandresult.txt file contains the command execution summary with a reference to the error log if the command fails: The naverrorlog.txt file lists compilation errors Merging application objects A dedicated set of PowerShell cmdlets in NAV Development Shell is available to aid in the tedious task of merging modifications in application objects Application developers turn to this collection of cmdlets when applying modifications made by the Microsoft development center to customized objects How to it… The following recipe illustrates the benefits and limitations of automated object merge: Import the unchanged version of the codeunit 50800 from Chapter source files This version of the object will serve as a base for comparison Create a folder MergeObjects and copy the source file with the unchanged codeunit in the folder as COD50800_Original.txt Open the codeunit 50800 in the object designer Modify the function GetCityByPostCode as follows: PostCodeCatalog.SETRANGE(Code,PostCode); IF PostCodeCatalog.FINDFIRST THEN EXIT(PostCodeCatalog.City); [ 422 ] PowerShell Save the codeunit and export it to the same MergeObjects folder as COD50800_Target.txt Import the unchanged version of the codeunit again (replacing the original object), and create a new function, GetCountryByPostCode: GetCountryByPostCode(PostCode : Code[20]) : Text[30] PostCodeCatalog.SETRANGE(Code,PostCode); PostCodeCatalog.FINDFIRST; EXIT(PostCodeCatalog.County); The function is a copy of GetCityByPostCode with minor changes in the code, so you can copy the original function and rename the copy The variable PostCodeCatalog is also a copy of a variable from the original function GetCityByPostCode It should be declared as a local variable of type Record with subtype Post Code Export the third version of the object to the MergeObjects folder Save it as COD50800_Modified.txt In NAV Development Shell, run the Merge-NAVApplicationObject cmdlet: Merge-NAVApplicationObject ` -OriginalPath "MergeObjects\COD50800_Original.txt" ` -ModifiedPath "MergeObjects\COD50800_Modified.txt" ` -TargetPath "MergeObjects\COD50800_Target.txt" ` -ResultPath "COD50800_Result.txt" When the command completes, the digested log is displayed, informing that one object was successfully merged: [ 423 ] PowerShell Open the result file COD50800_Result.txt It contains merged code from both versions Modified and Target The following code sample is the result of the successful merge: PROCEDURE GetCityByPostCode@1(PostCode@1001 : Code[20]) : Text[30]; VAR PostCodeCatalog@1000 : Record 225; BEGIN PostCodeCatalog.SETRANGE(Code,PostCode); IF PostCodeCatalog.FINDFIRST THEN EXIT(PostCodeCatalog.City); END; PROCEDURE GetCountryByPostCode@2(PostCode@1001 : Code[20]) : Text[30]; VAR PostCodeCatalog@1000 : Record 225; BEGIN PostCodeCatalog.SETRANGE(Code,PostCode); PostCodeCatalog.FINDFIRST; EXIT(PostCodeCatalog.County); END; 10 Now let's review another example Suppose, we want our modified version of the function to look for cities only in Great Britain Import the original version of the object from the COD50800_Original.txt file and make another modification: PostCodeCatalog.SETRANGE(Code,PostCode); PostCodeCatalog.SETRANGE("Country/Region Code",'GB'); PostCodeCatalog.FINDFIRST; EXIT(PostCodeCatalog.City); 11 Save the object and export it as a modified version into the COD50800_Modified.txt file [ 424 ] PowerShell 12 Run the cmdlet with the same parameters as in Step Now the log in the console notifies you that the automatic merge of modifications failed because there is conflicting code in two modified versions of the object: The COD50800.CONFLICT file created in the MergeObjects folder after the merge also indicates a failed merge attempt 13 To review the conflicting code, open the COD50800_Result.txt file Conflicting blocks of code are marked as ORIGINAL, MODIFED, and TARGET Code lines taken from corresponding files are listed under marks to highlight the conflict: PostCodeCatalog.SETRANGE(Code,PostCode); {>>>>>>>} ORIGINAL PostCodeCatalog.FINDFIRST; EXIT(PostCodeCatalog.City); {=======} MODIFIED PostCodeCatalog.SETRANGE("Country/Region Code",'GB'); PostCodeCatalog.FINDFIRST; EXIT(PostCodeCatalog.City); {=======} TARGET IF PostCodeCatalog.FINDFIRST THEN EXIT(PostCodeCatalog.City); {