Guide to Entity Forms for Power Apps Portals in Dynamics 365

Entity Forms are an essential component in Portal development. They are a mainstream method of presenting form data on the Portal so a user can add or edit records that will appear in your Dynamics 365 Sales app.

This blog will explain what Entity Forms are, show you how to create and control them, and give you some examples. I will not cover every field or scenario for Entity Forms. Instead, I emphasize items that may be more confusing or have more value than others.

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

What Are Entity Forms?

An Entity Form is a way to show a form in your Dynamics 365 Portal to allow your users to enter data.

There is one catch though – an Entity Form is a mirror projection of a D365 Sales form. For an Entity Form to exist, it must be associated to a Dynamics 365 Sales form. This means the D365 Sales form must be created before the D365 Portal Entity Form.

Entity-Form-Example

This is an Entity Form record, and the third field ties the Entity Form to an already-existing D365 Sales form. No D365 Sales form, no Entity Form. Both work together to display the final product on the Portal.

Why Use Entity Forms?

There are several reasons to use Entity Forms on the Portal; here are some of the most common:

  • One-page information-capture form
    • One-page contact us form
    • One-page feedback form
    • One-page information form
  • A detail form from a list
    • Insert, update, or read-only form
  • A modal form inside a Web Form

How to Create a Portal Entity Form

Entity Forms may be simple or complex, but, at a high level, here are the steps to get an Entity Form to display in your Portal:

1. Create a Dynamics 365 Sales Form

Log into make.powerapps.com, find or create the desired solution, and then add the desired entity to the solution. Select the entity, select forms, select Add form, and then select Main form. Add all the tabs, sections, and fields that should be displayed on the Portal. You may need to add some of the required fields now like Name or User, but, if needed, they can be hidden.

D365 Sales Form

We now have the core of what will be the Entity Form; this will be tied, or associated, to the Entity Form, which you will create next.

2. Create the Entity Form Itself

Inside Power Apps, click Apps, and then click the Model-driven app named Portal Management. From the left navigation, click Entity Forms. Click + New.

Active Entity Forms

3. Define the Entity, Form, and Tab Name

Enter a meaningful Name for the Entity Form record so when you see it in the list, it will make sense.

Select the correct entity of which the D365 Sales form is associated that you created above. Then for Form Name, select the correct D365 Sales form that belongs to the entity.

If you want only one tab to display on the Portal, you may select it for the Tab Name field.

New Entity Form

4. Define the Entity Form Mode

There are three choices for Mode: Insert, Edit, and Read Only. They are self-explanatory in that Insert will only create records, Edit will only modify records, and Read Only will provide a read-only display of the form data.

This is an important consideration when developing Portal and especially if you need to provide an overall estimate for a certain section of the Portal website.

For example, you are requested to create a one-page information capture Web Page that will utilize an Entity Form. You may provide a two-hour estimate but fail to ask vital questions like “Should the Portal User be able to edit their information?” or “Should the Portal User be able to see the information they have submitted in a read-only format?” It does not exactly triple your development time, but it will increase it, and there are other considerations as well.

In the screenshot below, I have decided to select Insert for the Mode. This means that this particular Entity Form can only be used to create new records inside the Microsoft Dataverse/D365 Sales environment.

Entity-Forms

5. Determine Record Source Type

You will notice that if Edit or Read Only are selected for Mode, other fields appear on the Entity Form. They are Record Source Type and Record ID Query String Parameter Name.

Record Source Type determines the source of information that should be edited or displayed. For Record Source Type, there are three options:  Query String, Current Portal User, and Record Associated to Current Portal User.

Record Source Type: Query String

When Query String is selected for Record Source Type, this means the record ID will be provided in the Portal URL when entering this page.

The URL could look something like this:  https://your-website.powerappsportals.com/application?id=7c061bc4-bf15-44c7-8c3e-2b21faa11361

On the Entity Form, it would be set up like this:

Record Source Type

And here is how it would be set up for Read Only:

Record Source Type

The Portal Edit form would look something like this:

Portal Edit Form

Record Source Type: Current Portal User

When Current Portal User is selected for Record Source Type, the GUID value of the Contact that is logged into the Portal will be used as the hidden URL.

On the Entity Form, it would be set up like this:

Record Source Type

On the Portal, notice the URL below; the ID is not appended to it because, behind the scenes, the Dataverse and D365 Portals knows what Contact is logged in and what record to display.

Form on Portal

As you would imagine, the Current Portal User will only work for records of the same type as who is logged in; in this case, it is Contact.

Record Source Type: Record Associated to Current Portal User

When Record Associated to Current Portal User is selected for Record Source Type, the GUID value of the associated record will be used as the hidden URL.

On the Entity Form, it would be set up like this:

Record Associated to Current Portal User

On the Portal, notice the URL below; the ID is not appended to it because, behind the scenes, the Microsoft Dataverse and D365 Portals knows what associated record to display.

Entity-Forms Entity-Forms

Inside D365 Sales, we can observe that the Contact only has one ID Document record.

Contact Record

IMPORTANT: If more than one record exists, the Portal page will fail to load:

Error Message

6. Enable Entity Permissions

This blog will not go into too many details about Entity Permissions, but if the checkbox is checked on the Entity Form, permissions will need to be defined.

Enable Entity Permissions

Otherwise, when navigating to the respective Web Page, this error message will display:

Error Message

At a high level, create a new Entity Permission record, and assign the desired privileges (permissions).

New Entity Permission

Once the record is created, Web Roles may be assigned to determine which Portal users will be able to perform any of the actions above.

Web Roles

If the actions are needed to be performed by non-logged in users, assign Anonymous Users Web Role.

Web Roles

Select the correct Website and Save.

New Entity Form

7. Create the Entity Form’s Web Page

If the Entity Form needs to be displayed on its own page on the Portal, a Portal Web Page needs to be created.

For example, consider a one-page application that needs to be displayed on a client’s Portal website. Here is the Entity Form:

Entity Form

But this by itself will not display anywhere on the Portal; we must specifically place it on a Web Page first.

Navigate to Web Pages in the left navigation and click + New.

Fill in the necessary information.

Entity Form

The focused item here is the Entity Form field; select the Entity Form you created above.

When we navigate to the actual Portal page, we will see the below:

Portal Page

Entity Form Options

The Form Options tab on the Entity Form record has exactly that – options. It provides options to add a layer of security, to easily make all fields required or to show each form tab as a step, and to append to the outgoing URL after the form has been successfully completed.

I’ll cover the following options:

Captcha

You have the ability to add security to your Portal website by including Captcha features, and it is super easy to implement.

Navigate to the appropriate Entity Form and Form Options tab. Check the Add Captcha box, save, and clear portal cache.

Power-Apps-Portals-entity-forms

When the Web Page is refreshed, the Captcha component will appear and function appropriately for either authenticated or anonymous users. If you only want to add this for authenticated users, check the Show Captcha for Authenticated Users.

Power-Apps-Portals-entity-forms

If the Captcha is not filled out correctly, the user will not be able to submit the form.

Validation Group

Here is Microsoft’s definition of this field:

The group name assigned to input controls for evaluating valid input of named groups.

This field allows you to group validation input controls so that if you need to add your own JavaScript validation, you can keep them separate if needed. Let us consider the following.

After developing the Application form, I realize I need to make Application Type a required field from the Dynamics 365 Sales side. By doing this, it will automatically make it a required field on the Portal.

Forcing the field to be required in Dynamics 365 Sales:

Power-Apps-Portals-entity-forms

Portal automatically makes it required.

Power-Apps-Portals-entity-forms

But now, a new requirement surfaces in that Sponsor needs to be required, but only on the Portal side of things. How do we accomplish this? You can use Entity Form Metadata to make the field required versus optional. But what should you do if you need specific validation outside of the field just being populated?

This is a scenario where Validation Group comes into play.

Navigate to the desired Entity Form, and enter a meaningful name for Validation Group on the Form Options tab.

Power-Apps-Portals-entity-forms

Once the Portal is refreshed and you view the source code, you will see some interesting things.

As a preface, this is not meant to be a detailed analysis of the HTML and JavaScript but rather a summary to give you an idea of how Validation Group can be used. In addition, I will demonstrate what code is auto-generated for Application Type to describe what is possible for other fields like Sponsor.

HTML of Validation Summary DIV

Power-Apps-Portals-entity-forms

This is an HTML DIV tag that is automatically generated when the page loads that holds the error messages that will be displayed to the Portal Users. It looks something like this:

Power-Apps-Portals-entity-forms

HTML of Application Type Field

Power-Apps-Portals-entity-forms

The code above provides the container for the Application Type field, and the result of this code looks like this:

Power-Apps-Portals-entity-forms

Validation Summary JavaScript

Power-Apps-Portals-entity-forms

When the user clicks the Submit button, Portal natively follows a form-validation process with JavaScript. The JavaScript above builds an Array object and adds the Application Type and Data Available fields to it so it can be used in the validation process.

Field Validation JavaScript

Power-Apps-Portals-entity-forms

In general, the code above builds out the necessary form validation for each specified field. In particular, the code does the following:

  • Line 3 assigns a JavaScript variable to the Validation Summary <div>.
  • Line 6-8 assigns a default error message to the variable.
  • Line 9 assigns the Validation Summary <div> to the AppGroup of which we defined in the Entity Form.
  • Line 11-15 assigns a JavaScript variable to the Application Type field.
  • Line 16-20 assigns a default error message to the variable for the Application Type field.
  • Line 22 assigns the Application Type JavaScript variable to the AppGroup.

Using this as an example, we could add our own JavaScript to make Sponsor a required field.

Using Arpit Shrivastava’s example, we can make the Sponsor field a required field and add any other data validation requirements if needed.

If we wanted, we could add it to a different Validation Group which means when the form is submitted, only the fields that are part of the JavaScript function that validates the form for that Validation Group would validate.

I know this section was quite detailed, but it gives you, hopefully, a better understanding of the purpose of Validation Group and how it can be consumed.

Auto Generate Steps from Tabs

We can spread out a large form across multiple steps using the Auto Generate Steps from Tabs. Try to get a better understanding of your clientele before you create Entity Forms or Web Forms. Some of the choices are: 1) large but few steps or 2) small but many steps.

From our previous Application form, we decide to add another tab to allow the Portal user to enter why they want to apply.

Power-Apps-Portals-entity-forms

With Auto Generate Steps from Tabs unchecked, the new Portal form would look like this:

Power-Apps-Portals-entity-forms

On the Portal, the Reason field is on the same “page” as that of the general information. Our preference is to have the Reason field all on its own, so we check the Auto Generate Steps From Tabs field:

Power-Apps-Portals-entity-forms

Save, clear Portal cache, and refresh the Portal page.

Power-Apps-Portals-entity-forms

Instead of the Submit button down at the bottom, we now have a Next button.

When clicking Next, we see this as the next step:

Power-Apps-Portals-entity-forms

The Reason field has become its own step, and now, there is a Previous and Submit down at the bottom.

Render Web Resources Inline

Inside Dynamics 365 Sales and their forms, separate containers of HTML can be added to increase value and functionality to the user. These same containers can be pushed out to the Portal Entity Forms.

Here is the Dynamics 365 Sales form editor for the Portal Application form.

Power-Apps-Portals-entity-forms

When displayed out to the Portal, it would look something like this:

Power-Apps-Portals-entity-forms

The HTML code looks like this:

Power-Apps-Portals-entity-forms

The HTML Web Resource is placed inside an iframe in the HTML code. And depending on what you are attempting to achieve, an iframe can cause difficulties for either developers or your users.

When we check the Render Web Resources Inline, the display will look similar, like this:

Power-Apps-Portals-entity-forms

You will notice the iframe border is removed and only the field border remains.

The code will look like this:

Power-Apps-Portals-entity-forms

The iframe tag is replaced with a custom literal tag.

Most likely you will not need to check this, but in case you have special circumstances in your Portal, now you know what it does and how it operates.

Enable Validation Summary Links

The default value for this field is checked.

Power-Apps-Portals-entity-forms

That means when a user experiences an error in the Portal for an Entity Form, the field-specific error is converted into a link.

Power-Apps-Portals-entity-forms

Clicking on the link will shift focus to the field in question; it is merely a feature to aid the user in finding the correct field.

With the field unchecked, we will see the below Portal error message instead:

Power-Apps-Portals-entity-forms

Validation Summary CSS Class

If special or additional CSS styling is needed for the error messaging, you can enter a CSS class value for the Validation Summary CSS Class field and then provide your own styling on the Validation Summary HTML element.

Power-Apps-Portals-entity-forms

After the Portal is refreshed and an error is purposefully generated, you can view the HTML code, and it will contain something like this:

Power-Apps-Portals-entity-forms

From here, you can add CSS styling to your CSS Web File(s) or to the Advanced tab of the containing Web Page. For display purposes, I will demonstrate the latter.

Adding CSS to the Portal Application Content Page Web Page (Not the Information Web Page):

Power-Apps-Portals-entity-forms

Testing error with added CSS:

Power-Apps-Portals-entity-forms

As the PowerApps Portals utilizes Bootstrap CSS, most likely several layers of CSS will need to be added to override or complement it.

Instructions

Several times it is necessary to provide users useful instructions on what information they need to fill out the form successfully or what steps to follow after the form is submitted. By filling out the HTML-supported Instructions section on the Form Options tab on the Entity Form, you can do that.

Power-Apps-Portals-entity-forms

Display of instructions on Portal form:

Power-Apps-Portals-entity-forms

There are no options of where to display the instructions; they automatically are placed on top of the form.

On Success Settings

What should happen when the user successfully completes the Portal form? The On Success Settings tab on the Entity Form record provides two options: Display Success Message and Redirect.

Power-Apps-Portals-entity-forms

Display Success Message

Here are the default settings for the On Success Settings tab:

Power-Apps-Portals-entity-forms

When the form is successfully completed, the form is hidden, and a default successful message is displayed:

Power-Apps-Portals-entity-forms

The URL remains the same, meaning that the user did not navigate to a different page. You may notice in the image above that the form instructions are still visible. This may be confusing for the user as they may expect to be redirected to another page, view different instructions, or maybe redirected back to a previous starting point. These are several good reasons to have the redirect option.

Redirect

For a redirect, we have many more choices that essentially will send the user somewhere else, bringing along some key information if needed.

Power-Apps-Portals-entity-forms

We can redirect to an external website (External URL) or to another Portal Web Page (Web Page).

Adding an External URL would look like this:

Power-Apps-Portals-entity-forms

Regardless of which option is followed, we can add parameters to the URL.

By checking Append Existing Query String, we would be redirected to the following:

Power-Apps-Portals-entity-forms

By checking Append Record ID To Query String, we would be redirected to the following:

Power-Apps-Portals-entity-forms

We can enter a legitimate name/value pair in the Append Custom Query String like this:

Power-Apps-Portals-entity-forms

We would be redirected to the following:

Power-Apps-Portals-entity-forms

We can even add a parameter and value from one of the fields of the specified (target) entity. We would add the following information like this:

Power-Apps-Portals-entity-forms

The logical name matches the name of the field in the solution:

Power-Apps-Portals-entity-forms

When completing the form successfully, we would be redirected like this:

Power-Apps-Portals-entity-forms

This last option has limitations, so use wisely. For example, if a customer or lookup field is added, only the GUID value would be represented in the URL.

Power-Apps-Portals-entity-forms

Examples

Example: An Insert Entity Form Attached to a Web Page

Developing an Insert Entity Form attached to a Web Page would look something like this:

Entity-Forms

When successfully completing the form and clicking Submit, you would receive this message:

Entity-Forms

Navigating to D365 Sales Applications, you would find the new record.

Entity-Forms

Example: Entity List to an Edit Entity Form with Web Page

Creating an Entity List that points to an Entity Form with a Target Type of Web Page is designed like this:

Entity-Forms

The Web Page would need to be created first (Portal Applications – Edit).

Entity-Forms

And would look like this:

Entity-Forms

Clicking one of the links for the Application would direct you to the Entity Form on a Web Page.

Entity-Forms

Example: Entity List to an Edit Entity Form

Creating an Entity List that points to an Entity Form with a Target Type of Entity Form is designed like this:

Entity-Forms

The Entity Form already exists so no need to create additional Portal components.

Entity-Forms

And would look like this:

Entity-Forms

Clicking one of the links for the Application would open an Edit dialog window.

Entity-Forms

Example: Read-Only Entity Form

Developing a Read Only Entity Form would look something like this:

Entity-Forms

Adding an Item Action for the Entity List that points to the read-only Entity Form looks like this:

Entity-Forms

It would look like this:

Entity-Forms Entity-Forms

This blog has explored some of the main features of Entity Forms. By all means, spin up a trial Dynamics 365 instance and Portal and trial and error your way through a greater understanding.

There are also some related topics you may want to learn about in more detail:

If you have any questions about Power Apps Portals, please get in touch with us.

Webinar - End-to-End Resource Scheduling in Dynamics 365 Project Operations

This webinar provides an end-to-end overview of how you can schedule resources in D365 Project Operations. This overview will be useful to project managers, schedulers, and sys admins.

October 11
9:00 am – 9:30 am PST

Register Here

Webinar - D365 Project Operations Scheduling

Oct. 11
9:00 am – 9:30 am PST

Register