Fancy swapping a GUID for an entire record with just 1 short line of code? J We can do precisely that with the entities object

If you’ve navigated around a portal before, maybe drilling through from an entity list to an entity form – you’ll likely have noticed the URL contains a unique identifier, the GUID of the record.

The goal of this tutorial:

• Use liquid to get the GUID from the URL
• Retrieve the full record using that GUID
• Learn how to output (‘print’) details from that record for any data type / field type available in Dataverse

So good news from the start… there’s no lengthy code involved.

• Getting the URL requires a single line of code
• Retrieving the full record requires a single line of code
• Outputting / printing a field is nice and easy too, really just a matter of dot notation and knowing how to handle complex field types like lookups and option sets – which we’ll cover J

Let’s get started!…

So in this example, we’ll retrieve the details of an album

When writing liquid, we’ll need the ‘logical’ names for the entities and fields we’re dealing with. You can get these from within https://make.powerapps.com … If you’re alrady familiar with how to get these, skip ahead to the coding bit

Get the logical name of the table (entity) you need to retrieve

To get the logical name for a table (previously known as an entity), go to Data > Tables and copy the value from the Name column. Ion my example, the table is called Artist and the logical name is musdyn_artist

Get the logical name of the column (field) you need to retrieve

To get the local name for a field, click on the Table to drill into the details

You should then see a list of all the columns this table contains

In addition to the Display Name (the naming used in the user interface in forms, views, etc.), you’ll see the logical name in the Name field to the right

For example, the Description field on my Artist entity has a logical name of musdyn_description

The coding bit: Use the entities object to retrieve the artist record matching the GUID passed in the id parameter in the URL

There are 3 ‘ingredients’ needed for this:

• The logical name of the entity
• The GUID of the record you wish to retrieve
• To actually do anything with the data we retrieve, we need to store the result in a variable – in other words assign it to a variable

So, to retrieve an artist record and store the record in a variable called artist, the liquid code would be:

{% assign artist = entities['musdyn_artist'][request.params.id] %}

In this example of course, we’re taking the GUID passed in the URL but we could equally hard-code a GUID e.g. ‘ae861f11-3a35-eb11-a813-0022481a4ca6’ or pass it the result of another query or variable

We’ve now retrieved the record stored in a variable called artist but there’s no visible result as yet. We’ll see in the next section how we access the fields from that record.

You’re likely wondering where do we get a GUID from in the first place? On real world project, this might be from an entity list on which you’ve configured an action to point to a Web Page to view details. In that case, the entity list automatically passes the GUID in the URL. For the sake of this tutorial, we can cheat and just copy one from your model driven app / Dynamics:

Open a record for the required entity

Copy the id part of the URL, like so (note – it’ll usually come after the name of the entity):

The format of the URL is as follows:

https://whateveryourportaliscalled.powerappsportals.com/partial-url/?id= GUID

In my example, that’s:

https://songify3.powerappsportals.com/artist-liquid-tutorial/?id=ae861f11-3a35-eb11-a813-0022481a4ca6

Output fields from the record using liquid and dot notation

We can access fields using the name of the variable and the logical name of the field, like so:

{{ artist.musdyn_name }}

The double curly braces are what tell liquid we want it to interpret and output something rather than literally type artist.musdyn_name on the page

Name was nice and straightforward because it’s a text field – no transformation, translation or complexity involved. For Lookup fields and Choice fields, we need to go one step further and specify what to output…

Outputting Choice fields (previously known as Option Sets)

For Choice fields (and statuses and status reasons for that matter), we need to specify whether it’s the numeric value we’re interested in, or the label

The numeric value tends to be more useful for logic like if statements as it’s less likely to change.

For that we’d use

{{ artist.statuscode.value }}

For outputting on web pages, the label is more suitable – a user likely understands ‘Completed Tasks’ better than ‘Tasks in Status 1’

For that, we’d use

{{ artist.statuscode.label }}

Outputting Lookup fields

In a very similar vein to Choice fields, we can choose whether we want to use the id of the record in the lookup field, or the name.

The id (GUID) tends to be more useful for URLs (much like in the example we’re building here!) and in logic like if statements as it’s less likely to change than the name.

For that we’d use

{{ artist.createdby.id }}

For outputting on web pages, the name is more suitable – a user likely understands ‘Completed Tasks’ better than ‘Tasks in Status 1’

For that, we’d use

{{ artist.createdby.name }}

Note – liquid respects entity permissions so users will need appropriate entity permissions to Read records on the lookup entity

Outputting Number fields

Technically, we’re not required to do anything in particular to output numeric fields like Whole Decimal Number, Currency, etc. However, you may find that liquid unexpectedly outputs 5 decimal places for your decimal number field rather than the 2 you see in your model driven app / Dynamics.

To round my currency field to 2 decimal places, I’d use:

{{ artist.musdyn_revenue | round: 2 }}

We can manipulate / shape the output using filters. Here’s some further detail on the numeric filters available in Liquid

Here’s some further detail on the numeric filters available in Liquid

Outputting Date fields

Again, we’re not required to do anything in particular to output Date Only or Date/Time fields. However, you likely want control over the format. Also, you may find that even for Date Only fields, a timestamp is also included – it’ll just always be 12 midnight.

As you may have guessed, it’s liquid filters to the rescue again. To output the First Album Release On date in dd/MM/yy format, I’d need to use:

{{ artist.musdyn_firstalbumreleasedate | date: 'MMMM dd, yyyy' }}

Here’s some further detail on the date filters available in Liquid

Further reading:

Error handling / graceful degradation… What IF there’s no GUID?

Navigating to the URL, I can see that all is good and my liquid returns the values I expect… except if someone were to navigate to the URL without providing a GUID. In that case, they’d get a rather nasty looking error:

Liquid error: Value cannot be null. Parameter name: key

Let’s plan around that and wrap our code in an if statement that checks for the presence of the id parameter…

{% if request.params.id %}

{% assign artist = entities['musdyn_artist'][request.params.id] %}

{{ artist.musdyn_name }}

{% endif %}

We could take that further with an else clause e.g.

{% if request.params.id %}

{% assign artist = entities['musdyn_artist'][request.params.id] %}

{{ artist.musdyn_name }}

{% else %}

Sorry, I wasn't sure which artist you were looking for - that or there's been a glitch in the matrix...

{% endif %}

And that’s it! So far there’s nothing we couldn’t have achieved more easily using portal configuration options like entity forms, web forms, entity lists. All we’ve done so fair is output some fields as text. The real power of this is being able to control the layout and mash up however you like. In my case, outputting an album detail page. That same code could be used to populate an audio player, create a record-centric dashboard, produce a slide, the world’s your oyster!

Well done for making it this far. I hope you found that as exciting as I did the first time!

You’ll no doubt be wondering:

• What if I don’t have the GUID? Maybe I just want the most recent record or the most popular record, the record with the highest value?
• How do I retrieve multiple records
• How do I retrieve child records e.g. all the tracks for a given artist or all the contacts for a given account

We’ll cover all that in the next post as we explore how to use Fetch XML with Liquid

Note – this post is part of a series I put together on the 3 4 5 6 Liquid skills to rule them all to support my presentation at the ever excellent Scottish Summit. Grab your free ticket now and I’ll see you there!