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 D365 are now officially 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?

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:

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:

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:

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.
    Entity Lists

    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:

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.
    Views Area
  2. Click + View and select your new View. Save.
    Save new view
  3. Navigate to your D365 Portal Web Page and refresh.Refresh D365 Portal Web Page
  4. Now you will see a View selector: Active Contacts and Active Contacts – Created or Modified in Last 90 Days. Select the new view.
    View Selector

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.

Display names

Multiple Views with better naming for your Portal Users

Multiple Views with better naming

How to Change Entity List Page Size

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

Pagination in Contact list

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

Page Size

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.

Improved pagination in Contact list

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.

Web Page for Details View

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.

Web Page for Create

Entity List Web Page with Create button

Entity List Web Page with Create button

Create form Web Page

Create form Web Page

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

Grid Configuration

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.

Entity Lists

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.

Portal User Attribute options

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.

Select Parent Contact

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.

Amie Gonzalez record

Results of ParentContactID Filter Condition

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.

Account Attribute options

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

Select Company Name

Fabrikam Robotics is the Company Name on my record.

Harrison Contact 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

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.

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:

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.

Search section

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

portals

Contact list after search is enabled:

Contact list after search is enabled

Placeholder Text

Placeholder Text

Tooltip Text:

Placeholder Text

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

Placeholder Text

You can search by Name:

Search by name

You can search by email address:

Search by email

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

No results when searching by a partial Company Name:

No results when searching by a partial Company Name:

Results when searching by Company Name with the asterisk:

Results when searching by Company Name with the asterisk

You can search by phone number:

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.

No results by city name

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.

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:

Linked city column

That link points to a Google Map:

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:

View of Grid Configuration on the Entity List

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

Active Contacts

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.Contact Entity 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
    Grid Configuration
  3. Refresh the Portal page and view the “New Contact” button.
    New Contact button

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

Modal form

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’.

Grid Configuration

A new Download section will appear. Enter a label.

Download label

Save.

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

Download Results button

File downloaded to local computer:

File downloaded

Download results:

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:

Details Item Action

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.

Entity Form

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

Entity List Portal dropdown options

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

Portal read-only modal

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:

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.

Override Column Attiributes

Entity List with changed column names:

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.

Dynamics 365 CE (CRM) How-To eGuide

41 pages of step-by-step instructions for 6 different key tasks in Dynamics 365 Customer Engagement (CRM). Includes interactions with PowerApps and Flow!

Get the eGuide

Dynamics 365 CE (CRM) How-To eGuide

Get the eGuide