Power Portal Web API Helper – An XrmToolBox Plugin

Web API for Portals is a new feature where you can finally issue Web API calls from your portal to the CDS. This post doesn’t go in the details of this feature, everything you want to know can be found here. The summary is that when you want to enable an entity for web api on the portal, you need to configure few site settings and some entity permissions and then call the Web API’s using some JavaScript code. This plugin is super simple and it just helps you in enabling/disabling the entity and any attribute for that entity for the WebAPI feature on the Portal. In addition to that, it provides you with simple JavaScript snippets that you can use as a starting point in your project.

How to use this plugin?

  1. Install the plugin from the Tool Library in XrmToolBox.
  2. Open the plugin and connect to your organization. The plugin should look like this

3. Click on Load Entities button from the command bar and the system and custom entities will be listed for you. You can search for your entity name in the filter box. You can also notice that a website selection appears in the command bar, you need to select the target website in case you have more than one in your target organization. Enabling an entity on Website A will only create the proper site settings for Website A, if you change the website, you need to enable the entity again as new site settings need to be created.

Note: Microsoft Docs clearly says that this feature should be used with data entities such as contact, account, case and custom entities. This feature shouldn’t be used on configuration entities such as adx_website or other system entities that store configuration data. Unfortunately and to my knowledge, I couldn’t find a very deterministic way for filtering every entity that shouldn’t be used with the Web API so if you know of a way, please do tell so that I can fix the filtering logic. The current logic is to exclude the list provided by Microsoft which consists mostly of the adx_ entities. I also did some judgment calls on other entities that store configuration data and not business data.

4. Once you select an entity, you can either enable or disable it and you also can select the fields you want to expose. When you are done, just click Save changes from the command bar and all the site settings will be created/updated for you.

5. If you are not very involved in JavaScript, and to help you get started quickly, clicking on Generate Snippets in the command bar will provide you with Create/Update/Delete snippets in addition to the wrapper ajax function that you use to issue the web api calls.

6. As an additional small feature, the JSON object you use for Create and Update snippets will have the selected attributes with default values. If you don’t see some of these attributes in your output JSON string, it is mostly because the attribute is not available for Create or Update as the plugin does the check for those conditions. For example, if you are creating an account record, you can provide the accountid in the create call but not in the update call as the accountid is not updatable.

That’s it, a simple plugin that will save you sometime when looking for those attributes logical names and when you want to enable entities for portal web api feature.

Project Link on GitHub: https://github.com/ZaarourOmar/PowerPortalWebAPIHelper/issues

Business Rules for PowerApps Portals – v1

When it comes to customizing Dynamics 365, I don’t care how we do it, I care about enabling the customers to use the system easily after it gets delivered to them. This of course means if we can get things done by OOB configuration and customization wizards, then it is the way to go, the last option is to write code. One example is the use of Business Rules instead of client side scripting, for simple to medium needs, a business rule can save us (and the customer) from nasty JavaScript code and enable them to change it later without worry.

The same problem applies to the Portals side of Dynamics. I’ve never worked on a portal project where the OOB features satisfy the client needs. This means any small change like hiding a field or a section needs to be backed up by some Javascript that lives inside the Entity form or the Web Form Step. Even though the needed Javascript can be simple, not everyone is comfortable doing it specially if the Dynamics Admin is not a technical person and honestly, they don’t need to know Javascript.

I though of a configuration-based solution that I call Portal Business Rules. This solution doesn’t have a fancy designer like the Business Rules in Dynamics Forms, but it is configuration based and it is capable of producing/modifying Javascript without the need to write it yourself. This solution has many of the common functionalities that a project needs. That being said, and similar to how client side scripting is still needed on the Dynamics side even with the existence of Business Rules, complex needs will still require Javascript on the portal and the good news is that this complex Java script can coexist with my proposed solution.

The current functionality of the solution is limited to:

  1. Each rule is governed by a single IF/ELSE condition.
  2. The rule works with Entity forms and Web form steps.
  3. Each rule can have unlimited number of actions. Actions include Show/Hide fields. Disable/Enable Fields, Make fields Required/Not Required, Set Field Value, Prevent Past Date and Prevent Future Date (for Datetime fields), Show/Hide Sections, Show/Hide Tabs.
  4. A rule will parse the XML of the related form or tab and suggest the fields/sections/tabs to be used in the rule logic.
  5. For some of the field types (Option sets and two option sets), a suggested value table shows up for ease of use. So instead of figuring out the integer value of an option set field, they will be listed for the user to select from.
  6. The ability to use “In” and “Not In” Operators. For example you can say if an option set value is in “2^3^4” which means if the option set is either of these 3 values, then the condition will hold true.
  7. You can see the generated Java script directly in a special tab.
  8. The Generated Java script for all the rules gets injected into the Entity form or web form step Custom Java script field and it is decorated with special comments to make it clear that this is generated by the solution and not by hand.
  9. When a rule is deleted or drafted, its logic gets removed automatically from the corresponding entity form or web form step.
  10. Basic error handling is added so that when the operands has the wrong value format, an error will show up to tell the user to fix it.

Here is a quick video showing the installation steps:

Here is a simple rule creation demo that shows/hides a tab based on a two option set value:

Another demo of multi action rule, where the Job Title field is shown and becomes required if the Company Name field is populated:

Another demo of how an option set is used in a rule. How error handling works if the operand value is of wrong format.

And finally, the “In” Operator is one of the advanced operators. Here is an example of how we can populate a field if the condition falls into one of a predetermined list of values:

Of course, there are many other possible operations features that you want to check out if you install the solution. Manipulating section visibility, field states (enabled and disabled) and many more.

Many will notice that we can only have one condition in a single rule for now and I’m currently thinking on the best way to associate other conditions to a rule with either AND or OR logical operators between them, similar to how Dynamics 365 Business Rules behave.

To be fair, the best solution for this problem is not my proposed solution but is to make the Business rules that currently exist for Dynamics forms work on the Portal Forms as well, I can say that this solution needs to be done by Microsoft itself as there no much visibility on the Business Rules engine for us,developers. Based on my knowledge, the business rules in Dynamics seem to be built using the Windows Workflow Foundation (from looking at their XAML).

In summary, the problem I’m trying to solve is reducing the need for code further, similar to how Business Rules reduced the need for client side scripting on the Dynamics 365 side. If code is still needed, then my solution and custom code can still live together.

Please refer to my repository on Github for installation steps. Feedback is really appreciated.

NOTE: For the Java script functions that I call in the back-end, I use this existing library on GitHub developed by Aung Khaing .

Update October 16, 2019

During some search, I found out that a company called North52 has a similar solution that was done before and they inject Javascript the same way I do but of course with a nicer interface :). I have a bit more functionality provided. Here is the Link