ENGINEERED CODE BLOG

Dynamics 365 Portal: Filter Criteria and Action Buttons

As a follow-up to last week’s post on conditional action buttons, I wanted to dive a bit deeper into a very cool, but completely undocumented, feature that exists in the Dynamics 365 Portal product: the Filter Criteria for action buttons.

What’s an Action Button?

In case you didn’t read last week’s post, I’ve copied and pasted the introduction to action buttons to save you a click:

If you’re not familiar with action buttons, they are a pretty powerful feature included in Entity Lists and Entity Forms allowing you to add buttons that perform actions (I know, they are well named!). For example, action buttons allow you to perform actions such as:

  • Create a new record
  • Download the list of records
  • View the details of a particular record
  • Edit a particular record
  • Delete a record
  • Run a workflow on a record
  • Create a related record
  • Activate a record
  • Deactivate a record

Within an Entity List, non-record-specific actions (like download or create) appear above the list, and the record-specific actions (like edit, delete, and run workflow) appear as options in a dropdown in an additional column in the grid. On an Entity Form, you have the choice of adding these buttons above or below the form itself. Of course, the necessary Entity Permissions are required for a user to perform these actions.

Hidden in the Advanced Settings

If you haven’t seen the Filter Criteria field in the action button configuration, then it’s probably because you’ve never turned on the Advanced Settings option available in the Action Button Configuration section on the Entity Form form, or the Grid Configuration section on the Entity List form:

Once you’ve checked that option, you should be able to see the Filter Criteria field within the configuration for action buttons.

Controlling Action Button Visibility

Normally, when you create an action button, it’s always shown unless you use JavaScript, CSS or some other technique to hide them (again, see my previous post). Filter Criteria allows you to hide action buttons if the record doesn’t match a FetchXML query.

To hide an action button using Filter Criteria, enter a FetchXML query that defines the conditions for when the button should be shown – if a record is returned in the results of the FetchXML query, it will be shown; if it’s not, it’s hidden. Filter Criteria can only be used to control visibility based on data related to the record the action would be performed on (either the record that is the source for the Entity Form, or the record corresponding to a row in the Entity List). Therefore, the primary entity type for the FetchXML has to match the entity type of the Entity List or Entity Form.

Let’s look at an example, which I’ve taken from an Edit button configured for the out-of-the-box Managed Opportunities Entity List in the Partner Portal:

<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
  <entity name="opportunity">
    <attribute name="opportunityid" />
    <order attribute="name" descending="false" />
    <filter type="and">
      <condition attribute="adx_partnercollaboration" operator="eq" value="0" />
    </filter>
  </entity>
</fetch>

As you can see, the Edit button in this case is only shown if the adx_partnercollaboration attribute equals 0.

How Does It Work Under the Hood?

Before the Portal code displays the action button, it executes a modified version of that FetchXML, and will only display the action button if the record is in the result set.

The query is modified for performance reasons – the code doesn’t want to have to go through all of the results of the query. This would be bad if there were a lot of records, especially if there were more than 5000 records in the result set, and then it had to start worrying about paging. So how is the query modified? The Portal code adds an IN condition on the Primary ID of the record to limit the result set. If the record in question is returned by the FetchXML query (meaning it matched all the other aspects of the FetchXML query), then the action button is shown; if not, it is hidden. In the case of the Entity List, all of the IDs of the records currently being shown in the list are included in the IN clause – this is done so that the visibility of a button for all currently shown records can be determined in a single query.

Real-world Usages

So now that we’ve seen how it works, why is this useful?

Microsoft has leveraged this functionality in the Partner Portal (and if I had to guess, it was probably added to the product because they wanted to build out some scenarios in the Partner Portal) to configure different Edit buttons for the same record type. So in the above example, there are actually multiple Edit buttons configured, so it is not necessarily about hiding an Edit button, but instead choosing which Edit button the user will see based on attributes of the opportunity. This allows you to point the user to different Entity Forms based on a value in the record itself.

As I mentioned, this feature only allows you to take into consideration a FetchXML query based on the record (and if you want to make a more complicated FetchXML query, you could do related records as well). However, you can’t take into account things like the current user’s permissions, as this type of information can’t be included in the FetchXML query.

What About List-level Action Buttons?

There are certain action buttons that don’t apply to specific records, like Download or Create, yet the Filter Criteria field can still be configured for them. Since there is no record to query against, what does adding a Filter Criteria do for these buttons? In short, nothing. Feel free to put whatever you want in these fields, it won’t have any affect on the visibility of these buttons. As far as I can tell, the value in that field is never used by the Portal code. If I had to guess, the Portal product team implemented a reusable configuration module for the action buttons, and didn’t hide the ones for the buttons where that particular field doesn’t apply.

How Did I Figure Out This Undocumented Feature?

If you’re curious how I was able to determine how the functionality worked, it all goes back to one of my old blog posts. No, I don’t have special access to product team developers that tell me how it works. Instead, I have access to the full source code for the product – and so do you! At least, we all have access to v8.3 code, which for most features, hasn’t changed a whole lot.

I often find myself digging through the Portals Source Code Release, or more accurately, the xRM Portals Community Edition, to figure out how something works. It’s an extremely useful technique, and something I think you need to learn how to do if you want to get serious about Dynamics 365 Portal development.

I’d also to point out this Microsoft Dynamics 365 Community forum post that I found while researching for this post, which includes helpful information on this topic from Business Applications MVPs, and Portal Experts, Colin Vermander (@koolin_) and Nick Doelman (@readyxrm).

Leave a Reply

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

Contact

Engineered Code is a web application development firm and Microsoft Partner specializing in web portals backed by Dynamics 365. Led by a professional engineer, our team of technology experts are based in Regina, Saskatchewan, Canada.