Unlocking the Power of Formatted Values in Dataverse

In the world of Dataverse and Dynamics 365, data comes in various forms—whether it’s simple strings, numbers, or more complex types like dates and entity references. While you can easily display and manipulate simple data types directly, certain types of data require more nuanced handling to present them correctly in your applications. This is where formatted values come into play.

Formatted values are essentially read-only string representations of your data that Dataverse generates, taking into account organizational settings, user preferences, and column-specific configurations. These formatted values ensure that your application displays data in a way that makes sense to the end-user, considering factors like time zones, currency symbols, and localized labels.

Accessing Formatted Values

To access these formatted values, you utilize the Entity.FormattedValues collection in your Dataverse data retrieval code. This collection is particularly useful when you want to display data types such as Boolean values, currency, dates, and entity references in a user-friendly format.

Let’s dive into an example to see how this works in practice.

Example: Retrieving Formatted Values from an Account Entity

Imagine you’re working with account records in your Dataverse environment. You want to retrieve a list of accounts, along with some specific columns, and display them in a formatted way. The columns of interest are:

• primarycontactid (Lookup to the primary contact)
• createdon (Date and time of record creation)
• revenue (Currency value)
• statecode (Status of the account)

Here’s how you can retrieve and display these values using C#:

static void FormattedValuesExample(IOrganizationService service)
{
    List<string> columns = new() {
        "name",
        "primarycontactid",
        "createdon",
        "revenue",
        "statecode"
    };

    QueryExpression query = new("account")
    {
        ColumnSet = new ColumnSet(columns.ToArray()),
        TopCount = 3
    };

    EntityCollection accounts = service.RetrieveMultiple(query);

    accounts.Entities.ToList().ForEach(x =>
    {
        string name = (string)x.Attributes["name"];
        string primarycontactid = x.Contains("primarycontactid") ? 
           x.FormattedValues["primarycontactid"] : 
           string.Empty;
        string createdon = x.FormattedValues["createdon"];
        string revenue = x.Contains("revenue") ? 
           x.FormattedValues["revenue"] : 
           string.Empty;
        string statecode = x.FormattedValues["statecode"];

        Console.WriteLine(@$"
name: {name}
    primary contact: {primarycontactid}
    created on: {createdon}
    revenue: {revenue}
    status: {statecode}"
        );
    });
}

Breakdown of the Code:

• Entity.Attributes: This collection holds the raw data values of the attributes.
• Entity.FormattedValues: This collection gives you the formatted string values for specific data types like dates, currency, and lookups.

In this example:

• primarycontactid: The formatted value shows the name of the contact rather than just the raw ID.
• createdon: Displays the date and time in the format that considers the user’s time zone and organizational settings.
• revenue: Presents the currency value with appropriate formatting, including currency symbols and decimal places.
• statecode: Displays the localized label for the account’s status, such as “Active” or “Inactive.”

Sample Output

Running the code would give you output similar to this:

name: A Datum (sample)
  primary contact: Rene Valdes (sample)
  created on: 2/28/2020 11:04 AM
  revenue: $10,000.00
  status: Active

name: City Power & Light (sample)
  primary contact: Scott Konersmann (sample)
  created on: 2/28/2024 11:04 AM
  revenue: $100,000.00
  status: Active

name: Contoso Pharmaceuticals (sample)
  primary contact: Robert Lyon (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $60,000.00
  status: Active

Why Use Formatted Values?

Formatted values provide a more human-readable representation of your data. This is particularly important in environments where data is consumed by non-technical users or displayed in user-facing applications. It ensures that the information is contextually accurate and adheres to regional and organizational settings.

For instance, dates will automatically be adjusted for time zones, currency amounts will reflect the appropriate symbols and decimal precision, and lookups will show meaningful names rather than just IDs.

Leveraging formatted values in Dataverse is crucial for creating applications that not only function correctly but also present data in a way that is meaningful and accessible to users. By using the Entity.FormattedValues collection, you can ensure that your applications respect user preferences and organizational settings, leading to a better overall user experience.

Whether you are displaying currency, dates, or even the names of related entities, formatted values help bridge the gap between raw data and user-friendly information.