Understanding Logical Name and Schema Name in Dynamics 365 and Microsoft Dataverse

 

Understanding Logical Name and Schema Name in Dynamics 365 and Microsoft Dataverse

When developing solutions in Dynamics 365 or the Microsoft Dataverse, one might encounter terms like "logical name" and "schema name". Both of these terms refer to the naming of entities and fields within the platform, but they have distinct purposes and conventions. Understanding the difference between the two can save developers considerable time and prevent potential errors.

Definitions:

1. Logical Name:

   • Convention: Always lowercase.
   • Usage: Predominantly in the backend, especially when working with the Web API, FetchXML, or server-side code.
   • Examples: account, contact, hs_wordtemplate, hs_documenttype.

2. Schema Name:

   • Convention: PascalCase (also known as upper camel case).
   • Usage: In the front end, especially in client-side scripting, form customizations, and certain Web API operations.
   • Examples: Account, Contact, hs_WordTemplate, hs_DocumentType.

Practical Application:

Let's consider a real-world example to illustrate the difference:

In a function designed to create a new record in Dynamics 365 using the Web API, a developer might structure their POST request like this:

javascript
async function createWordDocumentRecord()
{
    var clientUrl = parent.Xrm.Page.context.getClientUrl();
    var requestUrl = `${clientUrl}/api/data/v9.0/hs_worddocuments`;
    
    var formData = {
        "hs_WordTemplate@odata.bind": `/hs_wordtemplates(${document.getElementById("template").value})`,
        "hs_DocumentType@odata.bind": `/hs_documenttypes(${document.getElementById("documentType").value})`,
        "hs_sourcerecordname": document.getElementById("sourceRecordName").value,
        "hs_name": document.getElementById("sourceRecordName").value,
        "hs_note": document.getElementById("note").value
    };
    
    // ... (rest of the function)
}

In the above code:

• The use of hs_wordtemplates in the @odata.bind property is derived from the logical name of the entity. However, the term before @odata.bind, hs_WordTemplate, is the schema name of the lookup field on the hs_worddocuments entity.
• Meanwhile, fields like hs_sourcerecordname, hs_name, and hs_note are using the logical names directly.

Why Does This Matter?

Understanding the difference between logical names and schema names is crucial for several reasons:

• Correct API Calls: Using the wrong naming convention can result in 400 Bad Request errors, as the system won't recognize the provided names.
• Client vs. Server Code: When scripting on the client side, developers often have to refer to fields by their schema names, especially when dealing with form elements and certain relationship operations in the Web API.
• Efficiency: Recognizing the difference can save developers considerable troubleshooting time.

In the given example, the developer cleverly utilized the schema name with the @odata.bind operation to establish a relationship between records. Such nuanced usage is a testament to the depth and flexibility of the Dynamics 365 and Microsoft Dataverse platform, but it also underscores the importance of understanding these naming conventions.

Conclusion:

Whether you're a seasoned developer or just starting out with Dynamics 365 and the Microsoft Dataverse, understanding the difference between logical names and schema names is paramount. As you delve deeper into the platform, this knowledge will serve as a foundational pillar, ensuring your solutions are both efficient and error-free.