Common Error in Dynamics 365: Using Logical Name Instead of Schema Name for Lookup in API Calls

 Introduction

In Dynamics 365, developers often interact with entity records through the Web API. One frequent issue arises when updating lookup fields using incorrect field names. This article examines a specific case where a developer encountered an error while trying to update a lookup field due to the misuse of the logical name instead of the schema name.

Problem Statement

A Dynamics 365 developer attempted to update a lookup field (tri_CancelationReasonId) in the tri_programsession entity using the following JavaScript function:

function updateRecord(sessionId, reasonId) {

            sessionId = sessionId.replace(/[\{\}]/g, ''); // Clean GUID to remove curly braces if present

            reasonId = reasonId.replace(/[\{\}]/g, '');  // Clean GUID to remove curly braces if present

            const entity = {

                "tri_action": "Cancel",

                "tri_cancelationreasonid@odata.bind": `/tri_cancellationreasons(${reasonId})`

            };

            Xrm.WebApi.online.updateRecord("tri_programsession", sessionId, entity).then(

                function(response) {

                    console.log("Record updated successfully:", response);

                    closeDialog();

                },

                function(error) {

                    console.error("Error updating record:", error.message);

                }

            );

        }

Upon execution, the following error was encountered:

[storage] Error Messages: 1: Error identified in Payload provided by the user for Entity :'', For more information on this error please follow this help link https://go.microsoft.com/fwlink/?linkid=2195293 ----> InnerException : Microsoft.OData.ODataException: An undeclared property 'tri_cancelationreasonid' which only has property annotations in the payload but no property value was found in the payload. In OData, only declared navigation properties and declared named streams can be represented as properties without values.

Issue Analysis

The root cause of the error is the use of tri_CancelationReasonId in the OData bind operation. In Dynamics 365 API, the property name used in such operations must be the schema name, not the logical name. The schema name is typically the same as the logical name but with a specific case formatting (usually all lower case) and exact matching to the entity metadata definition in Dynamics 365.

Solution

To resolve this issue, ensure that the correct schema name is used in API operations, especially when dealing with lookup fields. Here’s a corrected version of the function:

function updateRecord(sessionId, reasonId) {

            sessionId = sessionId.replace(/[\{\}]/g, ''); // Clean GUID to remove curly braces if present

            reasonId = reasonId.replace(/[\{\}]/g, '');  // Clean GUID to remove curly braces if present

            const entity = {

                "tri_action": "Cancel",

                "tri_CancelationReasonId@odata.bind": `/tri_cancellationreasons(${reasonId})`

            };

            Xrm.WebApi.online.updateRecord("tri_programsession", sessionId, entity).then(

                function(response) {

                    console.log("Record updated successfully:", response);

                    closeDialog();

                },

                function(error) {

                    console.error("Error updating record:", error.message);

                }

            );

        }