How To Override The D365 JumpRef

View Details

As a reminder, Microsoft Dynamics 365 for Finance and Operations uses relational data. Therefore records often have fields that contain values that relate one record to another table with additional data. Instead of showing all the data on one form, users can click on the blue text, or right click and select ‘view details’ on a form to navigate to a related form. Then, create, modify, or view the related data on a that form.

In the last article, How to Use D365 View Details, I demonstrated how to use this functionality. I also explained how developers can use table relations and Form Rep property to allow this functionality to work.

This works for most scenarios. However, there are some scenarios where developers need to override the D365 jumpRef method to change what occurs. There is not a lot of Microsoft documentation on this method. So I will explain how and when to use it.

JumpRef

To explain, in D365, there are lots of methods on every form control. These determine how that control functions. The D365 jumpRef method is the method that controls how the ‘view details’ functionality works.

If a field has no table relations or EDT table relations, then the field value does not show as ‘blue text’. Additionally, when the user right-clicks on the field, the option for ‘view details‘ does not show up.

Conversely, if a field has a table relation or EDT table relation, then the field value will show as ‘blue text’. Additionally when the user right-clicks on the field, the option for ‘view details‘ does show in the drop-down list. Then, the system will use the related table, and the Form Ref property to determine which form to open, and how to filter that form.

Occasionally, there are scenarios where a developer needs to change the default behavior. In these scenarios, they need to override the D365 jumpRef method and add code.

Example

To better understand, let us start with an example. In D365, navigate to Accounts Receivable>Orders>All sales orders. Next, click on a sales ID to go into the sales order details form. Then, select or a create a sales line. Expand the Line details fast tab. Finally, click on Delivery tab. Locate the field ‘Shipping carrier’.

This form control has an overridden D365 jumpRef method. When this field is populated, the value is blue, and can be clicked on. Or, the user can right click on the field and select ‘View details’.

This takes the user to the Shipping carriers form.

Now that you have seen the functionality from the from end form, let us look at the code in Visual Studio.

Overriding The JumpRef Method

To see the overridden D365 JumpRef method, first search for SalesTable in the Application Explorer, in Visual Studio. Right click on the SalesTable form, and select ‘open designer‘.

Next, we need to locate the ‘Shipping carrier’ form control in the form. The easiest way to do this is right-click on the control’s label in the browser. A pop-up will show us the name of the control. In this example, we can see that it is named ‘TMSCarrierInfo_CarrierCode‘.

Now that we know the name of the control, go back to Visual Studio, and enter the control name into the top bar of the form designer. Then, push Enter. The system will change the Design window to only show the form control, and its parent nodes.

Now that we have located the control in the form, expand the control node, and Methods node. Notice, the D365 jumpRef method is shown.

This means that the jumpRef method has been overridden. When it is not shown, the functionality is still there. It just means that the method will work in its default way.

Next, double click on the jumpRef method node to open up this method in a code editor.

Additionally, you can right click on the SalesTable form now, and select ‘view code’. Then, search for the jumpRef method. However, double clicking on the node is faster as Visual Studio will take you right to the correct lines of code.

Calling A Form

The base Microsoft jumpRef method will open a form, and pass the current record to that form. Therefore, if a developer overrides this functionality, then they will need to write this code themselves.

There are two ways of writing code to open another form.

First, code can be written to call a Menu Item. Menu Items in the AOT have properties that specify the name of the form to open.
Secondly, code can be written to open a form directly by instantiating the FormRun class, and providing the name of the form to open.

I will show a couple examples. But for more information see my article How to Call A form Using X++.

Call The Menu Item

To continue with our example, right-click on the method that is called within the overridden jumpRef method. Then, select ‘Go to definition‘. This will take you to the code where this method is defined. Also notice, that the code ‘this.valueStr()’ takes the current value in this form control, and passes it to the calling method.

It is not necessary to always call another method. But in this case, putting this method on the TMSCarrier table, allows this method to be reused by other forms.

This method contains the following code:

public static void jumpRefCarrierCode(TMSCarrierCode _carrierCode)
    {
        Args            args = new Args();
        MenuFunction    menuFunction;

        TMSCarrier tmsCarrier = TMSCarrier::find(_carrierCode);
        args.record(tmsCarrier);
        args.lookupRecord(tmsCarrier);

        menuFunction = new MenuFunction(menuitemDisplayStr(TMSCarrier), MenuItemType::Display);
        menuFunction.run(args);
    }

To explain, the code instantiates a class named ‘Args’. This is a generic class that will be used to pass a record to the calling form, so that the calling form can filter on it.

First, the code uses the passed in _carrierCode variable to find a record in the TMSCarrier table.

Secondly, the code calls the ‘record‘ and ‘lookupRecord‘ methods on the Args class, passing in the TMSCarrier table buffer variable. If the record passed in is the same table as the main data source on the calling form, then the system will automatically filter the data source to that record. Very cool!

Thirdly, the code instantiates the MenuFunction class, and passes in the name of the Menu Item to call. In this example, there exists a display menu item name TMSCarrier.

Finally, the code calls the ‘run’ method on the MenuFunction class, and passes the args variable as a parameter. This tells the system to run the form connected to that Menu Item. Again, by passing in the args variable with the ‘record’ set, the calling form will be filtered to that record, as long as the data source and the record use the same table.

Call The Form Directly

Additionally, code can be written in D365 JumpRef method to call a form directly. Instead of calling a Menu Item, the ‘FormRun’ class can be used. Below is an example.

public void jumpRef()
{
    Args        args;
    FormRun     formRun;
 
    args = new Args(formstr(SalesTable));
 
    args.record(SalesTable::find(InvoiceId.valueStr()));
 
    formRun = classfactory.formRunClass(args);
    formRun.init();
    formRun.run();
    formRun.detach();
}

Why Override The JumpRef?

Now, you may be asking yourself: Why override the D365 JumpRef method? Why not use table relations? A developer should be using table relations when possible. However, there are a few scenarios where this may not be possible or work the way the developer needs it to.

No Table Relation Setup

First, in the above example, there is no relation on the SalesTable table between it and the TMSCarrier table. And therefore, the default functionality would be to now allow the user to click ‘View details’ on this field. Sometimes, adding a table relation can cause problems. However, if the ‘view details’ functionality is still desired, a developer can override the jumpRef method to make this functionality work.

There Is No Related Form

Secondly, there are times when a table relation exists, but there is no related form. In this scenario, clicking ‘view details’ would not do anything. So the jumpRef needs to be disabled to make sure the system does not try to navigate to a form that does not exist.

Again, here is another example from the MCRRoyaltyTable form, where the view details functionality is not desired.

To Control When It is Valid to Navigate

In this somewhat special example, the system will sometimes use the default jumpRef functionality, and sometimes not.

Use a RefRecId Field To Pass The Right Record

In this example from the MCRBrokerClaims form, the CustTransRecId field on the MCRBrokerAccrual_Lines data source is used to open a record on the CustTrans form. This is helpful when the ‘CustTransRecId‘ field isn’t the field being shown, or the CustTrans record isn’t the data source record.

To Control What Form To Open

Let’s pretend there exists a relation on the table, that would cause one form to be opened. But now, the developer wants an entirely different form to be opened. The developer can accomplish this by overriding the jumpRef method, and writing code to open a different form.

Override The JumpRef On A Custom Form

To override a D365 jumpRef method on a custom form that you created, right-click on the ‘methods’ node of a form control, then select ‘Override>jumpRef‘.

Or, override the jumpRef on a Data source field methods node. Next, when the code editor opens, add the code to call a related form.

Override A JumpRef On A Base Form

However, you cannot do this directly on a base Microsoft form.

The base form controls on the main form are locked, so you can’t add methods to those.

Additionally, when you add your own new form controls on a form extension, you are not able to override methods on those form controls because the ‘code’ part of the form is locked.

Therefore, you must use chain of command or an event handler class to add code to the form. And then you must add code to let the form know which method to use. Since there are some additional steps, I will show you how you can override the jumpRef on a base form in the next article.

Conclusion

While most of the time, you want the ‘view details’ hyper-link to take you to the related form, there are some exceptions. And for those exceptions it is helpful to understand that you can override the jumpRef method, and change how this functionality works. This is very helpful when there is more than one related form that can be used to create, edit, or view data.

Peter Ramer

Peter Ramer is a part of the Managed Application Services team at RSM working on Microsoft Dynamics 365. He focuses on the Retail and Commerce industries. When he is not solving problems and finding ways to accelerate his clients' business, he enjoys time with his three kids and amazing wife.