Retrieve Dynamics Optionset and Entity Reference data for use in Sitecore Forms

This article is going to look at how to create a custom dropdown lists, that have been populated with data directly from dynamics. The dropdown can then be added to any Sitecore Form, thus providing the user options and more importantly source values, that exactly match that which is expected when saving data to the Dynamics platform.

---

Data in Dynamics

When sending data to Dynamics, its important that the types and values that you send match that which the platform is expecting. With Microsoft Dynamics, as well as your standard ints, strings, bools and dates; you also might need to send references to other entities and/or one or more selections from a set of options.

Optionsets

An optionset in Dynamics is a predefined set of options that a given field is allowed to take. Under the hood, an optionset value is given an integer value, which is how the data is stored for a property.

Example:

• red [100000001]

• blue [100000002]

• green [100000003]

When setting an optionset property on an entity in Dynamics, you need to pass the int value. Or if setting the value in code, you pass an int value into the constructor of the object:

new OptionSetValue(100000001)

Alternatively, if you are setting multiple values, you might create a collection:

new OptionSetValueCollection {new OptionSetValue(100000001),new OptionSetValue(1000000002)}

EntityReferences

Microsoft Dynamics is essentially comprised of a various different entities that refer to each other, much the same as related SQL tables. An entity reference property is a pointer to a record in another table.

When setting an entity reference property in Dynamics, you need to pass the logical name (i.e. the type of entity) and also the Guid that uniquely identifies the record within that table. You can set the property in code in the following way:

new EntityReference("contact", ContactId); //where ContactId is a Guid

---

Calling Dynamics

Optionsets

Dynamics offers a number of API endpoints, that we can call to get data directly out of the platform.

For ‘optionsets’ you can use the following call:

/api/data/{ApiVersion}/EntityDefinitions(LogicalName='{Entity}')/Attributes(LogicalName='{attribute}')/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet

The response can then be parsed into a format to pass back to the dropdown:

public List> GetOptionSetValues(string entity, string attribute)
{
string endpoint = $"{_dynamicsBaseUrl}/api/data/{_dynamicsApiVersion}/EntityDefinitions(LogicalName='{entity}')/Attributes(LogicalName='{attribute}')/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet";
string token = GetAccessToken(_tenantId, _clientId, _clientSecret, _dynamicsBaseUrl);

using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = client.GetAsync(endpoint).Result;
response.EnsureSuccessStatusCode();

var json = response.Content.ReadAsStringAsync().Result;
var document = JsonDocument.Parse(json);

var options = new List>();

foreach (var option in document.RootElement
.GetProperty("OptionSet")
.GetProperty("Options")
.EnumerateArray())
{
var value = option.GetProperty("Value").GetInt32();
var label = option
.GetProperty("Label")
.GetProperty("UserLocalizedLabel")
.GetProperty("Label")
.GetString();

options.Add(new KeyValuePair(value, label));
}

return options;
}
}

EntityReference

In a similar manner, you can also get the required data about an entity set that you wish to make a reference too.

To do this, you first need to find the metadata for the entity you wish to examine. You do this by making a call to (where Entity refers to te LogicalName of the table you wish to examine):

/api/data/v9.2/EntityDefinitions?$select=LogicalName,EntitySetName&$filter=LogicalName eq '{Entity}'

From the above call, you can extract the EntitySetName of the table. The example below shows the response, when querying the entity mshied_program.

Example:

{
"LogicalName": "mshied_program",
"EntitySetName": "mshied_programs"
}

You can then use the EntitySetName to do a follow up call as below.

/api/data/v9.2/{EntitySetName}?$select=mshied_code,mshied_name

Note: In the example above, we are selecting mshied_code and also mshied_name. These might be different depending on the entity you are examining. In this case, the mshied_code represents the Guid identifier and mshied_name the name of the record.

---

Entity Access Helper

You can find an example wrapper, that gets an access token and then retrieves data using the API endpoints above in DynamicsEntityAccess class in the SitecoreToDynamics repository here.

---

This article looked at how to pull the relevant information out of Dynamics. In the next article, we will look at how we can push that data into a dynamic dropdown list, that can be added to any Sitecore Form.