Skip to main content

Notifications

How to Set and Get Lookup Fields in Dynamics 365 JavaScript

Introduction

Lookup fields in Dynamics 365 play a critical role in linking records across tables, allowing you to establish relationships between entities. However, they can be tricky to manage due to their unique structure, containing entity type, ID, and a formatted value. The xrm-ex library simplifies handling lookup fields by providing intuitive methods to get and set these values. This guide will help you understand lookup fields, how to use xrm-ex to work with them, and the versatility xrm-ex offers for more advanced scenarios.

Prerequisites

Understanding Lookup Fields

Lookup fields reference other records by storing:

  • id: The unique identifier (GUID) of the linked record.
  • entityType: The name of the entity (e.g., “account” or “contact”) that the lookup points to.
  • name: The display name or label shown in the UI, like “Contoso Ltd.” for an account.

In xrm-ex, you can easily retrieve and manipulate these properties through its Value property or dedicated methods.

Retrieving Lookup Field Properties

With xrm-ex, you can access the three main components of a lookup field:

  1. ID: The GUID of the related record.
  2. Entity Type: The logical name of the related entity (e.g., "account").
  3. Formatted Value: The display label of the record in the UI.

Here’s an example:

var lookupId = fields.Customer.Id;  // Retrieves the ID (GUID) of the lookup
var lookupEntityType = fields.Customer.EntityType;  // Retrieves the entity type, e.g., "account"
var lookupFormattedValue = fields.Customer.FormattedValue;  // Retrieves the formatted (display) value

This approach allows you to use each component of a lookup field independently, depending on your needs.

Setting Lookup Field Values

Using setLookupValue

xrm-ex offers the setLookupValue method, which simplifies assigning values to lookup fields. The method accepts the entity type, ID, formatted value, and an optional append parameter (useful for multi-value lookups).

Example of Setting a Single Lookup Field

fields.Customer.setLookupValue("account", "cfaeb904-fc99-4d48-b7a1-a13fdd6bfea1", "Contoso");

In this example:

  • "account" specifies the entity type.
  • "cfaeb904-fc99-4d48-b7a1-a13fdd6bfea1" is the record’s ID (GUID).
  • "Contoso" is the formatted display name.

Handling Multi-Value Lookups with append

For lookups that allow multiple values, such as the “To” field in an email, you can set the append parameter to true:

fields.To.setLookupValue("contact", "47f33b76-4fd2-40de-9c0e-23fa0b928ebb", "John Doe", true);

When append is true, the new value will be added to the existing list of values rather than replacing it.

Clearing Lookup Fields

You can clear a lookup field’s value by setting it to null, which removes the linked record from the field:

fields.Customer.Value = null;  // Clears the lookup field

This feature is useful when you need to reset or remove the association with the linked record.

Setting Lookup Fields from Retrieved Data

In scenarios where you need to set a lookup based on data retrieved from other records, xrm-ex provides a streamlined method with setLookupFromRetrieve. This method is particularly useful in workflows where lookups are set dynamically from Web API data.

Example with a Single Record Retrieve

Imagine you want to link a contact’s parent account to another record. Here’s how you’d do it with setLookupFromRetrieve:

var contact = await fields.Contact.retrieve("?$select=_parentcustomerid_value");
fields.Account.setLookupFromRetrieve("_parentcustomerid_value", contact);

In this example:

  • fields.Contact.retrieve(...) fetches the contact’s parent account.
  • setLookupFromRetrieve sets the account lookup field with the retrieved value.

Example with retrieveMultipleRecords

You may want to fetch multiple records and set the lookup based on a specific condition. Here’s how:

var result = await Xrm.WebApi.retrieveMultipleRecords("contact", "?$select=_parentcustomerid_value&$filter=prioritycode eq 1&orderby=createdon desc&$top=1");
if (result.entities.length > 0) {
    fields.Account.setLookupFromRetrieve("_parentcustomerid_value", result.entities[0]);
}

This example retrieves contacts with priority code 1, sorted by creation date. The first record’s account is then used to set the lookup.

Summary of Key Points

  • Accessing Properties: Use .Id, .EntityType, and .FormattedValue to retrieve specific properties of a lookup field.
  • Setting Lookup Values: Use setLookupValue with parameters for entity type, ID, and formatted value.
  • Handling Multi-Value Lookups: Use the append parameter in setLookupValue for lookups that support multiple values.
  • Clearing Lookup Fields: Set the lookup field’s Value to null to remove the association.
  • Setting from Retrieved Data: Use setLookupFromRetrieve with Web API data to dynamically set lookup fields.

Conclusion

By simplifying access to lookup properties and providing versatile methods for setting values, xrm-ex streamlines managing lookup fields in Dynamics 365. For more on handling other field types, check out these guides:


Comments

Liquid error: parsing "/forums/thread/details/?threadid=%27nvOpzp;%20AND%201=1%20OR%20(%3C%27%22%3EiKO))," - Too many )'s.