Dataverse Web API Tip #10: Formatted Values

,

Ever notice that the values a Dataverse Web API call returns aren’t always identical to what a Microsoft Power Apps/Dynamics user would see when viewing the same data in the UI?

For example:

  • In the UI, a Boolean is displayed using configurable “friendly” text like “Allow” or “Disallow”, “Yes” or “No”, “OK” or “Cancel”, etc.—but Web API responses always return Bool values as true or false.
  • Similarly, choices are returned as numeric codes by the Web API while the UI shows their corresponding textual value.
  • For lookup columns, the Web API returns the GUID of the related record while the UI shows its display name.
  • Dates and numbers are displayed nicely formatted in the UI but returned by the API in raw technical form.

Did you know that, thanks to an OData concept known as annotations, you can request that these display values (a.k.a. formatted values) accompany Web API results?

To do so, simply ask for OData.Community.Display.V1.FormattedValue annotations by setting the Prefer header to odata.include-annotations="OData.Community.Display.V1.FormattedValue":

GET {{webApiUrl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d)
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue" 
(include the "always include" headers)

In the response, formatted value annotations will be included, paired with the appropriate raw values. These accompanying annotations have the same name as their corresponding raw value columns, just with a suffix of @OData.Community.Display.V1.FormattedValue added. So, birtdate‘s formatted value annotation is returned in JSON property birthdate@OData.Community.Display.V1.FormattedValue.

{
  "@odata.context": "{{webApiUrl}}$metadata#contacts/$entity",
  "@odata.etag": "W/\"842270\"",
  "birthdate@OData.Community.Display.V1.FormattedValue": "5/16/1954",
  "birthdate": "1954-05-16",
  "merged@OData.Community.Display.V1.FormattedValue": "No",
  "merged": false,
  "modifiedon@OData.Community.Display.V1.FormattedValue": "4/8/2021 3:55 PM",
  "modifiedon": "2021-04-08T19:55:06Z",
  "_ownerid_value@OData.Community.Display.V1.FormattedValue": "Joe Smith",
  "_ownerid_value": "05537ae2-0596-eb11-b1ac-00063b3238fa",
  "statecode@OData.Community.Display.V1.FormattedValue": "Active",
  "statecode": 0,
  …
}

Of particular note, the formatted values for numbers, dates/times and currency are rendered according to the personalization settings of the user making the Web API call. Notice above how modifiedon‘s time component is 19:55:06 while its formatted value shows it as 3:55 PM. This formatting reflects the Web API user’s timezone preference, in this case of, Eastern Time (GMT -05:00), and that user’s time format styling, in this case of “hh:mm (AM/PM)”.

Note

Don’t forget to include the “always include” headers with every request sent to the Web API.

Reference

Include formatted values (in Query data using the Web API)

Leave a Reply

Your email address will not be published. Required fields are marked *