Managing Dynamics NAV with PowerShell

Since the 2013 release of Microsoft Dynamics NAV we have had the ability to manage the server using Windows PowerShell. You can think of PowerShell as Command Prompt on steroids. It gives you the ability, through cmdlets (command-lets) to control lots of aspects of Windows Server and the applications running on it.

What is it For?

You can read a list of all the available cmdlets for NAV here, but the main points are:

  • Databases – creating (from a SQL backup .bak file)
  • NAV Services – creating, removing, configuring, starting, stopping
  • Companies – creating, removing, renaming copying
  • Users – creating, removing, configuring
  • Permissions – creating, removing, assigning to users
  • Support for multitenancy installations – adding, removing, synchronising tenants

But wait, can’t you do all that from either the Server Administration Snap-In or the client itself? Yes, mostly you can. So why bother learning PowerShell? Two reasons (aside from maintaining the mystery of IT):

  1. Automation – stringing cmdlets together in a script can give you some powerful functionality. Microsoft include sample scripts on the NAV media to automatically:
    • Create a new virtual machine in Microsoft Azure
    • Upload the NAV media to that server
    • Create a new NAV database by restoring the SQL backup from the media
    • Install NAV including the server, client, web client and help server
    • Return a message with a URL to download a pre-configured Click-Once client for the user to log in with and a second URL to use the web client
    • Very powerful stuff and beyond the scope of this post – but well worth investigating at your leisure
  2. There are some things you can do more easily in PowerShell or that you can’t do in the client

First Things First

First of all let’s open the PowerShell environment. NAV installs what it calls the “Microsoft Dynamics NAV Administration Shell”. This is a PowerShell prompt which loads the NAV cmdlets automatically when you open it.

You could use this, but don’t. There is a better way.

Run “PowerShell ISE” instead. The ISE stands for “Integration Scripting Environment”. Running it as administrator will save getting any permissions errors later on. This environment provides intellisense for cmdlet names and parameters, the Command Add-On window with the list of commands and help entering them (View, Show Command Add-On), the ability to debug scripts and much more.

ise

What this environment doesn’t do is load the NAV cmdlets automatically. In order to do that run the Import-Module command and load the Microsoft.Dynamics.Nav.Management.dll file from the server installation – something like this:

Import-Module "C:\Program Files\Microsoft Dynamics NAV\71\Service\Microsoft.Dynamics.Nav.Management.dll"

Hit Refresh in the command window and the available NAV cmdlets will be loaded. You’re now ready to start firing some commands to the NAV server.

Example

Type “NAV” in the Name box of the Command Add-On to filter the cmdlets to show NAV commands.

The easiest way to enter a command is to select it from the list. The required and optional parameters are displayed underneath and you can enter the values as necessary. The Run button at the bottom will run the selected command while Insert will insert it into the editor.

ServerInstance

Nearly all the NAV commands have a ServerInstance required parameter. This tells PowerShell which NAV server you want it to send the command to and hence which NAV database you want to run the command against.

You can find the list of available the server instances from the NAV Administration snap-in (or by running the Get-NAVServerInstance PowerShell command).

Get-NAVServerPermission

A user has received a permission error, let’s say “You do not have permission to read from the Return Reason table”. The user needs this permission to do their work, so you must assign it to them.

But, which permission set do they need? Which permission sets include read permission to that table? A PowerShell cmdlet can help here.

Select Get-NAVServerPermission from the list of commands and you’ll see that there is one required parameter (indicated by the asterisk) and a few optional parameters.

image

Enter the server instance that the command should be run against (see above).

Optionally you can supply parameters for the object type (TableData in our example, not Table) and the object ID (the Return Reason table is number 6635).

Running this command will return a list of the permission sets in the database that include permissions to this table.

In a demo database, four permission sets include permission to the Return Reason table. These are displayed in a list. Fine if you only have 4 results, but not so easy to read if you have many more.

Format-Table is a useful command that tells PowerShell to return the results in a tabular format instead. To use this you can Insert the command (rather than hitting Run) and including “| Format-Table” on the end e.g.

Get-NavServerPermission –ServerInstance DynamicsNAV71 –objectId 6635 –objectType TableData | Format-Table

image

Further Reading Playing

Rather than writing out more examples I would recommend that you hook PowerShell up to a demonstration database and experiment with the different cmdlets. MSDN has good documentation for each command with examples of how to use them.

Incidentally, the above assumes that you are running PowerShell ISE on the NAV server itself. You can connect a PowerShell session to the NAV server remotely using Enable-PSRemoting.

Enjoy.

Leave a Reply