AddForeignKeyRelation using table relation property relatedTableRole. When and how to use it

Initial demo setup

CustTableMaster Table having three foreign keys [CustAccount1, CustAccount2, CustAccount3] added. All keys point to CustTable
CustTable master form having CustTableMaster as primary DS and additional Custable1, Custable2, Custable3 datasources outer joined to CustTableMaster

Test data in CustTableMaster

Notice that:

First row Custaccount1 points to US-001,Custaccount2 points to US-002,Custaccount3 points to US-003

Second row Custaccount1 points to US-004,Custaccount2 points to US-005,Custaccount3 points to US-006

Open CustTableMaster Form:

Notice that:

First row CustTable1_AccountNum points to US-001,CustTable2_AccountNum points to US-001 instead of US-002,CustTable3_AccountNum points to US-001 instead of US-003

Second row CustTable1_AccountNum points to US-004,CustTable2_AccountNum points to US-004 instead of US-005,CustTable3_AccountNum points to US-004 instead of US-006

Rename table relation roles

For example first role should be renamed to CustTable_CustAccount_Role1 and all others accordingly:

If UseDefaultRoleNames = Yes default name infering would be ussed. See Role names inferring for more information

In CustTableMaster form Overide init of these DS'es: CustTable1,CustTable2,CustTable3:

public void init()
{
    super();
    this.query().dataSourceName(this.name()).clearLinks();
    this.query().dataSourceName(this.name()).addForeignkeyRelation(identifierStr(CustTable_CustAccount_Role1));
}

Final  CustTableMaster form result

More information with of role names inferring

The following defaulting mechanism can be used for role names without having to fill out the two properties (by leaving
them blank and marking UseDefaultRoleNames to yes):
(1) <related table name> is used as the RelatedTableRole

Be aware, that you should not use UseDefaultRoleNames as it will result in conflicts in between relatedTableRoles of relations.

Hands on example

Put UseDefaultRoleNames = yes for CustAccount1 relation:

Now manually alter CustAccount2 RelatedTable role to CustTable

Compiling table throws error:

Clear CustAccount2 RelatedTable role to and set UseDefaultRoleNames to yes

Compiler throws error about conflicts between CustAccount1 and CustAccount2 roles