Use of Args.refField() method

Use of method refField()

The method refField() of the Args class is used to hard wire the field for a reference lookup to an explicitly defined field no matter how the standard relation would be.
This can be used to bypass standard relation behavior or to bypass problems when standard relation isn't working properly anymore because of multiple RecId relations (example below).

Example problem: multiple RecId relations

In my case we added a RefRecId field to the table VendTable which points to the table itself.

The EDT

The field has an extended data type with a relation on VendTable.RecId defined.
VendTableRefRecIdEDT

The table field

The table field was created by dragging and dropping the extended data type to the fields node on the table. No additional relations are specified on the table for this field.
vendTableRefRecIdFieldOnTable

Scenario leading to an error: calling the VendTable form from code with a record

When calling the form VendTable from code with a specific record to show the user details of a vendor, the standard behavior of linking the calling record with the one on the form via the field AccountNum doesn't work anymore because AX now tries to link the records over the field VendRefRecId.
As result, no record will be displayed to the user.

static void CallFormNormalWay(Args _args)
{
    Args        formArgs = new Args();
    Object      formRun;
    VendTable   vendTable;
    
    select firstOnly * from vendTable;
    
    formArgs.record(vendTable);
    
    MenuFunction::runCalled(menuitemDisplayStr(VendTable), MenuItemType::Display, false, formArgs);
}

Solution: method refField() on Args object

To solve this issue and make the system link the records over AccountNum again, use the method refField() on the args object to specifiy the field to link on:

static void CallFormRefField(Args _args)
{
    Args        formArgs = new Args();
    Object      formRun;
    VendTable   vendTable;
    
    select firstOnly * from vendTable;
    
    formArgs.record(vendTable);
    formArgs.refField(fieldNum(VendTable, AccountNum));
    
    MenuFunction::runCalled(menuitemDisplayStr(VendTable), MenuItemType::Display, false, formArgs);
}