Microsoft Dynamics AX Support

This blog contains posts by the Microsoft Dynamics AX Support teams Worldwide

Surrogate foreign keys in AIF

Surrogate foreign keys in AIF

Rate This
  • Comments 6

Although the use of "natural keys" in place of surrogate foreign keys in AIF is a documented design change in AX 2012, it seems there are still some questions around this functionality.

Per the documentation (

The document services framework "..replaces a surrogate foreign key (SFK) with the natural key for a specific table


A simple example is the ContactForParty field in the DirContactPersonsService. This field in the ContactPerson table has an EDT of DirPartyRecId, but an error will occur if you attempt something like this...

AxdEntity_ContactPerson contactPerson = new AxdEntity_ContactPerson();

contactPerson.ContactForParty = dirpartyrecId;


This won't work with a recId value, because the service will determine that ContactForParty is a surrogate foreign key and will look for the natural (replacement) key on DirPartyTable. The replacement key on DirPartyTable is PartyNumberIdx, so what we need to pass in via the service is the PartyNumber.

The concept seems pretty simple in this example, but it can become more complex when the replacement key is itself a surrogate foreign key. The WorkerSalesResponsible field in SalesTable is one such example.

  • WorkerSalesResponsible is a SFK referring to HcmWorker.
  • The HcmWorker table has a replacement key of Person (HcmWorker_AK1)
  • Person is itself a SFK referring to DirPerson.
  • DirPerson extends DirPartyTable, and the replacement key on DirPartyTable is again, PartyNumberIdx.
  • So we finally have the natural key we need. To import data into the WorkerSalesResponsible field via the SalesSalesOrderService we need to use a valid PartyNumber.


Leave a Comment
  • Please add 8 and 3 and type the answer here:
  • Post
  • So on the code example, how will you pass the PartyNumber value, is there a property to set like:

    AxdEntity_ContactPerson contactPerson = new AxdEntity_ContactPerson();

    contactPerson.PartyNumber = partyNumber ;

  • Actually, you just pass the partyNumber directly in ContactForParty, like this...

    AxdEntity_ContactPerson contactPerson = new AxdEntity_ContactPerson();

    contactPerson.ContactForParty = partyNumber;

    The service will handle the relations for you.

  • So is this working also when you use the excel add-in or when you directly use the Ax classes in X++ code? I guess I have to try it.

  • This applies to the document services framework, so if you are using AIF document data sources in the Excel Add-in then yes, this concept would apply in that case.

  • Hi Laura,

    First i want said thank you for your post and also,i would like to apologize for my English. Because i'm French.

    Actually i have a troubleshooting with the replacement of the SFK by a natural key by using document service Framework.

    The use case is the following :

    I try to update the ledger general service by adding new field in the ledgerJournalTable and  query axdLedgerGeneralJournal. One of the field that i add is the SFK on RecId of the table OMOperatingUnit. The replacement Key of Table OMOperatingUnit is OMOperatingUnitNumber. When i update the Ledger General Service document, in the data contract class ledgeGeneralJournal_LedgerJournalTable the input parameter of the parm method of my field "omoperatingUnit" doesn't replace by the naturalkey OMOperatingUnitNumber. Instead i have the OMOperatingUnitRefRecId.

    Can you help me ?

    Best regards.

  • The answer to Sanogo's question was to use the expandSurrogateForeignKeys method on the Axd class:

    public boolean expandSurrogateForeignKeys()


       return true;


Page 1 of 1 (6 items)