Walkthrough: Execute Azure Function from Microsoft Dynamics Entity Form

Azure Function is a fantastic mechanism for various integration scenarios. Here are few key characteristics:

• Being a serverless application, Azure Function has the best time to market when it comes to deploying a web service
• Pay-per-use pricing model means you pay only for what you use
• Built in integration options in PowerApps and Flow allows you to give non-developers new building blocks when designing application and processes
• CORS (Cross-Origin Resource Sharing) support allows consuming Functions from server/client side in any domain you find suitable

What can you do with Azure Functions in the context of Microsoft Dynamics integration scenarios? Just about anything:

• Export/Import data to/from external application/data storage
• Notify an external application on a business event
• Get notification from external source
• Handle complex or lengthy computation process (considering the Plug-in/Custom Workflow Activity execution timeout limitation)
• Allow a 3rd party to interact with your Dynamics 365 organization without directly exposing an Dynamics endpoint and access credentials

So Why would you want to Execute Azure Function from an Entity Form?

• To provide responsive and fluent UX
• To avoid writing Plug-in/Custom Workflow Activity code which is not easy to debug
• To respond to form level events such as field value change as it occurs

In this post, I’ll walkthrough executing Azure Function from Microsoft Dynamics 365 Entity form. This walkthrough was set up with Microsoft Dynamics 365 v9.0 but can be easily adapted to v8.2.
My sample scenario demonstrates sending new Lead data to an Azure data storage using Azure Function. Off course, you can use this walkthrough with an On-premises deployment, but you will have to allow access to Azure.
Thank you Nishant Rana  for an enlightening post that helped setup this walkthrough.

 

1. Setup an Azure Function App

   The Function App is a container that will contain your Functions and will allow you to manage these components.
   In your Azure Portal (open a trial if you don’t have a subscription), type in ‘Function App’ in the search box and select the Function App item in the Marketplace.

   

   In the next dialog, type in the Function App name (which will be part of the function URL) and fill all other required fields.
   Create a new Resource Group if you need one as well as Storage. Pin your function to the dashboard for easy access.

   

   After few seconds you will be navigated to the dashboard. Wait while your Function App is setup and then you will be navigated to the Function App design area

   

   Click the Functions node and then click the ‘+ New function’ button to add a new Function

   

   Select the Generic webhook option coupled with C#  language

   

   In the next dialog, give your function a meaningful name and click ‘Create’

   
   Since we want to handle new Lead data by queuing it, click the Integrate node to add a new Function output and select the Azure Queue Storage.

   

   In the next dialog, note the Message parameter name as it will be part of the function code. Click ‘Save’

   

   Click the Function node to access the Function code

   

   Replace the existing code with the following code block and click ‘Save’

   #r "Newtonsoft.Json"
   
   using System.Net;
   using Newtonsoft.Json;
   
   public class Lead
   {
       public string Topic { get; set;}
       public string FullName { get; set;}
       public string Email { get; set;}
   }
   
   //function entry point 
   public static async Task Run(HttpRequestMessage req, TraceWriter log, IAsyncCollector outputQueueItem)
   {
       //trace incoming request 
       log.Info($"New HandleNewLead request received");
   
       //parse request into Lead object
       string jsonContent = await req.Content.ReadAsStringAsync();
       var lead = JsonConvert.DeserializeObject(jsonContent);
   
       //trace Lead data
       log.Info($"Lead data: topic: {lead.Topic}, full name: {lead.FullName}, email: {lead.Email}");
   
       // add lead object to queue
       await outputQueueItem.AddAsync(lead);
   
       //return response to the caller 
       return req.CreateResponse(HttpStatusCode.OK, new { message = "Lead processed successfully" });
   }

   Opening the Logs pane below, you can see a successful compilation message

   

   To test your Function, open the right pane and click the Test tab. Feed in some test JSON data and click Run. If all went well, you will receive a success message as well as a Function response

   

   Clicking the Monitor node, you can see the queued test Lead data

   

   Before leaving the Function area, click the Get function URL and copy it. You will be using it later in your Entity form JavaScript code

   

2. Configure Cross-Origin Resource Sharing

   In order to consume your Function from Microsoft Dynamics 365 organization which may be residing in a different domain, you’ll need to define it as an allowed origin under the CORS element:

   

   Add your Microsoft Dynamics 365 organization base URL and click ‘Save’

   

3. Setup entity form code and event

   Head into your Microsoft Dynamics 365 organization and define a new JavaScript Web Resource named dyn_AzureServicesLib.js with the following code.
   Replace the AZURE_BASE_ENDPOINT and AZURE_FUNCTION_ENDPOINT constants with the Function URL you copied earlier. Note the separation of the base URL part from the the function and code part

   (function (ns) {
   
       //constants 
       Constants = function () {
           this.CALLING_MODULE_NAME = "dyn_AzureServicesLib.js";
           this.AZURE_BASE_ENDPOINT = "https://dyneventhandlersample.azurewebsites.net/api/";
           this.AZURE_FUNCTION_ENDPOINT = "HandleNewLead?code=xxx";
           this.FORM_TYPE_CREATE = 1;
           this.MSG_OPERATION_SUCCESS = "Lead successfully exported :)";
           this.MSG_OPERATION_FAILURE = "Something went wrong :(";
   
           return this;
       }();
   
       //members
       var formContext = null;
   
       //public methods 
   
       //Export newly created Lead record to external storage/application 
       ns.exportLead = function (executionContext) {
           debugger
   
           //get form context 
           formContext = executionContext.getFormContext();
   
           //get form type
           var formType = formContext.ui.getFormType();
   
           //operate for newly created records only
           if (formType == Constants.FORM_TYPE_CREATE) {
               //extract Lead details        
               var lead = {
                   firstname: formContext.getAttribute("firstname").getValue(),
                   lastname: formContext.getAttribute("lastname").getValue(),
                   email: formContext.getAttribute("emailaddress1").getValue()
               }
   
               //send Lead details to Azure Function 
               executeAzureFunction(lead, handleExportSuccess, handleExportFailure);
           }
       }
   
       //private methods
   
       //handle opertation success
       handleExportSuccess = function (response) {
           formContext.ui.setFormNotification(MSG_OPERATION_SUCCESS, "INFO", null);
       }
   
       //handle opertation failure
       handleExportFailure = function (response) {
           formContext.ui.setFormNotification(MSG_OPERATION_FAILURE, "ERROR", null);
       }
   
       //execute Azure Function to process Lead details
       executeAzureFunction = function (lead, successHandler, failureHandler) {
           debugger
   
           //set Azure Function endpoint
           var endpoint = Constants.AZURE_BASE_ENDPOINT + Constants.AZURE_FUNCTION_ENDPOINT;
   
           //define request
           var req = new XMLHttpRequest();
           req.open("POST", endpoint, true);
           req.setRequestHeader("Accept", "application/json");
           req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
           req.setRequestHeader("OData-MaxVersion", "4.0");
           req.setRequestHeader("OData-Version", "4.0");
           req.onreadystatechange = function () {
               if (this.readyState == 4) {
                   req.onreadystatechange = null;
   
                   if (this.status == 200) {
                       successHandler(JSON.parse(this.response));
                   }
                   else {
                       failureHandler(JSON.parse(this.response).error);
                   }
               }
           }
           //send request
           req.send(window.JSON.stringify(lead));
       }
   })(window.AzureServicesLib = window.AzureServicesLib || {});
   

   Next, go to the Lead entity form designer and add the dyn_AzureServicesLib.js Web Resource in the Form Properties dialog.
   Bind the form OnSave event to the AzureServicesLib.exportLead function.  Make sure you check the ‘Pass execution context…’ option.
   Save and Publish.

   

   

4. Test

   Create a new Lead record and save it. If all went well, you will see a form level success notification

   

   Going back to your Function monitoring area, you should see your new Lead data queued successfully

   

Advertisement

Accessing Form Header Web Resource

Although this Help article states that with Microsoft Dynamics CRM 2016/Online “You can’t include a web resource in a form header or footer”, you certainly can.

Sadly, form Footer Web Resource no longer display any content (as it did in version 2015). Form header displays content correctly, but adding it will spread the header fields all over the form width.

If you are ok with the UI, you might want to access the header Web Resource programmatically via JavaScript. Maybe when a form attribute value changes, the Web Resource content should change dynamically.
Unlike header attributes, which can be accessed using  Xrm.Page.getControl(“header_name”), the header Web Resource can not be accessed this way as it seem to be invisible to the getControl function.

So how can the header Web Resource ‘Listen’ to form and field events?

Since Web Resource can access the Xrm.Page object via the parent object, it has full access to the form elements and events. The addOnChange function allows the the Web Resource code to register an internal function as an event handler for a form or field event.

The following sample demonstrates HTML Web Resource located in the Account form header area, ‘listening’ to the Account Name attribute change event. 
The code is located in the HTML Web Resource:

//register event handler to the account name attribute onChange event

function registerRefreshEvent()
{
    if(parent.Xrm.Page != null)
    {
         parent.Xrm.Page.data.entity.attributes.get(“name”).addOnChange(refreshContent);
    }
}

//do something with the Web Resource content…

function refreshContent()
{
    alert(“Refreshing Web Resource content…”);
}

registerRefreshEvent();

Visible By Default – What Is It Good For?

Short answer: improving form performance & user experience, that’s what.

Long answer:

Since version 2011, major entity form elements (Control, Section, Tab) have the Visibility attribute added. This attribute, which is checked by default, determines if the form element will be visible to the user when the entity form loads.

Why would you want to render some elements invisible when the form loads? Here are some common reasons:

1. Conditional logic: The form has some business logic related process which requires displaying some elements according to the user actions, e.g, hide Government Id attribute if the user selected Organization as Customer Type.
2. Hiding built in required controls which can not be removed from the form and are meaningless to the end user.
3. Hiding controls that are used to support the form business logic and has no meaning or use to the end user.

One uncommon reason to use the Visibility attribute is to improve form performance. I would like to elaborate on this, since I noticed many Microsoft Dynamics CRM developers are not aware of the impact which JavaScript code has on form performance which In most cases directly affect UX.

How can the Visibility attribute improve form performance and UX?

Business logic often requires script to hide/display form elements according the user actions. When the form loads, only a subset of controls should be visible to the user.
In many cases, the JavaScript code/form business rules which is triggered by the form onLoad event, literally hides all the form elements (some times, each individual control) and then render the required elements visible again.
Not only this approach waste client resources (inefficiently hiding controls which were just ‘painted’) but it also provides bad UX as it slows the form load time. With low resources machines, the user can also see the controls flick on the form before they are hidden by the JavaScript code.

The right approach in this scenario would be to uncheck the ‘Visible by default’ attribute for the elements which are not required to display on form load  (preferring tabs over sections, sections over controls) and writing JavaScript code to render elements visible when required.

This approach will improve form performance & UX because of the following reasons:

1. Less form controls to render: the form will load faster because it has less controls to render. In control heavy forms/slow machines, this is substantial.
2. Less code lines to execute: since custom hiding related code/Business Rules logic is removed, the onLoad event will complete and turn control to the user faster. You can write less code by hiding/displaying containers such as Tabs and Section rather than relating to each individual control. Again, think control heavy forms.
3. Reduce visual load: no element flickering on the form will provide better UX.

User experience is critical to the application acceptance and over whole rating by users. Developers sometime miss these problems because the from loads fast enough on their dev machine.
For users who open record forms many times a day, even 2 seconds less form loading time can make a major difference.