Execute a Recurring Job in Microsoft Dynamics 365 with Azure Scheduler

The requirement for recurring job execution is quite common in Microsoft Dynamics implementations. Here are some of the business requirements I have encountered:

  • Send monthly newsletter to target customers
  • Synchronize MSCRM Users details with Active Directory once a day
  • Once a month, disqualify all leads that have no open activities
  • Once every hour, export Appointments from mail server and import into Dynamics 365

Microsoft Dynamics 365 has no reliable built in scheduling mechanism that can be leveraged for custom solutions. The Asynchronous Batch Process Pattern I have written about in the past can be used with daily recurring jobs but when it comes to hours resolution and less, it becomes unsteady.

Azure Scheduler is a reliable service that can run jobs in or out of Azure on a predefined schedule, multiple times or just once. So why not harness this mechanism to schedule Microsoft Dynamics 365 recurring jobs?

In this post, I’ll demonstrate how to use Azure Scheduler to execute a recurring job in Microsoft Dynamics 365.

Sample business requirement

Each day, automatically email a birthday greeting to contacts whose birthday occurs on that same day.

Implementation Details

Here are the solution main components:

  1. Custom Action dyn_SendBirthdayGreetings: activates a Custom Workflow Activity SendBirthdayGreeting which Retrieve all relevant Contact records by birthdate, creates and sends an email for each contact record.
  2. Azure Function BirthdayGreetingsFunction: invokes the dyn_SendBirthdayGreetings Custom Action via Microsoft Dynamics 365 API.
  3. Azure Scheduler BirthdayGreetingsSchduler: set to execute once a day at 9:00 for unlimited occurrences and invokes the BirthdayGreetingsFunction Azure Function

Architectural Notes

Why using Custom Action? Although it is possible to manage the required business logic in Azure Function, Dynamics related business logic should reside within Dynamics, managed and packaged in a Solution. This way, the Scheduling and Executing components are kept agnostic and isolated as possible and therefore easily maintained.
Having said that, you should be aware of the Sandbox Execution Timeout Limitation and consider using Custom Workflow Activity after assessing the business logic at hand.

Implementation Steps:

  1. Define dyn_SendBirthdayGreetings Custom Action

    Download, import and publish the unmanaged BirthdayGreetingAutomationSample_1_0_0_0 solution.
    It contains a Custom Action called dyn_sendBirthdayGreeting which will be later called from the BirthdayGreetingsFunction Azure Function.
    By default, the Custom Action will create a birthday greeting email but will not send it. To change this, disable the Custom Workflow Activity, edit the only step and change the Send greeting email after creation? property value to true. Note that this may actually send email to your contacts.
    The SendBirthdayGreeting Custom Workflow Activity code can be found here.

  2. Define BirthdayGreetingsFunction Azure Function

    After creating a Function App (follow the first 3 steps here), create a new C# Function of type Generic webhook under your Function App functions collection, name it SendBirthdayGreetingFunction

    Create a new Function of type Generic webhook under your Function App collection, name it SendBirthdayGreetingFunction

    name it SendBirthdayGreetingFunction
    Click the App Service Editor option in the Application Settings tab

    Click the App Service Editor option in the Application Settings tab

    Add a new file under your Function root, name it project.json. Copy the following JSON snippet into the text editor

    Add a new file under your Function root, name it project.json. Copy the following JSON snippet into the text editor

    {
    	"frameworks": 
    	{
    		"net46":
    		{
    			"dependencies": 
    			{
    				"Microsoft.CrmSdk.CoreAssemblies": "9.0.0.7",
    				"Microsoft.CrmSdk.XrmTooling.CoreAssembly": "9.0.0.7"
    			}
    		}
    	}
    }
    

    Close the App Service Editor to get back to your function. Selecting your Function App, click the Application settings tab.

    Close the App Service Editor to get back to your function. Selecting your Function App, click the Application settings tab

    Scroll down to the Connection strings area and add a new Connection string named TargetOrganization. This will be used to connect and authenticate to your Microsoft Dynamics 365 Organization.
    For the connection string value, set your organization details in the following format:

    AuthType=Office365;Username=XXX@ORGNAME.onmicrosoft.com;Password=PASSWORD;Url=https://ORGNAME.crm.dynamics.com

    Note the data center targeted, crm.dynamics.com is targeting an organization in North America data center.

    Click Save to save the newly created Connection String.

    Scroll down to the Connection strings area and add a new Connection string named TargetOrganization
    Navigate back to your SendBirthdayGreetingFunction function and  replace the default Function code with the following code snippet.
    Note that code is executing a Custom Action named dyn_SendBIrthdayGreetings.It also uses the TargetOrganization connection string when accessing Microsoft Dynamics 365 API.

    using System.Net;
    using System.Configuration;
    using Microsoft.Xrm.Sdk;
    using Microsoft.Xrm.Sdk.Client;
    using Microsoft.Xrm.Tooling.Connector;
    
    public static HttpResponseMessage Run(HttpRequestMessage req, TraceWriter log)
    {
        string actionResponse = string.Empty;
    
        //define Dynamics Custom target Action name 
        string actionName = "dyn_SendBirthdayGreetings";
    
        log.Info("Processing new SendBirthdayGreetingFunction request");
    
        //init Dynamics connection, authenticate and get referent to the Organization Service
        IOrganizationService organizationService = InitDynamicsConnection();
    
        //execute Custom Action  
        OrganizationRequest sendBirthdayGreetingsReq = new OrganizationRequest(actionName);
        OrganizationResponse sendBirthdayGreetingsRes = 
            (OrganizationResponse)organizationService.Execute(sendBirthdayGreetingsReq);
    
        //return completion status response 
        return actionResponse == null
            ? req.CreateResponse(HttpStatusCode.BadRequest, "An error occured")
            : req.CreateResponse(HttpStatusCode.OK, "Action completed successfully");
    }
    
    //init Dynamics connection
    private static IOrganizationService InitDynamicsConnection()
    {
        IOrganizationService result = null;
    
        ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12;
        CrmServiceClient client = new CrmServiceClient(
            ConfigurationManager.ConnectionStrings["TargetOrganization"].ConnectionString);
    
        result = client.OrganizationServiceProxy;
    
        return result;
    }
    

    Navigate to the Function Integrate area and set the Mode to standard. This will enable the consumption of the function using HTTP GET method.

    Navigate to the Function Integrate area and set the Mode to standard. This will enable the consumption of the function using HTTP GET method

    Back at your Function code editor, expand the collapsed Test pane and set the HTTP method to GET. Click Run to test your function. If all went well, a success message will be returned.

    Back at your Function code editor, open expand the collapsed Test pane and set the HTTP method to GET. Click Run to test your function. If all went well, a success message will be returned.

    Finally, click the </> Get function URL button on top and copy your function endpoint address.

  3. Define BirthdayGreetingSchduler Azure Scheduler

    Click the + New button on the left menu, type in Scheduler and select the Scheduler element returned. Click Create

    Click the + New button on the left menu, type in Scheduler and select the Scheduler element returned

    Define the scheduler name to BirthdayGreetingSchduler.

    Define the scheduler name to BirthdayGreetingSchduler

    Click the Action settings tile. Set the Action to Https, method to Get and paste in the Function URL you copied at the end of the step 2 above. Click OK

    Click the Action settings tile. Set the Action to Https, method to Get and paste in the Function URL you copied at the end of the step 2 above. Click OK

    Click the Schedule tile and set the schedule as Recurring, frequency to Days and End to Never. Click the Advanced schedule pane and set 9 in the Hours text box. Click Ok.
    This will trigger your function every day at 9:00 for unlimited number of times.
    Check Pin to dashboard and click Create.

    This will trigger your function every day at 9:00 for unlimited number of times.

    After a few seconds, you will be navigated to the Scheduler management area.

  4. Test

    To test the complete solution, update a Microsoft Dynamics 365 test Contact record birthdate to match the day and month of the current date.

    Go back to your Scheduler Job and click Run now.

    Go back to your Scheduler Job and click Run now.

    Clicking the History tab, you can monitor the Schedule job completion status

    Clicking the History tab, you can monitor the Schedule job completion status

    Refreshing the Sample Contact activities list, you should be able to view the newly created Birthday greeting email

    Refreshing the Sample Contact activities list, you should be able to view the newly created email

Advertisements

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.

    Select Function App

    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.

    Define Function App

    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

    Function App design area

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

    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

    Select the Generic webhook option coupled with C#  language

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

    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.

    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’

    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

    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

    Opening the Logs pane, you can see a success 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

    To test the function, open the right pane and click the Test tab. Feed in some test JSON data and click Run

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

    Clicking the Monitor node, you can see the queued 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

    Before leaving the Function area, click the Get function URL and copy it

  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:

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

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

    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.

    add the dyn_AzureServicesLib.js Web Resource in the Form Properties dialog

    Make sure you check the ‘Pass execution context…’ option

  4. Test

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

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

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

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

Sandbox Execution Timeout

While reviewing existing Microsoft Dynamics 365 Online implementations, I have noticed a repeating assumption by which Custom Workflow Activity, executing within an a-synchronous process, is not subjected to the sandbox 2 minutes execution timeout limitation.
This false assumption led to wrong architectural designs in which long running processes are assigned to be handled by CWA components.

As this article states, Custom Workflow Activity code registered to work in sandbox mode is subjected to the 2 min. execution timeout limit, just like Plug-in code. If you want to test this declaration yourself, just put a Sleep statement in your CWA code and get the following exception for both sync. and a-sync. processes:

The plug-in execution failed because the operation has timed-out at the Sandbox Host

So here are my tips regarding the Sandbox timeout limitation:

  1. Plan for big scales: You may have hundreds of records to process on day 1, but in a year or two, you might have thousands and your CWA/Plug-in component will start hitting the execution timeout limit.
  2. Use the right tool: Both CWA and Plug-in components are not meant for heavy lifting. For potentially long running processes or complex computations, these mechanisms should be used only as event wrappers, triggered by a business event and passing on execution to a more robust and manageable mechanisms such as Azure App Services, Azure Functions or other external mechanisms.

  3. Handle all exceptions: You can easily hit the the timeout limit, especially when integrating external services which you have no control of and may not response in a timely manner.
    In general, If you don’t handle exceptions, your business logic may disgracefully break and your users/clients might experience some ugly ass raw exceptions.
    While handling exceptions, you can single out timeout exception by testing the exception status:
    catch (WebException exception)
    {
    string str = string.Empty;
    if (exception.Response != null)
    {
    using (StreamReader reader = new StreamReader(exception.Response.GetResponseStream()))
    {
    str = reader.ReadToEnd();
    }
    exception.Response.Close();
    }
    if (exception.Status == WebExceptionStatus.Timeout)
    {
    throw new InvalidPluginExecutionException(
    “The timeout elapsed while attempting to process the request.”, exception);
    }
    throw new InvalidPluginExecutionException(String.Format(CultureInfo.InvariantCulture,
    “A Web exception occurred while attempting to process the request. {0}: {1}”, exception.Message, str), exception);
    }
  4. Diagnose: You can diagnose your CWA/Plugin components by using the Trace service in your code. Tracing can be easily switched to display all tracing, just error or turned off by setting the Plug-in and custom workflow activity tracing in the Organization Settings dialog and then viewed in the Plug-in Trace Log area.
    Tracing all incoming parameters values (as this article suggests) can help you better diagnose your CWA operations.

    Plug-in and custom workflow activity tracing in the Organization Settings dialog
     Plug-in Trace Log area

  5. Monitor: Sandbox Run time statistics can help you monitor your Plug-in/CWA performance over time, failures and running time metrics.
    Run the following FetchXML query to get statistics about your component. Replace the name attribute value with your component name.
    Note the averageexecutetimeinmilliseconds and failurecount results – it might indicate that your business logic is failing or close to failure.

    <fetch>
    <entity name=”plugintypestatistic”>
    <attribute name=”averageexecutetimeinmilliseconds” />
    <attribute name=”failurecount” />
    <attribute name=”failurepercent” />
    <attribute name=”crashpercent” />
    <attribute name=”crashcount” />
    <link-entity name=”plugintype” from=”plugintypeid” alias=”PluginType” to=”plugintypeid”>
    <attribute name=”isworkflowactivity”></attribute>
    <attribute name=”typename”></attribute>
    <filter>
    <condition attribute=”name” operator=”eq” value=”MyProject.Workflows.ProcessSomething“></condition>
    </filter>
    </link-entity>
    </entity>
    </fetch>

Drag & Drop File Upload (part 1)

I have been planning to do this for over a year now, finally found the time. Started learning HTML5 (I recommend Pluralsight courses), and this is my first project.

In version 2016, Microsoft finally introduced some drag & drop file upload for the Word/Excel template feature, but that’s it. I would like to have similar UX in entity forms and Dashboards.

In this two-parts post, I’ll describe a working solution that allows users to upload a file by dragging it to a specific area in any business entity form or Dashboard.
The solution version available in this post adds an uploaded file as an attachment to a new Note record related to the context business entity. The next post version will use a more modular approach that can be used if you manage files outside of Microsoft Dynamics CRM database.


WIIFM?

An unmanaged solution can be downloaded here. Feel free to change the code to better suit you needs.

As this solution relies on HTML5 features, it will probably not work with early browsers versions. I tested it successfully with IE 11, Edge and Google Chrome v54.0.2840.71.
The solution uses the Web API service and therefore suitable for Microsoft Dynamics CRM 2016 Online and on-premise. For earlier MSCRM versions, some changes are required (read the Bits & Bytes section below)

Drag and Drop demo

Using the Solution

  1. Download, import and publish the Drag & Drop File Upload solution
  2. Add a Web Resource control to any business entity form
  3. In the Web Resource form, make sure the “Pass record object-type code…” option is checked
  4. Set the Web Resource format to span over 13 rows at least
  5. Map the Web Resource control to the dyn_DnDFileUploadArea.htm Web Resource
  6. Save & publish
  7. Drag n Drop like crazy

    image

Bits & Bytes

  • The solution code portion is contained in the dyn_DnDServices.js Web Resource
  • As the code uses Web API to create a Note record, it will not work with versions earlier than 2016. You can adapt the solution to earlier MSCRM versions by changing the createRecord function in the dyn_DnDServices.js Web Resource to use the OrgannizationData Service (REST) or the Organization Service (SOAP) to create a Note (Annotation) record
  • The code prevents uploading some file types (exe, js, etc.) according to the default blocked file extensions defined in the System Settings area. Maximum uploaded file size is also limited. Both settings are managed as constants and can be easily changed

    Managing blocked files extentions and file size settings   

  • I considered retrieving the blocked file extensions from the server instead of managing as constant. I opted for constants as I rather have better performance all year round over minor maintenance effort required once a year or maybe never 
  • You can can position the dyn_DnDFileUploadArea.htm Web Resource in a Dashboard. It will create Note record along with file attachment but will not relate it to any business record
  • Unfortunately, there is no supported manner to refresh the native Notes control. It would have been useful to automatically display the latest note after uploading a file

Entity JavaScript Scaffold

In the last couple of years I have been writing more JavaScript code than Server side code in my Microsoft Dynamics CRM projects. Better UX, plethora of supporting JavaScript libraries, easier deployment and maintenance made me prefer client side solutions.

I usually create a JavaScript library for each entity requiring client side functionality (forms, command bars etc.).
Over time, I have formed a JavaScript class scaffold. As this scaffold has improved my productivity when it comes to developing, debugging and maintaining client side code, I would like to share it here.

Consistently using this or any other scaffold, especially in large teams/projects, can significantly lower the cost of maintenance as developers quickly learn to find the right location for new code or debugging breakpoint, even in code they have never seen before.

A few key concepts implemented by this scaffold:

  1. Using Namespace

    Using namespace help avoiding collisions with other functions or variables in the global namespace. External solutions may contain code which is beyond your control and so it is important to protect your code from collisions that can be hard to detect and debug.
    Using namespace also allow encapsulating private functions and variables while exposing public elements.

    image

    In this example, I am using ContactServices as my namespace. Consuming any public function from this class (e.g. form onLoad event handler) will use the namespace as prefix: ContactServices.HandleFormLoadEvent.
    The ns alias is used to attach public functions to the namespace.

  2. ‘Constants’ management
    Managing strings and magic numbers in a designated container lowers maintenance efforts as it eliminates the need to search for these values all over the code when a change is required.
    The const keyword can be used, but I am not sure it is supported by all browsers.

    image

  3. Generic event handlers
    The scaffold generic event handlers match the entity form events. I like to think of these as managing functions which doesn’t perform actual work (like any good manager) but activates the relevant worker functions.

    The ns prefix exposes the generic event handler as ‘public’  functions which can be wired to the form /attribute events.
    In my sample here, I would use ContactServices.HandleControlChangeEvent to launch the generic onChange event handler. Note that some of these generic event handler require context, so either check this in the event definition form or extract with code if not supplied by caller.

    Why should you use generic event handlers?
    Attaching event handlers via form is simplified since the event handling function name never changes.
    This is especially useful with attributes onChange event which is usually wired directly to event handling function.
    The following generic event handler extract the initiating attribute name from the context and use it to direct the event to the actual handler. This way, all onChange event handlers can be managed in one known location.
    The generic event handler also handles exceptions and frees the actual event handlers from this task.  This way, no exception can escape your catch block.

    image

  4. Public/Private elements
    Private variables and functions are used inside the namespace scope and are not exposed to external consumers.
    This allows exposing just the API you intend to and simplify matters for external consumers.
    Functions and variables which are prefixed with ns are exposed outside the namespace, other are invisible.
    To access a ‘public’ variable inside the namespace code, use this keyword.

    image

The full JavaScript scaffold code can be download here.
The scaffold is not wired to any specific Microsoft Dynamics CRM version. These concepts can be applied down to 2011 version at least.

If you have any comments or improvements for this scaffold, I would like to hear about it.  Share it here.

Plug-in Configuration Manager Utility

Plug-in components often require external configuration settings. Maybe the Plug-in code consumes a web service which end point alternates between test and production environments or maybe you use the Plug-in configuration to turn logging on and off. Basically, any code setting which depend upon external resources is worth exporting to external configuration as it may prevent code re-compilation, additional testing etc.

There are some common approaches to implement configuration settings for Plug-in components:

  1. Configuration file: each Plug-in instance consumes a configuration file
  2. Configuration record: each Plug-in instance executes a query to retrieve a designated Microsoft Dynamics CRM configuration record
  3. Step configuration: each Plug-in instance constructor receives configuration settings from the Step secure/unsecure configuration

Performance wise, option 3 is preferred as the Step’s secure/unsecure configuration is cached alongside the Plug-in step and no additional operation is required to retrieve it. Changing the Step’s secure/unsecure configuration will automatically un-cache and reload relevant Plug-in with updated configuration. If you are not familiar with this option implementation, read this.
Options 1 and 2 require an expensive IO operation or query as each Plug-in instance explicitly consumes additional resources to retrieve configuration settings. When one of these approaches are applied in large scale (or with poor server resources), it will take a considerable toll on server performance and sometimes, the UX.

While option 3 yields better performance, it is not maintenance friendly. In enterprise scale applications, you may have to go through hundreds of Plug-in steps to update secure/unsecure configuration settings. Now think about doing this while deploying a version to the Production environment a 3 AM.

In this post, I offer a utility which allows you to enjoy Step configuration performance benefit along with simple maintenance for configuration bound Plug-in components.

WIIFM?

An unmanaged solution can be downloaded here. Use this tool as is or change the code to better suit you needs.
Although this tool was designed and built for Microsoft Dynamics CRM 2016 (Online/On-premise), the approach behind it can be implemented with previous versions, probably down to 2011.

As displayed below, the Plug-in Configuration Utility allows you select a registered Plug-in assembly, view related Steps and finally view each Step configuration details.
Clicking the ‘Update Configuration’ while a single or multiple Steps are selected will updated the respective configuration settings.

By default, Custom Work Flow Activities and System owned Plug-in assemblies are hidden, but can be revealed by unchecking the matching checkbox. You can view some interesting configuration settings under the Microsoft.Crm.ObjectModel assembly Steps, which are hidden when using the Plugin Registration Tool.
Although possible, do not change any configuration settings for these Steps.

Plugin Configuration Manager Demo

Bits & Bytes

The entities used behind the scenes here are

  1. pluginAssembly – representing registered Plug-in DLL file
  2. pluginType – representing IPlugin event handler class contained in the Plug-in DLL file
  3. sdkMessageProcessingStep – representing Step details binding the plugintype event handler to specific entity and message. Contains the unsecure configuration string
  4. sdkMessageProcessingStepSecureConfig – representing a secure configuration record related to the sdkmessageprocessingstep. Contains the secure configuration string

Plugin Configruation Entity Model

Although the Plug-in Registration Tool displays the secure configuration string as part of the Step settings (represented by the sdkMessageProcessingStep entity), this attribute actually resides in the related sdkMessageProcessingStepSecureConfig entity. Moving the secure configuration string to a different entity allows setting different privileges, as the secure configuration string may contain sensitive data like password.

This also means the in order to programmatically set new secure configuration string for a Step, it is required to create and relate a new sdkMessageProcessingStepSecureConfig  record.

Plugin Step Secure Configruation Privileges

MSCRM 2016 Admin Utility – Personal Views Manager

You may have noticed that even under the almighty System Administrator Security Role, you can’t view (nor edit, share, assign or delete) other users Personal Views. Well, that’s what personal means. Via the application UI, only the view owner can manage it.

This restriction can be troubling in some scenarios:

  • A user who shared his Personal Views with other users or teams has left the organization and now no one can edit or delete these views which are irrelevant or just annoying
  • A user has defined and shared a resources hungry Personal View which execution make the application grind to a halt

In this post, I’ll demonstrate a utility which allows you manage other users Personal Views, as long as you have the right privilege.

WIIFM? 

As you can see below, after selecting a user, you can view and manage the user owned Personal Views by deleting or assigning to yourself:

Personal Views Manager demo

If you are not into JavaScript coding and just want to use this utility, you can download the unmanaged solution. After importing this solution, open it, navigate to the Configuration element and manage away. It is recommended that you have the System Administrator Security Role. 

Note
that this utility was developed and exported from Microsoft Dynamics CRM Online Organization (v2016) but it should work perfectly in an on-premise v2016 deployment.
If you are using an earlier version (2015 and below), this solution is not for you, as it uses v2016 new API. There are similar solutions available for earlier versions.

Curious about the implementation details? read on. 

Bits & Bytes

Major implementation notes:

  • Although this utility can be easily implemented on the server side, I opted for client side & Web API which requires less code lines to write and is easier to maintain
  • I intended to add an option to Share Personal Views but encountered Web API limitation, as the GrantAccess message is yet unsupported. One option to implement this feature is calling a Custom Action wrapping a Custom Workflow Activity to execute GrantAccess request
  • The entity used to represent a Personal View is userquery 
  • The magic feature enabling access to userquery records owned by other users is Web API impersonation
  • In order to use impersonation with MSCRM (client or server side), the executing user (consuming the Web Resource) must have the prvActOnBehalfOfAnotherUser privilege, which is granted by default by the built-in Delegate and System Administrator Security Roles:

    prvActOnBehalfOfAnotherUser privilege 

  • To execute code using impersonation, the MSCRMCallerID header must be added to XMLHTTPRequest along with the impersonated user id:

    using the MSCRMCallerID header

  • Some good news though: in order to Assign a record using Web API, you only have to update the onwerid attribute. Sound so trivial…why did we ever need AssignRequest?

    use update instead of AssignRequest