Create URLs to NAV Clients

By Mike Borg Cardona and Bogdana Botez at Microsoft Development Center Copenhagen

Abstract

This article illustrates NAV platform functionality to be used by C/AL developers.

The URL builder function, GETURL, is released in Microsoft Dynamics NAV 2013 R2 to reduce coding time for developers who need to create various URL strings to run application objects in either the win client, the web client, or on web services. In addition, the GETURL function makes multitenancy features more transparent to C/AL developers.

Description

Ever had to construct win client URLs like the one below?

dynamicsnav://myserver:7046/myInstance/myCompany/runpage?page=26

Today, Microsoft Dynamics NAV also provides a web client. This means that you must update your code to construct web client URLs too. What about multitenancy? The URL Builder should know if it is running in a multitenant setup and it should know how to choose the right tenant. What about maintaining this code?

The good news is that GETURL has been introduced to handle all URL building for you.

GETURL automatically handles:

• Multitenancy
• Correct URL format for each client
• Publicly accessible hostnames.

Usage

The format is:

[String :=] GETURL(ClientType[, Company][, Object Type][, Object Id][, Record])

Where:

• Client Type can be: Current, Default, Windows, Web, SOAP, or OData. This enables a range of scenarios for the C/AL developer, such as moving to the web client without changing code to decide where the URL should point to. This is done either by setting Client Type to Current, and just ensuring that web is used to invoke the link creation, or by setting Client Type to Default and changing its value to Web when it is ready to move to the web platform.
• Object Type and Object ID define the type of the application object to run (Table, Page, Report, Codeunit, Query, or XMLport) and its ID.
• Record specifies the actual data to run the URL on, such as:

Vendor.GET("Account No.");

GETURL(CLIENTTYPE:WEB,COMPANYNAME, OBJECTTYPE::Page,27,Vendor)

Note: It is currently not possible to set filters on the record that you sent as a last parameter to the GETURL function. However, it is possible to write your own code to compute and append the filter string to the URL that is created by the GETURL function.

The server name and instance are extracted automatically by GETURL and do not need to be specified by the C/AL developer. Furthermore, the multitenancy setup is transparent to the C/AL developer. No multitenancy parameters are specified when you call GETURL, because the function knows from the server setup if it is running in a multitenant environment and if so, it will add a string like “&tenant=MyTenant” to the URL.

When to Use

The GETURL function can generally be used every time a URL must be created. The following are some scenarios where the function is particularly useful.

• Document approvals. For more information, see the “NAV Usage Example” section.
• Reports containing drill-down links. (Beware of the resource cost of adding a new URL element to the Report dataset.)
• When planning to write code for, or migrate to, various display targets (Microsoft Dynamics NAV Windows client, Microsoft Dynamics NAV web client, Microsoft Dynamics NAV web services) without having to explicitly specify which client to use.

Examples of Usage

The following are examples of calls to GETURL and their corresponding return value:

If the GETURL function is called with invalid parameters, it will return an empty string. In that case, you can find the related error text by calling the GETLASTERRORTEXT function.

NAV Specific Example

The following example shows how to use the GETURL function in codeunit 440 to ensure that the notification mail in Document Approvals can link to both the Microsoft Dynamics NAV Windows client and the Microsoft Dynamics NAV web client:

This resulting UI looks as follows.

The first link opens the approval document in the Microsoft Dynamics NAV Windows client. The second link (Web view) opens the same document in the Microsoft Dynamics NAV web client.