How to Use Entity Lists for Power Apps Portals in Dynamics 365

Portals Entity Lists are a great method to display a list of records to your users in Dynamics 365. You can easily and quickly create a Dynamics 365 View, Entity List, and Web Page to present the necessary data for simple needs. You also have options to get quite complex if needed.

Note: Portals in Dynamics 365 are now officially called “Power Pages“. They were previously called “Power Apps Portals”, but are often still referred to as “Dynamics 365 Portals.”

In this blog post I will explain entity lists and highlight some items, features, and hidden realities that are sometimes not clearly identified in existing documentation. I will cover the following:

• What Is a Dynamics 365 Entity?
• Dynamics 365 View
• Multiple Views for One Entity List
• Display Name
• Page Size
• Web Page for Details View
• Web Page for Create
• Filter Conditions
• Search
• Custom JavaScript
• Grid Configuration
• What You Need to Know Right Now

What Is a Dynamics 365 Entity?

In D365 CRM solutions and Portals, an Entity is a container of information about a single object, whether it is a Lead, an Account, a Contact, an Opportunity, an Activity, etc.

Here are the components of the Contact entity as seen in the default solution:

A common dictionary definition for entity is “a thing with distinct and independent existence.” At the beginning of my programming days, the instructors repeatedly stressed that each object had its own properties and methods. Properties and methods, properties and methods, and don’t forget properties and methods. They are what make up an independent object, an item unique from surrounding objects.

When designing a D365 CRM system or a D365 Power Apps Portal website, this philosophy also holds true. We need to clearly identify each entity or object to determine how it looks and behaves in order to create a system that doesn’t stumble upon itself. I encourage clients to ask this vital question when planning or developing D365 entities: “who owns the data?” Go ahead and ask it; you’ll feel better and maybe even a little powerful. What do I mean by this?

Using Accounts and Contacts as my illustration, let’s focus on the Account address. Many times, clients want to place the Account address, physical or billing, on the Contact entity, and that’s fine – on the Contact form, but it doesn’t belong on the Contact entity. When considering the actual data model design, it’s the Account that owns the address, not the Contact. The Contact may work at that address, but it’s not theirs. So, who owns this address? When I drive to that location, I will see the business site, not a person’s house.

Here is how a system can fall down if not designed properly. A D365 User changes the address only on the Contact form, but the Account address is also on the Account form. Another user logs into the system to get the Account address and navigates to the Account record. They are looking at the wrong address! Unless a synchronization process is in place, incorrect data will abound. For this particular scenario, it would be better to display an Account Quick View Form on the Contact form.

So, what do entities and objects, properties and methods have to do with Entity Lists and D365 Power Apps Portals? Understanding these concepts will assist in your Entity List development, and help you to recognize their abilities and limitations.

Dynamics 365 View

A D365 Entity List is simply an extension of a D365 View. A View is an organized list of specified data about one or more entities.

Here is a D365 View Editor:

From this editor, you add and remove columns, change the width of columns, dictate the default sort order of the list, and determine the filtering conditions.

Display of View in D365:

To associate an Entity List to a D365 View, follow these instructions.

1. Navigate to the Portals Area in D365 and select Entity Lists.
2. Select + New.
   It may take a bit before the Entity Name field list populates; this is common with Portal entity records – a word of warning.
3. Select the desired entity “object” for Entity Name field.
4. Next, click + View and a new View section will appear in the Views area.
5. Select the desired D365 View in the Name list.
6. Save.
7. After creating a Web Page and pointing it to the Entity List, navigate to your D365 Portal.

D365 Portal Representation of the D365 View:

Multiple Views for One Entity List

The above View is nice, but how do we handle a situation if multiple Views need to be displayed to the D365 Portal user? First of all, let’s review why we would need to do this. You may have a desire to display all active Contacts like above, but you may also want to display all active Contacts that have been created or modified in the last 90 days, a much smaller list that also identifies CreatedBy, CreatedOn, ModifiedBy, and ModifiedOn, and is sorted by most recent on top.

Here are the steps:

1. In D365, create your View, ensuring you add your filtering criteria, Save, and Publish All Customizations. If you already have your Entity List record open, you will have to click Refresh View in the Views area.
   
2. Click + View and select your new View. Save.
   
3. Navigate to your D365 Portal Web Page and refresh.
4. Now you will see a View selector: Active Contacts and Active Contacts – Created or Modified in Last 90 Days. Select the new view.
   

How to Change the Display Name

Now that we have two views in our Entity List, the naming of the Views may not make sense to the Portal users. Display name mainly comes into play when there are multiple Views added for one Entity List.

Changing that is fairly simple: navigate back to the Entity List and add your values (Contacts; Recent Contacts) to the Display Names. Save.

Multiple Views with better naming for your Portal Users

How to Change Entity List Page Size

Did you notice this above on the main Contact list in Portals?

This is a common paging system for a list of records. We have the ability to change the Page Size for every Entity List.

When it comes to Page Size, paging, and performance, there is a fine balance. You may need to test this and request user feedback, but I feel 50 is a good starting number for Portals. After changing the Page Size from 10 to 50, and without showing the entire first page of results, you can see below that the number of Pages is quite a bit less. Page Size in combination with Filter Results and Search (covered later) gives you the benefit of showing the least amount of records to increase performance and provide the Portal user the functionality to quickly find the records they need.

Web Page for Details View and ID Query String Parameter Name

Many times your company will want Portal users to create and modify data.

In the Entity List record, assign a Web Page – that is already created and pointed to an Entity Form or Web Form – to the Web Page for Details View field. Enter a name for the value of the parameter that will be passed from the Entity List to the Details View Web Page. The default naming for this field is “id.” Save and refresh the Entity List Web Page.

When the Portal user clicks on Abraham’s record on the Entity List Web Page, the Portal will navigate to the Contact – Edit Web Page, sending the Contact ID value as a parameter. The Contact – Edit page will pick up that ID parameter, retrieve the necessary data, and populate the edit form.

The receiving Web Page could be an edit form, a read-only form, or a custom Web Page.

Web Page for Create

If Portal users also need to create a new record of the same type as the Entity List, create the Entity Form or Web Form and the corresponding Web Page, and then enter into the Web Page for Create field.

Entity List Web Page with Create button

Create form Web Page

Interestingly, this has the same effect as the Grid Configuration redirecting to a Web Page with a Create View Action.

Filter Conditions

We have the option to further limit the results of the D365 View; we don’t have a lot of choices, but they pack a powerful dynamic punch. In the Filter Conditions section on the Entity List record, I will discuss the first two: Portal User Attribute and Account Attribute.

I’m a database guy – got my feet wet many years ago with MS Access, dabbled a touch with DB2, spent over a decade with Oracle, explored MySQL, and have been working with SQL Server for quite some time now. I speak SQL. Sometimes I want to write SQL statements to my family, things like:

SELECT *

FROM LivingroomFloor

WHERE stuff IN (‘Your Shoes’, ‘Your Toys’, ‘Your Clothes’);

I’m sure they would throw me an exception!

To instruct on how to think about Entity List Filter Conditions, I will speak SQL.

No Filter Conditions

When no Filter Conditions are entered, you are basically requesting this:

SELECT *

FROM contacts

WHERE conditions = D365 View filter conditions;

You are not adding onto the D365 View filter conditions, and you will receive the same results from the Portal as you would in D365.

Portal User Attribute

Here are the Portal User Attribute options for the Contact Entity List.

If all Contact/User fields were exposed on the Contact form, you would see these fields above. We will select Parent Contact as the filter condition for the Contact Entity List.

And here is the vital understanding for Entity List Filter Conditions: filtering the Entity List is filtering by lookup fields on the Entity form with either a Contact/User or Account value. For this example, we are filtering by Contact ID.

In other words, you are requesting this:

SELECT *

FROM contacts

WHERE ParentCustomerID = PortalUser.ContactID

AND conditions = D365 View filter conditions;

As you know, a Customer field – in this case Parent Customer – is either an Account or Contact, so this statement is saying, “Give me all Contacts where the Parent Customer (Parent Contact) lookup field is equal to the Portal User that is logged in.”

I’m logged in as me, Gary Harrison, and I happen to be the Parent Customer, or Parent Contact, to several records, one of them being Amie Gonzales.

Results of ParentContactID Filter Condition

Account Attribute

The same concept and process applies to the Account Attribute, but it refers to the Account field.

Here are the Account Attribute options for the Contact Entity List.

Select Company Name (Parent Customer ID) for the Account Attribute on the Contact Entity List record.

Fabrikam Robotics is the Company Name on my record.

Here, we are requesting this:

SELECT *

FROM contacts

WHERE ParentCustomerID (AccountID) = PortalUser.ParentCustomerID (AccountID)

AND conditions = D365 View filter conditions;

This statement is saying, “Give me all Contacts where the Company Name lookup is equal to the Company Name lookup for the Portal User that is logged in.”

Results of ParentCustomerID Filter Condition

If you are excited about this capability and want to filter by more than just Contact, User, and Account, read this blog by ReadyXRM.

It’s also possible to filter one Portal Entity List by a parameter from another Portal Entity List.

Search

Entity lists provide a great search feature that allows a Portal User to search on records – across columns of data. It can quickly narrow a list of 50,000 records to 1,000; it is very similar to the quick find of Dynamics 365 CRM views.

Contact list before search is enabled:

To enable the search for your Dynamics 365 Portal list, log into your Dynamics 365 and navigate to your desired Entity List and scroll down to the Search section.

Check Enabled, enter appropriate Placeholder Text and helpful Tooltip Text if needed.

Contact list after search is enabled:

Placeholder Text

Tooltip Text:

Placeholder Text (When you leave it blank on the Entity List record):

You can search by Name:

You can search by email address:

When searching, don’t forget to use the * (asterisk) as it helps with your results.

No results when searching by a partial Company Name:

Results when searching by Company Name with the asterisk:

You can search by phone number:

One item of particular importance is that we cannot search by parent fields. For example, in the image below, we received no results when searching on the Contact’s Account city.

You can quickly identify these columns, as the column headers are not links.

Custom JavaScript

As Portal developers, we have the ability to extend Entity Lists through JavaScript. In Portals in Dynamics 365 | CSS, we discovered how we can change the look and feel of the Entity List, but what are some things we can do with JavaScript?

You can add a conditional CSS rendering (Nishant Rana) based on certain values. Here is a basic template structure for manipulating Entity Lists.

With the help of an AJAX Web Template call, you can do quite a few things like display the number of related records (Activities) for each Contact or retrieve other Dynamics 365 data. Always consider the performance impact.

Today, we are going to point the Portal User to a Google Map from the combination of city and state/province values. To get started, fire up the Developer Tools for the Portal page that contains the Entity List. Right click the first city value (Seattle) and choose Inspect Element.

We need to grab the data-attribute of both the city and state.

<td data-type="System.String" data-attribute="a_dc9b80f8c78146d89fd6a4b610836875.address1_city" data-value="Seattle" tabindex="0" data-th="Address 1: City (Company Name)" aria-label="Address1: City (Company Name) Seattle">Seattle

 

<td data-type="System.String" data-attribute="a_dc9b80f8c78146d89fd6a4b610836875.address1_city" data-value="WA" tabindex="0" data-th="Address 1: State/Province (Company Name)" aria-label="Address1: State/Province (Company Name) Seattle">WA

 

Back in Dynamics 365, navigate to the Entity List record and add the following JS code to the Custom JavaScript section. Change the data-attribute values accordingly.

The code is finding the city element (<td>), and from there finding the parent element (<tr>) so it can find all needed elements. It then grabs the city and state/province values and plugs them into a Google Map link.

$(document).read(function(){
  $(".entitylist.entity-grid").on("loaded", function () {
    $(this).children(".view-grid").find("td[data-attribute='a_dc9b80f8c78146d89fd6a4b610836875.address1_city']").parent().each(function (i, e) {
      var tr = $(this);
      var city = $(this).find("td[data-attribute='a_dc9b80f8c78146d89fd6a4b610836875.address1_city']");
      var state = $(this).find("td[data-attribute='a_dc9b80f8c78146d89fd6a4b610836875.address1_stateorprovince']");
      var city_state = city.data("value") + " " + state.data("value");
      console.log("City State = " + city_state);
      city.html("");
      city.html("<a href='https://www.google.com/maps/place/" + city_state + "'>" + city.data("value") + "</a>");
    });
  });
});

Now the city column is a link:

That link points to a Google Map:

You could make this much more complex, but I wanted to show some possibilities for illustration purposes.

Grid Configuration

Grid Configuration is a set of tools that adds functionality to your Entity List.

View of Grid Configuration on the Entity List:

In many ways, it is a replication of the Dynamics 365 navigation for a record.

View Actions

Create

With Create, you can point to an Entity Form, Web Page, or a URL. Here’s how:

1. Create your Entity Form that associates to the desired entity type. Here is a Contact Entity Form pointing to Contact Entity and Contact – Short Form.
2. Back on the Entity List in the Grid Configuration, click ‘Create’ and the below information and Save.
   Target Type = Entity Form
   Entity Form = Newly created Entity Form
   Button Label = Whatever you choose
   
3. Refresh the Portal page and view the “New Contact” button.
   

Because we pointed the Entity List to an Entity Form, a modal form appears when the New Contact button is clicked.

If we want to point the Portal User to a separate web page, we would need to create a Web Page that points to the Entity Form. Then we change the Entity List Grid Configuration Target Type to Web Page and select the correct Web Page.

If we want to point the Portal User to an URL on the Portal website, we can do that as well.

Download

With Download, you can allow the Portal User to download the Entity List results into an Excel spreadsheet.

Navigate to the Grid Configuration section on the Entity List form and click ‘+Download’.

A new Download section will appear. Enter a label.

Save.

Refresh the Dynamics 365 Portal Entity List page and view the new Download Results button.

File downloaded to local computer:

Download results:

Item Actions

I will not cover all options for Item Actions but wanted to cover a few so you get an idea of how they operate. As the name implies, it is an action taken against the selected record in Dynamics 365.

Details Item Actions

When you want Portal Users to view detailed information on a record but prevent them from making any changes, you can use the Details Item Actions.

Create a new Details Item Action and fill in the necessary data:

In order for this to work correctly, the Entity Form Mode needs to be set to Read-Only and Record Source Type to Query String with “id” as the parameter name.

After refreshing the Entity List Portal page, you will see a drop-down option for each row.

Upon clicking the Details action, a portal read-only modal will appear.

Edit

Edit is very similar to Details but would normally be pointed to an Entity Form that is set to Edit.

Workflow

From the Portal Entity List web page, Portal Users have the ability to fire a Dynamics 365 workflow. This action could be used to send an email notification to a Dynamics 365 User or request that record to move to the next stage in some processing.

Override Column Attributes

The last topic to cover for Grid Configuration is the mechanism to override the default column names. Many times, the column names just don’t make sense to Portal Users for your organization. For example, a particular Entity List is only listing schools, so “Company” doesn’t cut it. We can change that.

Default Entity List column names:

Navigate to the Dynamics 365 Entity List record and scroll down to the Override Column Attributes section under the Grid Configuration section. Click ‘+Column’, find the desired Attribute, and provide a different column name. Click Save.

Entity List with changed column names:

What You Need to Know Right Now

We have covered a lot of ground, but here is what you need to know right now about Entity Lists:

• Entity List is tied to only one D365 entity
  • You can display parent fields in the Entity List
• Multiple views can be displayed for one Entity List
• All Views for Entity List are visible and available for each logged-in User with appropriate permissions unless dynamically altered
  • You cannot hide one of the Views for a certain set of Portal Users
• All Views for Entity List point to the same Edit page, the same Create Page, and have the same grid configurations
• All Views for Entity List share the same Filter Conditions
  • Meaning you cannot direct a certain set of Portal Users to one page and another set of Portal Users to a different page with the same link
• If you Enable Entity Permissions on the Entity List, Portal Users must be added to that Entity’s Entity Permissions
  • If not, no results will display
• Portal Users cannot sort on parent fields

Thank your visiting this blog post. You might also be interested in our posts about Portals Entity Forms, Portals Web Pages, or Portals licensing.

If you have any questions about Portals in Dynamics 365, please reach out to us.