Use D365FO’s jumpRef() to Open Form in a Different Legal Entity

In Dynamics 365 Finance and Operations, the View details functionality allows users to quickly access related data directly from form controls. Users just need to right-click on a form control bound to a data field (or an EDT) and select the View details context menu option, which will navigate them to the default form showing the related table record. The same effect is achieved when the value in a form control that appears as a link is clicked.

For example, on the Sales order form, the Customer account field that references a customer enables users to directly open a Customer card form, showing the related Customer (CustTable) table record.

However, this default behavior may not always work as expected or not work at all, for example when the related table doesn't point to a default form to be opened with.

D365FO uses a form control method jumpRef() for navigation to the related table record opened with the table's default form (configured in the Form Ref table property), and by overriding it, we can customize the default behavior.

By overriding jumpRef(), we can navigate users to different forms showing the related data or even change the context to a different legal entity.

The Problem

Recently, we had a request to implement the View details functionality for a field in a cross-company table that has a table relation to a field in a company-specific table.

The easiest way to describe the problem is by demonstrating it through one of the functionalities of our Docentric AX reporting solution, such as saving reports to Print archive. We needed to improve this functionality by enabling users to save reports in the D365FO Print archive using different Document types for each legal entity (i.e. company). This enhancement allows generated documents to be archived in various locations in the background, such as different SharePoint locations for different reports.

Learn more about saving reports to Print archive in our how-to manuals and articles. The feature is part of Docentric AX Free Edition.

The setup supporting the above enhancement of D365FO Print archive is implemented on the Docentric AX parameters form, the Print archive tab, where a user first specifies a Company ID and then selects a Document type for archiving. Since Document types are specific to each company, meaning each company has its own Document types, the Document type for archiving field in the dropdown combobox only needs to display the Document types relevant to the selected company.

Furthermore, users can navigate to the Document types form for the company specified in the Company ID field by using View details or simply by clicking the value in the Document type for archiving field.

As a data source for this setup, we created a cross-company table Document types for archiving (DocPrintArchiveSettings), with two fields: CompanyId and DocuTypeId.

Next, we established a relation with the standard DocuType table using both CompanyId and DocuTypeId fields, as indicated in the screenshot below. We did this because the DocuType table is company-specific, while our custom DocPrintArchiveSettings table is cross-company.

By adding this relation, we enabled a dropdown Document type for archiving (DocPrintArchiveSettings.DocuTypeId) on the Docentric AX parameters form to be populated only with the Document types configured for the corresponding DocPrintArchiveSettings.CompanyId.

When View details is used for the Document type for archiving field (DocPrintArchiveSettings.DocuTypeId) on the Docentric AX parameters form, the Document types form is opened with the selected Document type because of the above relation and the Form Ref property of the DocuType table set to the DocuType (Document types) form.

So, where is the problem then, you might start asking? 😀

The problem is that the Document types form is open in the wrong (i.e. current) company and not in the company which is selected in the current Document types for archiving (DocPrintArchiveSettings) table record.

Let's say that we are in the THPM company, and we select the record where the CompanyID field has a USMF value. By clicking the File_USMF value or by right-clicking the Document type for archiving field and selecting the View details option, the Document Types form is opened in the THPM company instead of USMF.

The question here is how to tell D365FO to change the company?

The Solution

This is the tricky part, which can be accomplished by overriding the jumpRef() method and writing code to change the company. To better understand this, let us demonstrate how we did it on the DocPrintArchiveSettings.DocuTypeId data source field.

public void jumpRef()
{
	if (DocPrintArchiveSettings.CompanyId)
	{
		// change company, open form in modal mode and then revert it
		CompanyId curCompanyId = curExt();
		appl.setDefaultCompany(DocPrintArchiveSettings.CompanyId, false); //change company without warning

		try
		{
			// Standard sets args.record() which shows just one record on opened form.
			// We open the form from code using args.lookupRecord() which shows all records but selects
			// the given one.
			Args args = new Args();
			args.lookupRecord(DocuType::find(DocPrintArchiveSettings.DocuTypeId));
			args.caller(element);
			
			FormRun formRun = new MenuFunction(menuItemDisplayStr(DocuType), MenuItemType::Display).create(args);
			formRun.run();
			formRun.wait(true);
		}
		finally
		{
			appl.setDefaultCompany(curCompanyId, false);
		}
	}
	else
	{
		DocGlobalHelper::handleWarning("Please select first the company");
	}
}

public void jumpRef()

{

if (DocPrintArchiveSettings.CompanyId)

{

// change company, open form in modal mode and then revert it

CompanyId curCompanyId = curExt();

appl.setDefaultCompany(DocPrintArchiveSettings.CompanyId, false); //change company without warning

try

{

// Standard sets args.record() which shows just one record on opened form.

// We open the form from code using args.lookupRecord() which shows all records but selects

// the given one.

Args args = new Args();

args.lookupRecord(DocuType::find(DocPrintArchiveSettings.DocuTypeId));

args.caller(element);

FormRun formRun = new MenuFunction(menuItemDisplayStr(DocuType), MenuItemType::Display).create(args);

formRun.run();

formRun.wait(true);

}

finally

{

appl.setDefaultCompany(curCompanyId, false);

}

else

{

DocGlobalHelper::handleWarning("Please select first the company");

}

The important part in the code above is the method used to change the company.

To change the company, we used the setDefaultCompany() method of the Application class. The first parameter is the Company Id to which we want to change it, and the second indicates whether to display a warning.

In the code above, it's important to store the current company and revert it after the user navigates back from the Document types form to the Docentric AX parameters form or if something goes wrong and an error occurs.

Conclusion

While most of the time, we want the View details functionality to navigate to the form within the same legal entity, there are exceptions like this one. In such cases, a developer can override the jumpRef() method to make this functionality work as desired. Knowing this trick can save both time and nerves. 😊

The Problem

The Solution

Conclusion

Leave a Reply Cancel reply