Generating deep links for D365 FO forms and records

Dynamics 365 FO has an API to create URL links that point to certain forms and records, in other words “Deep links”. This way you can share a record or query within AX with others for example within an e-mail, or inside an extensible control you have written.

Below I give an example method, used in a runnable job, which generates a deep link for a record on a form, using a single field as a query parameter. To be able to test it, cop and paste the code into a runnable class and run it in USMF company of D365 one-box development environment:

using Microsoft.Dynamics.AX.Framework.Utilities;

class DeepLinkTestJob
{

private static str buildAXURL(MenuItemName _menuItemName, MenuItemType _menuItemtype, DataSourceName _dataSource='', FieldName _field='', str _value='' )
{
UrlHelper.UrlGenerator generator = new UrlHelper.UrlGenerator();
System.Uri currentHost = new System.Uri(UrlUtility::getUrl());

generator.HostUrl = currentHost.GetLeftPart(System.UriPartial::Authority);
generator.Company = curExt();
generator.MenuItemName = _menuItemName;
generator.MenuItemType = _menuItemtype;
generator.Partition = getCurrentPartition();
generator.EncryptRequestQuery = true;

if(_dataSource != '')
{
UrlHelper.RequestQueryParameterCollection requestQueryParameterCollection;

requestQueryParameterCollection = generator.RequestQueryParameterCollection;
requestQueryParameterCollection.UpdateOrAddEntry(_dataSource, _field, _value);
}

System.Uri fullURI = generator.GenerateFullUrl();

return fullURI.AbsoluteUri;
}

public static void main(Args _args)
{
str link;

link = DeepLinkTestJob::buildAXURL(menuItemDisplayStr(CustTable), MenuItemType::Display, formDataSourceStr(CustTable,CustTable), fieldstr(CustTable, AccountNum), "US-002" );

info(link);

}

}

If you later copy and paste the resulting link, you will be able to open the same record on a different browser window.

UPDATE: If you use this method inside a batch or custom API service of FO, the system standard UrlUtility::getUrl() method will fail. I describe a remedy for that in my new blog post : X++: How to get the D365FO URL correctly inside backend services

The API passes the form filter as an encrypted JSON query data in the query string and opens the form with that record only. You can see this JSON data if you set the generator.EncryptRequestQuery to false and URL decode the resulting URL. As far as Microsoft support told me, the encryption is mandatory for data security reasons and you cannot just remove it to make query string shorter, it will fall into an error and not open.

https://usnconeboxax1aos.cloud.onebox.dynamics.com/?cmp=USMF&prt=initial&mi=display:CustTable&q={"Parameters":[{"DataSource":"CustTable","FieldValues":[{"Field":"AccountNum","Value":"US-002"}]}]}

In my tests in update 11, deep links did not work with some forms, for example it failed with all upgraded List page type of forms from AX 2012. If you encounter problems with failing deep links, try setting this parameter in your display menu item to ‘Yes’ and it will probably solve the problem :

UPDATE: Recently another property here called “Allow Root Navigation” must also be enabled for deep links to work

For more information on deep links :

https://docs.microsoft.com/en-us/dynamics365/unified-operations/dev-itpro/user-interface/create-deep-links