C# on The CRM Chap

Getting Started with Microsoft Dataverse Plug-in Logging in Application Insights

Sun, 06 Mar 2022 00:00:00 +0000

In today’s post, we will be taking a lot at some new functionality that I had the fortunate opportunity to play around with a short time ago. If you’re looking to enhance the way you store and manage log information relating to your Microsoft Dataverse plug-ins, then be sure to read on. 😀

So What’s the Deal?

In the past, developers of plug-ins have been limited to storing telemetry information directly within Microsoft Dataverse via the capabilities on offer as part of trace logging. While this offers us the ability to debug and detect potential problems arising from any custom code we’ve written, attempting to work with this information outside of Dataverse has typically been challenging, if not impossible. To help address this need, it is now possible for developers to output detailed logging and telemetry information into Application Insights as well. This offers several distinct benefits, including:

The ability to easily extract and view this information via tools such as Power BI.
Support for generating alert rules and custom actions, such as triggering a Logic App or Azure Function.
No degradation in the quality of the outputted information; developers can expect to receive and work with the exact details currently available as part of trace logging.

Combined together, this capability affords new opportunities for organisations to more closely integrate their Power Platform solution with any existing monitoring capabilities that may already exist within their Microsoft Azure environment.

Now, it’s worth noting that all of this stuff is still currently in public preview, having been initially released in this manner in July last year as part of the Wave 1 2021 updates. Therefore, it’s recommended not to use this yet for any production scenarios; however, it represents an excellent opportunity for developers to review what’s on offer and take steps to consider using it in the future.

Getting Started

First, make sure you have an Application Insights resource stood up on Microsoft Azure, ideally within the same region as your Dataverse environment. From there, you will then need to navigate into the Power Platform Admin Center and navigate into the Data Export (preview) area:

Then, select New Data export:

On the New data export pane, select the CDS diagnostics and performance option and choose the environment you want to configure the integration for:

Then, on the final screen, select the Application Insights resource you created earlier and select Create - provided you have the relevant access, all possible Azure subscriptions/resource groups/resources will appear in the appropriate dropdowns:

(It’s worth noting here that there is a strict 1:1 binding for Environment and Application Insights resource. Therefore, you may need to set up additional Application Insights resources to accommodate this restriction.)

And that’s everything setup successfully, which we can confirm by navigating to the App Insights tab:

Pretty straightforward, I’m sure you’ll agree - provided you know where to find it, of course. 😉

Next, we need to implement a plug-in that uses the ILogger Interface. This is included as part of the System.Net.Http assembly, which should be added automatically as part of any new class assembly project; otherwise, add it in from NuGet. From there, we can start to think about using this in our code. Let’s assume our plug-in project is called JJG.Plugins.AppInsightsSample. First, create a folder in the project called Helper and then add in the following custom class:

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.PluginTelemetry;
using System;

namespace JJG.Plugins.AppInsightsSample.Helper
{
 /// <summary>
 /// Class used to consolidate all Tracing / Logger calls into a single action.
 /// </summary>
 public class Logger
 {
 private readonly ITracingService tracer;
 private readonly ILogger logger;
 public Logger(IServiceProvider serviceProvider)
 {
 tracer = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
 logger = (ILogger)serviceProvider.GetService(typeof(ILogger));
 }
 /// <summary>
 /// Logs information out to the Trace Log and Application Insights resource for the current environment.
 /// </summary>
 /// <param name="log">The actual message to log out.</param>
 public void LogInformation(string log)
 {
 logger.LogInformation(log);
 tracer.Trace(log);
 }
 /// <summary>
 /// Logs an error out to the Trace Log and Application Insights resource for the current environment.
 /// </summary>
 /// <param name="log">The actual message to log out.</param>
 /// <param name="log">Exception details to log out into Application Insights.</param>
 public void LogError(string log, Exception ex)
 {
 logger.LogError(ex, log);
 tracer.Trace(log);
 }
 }
}

The class acts as a means of simplifying any calls out to the Logger and the plug-in trace log, as and when we need to. I would advise always writing out to both destinations so that any relevant information from a debugging standpoint is also available within Dynamics 365.

Next, we’ll need to add in a plug-in that performs some action. In this case, we have a plug-in that goes off and creates a couple of Task rows on a Case, provided that the source of the Case does not equal Facebook:

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;
using JJG.Plugins.AppInsightsSample.Helper;
using System.Collections.Generic;

namespace JJG.Plugins.AppInsightsSample
{
 public class Case_OnUpdate_PushAppInsightsSample : IPlugin
 {
 private int facebookCaseOrigin = 2483;
 public void Execute(IServiceProvider serviceProvider)
 {
 //Obtain the execution context from the service provider.

 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

 // Check for EntityType and Message supported by your Plug-In
 if (context.MessageName != "Update" && context.PrimaryEntityName != "incident")
 throw new InvalidPluginExecutionException($"Plug-In {this.GetType()} is not supported for message " +
 $"{context.MessageName} of {context.PrimaryEntityName}");

 //Initialize Tracing / Logger for Application Insights - custom class used to simplify the calls
 Logger logger = new Logger(serviceProvider);
 logger.LogInformation("Tracing / Logging implemented successfully!");

 try
 {
 //For the sample, just create a couple of Tasks on the Case and output details to logging.
 //Also simulate an error scenario, based on the Case Origin value

 Entity incident = (Entity)context.InputParameters["Target"];
 Entity postIncident = context.PostEntityImages["PostImage"];
 logger.LogInformation($"Case ID: {incident.Id}");
 OptionSetValue incidentOrigin = postIncident.GetAttributeValue<OptionSetValue>("caseorigincode");
 logger.LogInformation($"Origin (Value): {incidentOrigin.Value}");

 if (incidentOrigin.Value == facebookCaseOrigin)
 {
 string error = $"Invalid Case Origin specified. Facebook Origin's are not allowed.";
 throw new InvalidPluginExecutionException(error);
 }
 else
 {
 logger.LogInformation($"Creating Tasks for Case ID {incident.Id}");

 //Get a reference to the Organization service.
 IOrganizationServiceFactory factory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
 IOrganizationService service = factory.CreateOrganizationService(context.UserId);

 List<int> taskNumbers = new List<int>()
 {
 1,2,3,4
 };

 foreach(int number in taskNumbers)
 {
 logger.LogInformation($"Processing Task # {number}...");
 Entity task = new Entity("task");
 task["subject"] = $"Case Task # {number}";
 task["scheduledend"] = DateTime.UtcNow.AddDays(7);
 task["regardingobjectid"] = new EntityReference("incident", incident.Id);
 Guid taskID = service.Create(task);
 logger.LogInformation($"Task ID {taskID} created successfully.");
 }

 logger.LogInformation($"Plugin {this.GetType()} execution successfully completed!");
 }
 }
 catch (InvalidPluginExecutionException pex)
 {
 logger.LogError(pex.Message, pex);
 throw;
 }
 catch (FaultException<OrganizationServiceFault> fex)
 {
 string message = fex.Detail.Message;
 string finalMessage = $"An error occurred in the {this.GetType().FullName}:{Environment.NewLine}{message}{Environment.NewLine}{fex}";
 logger.LogError(finalMessage, fex);
 throw new InvalidPluginExecutionException(finalMessage, fex);
 }
 catch (Exception ex)
 {
 string finalMessage = $"An error occurred in the {this.GetType().FullName}:{Environment.NewLine}{ex}";
 logger.LogError(finalMessage, ex);
 throw new InvalidPluginExecutionException(finalMessage, ex);
 }
 }
 }
}

This plug-in requires a post-operation step that should be registered on Update of any column on the Case table (it doesn’t matter which one). The plug-in step will also require a Post Image configuring, as indicated below:

Reviewing the Logs

With logging enabled at the environment level, what we will find is that our Application Insights logs start filling up with execution details for every plug-in within the environment, alongside additional information relating to user requests, API calls and other related telemetry. We, therefore, need to write particular sets of queries to retrieve the information we want. The appropriate object types available to us include:

dependencies: Stores details of all backend SDK operations executed in the environment, such as RetrieveMultiple, Update etc.
exceptions: All custom / unhandled errors will be logged into here
pageViews: Unrelated to our current purposes, we can use this object to see all actions carried out within a model-driven app by each user(s).
requests: This object will log all Web API and Organisation Service Requests made against the environment.
traces: Within here, every single message logged out using the LogInformation method will appear - one row for every single “trace”.

To help get you started, I’ve provided a couple of examples below, alongside an indication of the results we can expect to receive. To execute these, make sure we are in the Logs area of our Application Insights resource:

Return All Errors for Specific Plug-in

exceptions
| order by timestamp
| project timestamp, cloud_RoleInstance, customDimensions["FormattedMessage"], problemId, ['type'], assembly, method, outerType, outerMessage, outerAssembly, outerMethod
| where cloud_RoleInstance contains "SandboxRoleInstance" and method == "JJG.Plugins.AppInsightsSample.Case_OnUpdate_PushAppInsightsSample"

Get All Traces for Specific Plug-in Execution

traces
| project timestamp, message, itemType, customDimensions, operation_Id, session_Id
| where operation_Id == "918c491a-ffd6-4820-a432-3c332ed21248_9d7f35ed-376f-49a7-afa5-05bdc3d88ffe"

Get All Traces for All Failed Plug-in Executions

dependencies
| where type == "Plugin" and name == "JJG.Plugins.AppInsightsSample.Case_OnUpdate_PushAppInsightsSample" and success == false
| project operation_Id, timestamp, target
| join (traces
 | project operation_Id, message
 ) on $left.operation_Id == $right.operation_Id
| order by timestamp

Further Resources

Below are some links to the official Microsoft Docs on this subject - well worth a read, and I’m grateful to these posts in helping to put together this blog post:

What do you think of this new functionality? Beneficial or too much hassle to work with? Let me know your thoughts in the comments below!

What's The Deal with Schedule API? (Dynamics 365 Project Operations)

Sun, 05 Dec 2021 00:00:00 +0000

I had a great time recently getting involved as part of the Microsoft Dynamics ERP User Group, where I presented a session asking (channelling my inner Seinfeld in the process) “What’s the Deal with Schedule API in Dynamics 365 Project Operations?”. Off the back of this session, I wanted to do an accompanying blog post that helps to cover off some of the main topics from my talk and as a resource for anyone interested in diving into this subject again or for the very first time. So without much further ado, let’s jump in to try and answer this question as best as possible.

Schedule API Overview

Schedule API provides developers working with Dynamics 365 Project Operations the only mechanism to automate actions targeting the platform and ensure operations are replicated correctly between Microsoft Dataverse and Project for the web. Rather than using standard Create, Update or Delete actions targeting the core set of Scheduling Tables within Project Operations, developers must instead leverage the Schedule API to carry out these actions. Indeed, this is, in fact, the only supported way we can do this. When we talk about “Scheduling Tables”, we mean any of the following Project Operations table types:

Project Task (msdyn_projecttask)
Project Task Dependency (msdyn_projecttaskdependency)
Resource Assignment (msdyn_resourceassignment)
Project Bucket (msdyn_projectbucket)
Project Team Member (msdyn_projectteam)

The Schedule API’s are built using native capabilities that have been available within Microsoft Dataverse for many years, meaning we can call any of the Schedule API’s in the same way we would for any Custom Action or Custom API. With the Schedule API’s, we can carry out the desired automation and programmatic actions we want against Project Operations, using familiar tools and without the need to write a complex integration ourselves that will persist data out into Project for the web.

How It All Works

Because the actions we carry out within Project Operations / Microsoft Dataverse need to be replicated to Project for the web (and vice-versa), Microsoft provides a shared backend service used to process all actions. The following diagram from Microsoft offers an excellent overview of how this backend service works as we target actions against the Schedule API:

As part of this, developers don’t need to handle complex technical logic; instead, we can let the Schedule API do all the heavy lifting for us. 😀

Supported API’s

At the time of writing this post, the Schedule API supports the following actions:

Creation of new Projects synchronously (via the msdyn_CreateProjectV1 action)
Creation of new Team Members synchronously (via the msdyn_CreateTeamMemberV1 action)
Asynchronous Create, Update or Delete actions targeting any of the Scheduling Tables, using the following actions:
- msdyn_PSSCreateV1
- msdyn_PSSUpdateV1
- msdyn_PSSDeleteV1

OperationSets Overview

As the Schedule API’s rely on the backend services mentioned earlier, a mechanism is needed to ensure we can submit these requests and have complete atomicity as part of our transactions. This is provided for as part of OperationSets, a concept worthy of further discussion. In layman’s terms, these provide a wrapper to bundle all our Schedule API requests together. This request is then passed off to the Schedule API to execute the operations we’ve indicated. As such, every request we make to the Schedule API must be included as part of an OperationSet, and we must also link all OperationSets to a Project. We achieve all of this via a two-step process:

Initialise the OperationSet (via a msdyn_CreateOperationSetV1 request)
Execute the OperationSet (via a msdyn_ExecuteOperationSetV1 request)

Once we execute our OperationSets, this is then processed asynchronously by the backend Schedule API service; therefore, there can sometimes be a slight delay in processing substantial requests.

We can view the list of OperationSets created within Project Operations by navigating to the appropriate area within the sitemap:

For each row, we can then view details regarding its status, the Project associated with the OperationSet and each request added into the OperationSet:

All of this can be incredibly useful from a debugging and diagnosis standpoint.

Schedule API Usage Scenarios

In a nutshell, any scenario requiring you to automate critical operations targeting Project Operations and, specifically, any scheduling tables will be a good candidate for the Schedule API. This will include situations where, for example, you need to:

Batch Processing scenarios from external systems into Project Operations.
Automating the creation of new Projects based on existing template structures.
Handling complex Work Breakdown Structure’s (WBS’s) that are not easy to define manually in Project Operations.

Working with the Schedule API

Because the Schedule API leverages Dataverse actions, we can work with it in a variety of ways, including:

Any .NET application, using the official SDK assemblies from Microsoft.
.NET Dataverse Plug-ins
JavaScript / TypeScript, via the Dataverse Web API
Power Automate Cloud Flows via the Perform unbound action action step.

We can also use tools, such as Postman to test operations targeting the Schedule API. Check out my post from my PL-400 blog series, all about working with the Dataverse Web API to understand how we can do this.

To help better understand and work through some of the common ways we can work with the Schedule API, both via C# and Power Automate, check out the demo project on my GitHub repository, which you can download and experiment further with. I’ve included outline instructions on how to work with each sample provided - let me know in the comments below or on GitHub if you have any problems working with either of them.

Gotchas & Limitations

Helpful that the Schedule API may be, there are a couple of things to keep in mind while you are working with it:

All operations must execute as a fully licensed Project Operations user. This means that using a dedicated Application User account is not supported, as it’s impossible to assign a license to accounts of this type. My recommendation would be to set up a full user account, which you can then utilise as a service account that all automation targeting the Schedule API’s can then run as. Keep in mind that there will be a cost implication for taking the additional license. 😉
Microsoft restricts certain actions targeting specific columns on each of the scheduling tables. For example, we can’t write any information to a Project Task Actual Start or Actual End columns. Be sure to consult the complete list of unsupported columns to avoid getting caught out during your development work.
Any operation you execute using the Schedule API will be subject to any platform-level limitations that Project Operations enforces, such as the limit on the number of tasks and resources on a project. Again, ensure you’ve consulted the relevant Microsoft documentation to avoid any unwelcome surprises.

To full the view list of limitations, you can consult the dedicated Microsoft Docs article section devoted to this subject.

Troubleshooting Schedule API Issues

Things can, invariably, go wrong when working the Schedule API. The API’s do a pretty good job of identifying and throwing back any issues in your Operation Set Details as you submit them to the platform (e.g. if you provide a column that’s not supported with the API’s). Still, things can occasionally go wrong as the OperationSets are processed behind the scenes. For when problems occur, we can consult the PSS Error Log (msdyn_psserrorlog) table, which will log any errors that arise alongside the appropriate error code. The information exposed here can be somewhat limited currently, so you may need to escalate each error, along with its CorrelationId, to Microsoft for further investigation.

Additional Resources

Antti Pajunen remains, as always, my go-to person whenever it comes to anything Project Service Automation or Project Operations, and the following posts are particularly recommended. I’m indebted to the first of these in helping to put together the demos in my GitHub repository:

Another good resource you can turn to, which helps evaluate and understand the expected performance of Schedule API, is the Project Schedule API Performance Benchmarks article, which provides some example execution times for a variety of different request types.

I hope this post has helped remove any doubts or queries you may have had relating to the Schedule API in Dynamics 365 Project Operations. Let me know in the comments below if you have any questions

Blocking Duplicate Quotes in Dynamics 365 Sales Professional / Enterprise (C#)

Sun, 14 Nov 2021 00:00:00 +0000

As you might be able to tell from other recent blog posts, I’ve been doing lots of work lately with Dynamics 365 Sales and, specifically, the Professional variant of the application. Sales Professional can be best thought of as a “lite” CRM system, with much of the same type of functionality as we’d expect from the full-blown Enterprise application. I’ve blogged previously on the subject of differences between the two versions. The only major thing you lose with the Professional application is access to things like Competitors and restrictions on the number of custom tables that you can include as part of your solution. It’s worth consulting the licensing guide to break down the differences in detail before making a decision. Still, if you are in the market for your very first CRM system, you can’t go far wrong with considering Dynamics 365 Sales Professional.

As was the case with last week’s jolly jaunt into Dynamics 365 Sales, I was dealing yet again with another unusual requirement. In this case, the organisation in question wanted to have it so that only a single Draft Quote could ever exist for an Opportunity in the system. As part of the solution, some additional automation and reporting requirements relied upon information present within the most current Quote issued to Customers and salespeople in the organisation were, very often, creating multiple Quotes without realising. So we needed an approach that would prevent the duplicates from ever getting made. Duplicate Detection Rules provide a mechanism to discourage users from creating duplicate rows, but users could still override this if they felt mischievous. Therefore, we decided that a server-side solution and, specifically, a C# plug-in would be required to prevent duplicates from being created altogether. As far as I know, this is the only way we can meet such a requirement; answers on a postcard, though, if you think there’s a better way. 😉 With all of this in mind then, below is the code that was implemented to achieve the requirement:

namespace JJG.MyPlugins
{
 using System;
 using Microsoft.Xrm.Sdk;
 using Microsoft.Xrm.Sdk.Query;

 /// <summary>
 /// Blocks the Create or Update action for a Quote, if it's detected that another Draft Quote exists linked to the same Opportunity.
 /// </summary>
 public class BlockDuplicateQuoteForOpportunity : IPlugin
 {
 public void Execute(IServiceProvider serviceProvider)
 {
 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
 ITracingService tracer = (ITracingService)serviceProvider.GetService(typeof(ITracingService));

 // Check for EntityType and Message supported by your Plug-In
 if (!(context.MessageName == "Create" || context.MessageName == "Update") || context.PrimaryEntityName != "quote")
 {
 throw new InvalidPluginExecutionException($"Plug-In {this.GetType()} is not supported for message {context.MessageName} of {context.PrimaryEntityName}");
 }

 tracer.Trace($"Starting execution of {nameof(BlockDuplicateQuoteForOpportunity)}");

 // Get the newly create Quote (Create) or the Post Image for the Quote (Update), and the Opportunity lookup value
 Entity quote = (Entity)context.InputParameters["Target"];
 EntityReference opportunity = quote.GetAttributeValue<EntityReference>("opportunityid");

 if (opportunity == null)
 {
 tracer.Trace($"No Opportunity is present for Quote ID {quote.Id}. Cancelling plug-in execution");
 return;
 }

 // Attempt to retrieve other Draft Quotes that are linked to the same Opportunity ID we have here
 tracer.Trace($"Attempting to retrieve other Quote rows linked to Opportunity ID {opportunity.Id}...");

 IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
 IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

 QueryExpression qe = new QueryExpression()
 {
 EntityName = "quote",
 ColumnSet = new ColumnSet("quoteid"),
 Criteria =
 {
 Conditions =
 {
 new ConditionExpression("opportunityid", ConditionOperator.Equal, opportunity.Id),
 new ConditionExpression("statecode", ConditionOperator.Equal, 0),
 new ConditionExpression("quoteid", ConditionOperator.NotEqual, quote.Id),
 },
 },
 };

 EntityCollection quotes = service.RetrieveMultiple(qe);
 tracer.Trace($"Got {quotes.Entities.Count} Quotes!");

 // If one or more exist, then we throw an error to block the Create / Association
 if (quotes.Entities.Count >= 1)
 {
 tracer.Trace($"Multiple Draft Quotes exist for Opportunity ID {opportunity.Id}. Throwing error to cancel operation...");
 throw new InvalidPluginExecutionException("Draft Quote(s) already exist for the selected Opportunity. Only a single Draft Quote is allowed. Please edit or delete the other Draft Quote(s) before proceeding.");
 }
 else
 {
 tracer.Trace($"No other Draft Quotes are linked to Opportunity ID {opportunity.Id}. No action required. Cancelling plug-in execution");
 return;
 }
 }
 }
}

When registering this plug-in into the application, ensure that it’s aligned to the Post-Operation step on the following messages indicated below:

For the Update step, we also specifically filter on just the opportunityid row, to ensure the plug-in doesn’t fire unnecessarily:

When the user then attempts to create or associate more than one Quote to a single Opportunity, this will be the error message they will receive:

Because the plug-in throws the InvalidPluginExecutionException error message, the platform will roll back the entire transaction. We can then inject our own custom message into the dialog that appears.

As alluded to earlier, having a low/no-code solution to achieve this requirement would be preferred. But, unless I’m missing something obvious, doing something similar via a real-time workflow would be impossible due to the RetrieveMultiple request we have to perform to get other pre-existing Quotes. As much as I make a living out of implementing these types of solutions, we should always be cautious of adopting a code-first mindset if other routes are available to us within Dynamics 365 Sales and the Power Platform. Take care to understand the “baggage” involved with a solution like this so that you don’t get caught out in future as part of an upgrade or when you later incorporate additional functionality into the equation.

Reopening Won Quotes in Dynamics 365 Sales Professional / Enterprise (C#)

Sun, 07 Nov 2021 00:00:00 +0000

After you’ve spent any length of time working with the out of the box sales process within Dynamics 365 Sales Professional / Enterprise, you get used to some of the behavioural quirks that can commonly cause you challenges during an implementation. A prime candidate for consideration here concerns the various types of tables used by the application. When we consider these in detail, such as the Opportunity, Quote and Order table, many of the assumptions that we make about how things work are instantly proven wrong, as these tables tend to operate by their own set of rules. For example, the ability to easily map across attributes between the different product line table types (Opportunity Product, Quote Product etc.) becomes a challenge; we must instead revert to using custom code instead to satisfy this requirement. Little things like this can exasperate both new and long-time users of the application and can often be quite frustrating when explaining to organisations using the software. 😅 Notwithstanding these gripes, I still do genuinely believe the Dynamics 365 Sales platform provides a solid base for organisations to leverage out of the box functionality, with the ability to customise further, as needed. And, when we start to bring into the equation more advanced capabilities, via things such as custom pricing plug-ins, you begin to move to an entirely new level when it comes to what we can do with this application.

A particularly annoying behaviour quirk I dealt with recently involved Quotes marked as Won in the system. The organisation I was working with needed to, on occasions, modify details of a Won Quote after the fact. For example, if the salesperson included the wrong item or the customer changed their order after confirming it. As we can observe in the below screenshot, we have no option on the ribbon to reactivate the Quote once Won in the application:

The only “out of the box” way of dealing with this was to create and re-input all details into a new Quote; not a viable and time-effective solution. Fortunately, there is a faster way we can achieve the objective by working through the following outline steps:

First, we need to change the Status & Status Reason of the Quote back to Draft & In Progress.
After we have made modifications to the Quote, it needs to be set as Active again.
Once Active, the Quote then must be closed as Won. Microsoft wraps the logic for this within the WinQuote action, which we can call via the SDK or against the Microsoft Dataverse Web API.

These steps should be achievable via either a classic workflow or a Power Automate cloud flow automation, which would typically be our first preference for a requirement like this. However, in our case, we wanted to call these steps as part of a Custom API definition, which could then be called via a JavaScript action on a Ribbon button, similar to how I’ve described previously on the blog. And, most crucially, we needed all steps to be completed synchronously. So, given these requirements, we had to look at a solution leveraging C# instead.

With all of this in mind, let’s jump into the reason why you’re probably reading this post. 😉 To open a Won Quote using C#, we would need to write and execute the following code:

//TODO: Implement code to generate your IOrganizationService reference. For plug-ins, this would look something like this:
//IOrganizationServiceFactory serviceFactory = serviceProvider.GetService<IOrganizationServiceFactory>();
//IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

Guid quoteID = new Guid("9cc66ad5-2506-4394-854d-f60c35185d96");
Entity quote = new Entity("quote", quoteID);
quote["statecode"] = new OptionSetValue(0); // Draft
quote["statuscode"] = new OptionSetValue(1); // In Progress
service.Update(quote);

Then, once we’re ready to return the Quote to its previous state, we’d then run the following code to re-close the Quote. Note in particular, at this stage, we need to execute two separate actions and ensure they are completed successfully:

//TODO: Implement code to generate your IOrganizationService reference. For plug-ins, this would look something like this:
//IOrganizationServiceFactory serviceFactory = serviceProvider.GetService<IOrganizationServiceFactory>();
//IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

// We execute everything in a transaction, so we can rollback cleanly on failure
ExecuteTransactionRequest transactionRequest = new ExecuteTransactionRequest()
{
 Requests = new OrganizationRequestCollection(),
 ReturnResponses = true,
};
ExecuteTransactionResponse transactionResponse;

Guid quoteID = new Guid("9cc66ad5-2506-4394-854d-f60c35185d96");

// First, we need to Activate the Quote ...
Entity quote = new Entity("quote", quoteID);
quote["statecode"] = new OptionSetValue(1); // Active
quote["statuscode"] = new OptionSetValue(2); // In Progress

UpdateRequest updateRequest = new UpdateRequest()
{
 Target = quote,
};

transactionRequest.Requests.Add(updateRequest);

// ...with this done, now we can re-close the Quote as Won
Entity quoteClose = new Entity("quoteclose");
quoteClose["subject"] = "Quote Close" + DateTime.Now.ToString();
quoteClose["quoteid"] = quote.ToEntityReference();

WinQuoteRequest winQuoteRequest = new WinQuoteRequest()
{
 QuoteClose = quoteClose,
 Status = new OptionSetValue(-1),
};

transactionRequest.Requests.Add(winQuoteRequest);

transactionResponse = (ExecuteTransactionResponse)service.Execute(transactionRequest);
tracer.Trace($"Quote ID {quoteID} closed as won successfully!");

As stated earlier, if there wasn’t a need to execute these actions synchronously, then leveraging Power Automate cloud flows would be something I’d actively encourage instead, as both the ability to update and call action steps are supported via this tool. So before you act too gung-ho with the above, validate your approach against the requirements you are working against.

Regardless of the precise approach you take, it is a minor point of frustration that these types of steps are not natively supported within Dynamics 365 Sales. I understand why the system behaves like this, and there are arguable benefits to having a Quote locked after it’s been approved. However, I imagine the ability to make quick edits to a Won Quote is a common requirement across many different organisations, and expecting users to have to go through raising an entirely new Quote is both impractical and ludicrous in equal measure. It’s good to know that the underlying platform supports us in building workarounds such as this so that we are not left entirely adrift with a system that must fit around the business instead of the other way around.

Exam PL-400 Revision Notes: Series Roundup

Sun, 27 Jun 2021 00:00:00 +0000

Welcome to the final post in my series focused on providing a set of revision notes for the PL-400: Microsoft Power Platform Developer exam. In today’s post, I wanted to consolidate all of the content from the series into a single, concise post for ease of access. I’ll also provide some general advice and tips that I hope will come in useful for when you sit the exam.

This series has aimed to provide a broad outline of the core areas to keep in mind when tackling the exam, linked to appropriate resources for more focused study. Ideally, your revision should involve a high degree of hands-on testing and familiarity in working with the platform if you want to do well in this exam.

Microsoft has split the PL-400 exam into several different areas based on the specification found here. Therefore, I have linked below to the relevant blog/video content from the series for each applicable subject.

Create a technical design (10-15%)

Validate requirements and design technical architecture

design and validate the technical architecture for a solution
design authentication and authorization strategy
determine whether you can meet requirements with out-of-the-box functionality
determine when to use Logic Apps versus Power Automate flows
determine when to use serverless computing, plug-ins, or Power Automate
determine when to build a virtual entity data source provider and when to use connectors

Design solution components

design a data model
design Power Apps reusable components
design custom connectors
design server-side components

Describe Microsoft Power Platform extensibility points

describe Power Virtual Agents extensibility points including Bot Framework skills and Power Automate flows
describe Power BI extensibility points including Power BI APIs, custom visuals, and embedding Power BI apps in websites and other applications
describe Power Apps portal extensibility points including CRUD APIs and custom styling
describe Web Resources and their uses

Blog Posts

Exam PL-400 Revision Notes: Designing a Technical Architecture for the Power Platform

Exam PL-400 Revision Notes: Designing Solution Components within the Power Platform

Exam PL-400 Revision Notes: Reviewing Power Platform Extensibility Points

Configure Microsoft Dataverse (15-20%)

Configure security to support development

troubleshoot operational security issues
create or update security roles and field-level security profiles
configure business units and teams

Implement tables and columns

configure tables and table options
configure columns
configure relationships and types of behaviours

Implement application lifecycle management (ALM)

create solutions and manage solution components
import and export solutions
manage solution dependencies
create a package for deployment
automate deployments
implement source control for projects including solutions and code assets

Blog Posts

Exam PL-400 Revision Notes: Using Solutions to implement Application Lifecycle Management (ALM) Capabilities

Exam PL-400 Revision Notes: Modelling Data using Tables, Columns & Relationships in Microsoft Dataverse

Exam PL-400 Revision Notes: Implementing Security within Microsoft Dataverse

Videos

PL-400 Exam Prep: Creating and Deploying a Managed Solution

PL-400 Exam Prep: Working with the Solution Packager Tool

PL-400 Exam Prep: Extracting and Deploying Solutions using Azure DevOps

PL-400 Exam Prep: Working with Tables, Columns & Relationships in Microsoft Dataverse

PL-400 Exam Prep: Understanding Security in Microsoft Dataverse

Create and configure Power Apps (15-20%)

Create model-driven apps

configure a model-driven app
configure forms
configure columns
configure visualizations
configure commands and buttons

Create canvas apps

create and configure a canvas app
implement complex formulas to manage control events and properties
analyze app usage by using App Insights
build reusable component libraries

Manage and troubleshoot apps

troubleshoot app issues by using Monitor and other browser-based debugging tools
interpret results from App Checker and Solution Checker
identify and resolve connector and API errors
optimize app performance including pre-loading data and query delegation

Blog Posts

Exam PL-400 Revision Notes: Working with Model-Driven Power Apps

Exam PL-400 Revision Notes: Working with Canvas Apps

Exam PL-400 Revision Notes: Managing and Troubleshooting a Power App

Videos

PL-400 Exam Prep: Creating a Model-Driven Power App Form, Form, View, Chart & Dashboard

PL-400 Exam Prep: Working with Canvas Power Apps

Configure business process automation (5-10%)

Configure Power Automate

create and configure a flow
configure steps to use Dataverse connector actions and triggers
implement complex expressions in flow steps
implement error handling
troubleshoot flows by analyzing JSON responses from connectors

Implement processes

create and configure business process flows
create and configure business rules
create, manage, and interact with business process flows by using server-side and client-side code
troubleshoot processes

Blog Posts

Exam PL-400 Revision Notes: Working with Power Automate Flows

Exam PL-400 Revision Notes: Implementing Business Process Flows and Business Rules

Videos

PL-400 Exam Prep: Business Process Automation Using Power Automate Cloud Flows

PL-400 Exam Prep: Designing and Interacting with a Business Process Flow

PL-400 Exam Prep: Working with Business Rules

Extend the user experience (10-15%)

Apply business logic using client scripting

create JavaScript or TypeScript code that targets the Client API object model
register an event handler
create client-side scripts that target the Dataverse Web API

Create a Power Apps Component Framework (PCF) component

describe the PCF component lifecycle
initialize a new PCF component
configure a PCF component manifest
implement the component interfaces
package, deploy, and consume the component
configure and use PCF Device, Utility, and WebAPI features
test and debug PCF components by using the local test harness

Create a command button function

create commands
design command button rules and actions
edit the command bar by using the Ribbon Workbench
manage dependencies between JavaScript libraries

Blog Posts

Exam PL-400 Revision Notes: Implementing Client-Side Scripting on Model Driven Power Apps

Exam PL-400 Revision Notes: Creating a Power Apps Component Framework (PCF) Control

Exam PL-400 Revision Notes: Working with Ribbon Command Buttons

Videos

PL-400 Exam Prep: Creating a Basic JavaScript Form Function for a Model Driven Power App Form

PL-400 Exam Prep: Building & Deploying a Power Apps Component Framework (PCF) Control

PL-400 Exam Prep: Using the Ribbon Workbench to Create a Simple Command Button

Extend the platform (15-20%)

Create a plug-in

describe the plug-in execution pipeline
design and develop a plug-in
debug and troubleshoot a plug-in
implement business logic by using pre-images and post-images
perform operations on data by using the Organization service API
optimize plug-in performance
register custom assemblies by using the Plug-in Registration Tool
develop a plug-in that targets a custom action message

Create custom connectors

create a definition for the API
configure API security
use policy templates to modify connector behavior at runtime
expose Azure Functions as custom connectors
create custom connectors for public APIs by using Postman

Use platform APIs

interact with data and processes by using the Dataverse Web API or the Organization Service
implement API limit retry policies
optimize for performance, concurrency, transactions, and batching
query the Global Discovery service to discover the URL and other information for an organization
perform entity metadata operations with the Web API
perform authentication by using OAuth

Process workloads

process long-running operations by using Azure Functions
configure scheduled and event-driven function triggers in Azure Functions
authenticate to the Microsoft Power Platform by using managed identities

Blog Posts

Exam PL-400 Revision Notes: Building, Deploying & Debugging Plug-ins using C#

Exam PL-400 Revision Notes: Building a Power Platform Custom Connector

Exam PL-400 Revision Notes: Working with the Microsoft Dataverse Web API and Processing Workloads

Videos

PL-400 Exam Prep: Creating a Microsoft Dataverse Plug-in using Visual Studio 2019 & C#

PL-400 Exam Prep: Deploying a Microsoft Dataverse Plug-in using the Plug-in Registration Tool

PL-400 Exam Prep: Debugging a Microsoft Dataverse Plug-in using Trace Logging

PL-400 Exam Prep: Debugging a Microsoft Dataverse Plug-in Using the Plug-in Registration Tool

PL-400 Exam Prep: Creating a Custom Connector for an Azure Function

PL-400 Exam Prep: Authenticating into the Microsoft Dataverse Web API

PL-400 Exam Prep: Working with the Microsoft Dataverse Global Discovery Endpoint

PL-400 Exam Prep: Performing Common Operations with the Microsoft Dataverse API

PL-400 Exam Prep: Performing Batch Operations using the Microsoft Dataverse Web API

Develop Integrations (5-10%)

Publish and consume events

publish an event by using the API
publish an event by using the Plug-in Registration Tool
register service endpoints including webhooks, Azure Service Bus, and Azure Event Hub
implement a Dataverse listener for an Azure solution
create an Azure Function that interacts with Microsoft Power Platform

Implement data synchronization

configure entity change tracking
read entity change records by using platform APIs
create and use alternate keys

Blog Posts

Exam PL-400 Revision Notes: Publishing and Consuming Events

Exam PL-400 Revision Notes: Implementing Data Synchronisation using Microsoft Dataverse

Videos

PL-400 Exam Prep: Posting Microsoft Dataverse Events to Azure Service Bus

PL-400 Exam Prep: Registering & Consuming a Microsoft Dataverse Webhook from an Azure Function

PL-400 Exam Prep: Working with Change Tracking in the Microsoft Dataverse Web API

PL-400 Exam Prep: Working with Alternate Keys in the Microsoft Dataverse Web API

General Exam Preparation Tips

Hands-on preparation is essential if you wish to do well in the exam. You should ideally set up a Power Apps Developer Plan environment that you can use to experiment with the core functionality within the Power Platform.
Keep abreast of the latest Microsoft Docs and Learning Path materials that are related to this exam, as the platform is continually changing all of the time.
Familiarise yourself with the general format, length and expected types of questions within a Microsoft exam. If you want to get a feel for the level and type of questions to expect on the exam, you can also purchase an official practice test from Measure Up.
Due to the ongoing COVID-19 situation, you will more than likely have to sit your exam using the online proctored experience. Take some time to familiarise yourself with the process involved here, and perform a system test well in advance of your exam date - the last thing you need on the day of the exam is to stress out due to a system or access issue.

I hope that you’ve found this series useful. Good luck when sitting the exam, and let me know how you got on!

Exam PL-400 Revision Notes: Publishing and Consuming Events

Sun, 13 Jun 2021 00:00:00 +0000

Welcome to the eighteenth post in my series focused on providing a set of revision notes for the PL-400: Microsoft Power Platform Developer exam. Last time around, we explored some of the capabilities offered by the Microsoft Dataverse Web API, which can be particularly useful when you are building integrations targeting this platform. This post finished our discussion on the Extend the platform area of the exam, which has a 15-20% total weighting. We now move into the final exam area, Develop Integrations and our first subject area concerning events:

Publish and consume events

publish an event by using the API

publish an event by using the Plug-in Registration Tool

register service endpoints including webhooks, Azure Service Bus, and Azure Event Hub

implement a Common Data Service listener for an Azure solution

create an Azure Function that interacts with Power Platform

Although this area of the exam has a somewhat low weighting (5-10%) when compared with the other subjects we’ve looked at, there is still some essential things to learn here that is not only relevant to the exam itself but also for your daily travels with the platform. Events are just one way in which you can integrate your Microsoft Dataverse environment alongside Microsoft Azure. Developing modern cloud applications involving core Microsoft products invariably means you must have a general awareness of the capabilities within Azure, so this topic provides an excellent opportunity to increase your knowledge in this area. Let’s dive in now to see what events are all about and how they relate to Azure!

As with all posts in this series, the aim is to provide a broad outline of the core areas to keep in mind when tackling the exam, linked to appropriate resources for more focused study. Ideally, your revision should involve a high degree of hands-on testing and familiarity in working with the platform if you want to do well in this exam. It would help if you also understand working with plug-ins and the Plug-in Registration Tool, which we’ve already covered in the series.

What are Events?

You may be worried at this stage that events are a whole new concept that will take considerable time to understand. Fortunately, that’s not the case at all and, if you have good familiarity working with the IExecutionContext Interface from within a plug-in, you will find yourself right at home. This is because Events encapsulate all data points that we would typically work within our execution context - whether that be shared variables, output parameters, Business Unit ID or more. An example of how an event can look, when passed out as a JSON object, can be seen below:

{
 "BusinessUnitId": "f64c9d1f-d076-ea11-a812-000d3a86a586",
 "CorrelationId": "dfe79039-5a08-4d0a-b4ee-9534625c8654",
 "Depth": 1,
 "InitiatingUserAzureActiveDirectoryObjectId": "00000000-0000-0000-0000-000000000000",
 "InitiatingUserId": "c164a5aa-765e-4181-8771-537e8b1ebf3b",
 "InputParameters": [
 {
 "key": "Target",
 "value": {
 "__type": "Entity:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Attributes": [
 {
 "key": "territorycode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "address2_freighttermscode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "address2_shippingmethodcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "isprivate",
 "value": false
 },
 {
 "key": "followemail",
 "value": true
 },
 {
 "key": "donotbulkemail",
 "value": false
 },
 {
 "key": "donotsendmm",
 "value": false
 },
 {
 "key": "emailaddress1",
 "value": "john@domain.com"
 },
 {
 "key": "jobtitle",
 "value": "Manager"
 },
 {
 "key": "customertypecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "fullname",
 "value": "John Doe"
 },
 {
 "key": "isautocreate",
 "value": false
 },
 {
 "key": "ownerid",
 "value": {
 "__type": "EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Id": "c164a5aa-765e-4181-8771-537e8b1ebf3b",
 "KeyAttributes": [],
 "LogicalName": "systemuser",
 "Name": null,
 "RowVersion": null
 }
 },
 {
 "key": "isbackofficecustomer",
 "value": false
 },
 {
 "key": "donotbulkpostalmail",
 "value": false
 },
 {
 "key": "donotpostalmail",
 "value": false
 },
 {
 "key": "donotemail",
 "value": false
 },
 {
 "key": "statecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 0
 }
 },
 {
 "key": "address2_addresstypecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "donotphone",
 "value": false
 },
 {
 "key": "createdon",
 "value": "/Date(1598771723000)/"
 },
 {
 "key": "transactioncurrencyid",
 "value": {
 "__type": "EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Id": "785af3f0-d976-ea11-a812-000d3a86a586",
 "KeyAttributes": [],
 "LogicalName": "transactioncurrency",
 "Name": null,
 "RowVersion": null
 }
 },
 {
 "key": "contactid",
 "value": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce"
 },
 {
 "key": "haschildrencode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "modifiedby",
 "value": {
 "__type": "EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Id": "c164a5aa-765e-4181-8771-537e8b1ebf3b",
 "KeyAttributes": [],
 "LogicalName": "systemuser",
 "Name": null,
 "RowVersion": null
 }
 },
 {
 "key": "leadsourcecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "statuscode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "modifiedonbehalfby",
 "value": null
 },
 {
 "key": "preferredcontactmethodcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "lastname",
 "value": "Doe"
 },
 {
 "key": "firstname",
 "value": "John"
 },
 {
 "key": "createdby",
 "value": {
 "__type": "EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Id": "c164a5aa-765e-4181-8771-537e8b1ebf3b",
 "KeyAttributes": [],
 "LogicalName": "systemuser",
 "Name": null,
 "RowVersion": null
 }
 },
 {
 "key": "educationcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "yomifullname",
 "value": "John Doe"
 },
 {
 "key": "donotfax",
 "value": false
 },
 {
 "key": "merged",
 "value": false
 },
 {
 "key": "customersizecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "marketingonly",
 "value": false
 },
 {
 "key": "owningbusinessunit",
 "value": {
 "__type": "EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Id": "f64c9d1f-d076-ea11-a812-000d3a86a586",
 "KeyAttributes": [],
 "LogicalName": "businessunit",
 "Name": null,
 "RowVersion": null
 }
 },
 {
 "key": "shippingmethodcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "creditonhold",
 "value": false
 },
 {
 "key": "modifiedon",
 "value": "/Date(1598771723000)/"
 },
 {
 "key": "participatesinworkflow",
 "value": false
 },
 {
 "key": "preferredappointmenttimecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "exchangerate",
 "value": 1.0
 }
 ],
 "EntityState": null,
 "FormattedValues": [
 {
 "key": "territorycode",
 "value": "Default Value"
 },
 {
 "key": "address2_freighttermscode",
 "value": "Default Value"
 },
 {
 "key": "address2_shippingmethodcode",
 "value": "Default Value"
 },
 {
 "key": "isprivate",
 "value": "No"
 },
 {
 "key": "followemail",
 "value": "Allow"
 },
 {
 "key": "donotbulkemail",
 "value": "Allow"
 },
 {
 "key": "donotsendmm",
 "value": "Send"
 },
 {
 "key": "customertypecode",
 "value": "Default Value"
 },
 {
 "key": "isautocreate",
 "value": "No"
 },
 {
 "key": "isbackofficecustomer",
 "value": "No"
 },
 {
 "key": "donotbulkpostalmail",
 "value": "No"
 },
 {
 "key": "donotpostalmail",
 "value": "Allow"
 },
 {
 "key": "donotemail",
 "value": "Allow"
 },
 {
 "key": "statecode",
 "value": "Active"
 },
 {
 "key": "address2_addresstypecode",
 "value": "Default Value"
 },
 {
 "key": "donotphone",
 "value": "Allow"
 },
 {
 "key": "createdon",
 "value": "2020-08-30T07:15:23-00:00"
 },
 {
 "key": "haschildrencode",
 "value": "Default Value"
 },
 {
 "key": "leadsourcecode",
 "value": "Default Value"
 },
 {
 "key": "statuscode",
 "value": "Active"
 },
 {
 "key": "preferredcontactmethodcode",
 "value": "Any"
 },
 {
 "key": "educationcode",
 "value": "Default Value"
 },
 {
 "key": "donotfax",
 "value": "Allow"
 },
 {
 "key": "merged",
 "value": "No"
 },
 {
 "key": "customersizecode",
 "value": "Default Value"
 },
 {
 "key": "marketingonly",
 "value": "No"
 },
 {
 "key": "shippingmethodcode",
 "value": "Default Value"
 },
 {
 "key": "creditonhold",
 "value": "No"
 },
 {
 "key": "modifiedon",
 "value": "2020-08-30T07:15:23-00:00"
 },
 {
 "key": "participatesinworkflow",
 "value": "No"
 },
 {
 "key": "preferredappointmenttimecode",
 "value": "Morning"
 }
 ],
 "Id": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce",
 "KeyAttributes": [],
 "LogicalName": "contact",
 "RelatedEntities": [],
 "RowVersion": "4198516"
 }
 }
 ],
 "IsExecutingOffline": false,
 "IsInTransaction": false,
 "IsOfflinePlayback": false,
 "IsolationMode": 1,
 "MessageName": "Create",
 "Mode": 1,
 "OperationCreatedOn": "/Date(1598771723000+0000)/",
 "OperationId": "b1b1d88b-90ea-ea11-a815-000d3a86a3ce",
 "OrganizationId": "9c5d5db0-47c7-4741-aa25-08eb4cdf59a3",
 "OrganizationName": "orgad623a9e",
 "OutputParameters": [
 {
 "key": "id",
 "value": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce"
 }
 ],
 "OwningExtension": {
 "Id": "aa45df79-90ea-ea11-a815-000d3a86a3ce",
 "KeyAttributes": [],
 "LogicalName": "sdkmessageprocessingstep",
 "Name": null,
 "RowVersion": null
 },
 "ParentContext": {
 "BusinessUnitId": "f64c9d1f-d076-ea11-a812-000d3a86a586",
 "CorrelationId": "dfe79039-5a08-4d0a-b4ee-9534625c8654",
 "Depth": 1,
 "InitiatingUserAzureActiveDirectoryObjectId": "00000000-0000-0000-0000-000000000000",
 "InitiatingUserId": "c164a5aa-765e-4181-8771-537e8b1ebf3b",
 "InputParameters": [
 {
 "key": "Target",
 "value": {
 "__type": "Entity:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Attributes": [
 {
 "key": "emailaddress1",
 "value": "john@domain.com"
 },
 {
 "key": "jobtitle",
 "value": "Manager"
 },
 {
 "key": "lastname",
 "value": "Doe"
 },
 {
 "key": "firstname",
 "value": "John"
 },
 {
 "key": "creditonhold",
 "value": false
 },
 {
 "key": "donotpostalmail",
 "value": false
 },
 {
 "key": "donotfax",
 "value": false
 },
 {
 "key": "donotphone",
 "value": false
 },
 {
 "key": "donotbulkemail",
 "value": false
 },
 {
 "key": "followemail",
 "value": true
 },
 {
 "key": "donotemail",
 "value": false
 },
 {
 "key": "preferredcontactmethodcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "statuscode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "donotbulkpostalmail",
 "value": false
 },
 {
 "key": "transactioncurrencyid",
 "value": {
 "__type": "EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Id": "785af3f0-d976-ea11-a812-000d3a86a586",
 "KeyAttributes": [],
 "LogicalName": "transactioncurrency",
 "Name": null,
 "RowVersion": null
 }
 },
 {
 "key": "ownerid",
 "value": {
 "__type": "EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Id": "c164a5aa-765e-4181-8771-537e8b1ebf3b",
 "KeyAttributes": [],
 "LogicalName": "systemuser",
 "Name": null,
 "RowVersion": null
 }
 },
 {
 "key": "preferredappointmenttimecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "customersizecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "address2_shippingmethodcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "address2_freighttermscode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "educationcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "isautocreate",
 "value": false
 },
 {
 "key": "leadsourcecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "shippingmethodcode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "participatesinworkflow",
 "value": false
 },
 {
 "key": "marketingonly",
 "value": false
 },
 {
 "key": "territorycode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "isprivate",
 "value": false
 },
 {
 "key": "isbackofficecustomer",
 "value": false
 },
 {
 "key": "merged",
 "value": false
 },
 {
 "key": "donotsendmm",
 "value": false
 },
 {
 "key": "address2_addresstypecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "customertypecode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "haschildrencode",
 "value": {
 "__type": "OptionSetValue:http://schemas.microsoft.com/xrm/2011/Contracts",
 "Value": 1
 }
 },
 {
 "key": "contactid",
 "value": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce"
 }
 ],
 "EntityState": null,
 "FormattedValues": [],
 "Id": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce",
 "KeyAttributes": [],
 "LogicalName": "contact",
 "RelatedEntities": [],
 "RowVersion": null
 }
 },
 {
 "key": "SuppressDuplicateDetection",
 "value": false
 }
 ],
 "IsExecutingOffline": false,
 "IsInTransaction": false,
 "IsOfflinePlayback": false,
 "IsolationMode": 1,
 "MessageName": "Create",
 "Mode": 1,
 "OperationCreatedOn": "/Date(1598771723000+0000)/",
 "OperationId": "b1b1d88b-90ea-ea11-a815-000d3a86a3ce",
 "OrganizationId": "9c5d5db0-47c7-4741-aa25-08eb4cdf59a3",
 "OrganizationName": "orgad623a9e",
 "OutputParameters": [],
 "OwningExtension": {
 "Id": "aa45df79-90ea-ea11-a815-000d3a86a3ce",
 "KeyAttributes": [],
 "LogicalName": "sdkmessageprocessingstep",
 "Name": null,
 "RowVersion": null
 },
 "ParentContext": null,
 "PostEntityImages": [],
 "PreEntityImages": [],
 "PrimaryEntityId": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce",
 "PrimaryEntityName": "contact",
 "RequestId": "bda24fe5-1f23-4c96-a4ab-34739a2f5628",
 "SecondaryEntityName": "none",
 "SharedVariables": [
 {
 "key": "IsAutoTransact",
 "value": true
 },
 {
 "key": "DefaultsAddedFlag",
 "value": true
 },
 {
 "key": "ChangedEntityTypes",
 "value": [
 {
 "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
 "key": "contact",
 "value": "Update"
 }
 ]
 }
 ],
 "Stage": 30,
 "UserAzureActiveDirectoryObjectId": "00000000-0000-0000-0000-000000000000",
 "UserId": "c164a5aa-765e-4181-8771-537e8b1ebf3b"
 },
 "PostEntityImages": [
 {
 "key": "AsynchronousStepPrimaryName",
 "value": {
 "Attributes": [
 {
 "key": "fullname",
 "value": "John Doe"
 },
 {
 "key": "contactid",
 "value": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce"
 }
 ],
 "EntityState": null,
 "FormattedValues": [],
 "Id": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce",
 "KeyAttributes": [],
 "LogicalName": "contact",
 "RelatedEntities": [],
 "RowVersion": null
 }
 }
 ],
 "PreEntityImages": [],
 "PrimaryEntityId": "a2b1d88b-90ea-ea11-a815-000d3a86a3ce",
 "PrimaryEntityName": "contact",
 "RequestId": "bda24fe5-1f23-4c96-a4ab-34739a2f5628",
 "SecondaryEntityName": "none",
 "SharedVariables": [
 {
 "key": "IsAutoTransact",
 "value": true
 },
 {
 "key": "DefaultsAddedFlag",
 "value": true
 }
 ],
 "Stage": 40,
 "UserAzureActiveDirectoryObjectId": "00000000-0000-0000-0000-000000000000",
 "UserId": "c164a5aa-765e-4181-8771-537e8b1ebf3b"
}

The main difference with events is how we consume them; that is, outside of the application, as opposed to inside. There are a variety of reasons why it may be desirable to do this:

As we saw when discussing plug-ins, there are some particular limitations that sandbox processing can impose on your custom code - such as the restricted use of third party libraries and the 2-minute maximum execution time. However, by processing these operations external from Microsoft Dataverse, developers can circumvent these restrictions while still benefitting from working with the same type of information typically available as part of a standard plug-in.
For situations where your environment is processing hundreds or even thousands of record changes each hour, that then need to be processed asynchronously, events provide the most streamlined mechanism for achieving this. Also, it helps to reduce the reliance on the platform and the applications Asynchronous service in performing complex processing of these requests; instead, they can be straightforwardly “passed on” to a dedicated service responsible for this.
It may be necessary to immediately trigger an external endpoint or API as soon as a user creates, updates or deletes a table row. By using events alongside Webhooks (more on this shortly), developers have a streamlined mechanism to meet this requirement.
With the recent changes announced around API request and service protection limits at the platform level, developers may struggle to use the traditional plug-in assembly route to process complex operations. As such, we can realise benefits by moving this processing outside of the application and, as part of this, avoid hitting any nasty error messages resulting from an overage in the number of processed platform requests.

In most cases, you will typically use one of several different Microsoft Azure services when processing events received from the application. However, there are options available to integrate alongside other cloud platforms or systems. For the exam, focusing and having an awareness of the Azure options will be essential.

Understanding Service Endpoints & the Azure Service Bus

There are two core concepts to understand alongside events - service endpoints and the Azure Service Bus:

Service Endpoints: This defines the location you wish to write your events out to for further processing. In pretty much all cases, you will want to use the Plug-in Registration Tool to create your service endpoint, but you can also deploy one programmatically via the web API. You can also use a service endpoint to receive incoming requests back into Microsoft Dataverse for processing. Once defined, you must then register the appropriate steps that will trigger your endpoint request, much in the same way as defining a plug-in step (e.g. Update on Contact, Delete on Lead, etc.). An advantage with this is that we can include pre/post table images as part of each event payload. However, the critical thing to remember is that we must specify these as asynchronous operations; synchronous calls are not allowed. In most cases, your service endpoint will target an Azure Service Bus queue, but you can also configure an Azure Event Hub endpoint as well.
Azure Service Bus: Depending on the type of integration you are attempting to perform, the synchronous (i.e. all at once) processing of information may not be needed or desirable. This could be down to the single fact that the number of potential requests to process will be too high. For when this is relevant, Azure Service Bus comes into the equation by offering a decoupled, asynchronous mechanism to receive, analyse and route multiple requests to an intended destination - whether this is a database, another endpoint or a storage location. The service bus will process all events it receives in order, holding onto each request for as long as is necessary before handing it off. As well as allowing for a predictable flow of information, it can also provide assurances from a failure standpoint; if, for example, the backend endpoint goes offline for whatever reason, messages will remain in the queue and resume processing as soon as the endpoint comes back online. Developers have flexibility over the type of Azure Service Bus listener service to implement, which Microsoft outlines in this article, but the most common scenario is to use a queue. We can also define the format of events that get written out by the Azure Service Bus listener but, in most cases, outputting this as JSON will be the recommended option.

Demo: Posting Microsoft Dataverse Events to Azure Service Bus

In this video, we’ll walk through how to deploy out an Azure Service Bus resource and configure a service endpoint to receive requests from Microsoft Dataverse:

Webhooks Overview

A webhook is a lightweight mechanism for integrating multiple Web API’s. It operates on a publish and subscribe model; namely, we publish an event out, and an external endpoint subscribes to each event, processing it as it sees fit. As semi-automated, standard HTTP requests in their simplest form, they conform broadly to this pattern and - if they are a new concept - you should experience little difficulty in understanding them if you’ve previously worked with RESTful Web API’s. Webhooks are commonplace these days, both in the Microsoft world and across other vendors as well. For example, Azure supports the ability to write out any log alert event as a webhook to an endpoint of your choosing.

From a Microsoft Dataverse perspective, developers can register custom webhooks to any endpoint of their choosing. We can handle authentication into these endpoints in one of four ways:

HttpHeader: Here, we must declare the appropriate header key/value pair values that will allow us to authenticate into the endpoint. HttpHeader is the option you will need to go for if you use Basic or OAuth 2.0 authentication via an authorization bearer token.
WebhookKey: For this option, the platform will append a query string parameter called code onto the URL, whose value then allows you to authenticate into the API. If your endpoint is an Azure Function, then this is a possible candidate option for you to consider using, as all requests targeting your function will expect this by default.
HttpQueryString: Best suited for endpoints that support shared access signature (SAS) authentication, developers specify the appropriate key/value pairs for this, in the same manner as the HttpHeader option. The main difference here is that the platform will instead add these values onto the endpoint URL as query parameters.
Anonymous: Finally, it is possible to call any endpoint that does not enforce authentication. To do this, ensure you select the HttpHeader authentication type and supply a single key/value pair containing anything you like; otherwise, you may get errors when registering the Webhook.

Then, similar to working with service endpoints, we define the appropriate steps and Pre/Post images that will trigger the webhook call. The resulting operation will then initiate an HTTP POST request to your endpoint, containing the event data illustrated in the example earlier.

An important question arises around the usage of Webhooks in comparison to the Azure Service Bus. Certainly, Webhooks are the most attractive option to consider if you are integrating alongside non-Azure based services, your expected volume of API calls are low, or you need your request to execute synchronously. However, they will ultimately only be as reliable as the endpoint that you are contacting. Also, for high volume requests where we can tolerate a delay in processing, Webhooks will likely fall over pretty quickly. When this occurs, the Service Endpoint and Azure Service Bus option represent your optimal choice instead.

For more information on how to work with Webhooks, consult this Microsoft Docs article, which also provides some examples for you to work through.

Demo: Registering & Consuming a Microsoft Dataverse Webhook from an Azure Function

A common mechanism to work with Webhooks is via an Azure Function. With this in mind, check out the below video, which will show you how to consume webhook events in this manner:

We’re on the home stretch now, with only one more topic to look at before we wrap up the series. Next time around, we’ll look at how you can enable some specific capabilities on your Microsoft Dataverse to support data synchronisation scenarios.

Exam PL-400 Revision Notes: Building a Power Platform Custom Connector

Sun, 30 May 2021 00:00:00 +0000

Welcome to the sixteenth post in my series focused on providing a set of revision notes for the PL-400: Microsoft Power Platform Developer exam. In the last post, we saw how developers could leverage C# code as part of plug-ins to implement complex business logic within Microsoft Dataverse. We can now examine another extensibility component within the Extend the platform section of the exam as we discuss how to Create custom connectors. For this, Microsoft expects candidates to demonstrate knowledge of the following subjects:

Create custom connectors

create a definition for the API

configure API security

use policy templates to modify connector behavior at runtime

expose Azure Functions as custom connectors

create custom connectors for public APIs by using Postman

Depending on the type of system you wish to integrate alongside the Power Platform, a custom connector may suit your needs, thereby allowing you to leverage an existing API you have constructed or an entirely new one. What’s more, developers can then take these custom connectors and expose them out to other organisations or perhaps even to every other Power Platform user the world over. In short, they are a compelling feature to leverage. So let’s take a look at what they are all about and how you can get started with them.

Custom Connectors Overview

As we have seen when evaluating both canvas Power Apps and Power Automate flows, developers can use well over 325+ standard connectors, covering various Microsoft and other third-party systems, such as Salesforce, SAP and Oracle Database. This should give you everything you need to get disparate systems talking to each other within the Power Platform… in most situations. Custom connectors are there to provide additional headroom for when this is not possible to achieve. Powered by Azure API Management underneath the hood, Custom Connectors provide a guided, visual mechanism of exposing an entirely custom API, alongside its various operations, as an additional connector for the following services:

Canvas Power Apps
Power Automate Flows
Logic Apps

Developers can then utilise these in much the same manner as the other connectors discussed previously. For example, you can define trigger actions from your API, pull in entire datasets or perform core operations, such as updating an existing record. The capabilities within your current API ultimately dictate all of this, so, in some situations, developers may need to author a new API themselves and use services such as Azure Functions or Azure Web Apps to host it. Further discussion on how to do this is beyond the scope for this blog post and, indeed, the exam itself; candidates should instead focus their attention on the various supported options for connectors and - most crucially - the outline steps for creating one, which the below diagram summarises well:

The sections that follow will dive into these steps in further detail…

Supported Scenarios

…but first, we should touch upon some of the situations where you may need to consider using a custom connector:

Integrating with On-Premise APIs: As custom connectors fully support using the on-premises data gateway, they provide the securest and most streamlined mechanism for making any internal APIs accessible for use within your cloud systems.
Incorporating REST / SOAP APIs: It is worth noting that custom connectors only support APIs of these particular types. Specifically, canvas Power Apps and Power Automates can only work with HTTP REST APIs; Logic Apps support SOAP APIs too. For situations where your existing API does not meet these requirements, it will be impossible for you to use them with custom connectors.
Sharing an API within an Organisation: For situations where you envision only contacting an API a single time within, let’s say, a Power Automate flow, using an HTTP action step may be the most prudent (and fastest) option to consider. Going beyond this, if you think you will need to share out or utilise the same action steps across multiple flows and, also, you wish to provide a simplified means of accessing the same set of actions, a custom connector will fit your needs.
ISV Solution Development: Many of the custom connectors available today have their origin as internally developed ones, which have then been certified by Microsoft and published for general use. By doing this, ISV developers can help to drive further usage of their existing solutions and even introduce them to an entirely new audience.

Reviewing Custom Connector Creation Options

Developers have a few different options available to them when creating a custom connector. But, almost always, you will start from within the Power Apps Maker Portal. Then, by navigating to Data -> Custom Connectors, you can locate the appropriate option to kick off their creation:

The best thing about this is that we don’t necessarily need to reinvent the wheel, provided we have existing definitions of our API’s already built out. At the time of writing this post, developers can utilise the following, if available:

Postman: If you’ve never used this tool before and find yourself regularly poking into numerous API’s, then this tool could help you out. In short, the app provides you with a local “sandbox” to mock-up, execute and inspect the results of various HTTP actions. It has numerous valuable features, such as being able to store requests in collections, handling multiple different types of authentication, and providing online synchronisation capabilities. From a custom connector standpoint, you can use Postman to build out the various action requests that your API exposes out and then import these in as a collection file into the Power Apps Maker Portal. Note as part of this that only V1 Postman collections are supported. There’s a great article on the Postman website that shows you how to get started with collections.
OpenAPI: Similar in some respects to a Postman collection, an OpenAPI definition is instead intended as a complete declaration of all the capabilities stored within an API, using an open standard. Developers would typically generate this for their API to provide other developers with a valuable resource when working with the API in question. Thankfully, if you use Azure API Management as the backend for your API, you can quickly generate the appropriate specification using the Azure Portal. It is also possible to build this directly into your ASP.NET Core app if that is what your API is using; I’m sure it’s possible to do the same for other languages/stacks too, but I’ll leave that to you to find out. 😀
GitHub: Best for situations where you have built out a connector already or wish to leverage an existing, certified connector, you can very quickly bring it in from a GitHub repository of your choosing.

For the options listed in the screenshot above, it’s worth focusing on each of these in more detail:

Create from blank: Using this option, you must define each of the individual elements of your API, such as its security, actions and triggers. If you are unsure where to start and don’t have an appropriate Postman/OpenAPI definition at your disposal, then this will be the most suitable option to choose.
Import an OpenAPI file: With this, you can import the OpenAPI JSON definition file from your local computer.
Import an OpenAPI from URL: If your definition is instead available as part of a publicly accessible URL, use this option to import it instead.
Import a Postman Collection: This choice bears some similarities to the OpenAPI options, as it will let you import a JSON collection file generated from Postman. As mentioned earlier, make sure you export this as a V1 definition from the Postman app.

Regardless of which option you select, you can then populate some standard settings for your connector, such as its display name, image and description. At this point, you can also override the URL scheme, the host URL and the Base URL, if required:

Handling API Security

A custom connector can be secured using multiple mechanisms. These authentication profiles do not store sensitive credentials within the connector. Instead, they define the authentication options that users of the connector must set when using your custom connector for the first time. In this manner, it’s possible to connect to multiple instances of your API on the same tenant, using different credentials. A custom connector can support the following four types of authentication methods:

No Authentication: Best for when you are exposing a publically available API that requires no underlying authentication. This option, quite obviously, provides zero security for your API.
Basic Authentication: Utilising the same authentication method as the defined HTTP standard, here you outline details of the user name and password parameter labels that users must provide for your custom connector. I would typically advise against using Basic Authentication wherever possible, as it doesn’t afford the best security for your custom connector or API itself.
API Key: Here, you provide the details for an API Key that the custom connector includes as part of either the header or as a query parameter on the URL itself. Many of the Azure Cognitive Services API’s use API Key’s as their authentication mechanism. API Key’s suffer from the same security failings as Basic Authentication and, as such, should be avoided unless necessary.
OAuth 2.0: The recommended and most secure option for your custom connector, and also one that integrates neatly alongside Azure Active Directory (AAD) and a variety of other services, such as Google and Facebook. To see an example of how to set this up using an Azure App Registration for an Azure Function, you can consult the following Microsoft Docs article. In short, though, using AAD OAuth 2.0 requires you to set up an app registration on the appropriate tenant, which then exposes out the details you can use when defining your profile.

Working with Policy Templates

If you’ve had some experience working with Azure API Management or have been following my blog religiously, this topic might feel somewhat familiar. To fine-tune how your custom connector ultimately interacts with your API, you can perform various manipulation activities as each action/trigger gets fired. These are brought together within a list of re-usable templates that cover common operations that may be necessary and, from an Azure API Management standpoint, map back to the various policy definitions that this service supports. The list below provides an overview of the types of actions policy templates support:

Set host URL: Using this, you can replace the URL for the request with an entirely new one.
Route request: Let’s you route the action to a completely different path on the same URL from the one specified.
Set HTTP header: Allows you to append, skip or replace a Header value as part of the API request. For example, you could supply a Cache-Control value to help improve performance when the custom connector uses your API.
Set query string parameter: Allows you to append, skip or replace a query parameter value as part of the API request. For example, if your API is an OData endpoint, you might want to append a default $top query parameter to limit the number of returned results each time.

At the time of writing this post, there are also a couple of additional policy templates available marked as Preview, which allows you to do things such as converting objects into arrays and vice-versa. Microsoft will not assess candidates on preview features within exams, so it is unlikely that you will need to know about these as part of your exam prep.

Demo: Creating a Custom Connector for an Azure Function

To help you better understand the process involved in building out a custom connector, check out the video below, where we will build out one that integrates alongside an Azure Function app:

That pretty much wraps it up for the basics on custom connectors, which should be all you need to know for the exam. In the next post, we’ll look at how you can leverage the Microsoft Dataverse Web API to perform various operations and manage more complex workloads.

Exam PL-400 Revision Notes: Building, Deploying & Debugging Plug-ins using C#

Sun, 23 May 2021 00:00:00 +0000

Welcome to the fifteenth post in my series focused on providing a set of revision notes for the PL-400: Microsoft Power Platform Developer exam. In the previous post, we finished our discussion of the Extend the user experience exam area by evaluating command buttons and demonstrating how valuable the Ribbon Workbench tool is in helping us fine-tune aspects of a model-driven Power App’s interface. This topic rounded off our discussion of the Extend the user experience topic, meaning that we now move into a new section titled Extend the platform. This area has equal weighting (15-20%), and the first topic concerns how we Create a plug-in. Specifically, candidates must demonstrate knowledge of the following:

Create a plug-in

describe the plug-in execution pipeline

design and develop a plug-in

debug and troubleshoot a plug-in

implement business logic by using pre-images and post-images

perform operations on data by using the Organization service API

optimize plug-in performance

register custom assemblies by using the Plug-in Registration Tool

develop a plug-in that targets a custom action message

Developers who have previously worked with Dynamics 365 or Dynamics CRM should have very little trouble getting to grips with plug-ins, as they have been a mainstay within these applications for well over a decade now. Notwithstanding this, it’s always helpful to get a refresher on even the most familiar of topics 😉. With that in mind, let’s dive in!

As with all posts in this series, the aim is to provide a broad outline of the core areas to keep in mind when tackling the exam, linked to appropriate resources for more focused study. Ideally, your revision should involve a high degree of hands-on testing and familiarity with the platform if you want to do well in this exam. I would also recommend that you have a good general knowledge of working with the C# programming language before approaching plug-in development for the first time. Microsoft has published a whole range of introductory material to help you learn the language quickly.

What is a Plug-in?

In the series so far, we’ve already touched upon the following functional tools that developers may leverage when dealing with complex business requirements:

Business Rules: These provide an excellent mechanism for handling simple logic, targeting both model-driven app forms and platform-level operations.
Power Automate: Using flows authored by this tool, you can typically go the extra mile compared with classic workflows, thereby allowing you to integrate multiple systems when processing asynchronous actions.
JavaScript: For situations where Business Rules can’t meet your particular requirement, and you need specific logic to trigger as a user is working on a model-driven form, this is the best tool in your arsenal.

These are great, but there may be situations where they are unsuitable due to the sheer complexity of the business logic you are trying to implement. Also, some of the above tools do not support the ability to carry out synchronous actions (i.e. ones that happen straight away, as the user creates, updates, deletes etc, rows in the application). Finally, it may be that you need to work with some specific elements of the SDK that are not exposed out straightforwardly via alternative routes. In these situations, a custom-authored plug-in is the only solution you can turn to.

So what are they then? Plug-ins allow developers to write either C# or VB.NET code, which is then registered within the application as a .NET Framework class library (DLL) and executed based on specific conditions you specify within its configuration. For example, when a user creates a Contact, retrieve the details of the parent Account row and update the Contact to match. Developers will use Visual Studio when authoring a plug-in, typically using a class library project template. The Microsoft Dataverse SDK provides several modules that expose various operations that a plug-in can support. Some of the other things that plug-ins support include:

Both synchronous and asynchronous execution.
Custom un-secure/secure configuration properties that can modify the behaviour of a plug-in at runtime. For example, by providing credentials to a specific environment to access.
Pre and Post Table (previously known as Entity) Images, snapshots of how a record and its related attributes looked before and after a platform level operation occurs.
For specific operations, such as Update, plug-ins can also support filtering attributes - basically, a list of defined columns that, when modified, will cause the plug-in to trigger.
Being able to specify the execution order for one or multiple plug-in steps. This capability can be helpful when you need to ensure a set of steps execute in your desired order.

These days, thanks to Business Rules and Power Automate, we see the lessening importance of plug-ins, and, typically, you would want to avoid using them straight out the gate. However, they still have a place and, when used appropriately, become the only mechanism you can resort to when working with complicated business logic.

Understanding Messages, the Execution Pipeline & Steps

Before we start diving into building a plug-in for the first time, it’s prudent to provide an overview of the three core concepts that every plug-in developer needs to know:

Messages: These define a specific, platform level operation that the SDK exposes out. Some of the more commonly used Messages within the application include Create, Update or Delete. Some system tables may have their own set of unique Messages; CalculatePrice is an excellent example of this. From a plug-in perspective, developers essentially “piggyback” onto these operations as they are performed and inject their custom code.
Execution Pipeline: As a user triggers a particular message, the application processes it using a defined set of stages, known as the execution pipeline. These are discussed in detail in this Microsoft Docs article, but the key ones we need to be aware of are:
- PreValidation: At this stage, the database transaction has not started. Also, the application has not yet performed any appropriate security checks, potentially meaning that the operation may fail if the user does not have the correct security privileges.
- PostValidation: Here, the database transaction has already started. The platform knows at this stage that no security constraints will prevent the operation from completing, but the transaction may still fail for other reasons.
- PostOperation: Although the database transaction has still not completed at this stage, the core operation of the message (executed within the MainOperation stage) will almost certainly commit successfully, assuming no errors occur via a custom plug-in.
A failure at any of these stages will cause the database transaction to roll back entirely, returning any affected row(s) to their original state. Now, from a plug-in perspective, the execution pipeline is exposed out to developers as stages where your custom code can execute. This can provide developers with a high degree of flexibility and capability when running their custom code. As a general rule of thumb, developers would use each of these stages under the following circumstances:
- PreValidation: Use this stage to perform checks to cancel the operation.
- PostValidation: This stage is handy for modifying any values before they hit the database. Doing this at this stage would also prevent triggering another platform Message.
- PostOperation: Use this stage for when you need to carry out additional logic not related to the current record or potentially provide additional information back to the caller after the platform completes the core operation.
Developers will typically need to give some thought towards the execution pipeline and the most appropriate one to select, based on the requirements being worked with.
Steps: Simply writing a plug-in class and deploying out the library is not sufficient to trigger your custom logic. Developers must also provide a set of “instructions”, commonly known as Steps, that tell the application when and where to execute your custom code. It is here where both the Message and Execution Pipeline come into play, and you would always specify this information when creating a Step. Additional info you can include here includes the execution order, whether the plug-in will execute synchronously or not and the display name of the Step when viewed within the application.

We will see shortly how these topics come into play as part of using the Plug-in Registration Tool.

Building Your First Plug-In: Pre-Requisites

Before you start thinking about developing a plug-in, you need to make sure that you have a few things installed onto your development machine:

Visual Studio: I would recommend using Visual Studio 2019 where possible. If you don’t have a Visual Studio/MSDN subscription, we can use the Community Edition instead.
A Microsoft Dataverse Environment: Because where else are you going to deploy out and test your plug-in? 😀
Knowledge of C# / VB.NET: Attempting to write a plug-in for the first time without at least a basic grasp of one of these languages will impede your progress.
Plug-in Registration Tool: To deploy your plug-in out, you will need access to this tool as well. We’ll cover this off later in the post.

Demo: Creating a Microsoft Dataverse Plug-in using Visual Studio 2019 & C#

The best way to learn how to create a plug-in is to see someone build one from scratch. In the YouTube video below, I talk through how to build a straightforward plug-in using Visual Studio 2019 and C#:

For those who would prefer to read a set of instructions, then this Microsoft Docs article provides a separate tutorial you can follow instead.

Using the Plug-in Registration Tool

Once you’ve written your first plug-in, you then need to consider how to deploy this out. In most cases, you will use the Plug-in Registration Tool to accomplish this. Available on NuGet, this lightweight application supports the following features:

Varied access options when working with multiple Dataverse environments.
The ability to register one or multiple plug-in assemblies.
The registering of plug-in steps and images, including the various settings, discussed earlier.
Via the tool, you can install the Plug-in Profiler, an essential tool for remote debugging your plug-ins; more on this capability later.

The Plug-In Registration Tool is also necessary for deploying other extensibility components, including Service Endpoints, WebHooks or Custom Data Providers. We will touch upon some of these later on in the series. For this topic area and the exam, you must have a good general awareness of deploying and updating existing plug-in assemblies.

Demo: Deploying a Microsoft Dataverse Plug-in using the Plug-in Registration Tool

In this next video, I’ll show you how to take the plug-in developed as part of the previous video and deploy it out using the Plug-in Registration Tool:

There is also a corresponding Microsoft Docs tutorial that covers these steps too.

Debugging Options for Plug-ins

Plug-ins deployed out into Microsoft Dataverse must always run within sandbox execution mode. As a result, this imposes a couple of limitations (some of which I’ll highlight in detail later on), the main one being that it greatly hinders the ability to debug deployed plug-ins easily. To get around this, Microsoft has provided two mechanisms that developers can leverage:

Plug-in Trace Logging: Using this, developers can write out custom log messages into the application at any point in their code. This can be useful in identifying the precise location where a plug-in is not working as expected, as you can output specific values to the log for further inspection. You can also utilise them to provide more accurate error messages for your code that you would not necessarily wish to show users as part of a dialog box. Getting to grips with trace logging is easy - it’s just a few lines of code that you need to add to your project - and you can find out more about how to work with it on the Microsoft Docs site.
Plug-in Registration Tool & Profiling: While trace logging is undoubtedly useful, there will be situations where you need something more. For example, it may become desirable to breakpoint code, inspect values/properties as they are processed, and determine when your plug-in hits specific conditions or error messages. The Profiler comes into play for these situations by allowing developers to “playback” their code execution using Visual Studio and the Plug-in Registration Tool. We mentioned the Plug-in Profiler tool earlier, which is a mandatory requirement and must be deployed to your instance first. From there, you can generate a profile file that allows you to rewind execution within Visual Studio.

Developers will typically use both of these debugging methods in tandem to figure out issues with their code. The first option provides a friendly, discreet mechanism of inspecting how a plug-in has got on. The Profiler acts as the “nuclear” option when we cannot discern the problem easily via trace logging alone. Understanding the benefits/disadvantages of both and how to use them will be essential as part of your exam preparation. With this in mind, check out the two demo videos below that show you how to work with these features in-depth:

Demo: Debugging a Microsoft Dataverse Plug-in using Trace Logging

Demo: Debugging a Microsoft Dataverse Plug-in Using the Plug-in Registration Tool

General Performance / Optimization Tips

Anyone can build and deploy a plug-in, but it can take some time before you can do this well. Here are a few tips that you should always follow to ensure your plug-ins perform well when deployed out:

Keep in mind some of the limitations as part of sandbox execution for your plug-ins, including:
- The 2 minute limit on execution time.
- The inability to use specific 3rd party DLL’s, such as Newtonsoft.Json
- Various restrictions around accessing operating system level information, such as directories, system state etc.
For situations where sandbox limitation will cause issues in executing your business logic, you will need to consider moving away from a plug-in and adopting another solution.
Filtering attributes provide a great way of ensuring your code only executes when you need it to. You should always use these wherever possible.
Make sure to disable any plug-in profiling and remove the Profiler solution once you are finished. Active profiles can considerably slow down performance, and the Profile solution can also introduce unintended dependencies on core tables, causing difficulties when moving changes as part of a solution file.
The Solution Checker provides an excellent mechanism for quality checking your code and can give some constructive recommendations on where your plug-in can be improved. Running this at least once before moving your plug-in out into other environments is highly recommended.
Read through the following Microsoft Docs article and take care to follow the suggestions it outlines.

Don’t Forget…Custom Actions & Global Discovery Service Endpoint

As Microsoft has included them in the exam specification, it’s worth talking about these two topics briefly. However, only a general awareness of them should be sufficient, and I wouldn’t devote too much of your revision time to them.

We’ve already looked at Messages in-depth and seen how they can act as a “gateway” for developers to bolt on specific logic when an application-level event occurs. Custom Actions allow you to take this a step further by creating SDK/API exposable, custom Messages. For example, you could combine the Create/Update Messages of the Lead/Opportunity tables into a new message called SalesProcess. Plug-ins or operations targeting the Web API could then work with or trigger actions based on this. Custom Actions have been available within the application for many years now, and many developers continually argue them as being one of the most underrated features in Microsoft Dataverse. They are also fully supported for use as part of Power Automate flows too. In short, they can be incredibly useful if you need to group multiple default messages into a single action that can then be called instead of each one.

Finally, it is worth touching upon how developers use the Global Discovery Endpoint from a plug-in standpoint, but we must first outline the concepts of early-binding and late binding. In the video demos above, I wrote all of the code using the late-binding mechanism. This means that instead of declaring an object for the specific table I wanted to work with (such as Contact), I instead used the generic Entity class and told the code which attributes I wanted to work with by specifying their logical names as strings. This is fine and gives me some degree of flexibility, but it ultimately means that I won’t detect any issues with my code (such as an incorrect field name) until runtime. Also, I have no easy way to tell how my table looks using Intellisense; instead, I must continuously refer to the application to view these properties. To get around this, we can use a mechanism known as early-binding, where all of the appropriate table structures are generated within the project and referenced accordingly. The CrmSvcUtil.exe application provides a streamlined means of creating these early-bound classes, and, as you might have guessed, you need to use the Global Discovery Endpoint to generate these classes successfully. There have been many previous wars and mounds of dead developers debates online regarding which mechanism is better. While early-binding does afford some great benefits, it does add some overhead into your development cycle, as you must continuously run the CrmSvcUtil application each time your tables change within Microsoft Dataverse. All I would recommend is to try both options, identify the one that works best for you and, most importantly, adopt your preferred solution consistently.

Plug-ins can help when modelling out complicated business logic that is impossible to achieve via other functional tools within the Power Platform. I hope this post has provided a good insight into their capabilities and to help you in your revision. In the next post, I’ll show you how you can extend Power Automate and Power Apps via custom API connectors, thereby allowing you to connect to a myriad of different systems.

Avoiding Parallel Execution within Power Apps / Common Data Service Plug-ins

Sun, 20 Sep 2020 00:00:00 +0000

The Power Apps Solution Checker provides developers with a great mechanism to verify the quality of custom code targeting either Dynamics 365 Online or the Common Data Service. We can use the recommendations it produces to help write better, more optimised code, that will better benefit our deployments and the individuals working with the apps we’ve built. Typically, the recommendations it produces will be informative enough to get you on your way; Microsoft will provide a summary of the problem and a link to the relevant Docs article that contains links/code samples for you to adapt accordingly. However, this is not always the case, and you may need to scratch your head a little harder to get to the root of the problem. This happened to me recently when I was dealing with the following recommendation:

The Docs article link for this recommendation doesn’t give us much to go on when figuring out what to do to get our code fixed. But we must still, somehow, address the problem it raises - the idea of potentially conflicting transactions and generic SQL errors is enough, I’d warrant, to scare even the most hardened Dynamics 365 / Power Platform developer. 🙂 So let’s take a look at how I resolved the issue within this specific scenario. Hopefully, it might help you if you find yourself facing the same problem.

As this is a code related issues, let’s, first of all, take a look at the offending blocks of code in question. First of all, we had the following method that would call an external OData endpoint. This formed part of a Custom Data Provider for a virtual entity that would require OAuth 2.0 authentication; something that, regrettably, is not supported by the default OData provider Microsoft provides us with:

private async Task<T> GetRecordById<T>(ITracingService tracer, string id, string entity, string token)
{
 //Generate the OData endpoint request

 string oDataURL = $"{this.aadConfig.ODataURL}/{entity}({id})";
 tracer.Trace(oDataURL);

 HttpRequestMessage oDataReq = new HttpRequestMessage(HttpMethod.Get, new Uri(oDataURL));
 oDataReq.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

 using (HttpClient client = HttpHelper.GetHttpClient())
 {
 try
 {
 HttpResponseMessage oDataResponse = await client.SendAsync(oDataReq);
 if (!oDataResponse.IsSuccessStatusCode)
 {
 tracer.Trace(oDataResponse.StatusCode.ToString());
 throw new GenericDataAccessException($"A problem occurred when retrieving the {entity} data.");
 }

 //Retrieve data from the endpoint using the bearer token.
 using (var stream = new MemoryStream(Encoding.UTF8.GetBytes(oDataResponse.Content.ReadAsStringAsync().Result)))
 {
 DataContractJsonSerializerSettings settings = new DataContractJsonSerializerSettings()
 {
 UseSimpleDictionaryFormat = true
 };

 DataContractJsonSerializer ser = new DataContractJsonSerializer(typeof(T), settings);
 return (T)ser.ReadObject(stream);
 }
 }
 catch (Exception e)
 {
 tracer.Trace(e.Message);
 throw new GenericDataAccessException($"A problem occurred when retrieving the {entity} data.");
 }
 }
}

Note the following with this method:

It has been set to execute asynchronously as a task, as indicated by the async and Task keyword.
The core HTTP call is wrapped within a using statement and executed as a HttpClient request.
The method is generic in terms of its return type, therefore allowing us to retrieve and then cast out to a variety of different classes if required.

This method was then called at relevant points elsewhere in the code using the snippet below:

var getEntityByIdTask = Task.Run(async () => await GetRecordById<Entity>(tracer, target.Id.ToString(), "Entity", getAccessToken.Result.access_token));
Task.WaitAll(getEntityByIdTask);

var result = getEntityByIdTask.Result;

tracer.Trace($"Entity found: {result.ID}");

Here, and as mentioned earlier, we are calling the asynchronous task method to return us a result set of type Entity, which represents our result from the OData endpoint.

Going back then to the recommendation raised earlier, we can best summarise the main issues with the “as-is” code as follows:

The method will always run as a separate, asynchronous call within the current database transaction. As well as being the cause of a solution checker recommendation, this could also lead to longer-running transactions and us unintentionally hitting the two-minute execution limit for sandbox, if our outbound call takes far longer to execute than expected.
The HttpClient class supports asynchronous execution only; there is no way of forcing it to execute synchronously, meaning that we must instead resort to using other class types, such as HttpWebRequest and HttpWebResponse
The code snippet itself is expecting the method to run asynchronously; this needs to be adjusted accordingly to match any changes to the GetRecordById method.

With all this in mind, we can look to tweak our method…

private T GetRecordById<T>(ITracingService tracer, string id, string entity, string token)
{
 //Generate the OData endpoint request
 try
 {
 string oDataURL = $"{this.aadConfig.ODataURL}/{entity}({id})";
 tracer.Trace(oDataURL);

 HttpWebRequest req = (HttpWebRequest)WebRequest.Create(new Uri(oDataURL));
 req.Method = "GET";
 req.KeepAlive = false;
 req.Headers.Add("Authorization", "Bearer " + token);

 var res = (HttpWebResponse)req.GetResponse();

 if (res.StatusCode != HttpStatusCode.OK)
 {
 tracer.Trace(res.StatusCode.ToString());
 throw new GenericDataAccessException($"A problem occurred when retrieving the {entity} data.");
 }

 using (var stream = new StreamReader(res.GetResponseStream(), Encoding.UTF8))
 {
 DataContractJsonSerializerSettings settings = new DataContractJsonSerializerSettings
 {
 UseSimpleDictionaryFormat = true
 };

 DataContractJsonSerializer ser = new DataContractJsonSerializer(typeof(T), settings);

 return (T)ser.ReadObject(stream.BaseStream);
 }
 }
 catch (Exception e)
 {
 tracer.Trace(e.Message);
 throw new GenericDataAccessException($"A problem occurred when retrieving the {entity} data.");
 }
}

…and the related snippet that calls it…

var entity = GetRecordById<Entity>(tracer, target.Id.ToString(), "Entity", getAccessToken.Result.access_token);
tracer.Trace($"Entity found: {entity.ID}");

Now, it is worth highlighting that Microsoft advises not to use the HttpWebRequest class for new development work. However, I have struggled to find an alternative solution that fixes this problem. Answers on a postcode if you think there’s a better way of doing this, and I will happily update this post and provide full credit for any solution that gets around this; but otherwise, looks like we are stuck with using this!

The Solution Checker is a fantastic tool to have in your arsenal to provide you with an automated, bespoke way of flagging common issues with your Dynamics 365 / Power Apps solution. Granted, it will never take the place of a formal code review alongside a senior developer. Still, it can be a potential lifesaver if you find yourself performing solo development work targeting the application. Give it a go if you haven’t already and, hopefully, if you see yourself getting the same recommendation outlined in this post, you now know what to do to get your code sorted.

Exam MB-400 Revision Notes: Series Roundup

Sun, 13 Sep 2020 00:00:00 +0000

Welcome to the final post in my series focused on providing a set of revision notes for the MB-400: Microsoft Power Apps + Dynamics 365 Developer exam. In today’s post, I wanted to consolidate all of the content from the series into a single, concise post for ease of access. I’ll also provide some general advice and tips that I hope will come in useful for when you sit the exam.

This series has aimed to provide a broad outline of the core areas to keep in mind when tackling the exam, linked to appropriate resources for more focused study. Your revision should, ideally, involve a high degree of hands-on testing and familiarity in working with the platform if you want to do well in this exam.

The MB-400 exam is split into several different areas, based on the specification found here. For each applicable subject, I have linked below to the relevant blog/video content from the series.

Create a Technical Design (10-15%)

Validate requirements and design technical architecture

Skills Measured

design and validate technical architecture
design authentication and authorization strategy
determine whether requirements can be met with out-of-the-box functionality
determine when to use Logic Apps versus Power Automate flows
determine when to use serverless computing vs. plug-ins
determine when to build a virtual entity data source provider vs. when to use connectors

Create a data model

Skills Measured

design a data model

Blog Posts

Exam MB-400 Revision Notes: Creating a Technical Design with the Power Platform

Useful Resources

Configure Common Data Service (15-20%)

Configure security to support development

Skills Measured

troubleshoot operational security issues
create or update security roles and field-level security profiles

Implement entities and fields

Skills Measured

configure entities
configure fields
configure relationships

Create and maintain solutions

Skills Measured

configure solutions
import and export solutions
manage solution dependencies

Blog Posts

Exam MB-400 Revision Notes: Configuring the Common Data Service

Videos

MB-400 Exam Prep: Creating Entities, Fields and Relationships

MB-400 Exam Prep: Working with Solutions

MB-400 Exam Prep: Security Roles & Field Security Profiles

Useful Resources

Create and Configure Power Apps (10-15%)

Create model-driven apps

Skills Measured

configure a model-driven app
configure forms
configure views
configure visualizations

Create Canvas Apps

Skills Measured

configure a Canvas App
develop complex expressions

Blog Posts

Exam MB-400 Revision Notes: Working with Model-Driven Apps

Exam MB-400 Revision Notes: Working with Canvas Apps

Videos

MB-400 Exam Prep: Building a Model-Driven App

https://youtu.be/EEBTENhcQ-0

MB-400 Exam Prep: Creating a Canvas App

Useful Resources

Configure business process automation (10-15%)

Configure Power Automate

Skills Measured

configure a Flow
configure actions to use Common Data Service connectors
develop complex expressions

Implement processes

Skills Measured

create and configure business process flows
create and configure business rule

Blog Posts

Exam MB-400 Revision Notes: Using Power Automate Flows

Exam MB-400 Revision Notes: Mapping a Business Process with Business Process Flows

Exam MB-400 Revision Notes: Implementing Business Rules

Videos

MB-400 Exam Prep: Introduction to Power Automate Flows

MB-400 Exam Prep: Creating a Business Process Flow

MB-400 Exam Prep: Working with Business Rules

Useful Resources

Extend the user experience (15-20%)

Apply business logic using client scripting

Skills Measured

configure supporting components
create JavaScript or Typescript code
register an event handler
use the Web API from client scripting

Create a Power Apps Component Framework (PCF) component

Skills Measured

initialize a new PCF component
configure a PCF component manifest
implement the component interfaces
package, deploy, and consume the component
use Web API device capabilities and other component framework services

Create a command button function

Skills Measured

create the command function
design command button triggers, rules, and actions
edit the command bar using the Ribbon Workbench
modify the form JavaScript library dependencies

Blog Posts

Exam MB-400 Revision Notes: Implementing Client-Side Scripting on Model Driven Power Apps

Exam MB-400 Revision Notes: Introduction to Power Apps Component Framework (PCF) Controls

Exam MB-400 Revision Notes: Working with Command Buttons

Videos

MB-400 Exam Prep: Deploying a Basic JavaScript Form Function

MB-400 Exam Prep: Setting up your environment for Power Apps Component Framework Control Development

MB-400 Exam Prep: Developing, Testing and Deploying a Power Apps Component Framework (PCF) Control

MB-400 Exam Prep: Creating Command Buttons Using the Ribbon Workbench

Useful Resources

Extend the platform (15-20%)

Create a plug-in

Skills Measured

debug and troubleshoot a plug-in
develop a plug-in
use the global Discovery Service endpoint
optimize plug-ins for performance
register custom assemblies by using the Plug-in Registration Tool
create custom actions

Configure custom connectors for Power Apps and Flow

Skills Measured

create a definition for the API
configure API security
use policy templates

Use platform APIs

Skills Measured

interact with data and processes using the Web API
optimize for performance, concurrency, transactions, and batching
perform discovery using the Web API
perform entity metadata operations with the Web API
use OAuth with the platform APIs

Blog Posts

Exam MB-400 Revision Notes: Building, Deploying & Debugging Plug-ins using C#

Exam MB-400 Revision Notes: Building a Custom Connector for Power Apps & Power Automate

Exam MB-400 Revision Notes: Working with the Dynamics 365 Web API

Videos

MB-400 Exam Prep: Building a C# Plug-in Using Visual Studio 2019

MB-400 Exam Prep: Deploying a C# Plug-in Using the Plug-in Registration Tool

MB-400 Exam Prep: Debugging a C# Plug-in Using Trace Logging

MB-400 Exam Prep: Debugging a C# Plug-in Using the Plug-in Registration Tool

MB-400 Exam Prep: Building a Custom Connector Using Azure Cognitive Services

MB-400 Exam Prep: Authenticating to the Dynamics 365 Web API

MB-400 Exam Prep: Working with the Dynamics 365 Discovery URL

MB-400 Exam Prep: Retrieving Entity Metadata using the Web API

MB-400 Exam Prep: Performing Batch Operations using the Web API

Useful Resources

Develop Integrations (10-15%)

Publish and consume events

Skills Measured

publish an event by using the API
publish an event by using the Plug-in Registration Tool
register a webhook
create an Azure event listener application

Implement data synchronization

Skills Measured

configure and use entity change tracking
configure the data export service to integrate with Azure SQL Database
create and use alternate keys

Blog Posts

Exam MB-400 Revision Notes: Publishing and Consuming Events

Exam MB-400 Revision Notes: Implementing Data Synchronisation with the Data Export Service

Videos

MB-400 Exam Prep: Posting Dynamics 365 Events to Azure Service Bus

MB-400 Exam Prep: Registering & Consuming a Dynamics 365 Webhook

MB-400 Exam Prep: Deploying the Dynamics 365 Data Export Service

Useful Content

General Exam Preparation Tips

Hands-on preparation is essential if you wish to do well in the exam. You should ideally set up a trial environment that you can use to experiment with the core functionality within Dynamics 365 / the Power Platform. You can watch this great video from Microsoft’s Chris Huntingford, where he will show you how to deploy an extended trial of Dynamics 365 Online and Microsoft 365 E5. These subscriptions will give you everything you need.
Keep abreast of the latest Microsoft Docs and Learning Path materials that are related to this exam, as the platform is continually changing all of the time.
Due to the ongoing COVID-19 situation, you will more than likely have to sit your exam using the online proctored experience. Take some time to familiarise yourself with the process involved here, and perform a system test well in advance of your exam date - the last thing you need on the day of the exam is to stress out due to a system or access issue.
At the time of writing this post, Microsoft has announced the deprecation of the MB-400 exam in January 2021. I’ve discussed these changes in-depth previously on the blog and what it means if you’ve got an exam booked over the next few months. I would still advise that you sit this exam while it is available, as it will count towards any certification pathway that you are working towards. Additionally, there will be more content (and I don’t necessarily mean my own here 🙂 ) available covering this exam, which will provide better aid as part of your revision.

I hope that you’ve found this series useful. Good luck when sitting the exam and let me know how you got on!

Working with the TryGetAttributeValue Method (Dynamics 365 / Common Data Service SDK)

Sun, 23 Aug 2020 00:00:00 +0000

You can discover all sorts of useful capabilities if you dive your nose deep enough into the Dynamics 365 Online / Common Data Service SDK. And, given that these products are evolving continually within the cloud, new features are being introduced all the time. With this in mind, it’s perhaps natural to expect that even the so-called “experts” of these platforms may sometimes overlook new or seemingly obvious changes…😅 I’m unsure which of these categories the focus of today’s blog post fits into it but, given that Microsoft has not documented its capabilities very well, I thought I’d take some time to explore it further.

We’ve seen previously on the blog how to use the GetAttributeValue method, as being the “nice” way of accessing the various attributes you may need to work with as part of your C# code targeting Dynamics 365 / the Common Data Service. I won’t repeat too much old ground here but, suffice to say, I would highly recommend you always use this method as much as possible. As much as I like it though, one issue it does have is that you must always know the underlying data type that you are attempting to process. If, for example, you’re working with a defined list of attributes, but without their corresponding types declared, this method becomes pretty useless. Consider the following code snippet:

List<string> myAttributes = new List<string>();
myAttributes.Add("name");
myAttributes.Add("description");
myAttributes.Add("industrycode");

Entity e = Service.Retrieve("account", new Guid("9e03afdc-5d37-e911-a97c-0022480749f0"), new ColumnSet(true));

foreach(string a in myAttributes)
{
 string aVal = e.GetAttributeValue<string>(a);
 tracer.Trace(aVal);
}

This code works fine and dandy up until it hits the industrycode value in the myAttributes list, as this is the name of an Option Set, not a Single Line of Text (i.e. string) field. If a user has not populated this field with a value, then the code will silently skip over this and return a null value, but if it isn’t, you will get an error thrown with the following message:

An error has occurred: Unable to cast object of type ‘Microsoft.Xrm.Sdk.OptionSetValue’ to type ‘System.String’.

In this situation, therefore, it becomes desirable to test our incoming attributes to confirm they are of the correct type before we try to access their values.

Enter stage left the TryGetAttribute method. You can probably make a reasonable guess as to what this is doing from its name alone; namely, that it allows us to attempt to obtain an attribute’s value into our desired type, without necessarily throwing a nasty error if we screw up at all. What’s more, we can use the method to still obtain our attribute value, in much the same way as GetAttributeValue does, provided we have made the correct assumption regarding its underlying type. The method requires us to declare an object that will potentially store our attribute value when we call it. Apart from this main difference, it works pretty much as we’d hope it to - as the tweaked example below demonstrates:

List<string> myAttributes = new List<string>();
myAttributes.Add("name");
myAttributes.Add("description");
myAttributes.Add("industrycode");

Entity e = Service.Retrieve("account", new Guid("9e03afdc-5d37-e911-a97c-0022480749f0"), new ColumnSet(true));

foreach(string a in myAttributes)
{
 string strVal;
 OptionSetValue osVal;

 bool tryStr = e.TryGetAttributeValue<string>(a, out strVal);
 bool tryOS = e.TryGetAttributeValue<OptionSetValue>(a, out osVal);

 if (tryStr)
 tracer.Trace(strVal);
 if (tryOS)
 tracer.Trace(osVal.Value.ToString());
}

As we can see, all we need to do is declare a Boolean type, through which our code stores the results of the TryGetAttributeValue method. Using this, we can then determine whether to output the value strVal or osVal to our trace log, which will store value obtained by TryGetAttributeValue, provided that this did not result in false when called. If needed, we can extend the solution out to support all possible data types within Dynamics 365 / Common Data Service and, in the process, not worry about implementing a solution to figure out the correct data types or make subsequent API calls to determine this information. In short, the TryGetAttributeValue method provides a flexible and easy means of working with many different types of attributes simultaneously, that may be subject to change at runtime or difficult to infer easily. What’s more, the method shares the same benefit as GetAttributeValue by defaulting to a null value if the attribute, or its underlying value, does not exist, avoiding any needless errors from cropping up in your code.

I guess you could say I derive a weird sense of pleasure whenever I discover a cool new feature as part of Dynamics 365/ the Common Data Service and, as you might have guessed, TryGetAttributeValue very much fits into this category. I’m unsure when Microsoft added this method to the SDK or, indeed, if it’s something that I have naively overlooked for many years now. Regardless, I would urge you to consider using it within your code if the right circumstances arise, and I hope this blog post has been useful in showing you how to use it in practice. 🙂

Exam MB-400 Revision Notes: Building, Deploying & Debugging Plug-ins using C#

Sun, 02 Aug 2020 00:00:00 +0000

Welcome to the eleventh post in my series focused on providing a set of revision notes for the MB-400: Microsoft Power Apps + Dynamics 365 Developer exam. For those following the series, apologies again for the mini-hiatus. In fact, it’s been so long that Microsoft has now announced that MB-400 will be going the way of the Dodo at the end of the year. Despite this, I will be continuing and, all being well, finishing off this blog series for the following reasons:

People may still choose to sit the current exam while they still can. For this reason, the series may yet have some value once completed entirely.
Looking at the Skills Measured document for the new replacement PL-400: Microsoft Power Platform Developer exam, and there is a lot of crossover in content. Therefore, the existing posts and accompanying videos may still have some merit in the new state of play. I’ll be able to make an appropriate determination of this after Microsoft release PL-400 and I’ve been able to sit it. But, hopefully, some of this content will remain useful for at least another year or so.
I set out to run this series to completion, no matter what it takes 🙂

So with this in mind, I hope you continue to stick around for future posts and that they provide you with a useful tool as part of any revision or learning you are doing.

Last time around in the series, we took a deep-dive look into command buttons, as well as demonstrating how valuable the Ribbon Workbench tool is in helping us to fine-tune aspects of a model-driven Power App’s interface. This topic rounded off our discussion of the Extend the user experience area of the exam, meaning that we now move into the Extend the platform section. This area has equal weighting to Extend the user experience (15-20%), and the first topic concerns how we Create a plug-in. Specifically, candidates must demonstrate knowledge of the following:

Create a plug-in

debug and troubleshoot a plug-in

develop a plug-in

use the global Discovery Service endpoint

optimize plug-ins for performance

register custom assemblies by using the Plug-in Registration Tool

create custom actions

Plug-ins have been a mainstay within Dynamics 365, and its predecessor Dynamics CRM, for well over a decade now. Longstanding developers are, therefore, probably going to be well-versed in how to build them, but it’s always useful to get a refresher of old topics. With that in mind, let’s dive in!

As with all posts in this series, the aim is to provide a broad outline of the core areas to keep in mind when tackling the exam, linked to appropriate resources for more focused study. Your revision should, ideally, involve a high degree of hands-on testing and familiarity in working with the platform if you want to do well in this exam. I would also recommend that you have a good, general knowledge of how to work with the C# programming language before approaching plug-in development for the first time. Microsoft has published a whole range of introductory material to help you learn the language quickly.

What is a Plug-in?

In the series so far, we’ve already touched upon the following, functional tools that developers may leverage when dealing with complex business requirements:

Business Rules: These provide an excellent mechanism for handling simple logic, targeting both model-driven app forms and also platform-level operations.
Power Automate Flows: Using this, you can typically go the extra mile when compared with classic workflows, thereby allowing you to integrate multiple systems when processing asynchronous actions.
JavaScript: For situations where Business Rules can’t meet your particular requirement, and you need specific logic to trigger as a user is working on a model-driven form, this is the best tool in your arsenal.

All of these are great, but there may be situations where they are unsuitable, due to the sheer complexity of the business logic you are trying to implement. Also, some of the above tools do not support the ability to carry out synchronous actions (i.e. ones that happen straight away, as the user creates, updates, deletes etc. records in the application). Finally, it may be that you need to work with some specific elements of the SDK that are not exposed out straightforwardly via alternative routes. In these situations, a custom-authored plug-in is the only solution you can turn too.

So what are they then? Plug-ins allow developers to write either C# or VB.NET code, that is then registered within the application as a .NET Framework class library (DLL) and executed based on specific conditions you specify within its configuration. For example, when a user creates a Contact, retrieve the details of the parent Account record and update the Contact so that these details match. Developers will use Visual Studio when authoring a plug-in, typically using a class library project template. The Dynamics 365 SDK provides several modules that expose out the variety of different operations that a plug-in can support. Some of the other things that plug-ins support include:

Both synchronous and asynchronous execution.
Custom un-secure/secure configuration properties that can modify the behaviour of a plug-in at runtime. For example, by providing credentials to a specific environment to access.
Pre and Post Entity Images, snapshots of how a record and its related attributes looked before and after a platform level operation occurs.
For specific operations, such as Update, plug-ins can also support filtering attributes - basically, a list of defined fields that, when modified, will cause the plug-in to trigger.
Being able to specify the execution order for one or multiple plug-in steps. This capability can be useful when you need to ensure a set of steps execute in your desired order.

These days, thanks to tools such as Business Rules and Power Automate, we see the lessening importance of plug-ins and, typically, you would want to avoid considering their usage straight out the gate. However, they still have a place and, when used appropriately, become the only mechanism you can resort to when working with complicated business processes.

Understanding Messages, the Execution Pipeline & Steps

Before we start diving into building a plug-in for the first time, it is useful to provide an overview of the three core concepts that every plug-in developer needs to know:

Messages: These define a specific, platform level operation that the SDK exposes out. Some of the more commonly used Messages within the application include Create, Update or Delete. Some system entities may have their own set of unique Messages; CalculatePrice is an excellent example of this. From a plug-in perspective, developers essentially “piggyback” onto these operations as they are performed and inject their custom code. The following Microsoft Docs provides a detailed list of all supported messages and their corresponding entities and is well worth a read as part of preparing for the exam.
Execution Pipeline: As a user triggers a particular message, the application processes it using a defined set of stages, known as the execution pipeline. These are discussed in detail on this Microsoft Docs article, but the key ones we need to be aware of are:
- PreValidation: At this stage, the database transaction has not started. Also, the application has not yet performed any appropriate security checks; potentially meaning that the operation may fail if the user does not have the correct security privileges.
- PostValidation: Here, the database transaction has already started. The platform knows at this stage that no security constraints are preventing the operation from completing, but the transaction may still fail for other reasons.
- PostOperation: Although the database transaction has still not completed at this stage, the core operation of the message (executed within the MainOperation stage) will have completed by this stage.
A failure at any of these stages will cause the database transaction to rollback entirely, returning the record(s) to their original state. Now, from a plug-in perspective, the execution pipeline is exposed out to developers as stages where your custom code can execute. This can provide developers with a high degree of flexibility and capability when it comes to running their custom code. As a general rule of thumb, developers would use each of these stages under the following circumstances:
- PreValidation: Use this stage to perform checks to cancel the operation.
- PostValidation: This stage is useful for when you need to modify any values, based on some kind of business logic. Doing this at this stage would also prevent triggering another platform Message.
- PostOperation: Use this stage for when you need to carry out additional logic not related to the current record or potentially provide additional information back to the caller after the platform completes the core operation.
Developers will typically need to give some thought towards the execution pipeline and the most appropriate one to select, based on the requirements being worked with.
Steps: Simply writing a plug-in class and deploying out the library is not sufficient to trigger your custom logic. Developers must additionally provide a set of “instructions”, commonly known as Steps, that tells the application when and where to execute your custom code. It is here where both the Message and Execution Pipeline come into play, and you would always specify this information when creating a Step. Additional info you can include here includes the execution order, whether the plug-in will execute synchronously or not and the display name of Step when viewed within the application.

We will see shortly how these topics come into play, as part of using the Plug-in Registration Tool.

Building Your First Plug-In: Pre-Requisites

Before you start thinking about building your very first plug-in, you need to make sure that you have a few things installed onto your development machine:

Visual Studio: I would generally recommend using either Visual Studio 2017 or 2019 when developing for Dynamics 365 online. If you don’t have a Visual Studio/MSDN subscription, then the Community Edition can be used instead.
A Dynamics 365 / Common Data Service Tenant: Because where else are you going to deploy out and test your plug-in? 🙂
Knowledge of C# / VB.NET: Attempting to write a plug-in for the first time without at least a basic grasp of one of these languages will impede your progress.
Plug-in Registration Tool: To deploy your plug-in out, you will need access to this tool as well. We will cover this off later in the post.

Demo: Creating a Basic Plug-in using Visual Studio 2019 & C#

For those who would prefer to read a set of instructions, then this Microsoft Docs article provides a separate tutorial you can follow instead.

Using the Plug-in Registration Tool

Varied access options for when working with multiple Dynamics 365 environments, both online and on-premise.
The ability to register one or multiple plug-in assemblies.
The registering of plug-in steps and images, including the various settings, discussed earlier.
Via the tool, you can install the Plug-in Profiler, an essential tool when it comes to remote debugging your plug-ins; more on this capability later.

The Plug-In Registration Tool is also necessary for when you are deploying out other extensibility components, including Service Endpoints, Web Hooks or Custom Data Providers. We will touch upon some of these later on in the series. For this topic area and the exam, you must have a good general awareness of how to deploy and update existing plug-in assemblies.

Demo: Deploying a Basic Plug-in using the Plug-in Registration Tool

In this next video, I’ll show you how to take the plug-in developed as part of the previous video and deploy it out using the Plug-in Registration Tool:

There is also a corresponding Microsoft Docs tutorial that covers off these steps too.

Debugging Options for Plug-ins

Plug-ins deployed out into Dynamics 365 must always run within sandbox execution mode. As a result, this imposes a couple of limitations (some of which I’ll highlight in detail later on), the main one being that it greatly hinders the ability to debug deployed plug-ins easily. To get around this, Microsoft has provided two mechanisms that developers can leverage:

Plug-in Trace Logging: Using this, developers can write out custom log messages into the application, at any point in their code. This can be useful in identifying the precise location where a plug-in is not working as expected, as you can output specific values to the log for further inspection. You can also utilise them to provide more accurate error messages for your code that you would not necessarily wish to show users as part of a dialog box. Getting to grips with trace logging is easy - it’s just a few lines of code that you need to add to your project - and you can find out more about how to get started with it on the Microsoft Docs site.
Plug-in Registration Tool & Profiling: While trace logging is undoubtedly useful, there will be situations where you need something more. For example, it may become desirable to breakpoint code, inspect values/properties as they are processed through and determine when your plug-in hits specific conditions or error messages. For these situations, the Profiler comes into play, by allowing developers to “playback” their code execution using Visual Studio and the Plug-in Registration Tool. We mentioned the Plug-in Profiler tool earlier, which is a mandatory requirement as part of this and must be deployed out to your instance first. From there, you can generate a profile file that allows you to rewind execution within Visual Studio.

Developers will typically use both of these debugging methods in tandem when trying to figure out issues with their code. The first option provides a friendly, unobtrusive mechanism of inspecting how a plug-in has got on, with the Profiler acting as the nuclear option when the problem cannot be discerned easily via trace logging alone. Understanding the benefits/disadvantages of both and how to use them will be essential as part of your exam preparation. With this in mind, check out the two demo videos below that show you how to work with these features in-depth:

Demo: Debugging a Basic Plug-in using Trace Logging

Demo: Debugging a Basic Plug-in Using the Plug-in Registration Tool

General Performance / Optimization Tips

Always keep in mind some of the limitations as part of sandbox execution for your plug-ins, including:
- The 2 minute limit on execution time.
- Restriction on the use of specific 3rd party DLL’s, such as Newtonsoft.Json
- Various restrictions around accessing operating system level information, such as directories, system state etc.
For situations where sandbox limitation will cause issues in executing your business logic, you will need to consider moving away from a plug-in and adopting another solution.
Filtering attributes provide a great way of ensuring your code only executes when you need it to. You should always use these wherever possible.
Make sure to disable any plug-in profiling and remove the Profiler solution once you are finished. Active profiles can considerably slow down performance, and the Profile solution can also introduce unintended dependencies on core entities, causing difficulties when moving changes as part of a solution file.
The Solution Checker provides an excellent mechanism for quality checking your code and can give some constructive recommendations on where your plug-in can be improved. You should always run this at least once before moving your plug-in out into other environments.
Read through the following Microsoft Docs article and take care to follow the suggestions it outlines.

Don’t Forget…Custom Actions & Global Discovery Service Endpoint

As Microsoft has included them on the exam specification, it’s worth talking about these two topics briefly. However, only a general awareness of them should be sufficient, and I wouldn’t devote too much of your revision time towards them.

We’ve already looked at Messages in-depth and seen how they can act as a “gateway” for developers to bolt on specific logic when an application-level event occurs. Custom Actions allow you to take this a step further, by creating SDK/API exposable, custom Messages. For example, you could combine the Create/Update Messages of the Lead/Opportunity entities into a new message called SalesProgress. Plug-ins or operations targeting the Web API could then work with or trigger actions based on this. Custom Actions have been available within the application for many years now, and many developers continually argue them as being one of the most underrated features in Dynamics 365. They are also fully supported for use as part of Power Automate flows too. In short, they can be incredibly useful if you need to group multiple default messages into a single action, that can then be called instead of each one.

Finally, it is worth touching upon how developers use the Global Discovery Endpoint from a plug-in standpoint, but we must first touch upon the concepts of early-binding and late binding. In the video demos above, I wrote all of the code out using the late-binding mechanism. What this means is that, instead of declaring an object for the specific entity I wanted to work with (such as Contact), I instead used the generic Entity class and told the code which entity it’s supposed to represent. Which is fine, and gives me some degree of flexibility…but it does ultimately mean that I won’t detect any issues with my code (such as an incorrect field name) until runtime. Also, I have no easy way to tell how my entity looks using Intellisense; instead, I must continuously refer back to the application to view these properties. To get around this, we can use a mechanism known as early-binding, where all of the appropriate entity structures are generated within the project and referenced accordingly. The CrmSvcUtil.exe application provides a streamlined means of creating these early-bound classes and, as you might have guessed, you need to use the Global Discovery Endpoint to generate these classes successfully. There have been many previous wars and mounds of dead developers debates online regarding which mechanism is better. While early-binding does afford some great benefits, it does add some overhead into your development cycle, as you must continuously run the CrmSvcUtil application each time your entities change within Dynamics 365. All I would recommend is to try both options, identify the one that works best for you and, most importantly, adopt your preferred solution consistently.

Plug-ins can help when modelling out complicated business logic, that is impossible to achieve via other functional tools within the Power Platform. I hope this post has provided a good insight into their capabilities and to help you in your revision. In the next post, I’ll show you how you can extend Power Automate and Power Apps via custom API connectors, thereby allowing you to connect to a myriad of different systems.

Using SQL Server Views within Entity Framework Core (Code First Data Annotations)

Sun, 05 Jul 2020 00:00:00 +0000

If you’ve done any serious work involving Entity Framework (EF) Core in the past, there’s a good chance that you’ve worked with Code First Data Annotations when modelling your classes in C#. To summarise, these provide you with an in-line mechanism of describing the various DDL objects that you are referencing from your underlying data source. Typically, this may be required when you need the names, attributes and other general properties of your classes to differ from what your data source is surfacing. They are also an almost mandatory requirement when you want EF Core to handle the creation of your database automatically when deploying out your project for the first time. While I do personally find this approach to be borderline heretical, it is nonetheless a valid means of modelling out a database that is intrinsically bound to your EF Core project. So don’t let me put you off from using it if it will meet your particular requirements.

Now, it’s all well and good saying that something is good, but it’s far more important, I think, to see how it works in action. With this in mind, let’s assume we are adopting a pious approach for our EF Core project - namely, our database is already existing - and we are dealing with a mismatch between our database and class object names. Specifically, suppose we want to expose out a class called MyClass, but our underlying data source is a SQL Server table called MyTable. We would have to utilise the Table annotation, as demonstrated below, to ensure our code can navigate across to our intended location at runtime:

using System;
using System.ComponentModel.DataAnnotations.Schema;

namespace MyEFProject.Classes
{
 [Table("MyTable")]
 public class MyClass
 {
 //Column definitions go here...
 }
}

We can extend this further if we happen to be using custom schemas within our database. So, if we choose to create our MyTable within a schema called Sample, we can adjust the annotation as follows:

using System;
using System.ComponentModel.DataAnnotations.Schema;

namespace MyEFProject.Classes
{
 [Table("MyTable", Schema = "Sample")]
 public class MyClass
 {
 //Column definitions go here...
 }
}

Pretty neat. But what happens if we need to reference a view as opposed to a table instead? I dealt with this requirement recently when building out a read-only OData endpoint using ASP.NET Core MVC and, despite my efforts, I could not locate a valid source to tell me that views are a supported. Well, after experimenting further, I can confirm that it IS possible to do this via the very same Table Annotation used earlier. So, if our SQL Server view is called vw_MyView and exists on the very same schema referenced earlier, here’s how our class would need to look:

using System;
using System.ComponentModel.DataAnnotations.Schema;

namespace MyEFProject.Classes
{
 [Table("vw_MyView", Schema = "Sample")]
 public class MyClass
 {
 //Column definitions go here...
 }
}

And, although I have not tested this myself, it should also be possible for you to then write or update data into the view, in much the same manner as we can write manual SQL queries to do just this.

Using Data Annotations within EF Core can significantly simplify the process for handling situations like the ones described in this post, without needing to write a whole bunch of specialised code instead. If you haven’t already, I will urge you to read through this informative Microsoft Docs article, which talks through in detail the types of things you can do with them. To summarise then, never treat Data Annotations as a one-trick pony. Regardless of whether you are getting EF Core to handle the creation of your database structure automatically or are referencing an existing database, there will be a whole host of options available here to help you along.

Using Logic Apps & Azure Functions to Parse Variable Common Data Service Entity Data

Sun, 17 May 2020 00:00:00 +0000

The great thing when you are working with Azure Logic Apps is that, if you have previously spent any amount of time understanding Power Automate flows, the knowledge gained in this area is instantly transferable. That’s mainly because Power Automate is utilising Logic Apps underneath the hood. In practice, therefore, you can anticipate that a lot of the same trigger actions, connectors and general functionality will be identical. So why would you consider using Logic Apps at all in the first place? There are a few reasons why:

Logic Apps are a consumption-based service, meaning you are charged based on the number of monthly executions. Depending on the volumes involved, this can come in significantly cheaper when compared to buying a Power Automate license.
Logic Apps support the ability to execute within a dedicated location as part of integration service environments (ISE’s).
It is far easier to incorporate Logic Apps development as part of your Application Lifecycle Management (ALM) processes, with the ability to do one-click extracts of deployment templates. What’s more, you have a high degree of control over the parameterisation, deployment location and general functionality of Logic Apps when compared with Power Automate flows.

So in most senses, Logic Apps functionality can be argued as being on a par with that of Power Automate flows, often exceeding capabilities in some areas and being far better suited for large-scale, pro-developer integrations between systems.

Now, I use the work argued, as I cannot reliably say that the functionality on offer is complete like-for-like, especially when it comes to working with Dynamics 365 / the Common Data Service. Now it is true that we have a Common Data Service connector within Logic Apps, that has a list of actions that is equivalent to what is available within Power Automate:

However, there are two issues I can specifically highlight here:

Power Automate introduced the Common Data Service (current environment) connector a while back, which does exactly what it says on the tin. Also, this connector offers several additional features/benefits, such as the ability to execute change set requests or upload files/images to an entity record. This connector is not exposed at all within Logic Apps, even if you are in the same tenant where your Common Data Service environments reside. Logic App users, therefore, lose some degree of functionality here compared to Power Automate flows.
When using the List records action, you have access to all of the common OData filter queries, such as filter, top and orderby, thereby allowing you to return a specific subset of the data you require. However, you have no option here to indicate the precise fields you wish to return - via a select option or similar. This limitation can lead to your requests into the Common Data Service processing far more data than necessary and lengthen the execution time of your Logic Apps.

You can get around the second of these issues straightforwardly enough by using a Parse JSON action to consume and then remove any fields you don’t wish to process any further as part of your Logic App. But what if the data you wish to process from the Common Data Service is variable? For example, let’s assume that the entity and list of fields to be processed differs each time the Logic App runs - dictated by either the creation of a database record or by the details of a request passed to an HTTP endpoint setup on the Logic App. In this instance, it is not possible to use the Parse JSON action to parameterise this information satisfactorily. Indeed, to the best of my knowledge, it is not possible to utilise any of the collection/data operation functions available via the Workflow Definition Language to perform this action instead. Fortunately, where there is a will - and a bit of knowledge of C# - there is a way ;)

Logic Apps have had the longstanding capability to integrate alongside Azure Functions, thereby allowing developers to off-load any complex processing to a programming interface that can do almost anything you can imagine. So, in this case, Azure Functions becomes our rescuer and allows us to build out a basic Function App to support us. We can design the function app to accept two core bits of information:

A JSON array containing the response from Common Data Service. The JSON’s basic structure should look somewhat similar to the example below, representing two Lead records, for the function to parse it correctly. As you can see, this is a LOT of data that Logic Apps returns by default, for a measly 2 Lead records:

[
 {
 "@odata.id": "https://mycrminstance.crm11.dynamics.com/api/data/v9.0/leads(cd4299fe-a080-ea11-a811-002248012503)",
 "@odata.etag": "",
 "ItemInternalId": "cd4299fe-a080-ea11-a811-002248012503",
 "prioritycode": 1,
 "_prioritycode_label": "Default Value",
 "address2_addresstypecode": 1,
 "_address2_addresstypecode_label": "Default Value",
 "merged": false,
 "emailaddress1": "someonel1@example.com",
 "confirminterest": false,
 "numberofemployees": 200,
 "decisionmaker": false,
 "msdyn_ordertype": 192350000,
 "_msdyn_ordertype_label": "Item based",
 "modifiedon": "2020-04-17T11:46:57Z",
 "importsequencenumber": 1,
 "address1_composite": "789 Jones Blvd\r\nLa Vergne, TN 57332\r\nU.S.",
 "lastname": "McKay (sample)",
 "donotpostalmail": false,
 "revenue_base": 100000.0,
 "preferredcontactmethodcode": 1,
 "_preferredcontactmethodcode_label": "Any",
 "_ownerid_value": "9ec35ef0-9ec9-4e2e-b4af-e16bf5ba3b9b",
 "_ownerid_type": "systemusers",
 "_campaignid_value": "e14099fe-a080-ea11-a811-002248012503",
 "_campaignid_type": "campaigns",
 "firstname": "Yvonne",
 "evaluatefit": false,
 "yomifullname": "Yvonne McKay (sample)",
 "donotemail": false,
 "fullname": "Yvonne McKay (sample)",
 "msdyn_gdproptout": false,
 "statuscode": 1,
 "_statuscode_label": "New",
 "createdon": "2020-04-17T11:46:57Z",
 "address1_stateorprovince": "TN",
 "companyname": "Fourth Coffee (sample)",
 "donotfax": false,
 "leadsourcecode": 1,
 "_leadsourcecode_label": "Advertisement",
 "jobtitle": "Purchasing Manager",
 "address1_country": "U.S.",
 "versionnumber": 11127594,
 "address1_line1": "789 Jones Blvd",
 "telephone1": "555-0146",
 "donotsendmm": false,
 "leadqualitycode": 2,
 "_leadqualitycode_label": "Warm",
 "donotphone": false,
 "_transactioncurrencyid_value": "d85b13bb-081f-ea11-a812-00224801bc51",
 "_transactioncurrencyid_type": "transactioncurrencies",
 "subject": "New store opened this year - follow up (sample)",
 "address1_addresstypecode": 1,
 "_address1_addresstypecode_label": "Default Value",
 "donotbulkemail": false,
 "exchangerate": 1.0,
 "_modifiedby_value": "9ec35ef0-9ec9-4e2e-b4af-e16bf5ba3b9b",
 "_modifiedby_type": "systemusers",
 "followemail": true,
 "leadid": "cd4299fe-a080-ea11-a811-002248012503",
 "_createdby_value": "9ec35ef0-9ec9-4e2e-b4af-e16bf5ba3b9b",
 "_createdby_type": "systemusers",
 "websiteurl": "http://www.fourthcoffee.com/",
 "address1_city": "La Vergne",
 "salesstagecode": 1,
 "_salesstagecode_label": "Default Value",
 "revenue": 100000.0,
 "participatesinworkflow": false,
 "statecode": 0,
 "_statecode_label": "Open",
 "_owningbusinessunit_value": "9941c9c6-f71e-ea11-a812-00224801bc51",
 "_owningbusinessunit_type": "businessunits",
 "address1_postalcode": "57332",
 "budgetamount_base": null,
 "salutation": null,
 "address1_latitude": null,
 "address1_fax": null,
 "sic": null,
 "yomilastname": null,
 "address1_longitude": null,
 "telephone2": null,
 "timespentbymeonemailandmeetings": null,
 "address1_upszone": null,
 "schedulefollowup_qualify": null,
 "_slainvokedid_value": null,
 "schedulefollowup_prospect": null,
 "purchasetimeframe": null,
 "_purchasetimeframe_label": "",
 "_owningteam_value": null,
 "industrycode": null,
 "_industrycode_label": "",
 "budgetstatus": null,
 "_budgetstatus_label": "",
 "stageid": null,
 "_accountid_value": null,
 "lastonholdtime": null,
 "address2_country": null,
 "address1_utcoffset": null,
 "onholdtime": null,
 "address1_line2": null,
 "_createdonbehalfby_value": null,
 "telephone3": null,
 "fax": null,
 "emailaddress2": null,
 "_parentcontactid_value": null,
 "businesscard": null,
 "estimatedamount": null,
 "address2_telephone1": null,
 "description": null,
 "overriddencreatedon": null,
 "address2_county": null,
 "address2_stateorprovince": null,
 "_masterid_value": null,
 "_qualifyingopportunityid_value": null,
 "address2_city": null,
 "lastusedincampaign": null,
 "address2_composite": null,
 "_originatingcaseid_value": null,
 "utcconversiontimezonecode": null,
 "purchaseprocess": null,
 "_purchaseprocess_label": "",
 "address2_line3": null,
 "emailaddress3": null,
 "salesstage": null,
 "_salesstage_label": "",
 "_relatedobjectid_value": null,
 "processid": null,
 "pager": null,
 "address2_name": null,
 "address2_upszone": null,
 "_modifiedonbehalfby_value": null,
 "mobilephone": null,
 "initialcommunication": null,
 "_initialcommunication_label": "",
 "address2_latitude": null,
 "qualificationcomments": null,
 "address1_name": null,
 "middlename": null,
 "address1_telephone2": null,
 "address2_utcoffset": null,
 "entityimage": null,
 "_parentaccountid_value": null,
 "address1_telephone1": null,
 "address1_county": null,
 "address1_line3": null,
 "yomicompanyname": null,
 "need": null,
 "_need_label": "",
 "yomimiddlename": null,
 "entityimage_url": null,
 "entityimageid": null,
 "address2_telephone3": null,
 "_slaid_value": null,
 "address2_line1": null,
 "address2_postofficebox": null,
 "address2_longitude": null,
 "address2_telephone2": null,
 "address2_fax": null,
 "traversedpath": null,
 "address2_line2": null,
 "businesscardattributes": null,
 "address1_postofficebox": null,
 "entityimage_timestamp": null,
 "_customerid_value": null,
 "teamsfollowed": null,
 "yomifirstname": null,
 "timezoneruleversionnumber": null,
 "_contactid_value": null,
 "address1_telephone3": null,
 "estimatedvalue": null,
 "estimatedclosedate": null,
 "address2_postalcode": null,
 "budgetamount": null,
 "estimatedamount_base": null
 },
 {
 "@odata.id": "https://mycrminstance.crm11.dynamics.com/api/data/v9.0/leads(cf4299fe-a080-ea11-a811-002248012503)",
 "@odata.etag": "",
 "ItemInternalId": "cf4299fe-a080-ea11-a811-002248012503",
 "prioritycode": 1,
 "_prioritycode_label": "Default Value",
 "address2_addresstypecode": 1,
 "_address2_addresstypecode_label": "Default Value",
 "merged": false,
 "emailaddress1": "someonel2@example.com",
 "confirminterest": false,
 "numberofemployees": 2000,
 "decisionmaker": false,
 "msdyn_ordertype": 192350000,
 "_msdyn_ordertype_label": "Item based",
 "modifiedon": "2020-04-17T11:46:58Z",
 "importsequencenumber": 1,
 "address1_composite": "797 Roosevelt Ave NE\r\nSaint Louis, MO 83385\r\nU.S.",
 "lastname": "Stubberod (sample)",
 "donotpostalmail": false,
 "revenue_base": 150000.0,
 "preferredcontactmethodcode": 1,
 "_preferredcontactmethodcode_label": "Any",
 "_ownerid_value": "9ec35ef0-9ec9-4e2e-b4af-e16bf5ba3b9b",
 "_ownerid_type": "systemusers",
 "_campaignid_value": "e14099fe-a080-ea11-a811-002248012503",
 "_campaignid_type": "campaigns",
 "firstname": "Susanna",
 "evaluatefit": false,
 "yomifullname": "Susanna Stubberod (sample)",
 "donotemail": false,
 "fullname": "Susanna Stubberod (sample)",
 "msdyn_gdproptout": false,
 "statuscode": 1,
 "_statuscode_label": "New",
 "createdon": "2020-04-17T11:46:58Z",
 "address1_stateorprovince": "MO",
 "companyname": "Litware, Inc. (sample)",
 "donotfax": false,
 "leadsourcecode": 7,
 "_leadsourcecode_label": "Trade Show",
 "jobtitle": "Purchasing Manager",
 "address1_country": "U.S.",
 "versionnumber": 11127601,
 "address1_line1": "797 Roosevelt Ave NE",
 "telephone1": "555-0127",
 "donotsendmm": false,
 "leadqualitycode": 1,
 "_leadqualitycode_label": "Hot",
 "donotphone": false,
 "_transactioncurrencyid_value": "d85b13bb-081f-ea11-a812-00224801bc51",
 "_transactioncurrencyid_type": "transactioncurrencies",
 "subject": "Mailed an interest card back (sample)",
 "address1_addresstypecode": 1,
 "_address1_addresstypecode_label": "Default Value",
 "donotbulkemail": false,
 "exchangerate": 1.0,
 "_modifiedby_value": "9ec35ef0-9ec9-4e2e-b4af-e16bf5ba3b9b",
 "_modifiedby_type": "systemusers",
 "followemail": true,
 "leadid": "cf4299fe-a080-ea11-a811-002248012503",
 "_createdby_value": "9ec35ef0-9ec9-4e2e-b4af-e16bf5ba3b9b",
 "_createdby_type": "systemusers",
 "websiteurl": "http://www.litwareinc.com/",
 "address1_city": "Saint Louis",
 "salesstagecode": 1,
 "_salesstagecode_label": "Default Value",
 "revenue": 150000.0,
 "participatesinworkflow": false,
 "statecode": 0,
 "_statecode_label": "Open",
 "_owningbusinessunit_value": "9941c9c6-f71e-ea11-a812-00224801bc51",
 "_owningbusinessunit_type": "businessunits",
 "address1_postalcode": "83385",
 "budgetamount_base": 3000.0,
 "salutation": null,
 "address1_latitude": null,
 "address1_fax": null,
 "sic": null,
 "yomilastname": null,
 "address1_longitude": null,
 "telephone2": null,
 "timespentbymeonemailandmeetings": null,
 "address1_upszone": null,
 "schedulefollowup_qualify": null,
 "_slainvokedid_value": null,
 "schedulefollowup_prospect": null,
 "purchasetimeframe": 2,
 "_purchasetimeframe_label": "Next Quarter",
 "_owningteam_value": null,
 "industrycode": null,
 "_industrycode_label": "",
 "budgetstatus": null,
 "_budgetstatus_label": "",
 "stageid": null,
 "_accountid_value": null,
 "lastonholdtime": null,
 "address2_country": null,
 "address1_utcoffset": null,
 "onholdtime": null,
 "address1_line2": null,
 "_createdonbehalfby_value": null,
 "telephone3": null,
 "fax": null,
 "emailaddress2": null,
 "_parentcontactid_value": null,
 "businesscard": null,
 "estimatedamount": null,
 "address2_telephone1": null,
 "description": null,
 "overriddencreatedon": null,
 "address2_county": null,
 "address2_stateorprovince": null,
 "_masterid_value": null,
 "_qualifyingopportunityid_value": null,
 "address2_city": null,
 "lastusedincampaign": null,
 "address2_composite": null,
 "_originatingcaseid_value": null,
 "utcconversiontimezonecode": null,
 "purchaseprocess": 1,
 "_purchaseprocess_label": "Committee",
 "address2_line3": null,
 "emailaddress3": null,
 "salesstage": null,
 "_salesstage_label": "",
 "_relatedobjectid_value": null,
 "processid": null,
 "pager": null,
 "address2_name": null,
 "address2_upszone": null,
 "_modifiedonbehalfby_value": null,
 "mobilephone": null,
 "initialcommunication": null,
 "_initialcommunication_label": "",
 "address2_latitude": null,
 "qualificationcomments": null,
 "address1_name": null,
 "middlename": null,
 "address1_telephone2": null,
 "address2_utcoffset": null,
 "entityimage": null,
 "_parentaccountid_value": null,
 "address1_telephone1": null,
 "address1_county": null,
 "address1_line3": null,
 "yomicompanyname": null,
 "need": null,
 "_need_label": "",
 "yomimiddlename": null,
 "entityimage_url": null,
 "entityimageid": null,
 "address2_telephone3": null,
 "_slaid_value": null,
 "address2_line1": null,
 "address2_postofficebox": null,
 "address2_longitude": null,
 "address2_telephone2": null,
 "address2_fax": null,
 "traversedpath": null,
 "address2_line2": null,
 "businesscardattributes": null,
 "address1_postofficebox": null,
 "entityimage_timestamp": null,
 "_customerid_value": null,
 "teamsfollowed": null,
 "yomifirstname": null,
 "timezoneruleversionnumber": null,
 "_contactid_value": null,
 "address1_telephone3": null,
 "estimatedvalue": null,
 "estimatedclosedate": null,
 "address2_postalcode": null,
 "budgetamount": 3000.0,
 "estimatedamount_base": null
 }
]

A query parameter header - called attributes - containing the list of attributes we wish to return as a comma-separated list e.g. fullname,companyname

You can then feed these two bits of information into an Azure Function endpoint, with the complete code for this illustrated below:

using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Linq;
using System.Collections.Generic;

namespace APIHelper.LogicApps
{
 public static class SelectJSONAttributes
 {
 [FunctionName("SelectJSONAttributes")]
 public static async Task<IActionResult> Run(
 [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = null)] HttpRequest req,
 ILogger log)
 {
 log.LogInformation("C# HTTP trigger function processed a request.");

 string attributes = req.Query["attributes"];

 string requestBody = await new StreamReader(req.Body).ReadToEndAsync();

 try
 {
 JArray json = JArray.Parse(requestBody);
 attributes = attributes ?? json?.ToString();
 if (attributes == null)
 {
 return new BadRequestObjectResult("The 'attributes' query parameter is missing from the request.");
 }

 foreach(JObject item in json.Children())
 {
 IList<string> keys = item.Properties().Select(p => p.Name).ToList();
 IList<string> retainKeys = attributes.Split(',');
 IList<string> removeKeys = keys.Except(retainKeys).ToList();

 foreach(string attribute in removeKeys)
 {
 item.Property(attribute).Remove();
 }
 }

 return new OkObjectResult(json);
 }

 catch(JsonReaderException e)
 {
 return new BadRequestObjectResult(e.Message);
 }

 catch (JsonSerializationException e)
 {
 return new BadRequestObjectResult(e.Message);
 }
 }
 }
}

To then add this onto your Logic Apps after deploying out to your function app, there are a few additional steps you’ll need to do:

Enable the managed identity for your Logic App. I recommend using the system-assigned option, as it makes the setup process a whole lot easier.
One enabled, this managed identity object needs to be granted Contributor permission or higher onto the Azure Function App.
When setting up the Logic App, ensure that the authentication settings mirror the options indicated below:

With all that done, we can test the Logic App and confirm everything works as expected:

It’s working! 🙂 And thanks to the capabilities built into the Newtonsoft JSON framework, the amount of actual code written is kept to an absolute minimum.

Now, even though I am blogging about this solution, I must highlight that I am not an overall fan and am frustrated slightly that Logic Apps does not have a way around this. Answers on a postcard if you think I have missed something glaringly obvious but, for now, and until the Common Data Service connector exposes out an appropriate select column option, this is the best solution we have available to us. Ultimately, we should take solace in the fact that Azure Functions are blisteringly easy to get set up and running. Also, for this particular scenario, they provide a streamlined way for us to leverage the low-code capabilities of Logic Apps and dip into more complex, bespoke processing, without necessarily needing to throw Logic Apps out of the window in the first place.

A Few Observations on Using Custom Pricing Plugins Alongside Project Service Automation

Sun, 11 Aug 2019 00:00:00 +0000

The problem sometimes, when developing a bespoke solution, is that it is impossible to anticipate how it may evolve. Whether it becomes dependent on changed functionality or new systems introduced into the equation, this eventuality is not necessarily down to a scoping or requirements gathering error. Organisations can, and will, drive off into all sorts of unexpected directions over time and, like it or lump it, IT systems are generally the last to follow behind any change. In this week’s post, I want to focus on a recent example I was involved in related to this theme, involving Dynamics 365 Customer Engagement (D365CE) and the Project Service Automation (PSA) add-on.

Setting the Scene: What is a Custom Pricing Plug-in?

Those familiar the D365CE will no doubt be able to explain how the application automatically totals up the various product line items for core, sales-related entities - Opportunity, Quote etc. Typically, this behaviour will be suitable for most scenarios, but there may be situations where fine-tuning is required to factor in additional calculations or perform a bespoke integration. For example, there may be a requirement to query an external ERP system to ensure that the Cost Price value for a line item record is correct. And, while it is undoubtedly possible to customise the application around how the default pricing calculations work, solutions of this nature can typically become unwieldy to maintain over time. Besides, you always remain at the mercy of how the application decides to perform sales entity calculations, which may be subject to change between major version releases of D365CE.

Fortunately, one of (I believe) the best-kept secrets concerning this functionality is that a) it can be disabled entirely and b) replaced with new pricing logic of your choosing. The CalculatePrice message is the C#/VB.NET developer’s gateway towards achieving this and, by developing a bespoke plug-in, it is possible to tailor all sales calculations completely. While implementing a solution of this nature does, invariably, introduce a degree of complexity into your D365CE deployment, it does have several benefits:

Avoids a messy/“hacky” solution from being implemented using Business Rules, Flows or any other customisation feature within the application.
Provides the capability to apply the same calculations to all sales entities quickly or implement bespoke logic to calculate Quotes differently from Opportunity records, for example.
Allows you to achieve more complex integration requirements, such as those involving separate application systems.

I am a major proponent of implementing custom pricing solutions and have discussed how to get started with custom pricing plug-ins previously on the blog. However, I do always heavily caution their use, and it is a “last resort” if you cannot work with D365CE’s default pricing functionality. The old maxim stands true: just because you CAN do something, doesn’t necessarily mean you should 🙂

PSA + Custom Pricing Plugin = ?

Going back now to the example I alluded to at the start of this post…I was contacted by a customer who was having issues with a custom pricing solution I had implemented for them a while back. Since then, the organisation had implemented PSA and had started to get very nasty error messages appearing when working with Project-based Line records, as indicated below:

As the error message demonstrates, the culprit was the custom pricing plug-in, which was preventing the creation of any associated Line Detail record. Evaluating the tracing logs for this plug-in showed that everything worked fine and dandy, up until the point when any actual calculation values needed applying to the Quote Line record. This step would fail with the following error message:

CalculatePrice: System.ServiceModel.FaultException`1[Microsoft.Xrm.Sdk.OrganizationServiceFault]: The total line amount and estimated tax of all Sales Document Line Details must equal the line amount and estimated tax of the Sales Document Line. (Fault Detail is equal to Exception details:

Further investigation of the error logs pointed towards the PSA managed solution plug-in Microsoft.Dynamics.ProjectService.Plugins.PreValidatequotedetailUpdate being the culprit for the raising of the OrganisationServiceFault error in the first place.

Understanding How PSA Works

At this stage, I had to get to grips with how this nice-looking PSA application worked under the hood, having previously only a surface-level awareness of its behaviour. PSA is designed to work very closely alongside the existing Sales functionality within D365CE. This approach provides not only the ability to manage/plan projects at a resource-level but ensures the appropriate factoring of any delivery costs into generated sales records. For “time & material” projects, this is crucial, as providing sufficient accounting for a resources time and financial return is imperative. For the most part, PSA relies on the tried and tested Sales module functionality to deliver most of these requirements, but also provides the following, additional Line Detail entities, linked to the corresponding sales/product line entity:

Opportunity Line Detail
Quote Line Detail
Sales Contract (i.e. Order) Line Detail
Invoice Line Detail

The purpose of these entities (except for the Opportunity Line Detail, which records a “finger in the air” budget value instead) is to allow multiple resources to be associated with a Quote Line record. For example, let’s assume you are charging a customer for Project Scoping. As part of this, the following resources need to be assigned:

4 hours for a Solution Architect
6 hours for a Pre-Sales Consultant
6 hours for a Project Manager

In this scenario, all three of these roles would be created as Line Detail records against a Project Scoping Line record. Although this process does involve a few additional steps compared to the default Sales module, this functionality is also useful as it allows you to:

Factor in whether a resource is chargeable as part of an activity or not.
Allows you to categorise the type of cost that the Line Detail is.
Indicate the anticipated length of time that the resource will require involvement as part of an engagement.

So with a combination of understanding how the application works and a thorough diagnosis of the error message in question, the answer to the problem seems relatively apparent. Any PSA custom pricing plug-in must factor the total, chargeable value of all related Line Detail’s, ensuring the Amount and Estimated Tax fields update accordingly.

The Techie Bit: Evaluating a Suggested Approach

Now that we know the problem, we can start to think about a potential resolution. The C# class below shows a potential approach for calculating PSA Product Line details records. Pass any Line record through, and the pesky error message shown above should no longer appear, and all expected calculation will be applied:

private static void CalculatePSAProduct(Entity e1, IOrganizationService service, ITracingService tracingService)
{
 //Determine which Line Detail records to retrieve from - throw an error if an unexpected record has been passed through.
 //Also need to determine the lookup field name as part of this operation - either msdyn_quotelineid or msdyn_salescontractlineid
 string detailName;
 string detailRelatedEntityName;

 switch (e1.LogicalName)
 {
 case "quotedetail":
 detailName = "msdyn_quotelinetransaction";
 detailRelatedEntityName = "msdyn_quotelineid";
 tracingService.Trace("Record being calculated = Quote Line Detail");
 break;
 case "salesorderdetail":
 detailName = "msdyn_orderlinetransaction";
 detailRelatedEntityName = "msdyn_salescontractlineid";
 tracingService.Trace("Record being calculated = Order Line Detail");
 break;
 default:
 throw new InvalidPluginExecutionException("An error occurred when applying custom pricing. An incorrect entity name was passed to the CalculatePSAProduct method");
 }

 //Retrieve all related, chargeable Line Detail records that have a Transaction Type value of "Project Contract" with the Amount, Tax and amount_after_tax field values

 tracingService.Trace("Retrieving all related, chargeable " + detailName + " records...");
 QueryByAttribute qba = new QueryByAttribute(detailName);
 qba.ColumnSet = new ColumnSet("msdyn_amount", "msdyn_tax", "msdyn_amount_after_tax");
 qba.Attributes.AddRange("msdyn_billingtype");
 qba.Values.AddRange(192350001);
 qba.Attributes.AddRange("msdyn_transactiontypecode");
 qba.Values.AddRange(192350004);
 qba.Attributes.AddRange(detailRelatedEntityName);
 qba.Values.AddRange(e1.Id);

 EntityCollection lt = service.RetrieveMultiple(qba);
 tracingService.Trace("Got " + lt.Entities.Count.ToString() + " " + detailName + " records!");

 //Total up each individual Line Detail record to determine Amount, Estimated Tax and Amount After Tax

 decimal ppu = 0;
 decimal t = 0;
 decimal ea = 0;

 for (int i = 0; i < lt.Entities.Count; i++)
 {
 //If no value in the returned fields, default to 0
 ppu += ((Money)lt.Entities[i]["msdyn_amount"])?.Value ?? 0;
 t += ((Money)lt.Entities[i]["msdyn_tax"])?.Value ?? 0;
 ea += ((Money)lt.Entities[i]["msdyn_amount_after_tax"])?.Value ?? 0;
 }

 //From here, you can begin to apply any custom calculations needed to satisfy your individual requirements.
 //In this example, we simply pass the totals from above onto the relevant Line fields and then update the Line record.

 e1["priceperunit"] = new Money(ppu);
 tracingService.Trace("Quoted/Contracted Amount = " + ppu.ToString());
 e1["tax"] = new Money(t);
 tracingService.Trace("Estimated Tax = " + t.ToString());
 e1["extendedamount"] = new Money(ea);
 tracingService.Trace("Quoted/Contracted Amount After Tax = " + ea.ToString());

 service.Update(e1);
 tracingService.Trace(e1.LogicalName + " updated successfully!");
}

Some further explanation on this class may be required, given some additional quirks that PSA throws into the mix:

The code is designed to be Line Detail record agnostic, which is why a switch statement is needed to determine certain field values needed within the QueryByAttribute query. The Opportunity Line and Invoice Detail entities do not behave the same way as the Quote & Order Line entities, so these are specifically excluded.
It would appear that the PSA application creates several, hidden Line Detail records in the application for every Line Detail record that a user creates. These blank records do not contain any of the expected pricing values. Therefore, to avoid potential issues, the QueryByAttribute filters specifically ensure these do not return and, also, ensures that only records marked as chargeable are brought back.

Beyond that, most of the code should be self-explanatory for those familiar working with C# - however, let me know in the comments below if you have any queries.

All Change Ahead

At the time of writing this post, we have just recently seen a major upgrade of PSA take place, from version 2 to version 3. This particular release saw a lot of change within PSA and, indeed, users of version 2 of the application need to specifically request Microsoft to allow them to upgrade to the newer version. This requirement is likely due to the risk of stuff breaking between versions. Now, I am hearing on the grapevine that another significant upgrade will be coming as part of the fall 2019 release. A reading of the release notes would seem to suggest this to be a major overhaul, likely involving the removal entirely of the current Microsoft Project embedded functionality. We will no doubt find out more about this soon, but I would caveat this entire post by saying it’s outlined fix could become redundant within months. All we can do for now is keep a keen eye on the release notes and see how things ultimately pan out.

The Community is Awesome

In times of crisis new and exciting learning opportunities, you can always rest assured that the fantastic D365CE community will be on hand to assist. In this case, I must give thanks to the PSA wizard Antti Pajunen for being a reliable and authoritative steer on PSA and in helping to answer my questions relating to it. If you are working with PSA and are not already following his blog, then get over there today - you won’t be disappointed!

I Could Talk All Day About This Stuff…

No, seriously, I could. Feel free to leave a comment below or contact me if you would like to find out how to implement a custom pricing solution within your D365CE system.

Extract New Record GUID from Dynamics 365 Customer Engagement Create Web API Request (C#)

Sun, 16 Jun 2019 00:00:00 +0000

Typically, when working with a database/application to programmatically create new records, it is desirable for us to return some information relating to any newly created records; this would typically take the form of a Globally Unique Identifier (GUID), primary key value or something else that uniquely identifies the record in question. Doing this may be useful for several reasons:

By returning this type of data, we can implicitly confirm that the record has been created successfully, as such a value would not exist otherwise.
There may be some additional operations that need to be carried out against the new record, post-creation. By returning its unique identifier, we can carry out such activities without any further impediment and do not need to rely on a separate retrieval operation to obtain this property.
The unique identifier may be required elsewhere within our application. For example, we may want to store the unique identifier within a separate system, to satisfy any current/future data integration requirements.

Dynamics 365 Customer Engagement (D365CE) is no different in this regard, and you traditionally may have had to devote some effort to accommodate this scenario. Fortunately, if you are working with tools such as Jason Lattimer’s CRM REST Builder, a lot of the hassle involved here becomes virtually non-existent, as you can very quickly generate code snippets that not only perform your entire create record operation but also return the records GUID after the transaction has completed successfully. An example of the type of code that the tool can generate is seen below:

var entity = {};
entity.name = "CRM Chap";

var req = new XMLHttpRequest();
req.open("POST", Xrm.Page.context.getClientUrl() + "/api/data/v9.1/accounts", true);
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.onreadystatechange = function() {
 if (this.readyState === 4) {
 req.onreadystatechange = null;
 if (this.status === 204) {
 var uri = this.getResponseHeader("OData-EntityId");
 var regExp = /\(([^)]+)\)/;
 var matches = regExp.exec(uri);
 var newEntityId = matches[1];
 } else {
 Xrm.Utility.alertDialog(this.statusText);
 }
 }
};
req.send(JSON.stringify(entity));

In this example, lines 14-17 of the snippet handle the process of returning the newly created records GUID, with some specific steps required to ensure this renders nicely. This is because D365CE returns the newly created record as part of a complete URL by default (e.g. the above example, unmodified, would return something like https://mycrminstance.crm11.dynamics.com/api/data/v9.1/accounts(711cd182-0f90-e911-a97b-002248014773)). Therefore, a Regular Expression (RegEx) is used to strip out all of the URL components and, instead, supply us with the record GUID as part of the newEntityId variable. VERY handy and another reason why we should all be thanking Jason for building such an amazing tool.

While this is all well and good if you are working with the Web API using JScript, there may be other programming languages that you wish to utilise alongside D365CE’s Web API. A natural example of this is C# and, fortunately, there are also code samples freely available to help simplify development. However, these samples do not implement the same kind of transformation that Jason’s tool very kindly does by default. So how can we replicate this functionality using C#? Thanks mostly to the excellent Regular Expression engine built directly into .NET, the task of porting across similar functionality to C# is greatly simplified. By adding a using System.Text.RegularExpressions; statement to the top of our C# class file, we can then use the following three lines of code to extract out the CRM record GUID as a string value (where entityUri is the same URL example shown above):

Regex rx = new Regex(@"\(([^)]+)\)");
Match match = rx.Match(entityUri);
string entityID = match.Value;

From there, we could then look to cast the entityID string into a Guid data type to, for example, associate the record to another within the application, update our external application system, print it out to a log file/console window…the possibilities are endless! What matters the most is that we can get something unique that identifies our newly created D365CE record and all it took was a few lines of code in C# - which is always nice. 🙂

Override the Modified On Field Value When Reassigning Resolved Cases (Dynamics 365 for Customer Service)

Sun, 22 Apr 2018 00:00:00 +0000

Typically, when working with Dynamics 365 for Customer Service entities, you expect a certain type of behaviour. A good example of this in practice is entity record activation and the differences between Active and Inactive record types. In simple terms, you are generally restricted in the actions that can be performed against an Inactive record, most commonly being the modification of a field value. You can, however, perform actions such as deleting and reassigning records to other users in the application. The latter of these can be particularly useful if, for example, an individual leaves a business and you need to ensure that another employee requires access to old, inactive records.

When it comes to reporting on time intervals for when a record was last changed, I often - rightly or wrongly - see the Modified On field used for this purpose. This, essentially, stores the date and time of when the record was…well…last modified in the system! Since only more recent changes to the application have facilitated an alternative approach in reporting a record’s age and its current stage within a process, it is perhaps understandable why this field is often chosen when attempting to report, for example, the date on which a record was moved to Inactive status. Where you may encounter issues with this is if you are working in a similar situation highlighted above - namely, an individual leaving a business - and you need to reassign all of the inactive records owned by them. Doing either of these steps will immediately update the Modified On value to the current date and time, skewering any dependent reporting.

Fortunately, there is a way of getting around this, if you don’t have any qualms about opening up Visual Studio and putting together a plug-in in C#. Via this route, you can prevent the Modified On value of a record from being updated by capturing the original value and forcing the platform to commit this value to the database during the Pre-Operation stage of the transaction, as opposed to the date and time of when the record is reassigned. In fact, using this method, you can set the Modified On value to be whatever you want. Here’s the code that illustrates how to achieve both scenarios:

using System;

using Microsoft.Xrm.Sdk;

namespace Sample.OverrideCaseModifiedDate
{
 public class PreOpCaseAssignOverrideModifiedDate : IPlugin
 {
 public void Execute(IServiceProvider serviceProvider)
 {
 //Obtain the execution context from the service provider.

 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

 //Extract the tracing service for use in debugging sandboxed plug-ins

 ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));

 tracingService.Trace("Tracing implemented successfully!");

 if (context.InputParameters.Contains("Target") && context.InputParameters["Target"] is Entity)

 {
 Entity incident = (Entity)context.InputParameters["Target"];
 Entity preIncident = context.PreEntityImages["preincident"];

 //At this stage, you can either get the previous Modified On date value via the Pre Entity Image and set the value accordingly...

 incident["modifiedon"] = preIncident.GetAttributeValue<DateTime>("modifiedon");

 //Or alternatively, set it to whatever you want - in this example, we get the Pre Entity Image createdon value, add on an hour and then set the value

 DateTime createdOn = preIncident.GetAttributeValue<DateTime>("createdon");
 TimeSpan time = new TimeSpan(1, 0, 0);
 DateTime newModifiedOn = createdOn.Add(time);
 incident["modifiedon"] = newModifiedOn;

 }
 }
 }
}

When deploying out your plug-in code to the application (something that I hope regular readers of the blog will be familiar with), make sure that the settings you configure for your Step and the all-important Entity image resemble the images below:

Now, the more eagle-eyed readers may notice that the step is configured on the Update as opposed to the Assign message, which is what you (and, indeed, I when I first started out with this) may expect. Unfortunately, because the Input Parameters of the Assign message only returns two Entity Reference objects - the incident (Case) and systemuser (User) entities, respectively - as opposed to an Entity object for the incident entity, we have no means of interfering with the underlying database transaction to override the required field values. The Update message does not suffer from this issue and, by scoping the plug-in’s execution to the ownerid field only, we can ensure that it will only ever trigger when a record is reassigned.

With the above plug-in configured, you have the flexibility of re-assigning your Case records without updating the Modified On field value in the process or expanding this further to suit whatever business requirement is needed. In theory, as well, the approach used in this example could also be applied to other what we may term “system defined fields”, such as the Created On field. Hopefully, this post may prove some assistance if you find yourself having to tinker around with inactive Case records in the future.

Dynamics 365 Customer Engagement Deep Dive: Creating a Basic Custom Workflow Assembly

Sun, 18 Mar 2018 00:00:00 +0000

This is an accompanying blog post to my YouTube video Dynamics 365 Customer Engagement Deep Dive: Creating a Basic Custom Workflow Assembly. The video is part of my tutorial series on how to accomplish developer focused tasks within Dynamics 365 Customer Engagement. You can watch the video in full below:

Below you will find links to access some of the resources discussed as part of the video and to further reading topics:

Full Code Sample

using System;
using System.Activities;

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Workflow;
using Microsoft.Xrm.Sdk.Query;

namespace D365.SampleCWA
{
 public class CWA_CopyQuote : CodeActivity
 {
 protected override void Execute(CodeActivityContext context)
 {
 IWorkflowContext c = context.GetExtension<IWorkflowContext>();

 IOrganizationServiceFactory serviceFactory = context.GetExtension<IOrganizationServiceFactory>();
 IOrganizationService service = serviceFactory.CreateOrganizationService(c.UserId);

 ITracingService tracing = context.GetExtension<ITracingService>();

 tracing.Trace("Tracing implemented successfully!", new Object());

 Guid quoteID = c.PrimaryEntityId;

 Entity quote = service.Retrieve("quote", quoteID, new ColumnSet("freightamount", "discountamount", "discountpercentage", "name", "pricelevelid", "customerid", "description"));

 quote.Id = Guid.Empty;
 quote.Attributes.Remove("quoteid");

 quote.Attributes["name"] = "Copy of " + quote.GetAttributeValue<string>("name");
 Guid newQuoteID = service.Create(quote);

 EntityCollection quoteProducts = RetrieveRelatedQuoteProducts(service, quoteID);
 EntityCollection notes = RetrieveRelatedNotes(service, quoteID);

 tracing.Trace(quoteProducts.TotalRecordCount.ToString() + " Quote Product records returned.", new Object());

 foreach (Entity product in quoteProducts.Entities)
 {
 product.Id = Guid.Empty;
 product.Attributes.Remove("quotedetailid");
 product.Attributes["quoteid"] = new EntityReference("quote", newQuoteID);
 service.Create(product);
 }
 foreach (Entity note in notes.Entities)
 {
 note.Id = Guid.Empty;
 note.Attributes.Remove("annotationid");
 note.Attributes["objectid"] = new EntityReference("quote", newQuoteID);
 service.Create(note);
 }
 }

 [Input("Quote Record to Copy")]
 [ReferenceTarget("quote")]

 public InArgument<EntityReference> QuoteReference { get; set; }
 private static EntityCollection RetrieveRelatedQuoteProducts(IOrganizationService service, Guid quoteID)
 {
 QueryExpression query = new QueryExpression("quotedetail");
 query.ColumnSet.AllColumns = true;
 query.Criteria.AddCondition("quoteid", ConditionOperator.Equal, quoteID);
 query.PageInfo.ReturnTotalRecordCount = true;

 return service.RetrieveMultiple(query);
 }
 private static EntityCollection RetrieveRelatedNotes(IOrganizationService service, Guid objectID)
 {
 QueryExpression query = new QueryExpression("annotation");
 query.ColumnSet.AllColumns = true;
 query.Criteria.AddCondition("objectid", ConditionOperator.Equal, objectID);
 query.PageInfo.ReturnTotalRecordCount = true;

 return service.RetrieveMultiple(query);
 }
 }
}

Download/Resource Links

Visual Studio 2017 Community Edition

Setup a free 30 day trial of Dynamics 365 Customer Engagement

C# Guide (Microsoft Docs)

Source Code Management Solutions

Visual Studio Team Services - Free for up to 5 users and my recommended choice when working with Dynamics 365 Customer Engagement
BitBucket
GitHub

Top 10 Most Viewed CRM Chap Blog Posts

Sun, 18 Feb 2018 00:00:00 +0000

Slight change of pace with this week’s blog post, which will be a fairly condensed and self-indulgent affair - due to personal circumstances, I have been waylaid somewhat when it comes to producing content for the blog and I have also been unable to make any further progress with my new YouTube video series. Hoping that normal service will resume shortly, meaning additional videos and more content-rich blog posts, so stay tuned.

I’ve been running the CRM Chap blog for just over 2 years now. Over this time, I have been humbled and proud to have received numerous visitors to the site, some of whom have been kind enough to provide feedback or to share some of their Dynamics CRM/365 predicaments with me. Having reached such a landmark now seems to be good a time as any to take a look back on the posts that have received the most attention and to, potentially, give those who missed them the opportunity to read them. In descending order, here is the list of the most viewed posts to date on the crmchap.co.uk website:

I suppose it is a testament to the blog’s stated purpose that posts covering areas not exclusive to Dynamics CRM/365 rank so highly on the list and, indeed, represents how this application is so deeply intertwined with other technology areas within the Microsoft “stack”.

To all new and long-standing followers of the blog, thank you for your continued support and appreciation for the content 🙂

System.AggregateException: One or more errors occured (Dynamics CRM/Dynamics 365 Customer Engagement Plug-in)

Sun, 11 Feb 2018 00:00:00 +0000

As part of developing Dynamics CRM/Dynamics 365 Customer Engagement (CRM/D365CE) plug-ins day in, day out, you can often forget about the Execution Mode setting. This can be evidenced by the fact that I make no mention of it in my recent tutorial video on plug-in development. In a nutshell, this setting enables you to customise whether your plug-in executes in Synchronous or Asynchronous mode. Now, you may be asking - just what the hell does that mean?!? The best way of understanding is by rephrasing the terminology; it basically tells the system when you want your code to be executed. Synchronous plug-ins execute all of your business logic whilst the record is being saved by the user, with this action not being considered complete and committed to the backend database until the plug-in completes. By comparison, Asynchronous plug-ins are queued for execution after the record has been saved. A System Job record is created and queued alongside other jobs in the system via the Asynchronous Service. Another way of remembering the difference between each one is to think back to the options available to you as part of a Workflow. They can either be executed in real time (synchronously) or in the background (asynchronously). Plug-ins are no different and give you the flexibility to ensure your business logic is applied immediately or, if especially complex, queued so that the system has sufficient time to process in the background.

I came across a strange issue with an arguably even stranger Synchronous plug-in the other day, which started failing after taking an inordinately long time saving the record:

Unexpected exception from plug-in (Execute): MyPlugin.MyPluginClass: System.AggregateException: One or more errors occurred.

The “strange” plug-in was designed so that, on the Create action of an Entity record, it goes out and creates various related records within the application, based on a set of conditions. We originally had issues with the plug-in a few months back erroring, due to the execution time exceeding the 2 minute limit for sandbox plug-ins. A rather ingenious and much more accomplished developer colleague got around the issue by implementing a degree of asynchronous processing within the plug-in, achieved like so:

await Task.Factory.StartNew(() =>
{
 lock (service)
 {
 Stopwatch stopwatch = Stopwatch.StartNew();
 Guid record = service.Create(newRecord);
 tracing.Trace("Record with ID " + record.ToString() + " created successfully after: {0}ms.", stopwatch.ElapsedMilliseconds);
 }
});

I still don’t fully understand just exactly what this is doing, but I put this down to my novice level C# knowledge 🙂 The important thing was that the code worked…until some additional processing was added to the plug-in, leading to the error message above.

At this juncture, our only choice was to look at forcing the plug-in to execute in Asynchronous mode by modifying the appropriate setting on the plug-in step within the Plugin Registration Tool:

After making this change and attempting to create the record again in the application, everything worked as expected. However, this did create a new problem for us to overcome - end users of the application were previously used to seeing the related records created by the plug-in within sub-grids on the Primary Entity form, which would then be accessed and worked through accordingly. As the very act of creating these records now took place within the background and took some time to complete, we needed to display an informative message to the user to advise them to refresh the form after a few minutes. You do have the ability within plug-ins to display a custom message back to the user, but this is only in situations where you are throwing an error message and it didn’t seem to be a particularly nice solution for this scenario.

In the end, the best way of achieving this requirement was to implement a JScript function on the form. This would trigger whenever the form is saved and displays a message box that the user has to click OK on before the save action is carried out:

function displaySaveMessage(context) {

 var eventArgs = context.getEventArgs();
 var saveMode = eventArgs.getSaveMode();

 if (saveMode == 70 || saveMode == 2 || saveMode == 1 || saveMode == 59) {
 var message = "Records will be populated in the background and you will need to refresh the form after a few minutes to see them on the Sub-Grid. Press OK to save the record."
 Xrm.Utility.alertDialog(message, function () {
 Xrm.Page.data.save().then(function () {
 Xrm.Page.data.refresh();
 })
 });
 }
}

By feeding through the execution context parameter, you are able to determine the type of save action that the alert will trigger on; in this case, Save, Save & Close, Save & New and Autosave. Just make sure you configure your script with the correct properties on the form, which are:

Using the OnSave event handler
With the Pass execution context as first parameter setting enabled

From the end-users perspective, they will see something similar to the below when the record is saved:

It’s a pity that we don’t have similar kind of functionality exposed via Business Rules that enable us to display OnSave alerts that are more in keeping with the applications look and feel. Nevertheless, the versatility of utilising JScript functions should be evident here and can often achieve these types of bespoke actions with a few lines of code.

When it comes to plug-in development, understanding the impact and processing time that your code has within the application is important for two reasons - first, in ensuring that end users are not frustrated by long loading times and, secondly, in informing the choice of Execution Mode when it comes to deploying out a plug-in. Whilst Asynchronous plug-ins can help to mitigate any user woes and present a natural choice when working with bulk operations within the application, make sure you fully understand the impact that these have on the Asynchronous Service and avoid a scenario where the System Job entity is queued with more jobs then it can handle.

Dynamics 365 Customer Engagement Deep Dive: Creating a Basic Plug-in

Sun, 28 Jan 2018 00:00:00 +0000

This is an accompanying blog post to my YouTube video Dynamics 365 Customer Engagement Deep Dive: Creating a Basic Plug-in, the second in a series aiming to provide tutorials on how to accomplish developer focused tasks within Dynamics 365 Customer Engagement. You can watch the video in full below:

Below you will find links to access some of the resources discussed as part of the video and to further reading topics:

Full Code Sample

[snippet id=“390”]

Download/Resource Links

Visual Studio 2017 Community Edition

Setup a free 30 day trial of Dynamics 365 Customer Engagement

C# Guide (Microsoft Docs)

Source Code Management Solutions

Visual Studio Team Services - Free for up to 5 users and my recommended choice when working with Dynamics 365 Customer Engagement
BitBucket
GitHub

Mapping Product Attributes to Quote/Order/Invoice Line Items (Dynamics 365 Customer Engagement)

Sun, 24 Dec 2017 00:00:00 +0000

Working in-depth amidst the Sales entities (e.g. Product, Price List, Quote etc.) within Dynamics CRM/Dynamics 365 Customer Engagement (CRM/D365CE) can produce some unexpected complications. What you may think is simple to achieve on the outset, based on how other entities work within the system, often leads you in a completely different direction. A good rule of thumb is that any overtly complex customisations to these entities will mean having to get down and dirty with C#, VB.Net or even JScript. For example, we’ve seen previously on the blog how, with a bit of a developer expertise, it is possible to overhaul the entire pricing engine within the application to satisfy specific business requirements. There is no way in which this can be modified directly through the application interface, which can lead to CRM deployments that make imaginative and complicated utilisation of features such as Workflows, Business Rules and other native features. Whilst there is nothing wrong with this approach per-say, the end result is often implementations that look messy when viewed cold and which become increasingly difficult to maintain in the long term. As always, there is a balance to be found, and any approach which makes prudent use of both application features and bespoke code is arguably the most desirous end goal for achieving certain business requirements within CRM/D365CE.

To prove my point around Sales entity “oddities”, a good illustration can be found when it comes to working with relationship field mappings and Product records. The most desirable feature at the disposal of CRM customisers is the ability to configure automated field mapping between Entities that have a one-to-many (1:N) relationship between them. What this means, in simple terms, is that when you create a many (N) record from the parent entity (1), you can automatically copy the field values to a matching field on the related entity. This can help to save data entry time when qualifying a Lead to an Opportunity, as all the important field data you need to continue working on the record will be there ready on the newly created Opportunity record. Field mappings can be configured from the 1:N relationship setting window, via the Mappings button:

There are a few caveats to bear in mind - you can only map across fields that have the same underlying data type and you cannot map multiple source fields to the same target (it should be obvious why this is 🙂) - but on the whole, this is a handy application feature that those who are more accustomed to CRM development should always bear in the mind when working with CRM/D365CE.

Field mappings are, as indicated, a standard feature within CRM/D365CE - but when you inspect the field relationships between the Product and Quote Product entity, there is no option to configure mappings at all:

Upon closer inspection, many of the relationships between the Product entity and others involved as part of the sales order process are missing the ability to configure field mappings. So, for example, if you have a requirement to map across the value of the Description entity to a newly created Quote Product record, you would have to look at implementing a custom plugin to achieve your requirements. The main benefit of this route is that we have relatively unrestricted access to the record data we need as part of a plugin execution session and - in addition - we can piggyback onto the record creation process to add on our required field “in-flight” - i.e. whilst the record is being created. The code for achieving all of this is as follows:

using System;

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;

namespace D365.BlogDemoAssets.Plugins
{
 public class PreQuoteProductCreate_GetProductAttributeValues : IPlugin
 {
 public void Execute(IServiceProvider serviceProvider)
 {
 //Obtain the execution context from the service provider.

 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

 //Get a reference to the Organization service.

 IOrganizationServiceFactory factory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
 IOrganizationService service = factory.CreateOrganizationService(context.UserId);

 //Extract the tracing service for use in debugging sandboxed plug-ins

 ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));

 tracingService.Trace("Tracing implemented successfully!");

 if (context.InputParameters.Contains("Target") && context.InputParameters["Target"] is Entity)

 {
 Entity qp = (Entity)context.InputParameters["Target"];

 //Only execute for non-write in Quote Product records

 EntityReference product = qp.GetAttributeValue<EntityReference>("productid");

 if (product != null)

 {

 Entity p = RetrieveProductID(service, product.Id);
 string desc = p.GetAttributeValue<string>("description");
 tracingService.Trace("Product Description = " + desc);
 qp.Attributes["description"] = desc;

 }

 else

 {
 tracingService.Trace("Quote Product with record ID " + qp.GetAttributeValue<Guid>("quotedetailid").ToString() + " does not have an associated Product record, cancelling plugin execution.");
 return;
 }
 }
 }

 public Entity RetrieveProductID(IOrganizationService service, Guid productID)
 {
 ColumnSet cs = new ColumnSet("description"); //Additional fields can be specified using a comma seperated list

 //Retrieve matching record

 return service.Retrieve("product", productID, cs);
 }
 }
}

They key thing to remember when registering your Plugin via the Plugin Registration Tool (steps which regular readers of the blog should have a good awareness of) is to ensure that the Event Pipeline Stage of Execution is set to Pre-operation. From there, the world is your oyster - you could look at returning additional fields from the Product entity to update on your Quote Product record or you could even look at utilising the same plugin for the Order Product and Invoice Product entities (both of these entities also have Description field, so the above code should work on these entities as well).

It’s a real shame that Field Mappings are not available to streamline the population of record data from the Product entity; or the fact that there is no way to utilise features such as Workflows to give you an alternate way of achieving the requirement exemplified in this post. This scenario is another good reason why you should always strive to be a Dynamics 365 Swiss Army Knife, ensuring that you have a good awareness of periphery technology areas that can aid you greatly in mapping business requirements to CRM/D365CE.

Determining the Initiating User Details on a C# Plug-in (Dynamics 365 for Customer Engagement)

Sun, 03 Dec 2017 00:00:00 +0000

In last week’s post, we took a look at how a custom Workflow activity can be implemented within Dynamics CRM/Dynamics 365 for Customer Engagement to obtain the name of the user who triggered the workflow. It may be useful to retrieve this information for a variety of different reasons, such as debugging, logging user activity or to automate the population of key record information. I mentioned in the post the “treasure trove” of information that the IWorkflowContext interface exposes to developers. Custom Workflow activities are not unique in having execution-specific information exposable, with an equivalent interface at our disposal when working with plug-ins. No prizes for guessing its name - the IPluginExecutionContext.

When comparing both interfaces, some comfort can be found in that they share almost identical properties, thereby allowing us to replicate the functionality demonstrated in last weeks post as Post-Execution Create step for the Lead entity. The order of work for this is virtually the same:

Develop a plug-in C# class file that retrieves the User ID of the account that has triggered the plugin.
Add supplementary logic to the above class file to retrieve the Display Name of the User.
Deploy the compiled .dll file into the application via the Plug-in Registration Tool, adding on the appropriate execution step.

The emphasis on this approach, as will be demonstrated, is much more focused towards working outside of the application; something you may not necessarily be comfortable with. Nevertheless, I hope that the remaining sections will provide enough detail to enable you to replicate within your own environment.

Developing the Class File

As before, you’ll need to have ready access to a Visual Studio C# Class file project and the Dynamics 365 SDK. You’ll also need to ensure that your project has a Reference added to the Microsoft.Xrm.Sdk.dll. Create a new Class file and copy and paste the following code into the window:

using System;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;

namespace D365.BlogDemoAssets.Plugins
{
 public class PostLeadCreate_GetInitiatingUserExample : IPlugin
 {
 public void Execute(IServiceProvider serviceProvider)
 {
 // Obtain the execution context from the service provider.

 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

 // Obtain the organization service reference.
 IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
 IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

 // The InputParameters collection contains all the data passed in the message request.
 if (context.InputParameters.Contains("Target") &&
 context.InputParameters["Target"] is Entity)

 {
 Entity lead = (Entity)context.InputParameters["Target"];

 //Use the Context to obtain the Guid of the user who triggered the plugin - this is the only piece of information exposed.

 Guid user = context.InitiatingUserId;

 //Then, use GetUserDisplayCustom method to retrieve the fullname attribute value for the record.

 string displayName = GetUserDisplayName(user, service);

 //Build out the note record with the required field values: Title, Regarding and Description field

 Entity note = new Entity("annotation");
 note["subject"] = "Test Note";
 note["objectid"] = new EntityReference("lead", lead.Id);
 note["notetext"] = @"This is a test note populated with the name of the user who triggered the Post Create plugin on the Lead entity:" + Environment.NewLine + Environment.NewLine + "Executing User: " + displayName;

 //Finally, create the record using the IOrganizationService reference

 service.Create(note);
 }
 }
 }
}

Note also that you will need to rename the namespace value to match against the name of your project.

To explain, the code replicates the same functionality developed as part of the Workflow on last week’s post - namely, create a Note related to a newly created Lead record and populate it with the Display Name of the User who has triggered the plugin.

Retrieving the User’s Display Name

After copying the above code snippet into your project, you may notice a squiggly red line on the following method call:

The GetUserDisplayName is a custom method that needs to be added in manually and is the only way in which we can retrieve the Display Name of the user, which is not returned as part of the IPluginExecutionContext. We, therefore, need to query the User (systemuser) entity to return the Full Name (fullname) field, which we can then use to populate our newly create Note record. We use a custom method to return this value, which is provided below and should be placed after the last 2 curly braces after the Execute method, but before the final 2 closing braces:

private string GetUserDisplayName(Guid userID, IOrganizationService service)
 {
 Entity user = service.Retrieve("systemuser", userID, new ColumnSet("fullname"));
 return user.GetAttributeValue<string>("fullname");
 }

Deploy to the application using the Plug-in Registration Tool

The steps involved in this do not differ greatly from what was demonstrated in last week’s post, so I won’t repeat myself. 🙂 The only thing you need to make sure you do after you have registered the plug-in is to configure the plug-in Step. Without this, your plug-in will not execute. Right-click your newly deployed plug-in on the main window of the Registration Tool and select Register New Step:

On the form that appears, populate the fields/values indicated below:

Message: Create
Primary Entity: Lead
Run in User’s Context: Calling User
Event Pipeline Stage of Execution: Post-Operation

The window should look similar to the below if populated correctly. If so, then you can click Register New Step to update the application:

All that remains is to perform a quick test within the application by creating a new Lead record. After saving, we can then verify that the plug-in has created the Note record as intended:

Having compared both solutions to achieve the same purpose, is there a recommended approach to take?

The examples shown in the past two blog posts indicate excellently how solutions to specific scenarios within the application can be achieved via differing ways. As clearly evidenced, one could argue that there is a code-heavy (plug-in) and a light-touch coding (custom Workflow assembly) option available, depending on how comfortable you are with working with the SDK. Plug-ins are a natural choice if you are confident working solely within Visual Studio or have a requirement to perform additional business logic as part of your requirements. This could range from complex record retrieval operations within the application or even an external integration piece involving specific and highly tailored code. The Workflow path clearly favours those of us who prefer to work within the application in a supported manner and, in this particular example, can make certain tasks easier to accomplish. As we have seen, the act of retrieving the Display Name of a user is greatly simplified when we go down the Workflow route. Custom Workflow assemblies also offer greater portability and reusability, meaning that you can tailor logic that can be applied to multiple different scenarios in the future. Code reusability is one of the key drivers in many organisations these days, and the use of custom Workflow assemblies neatly fits into this ethos.

These are perhaps a few considerations that you should make when choosing the option that fits the needs of your particular requirement, but it could be that the way you feel most comfortable with ultimately wins the day - so long as this does not compromise the organisation as a consequence, then this is an acceptable stance to take. Hopefully, this short series of posts have demonstrated the versatility of the application and the ability to approach challenges with equally acceptable pathways for resolution.

Obtaining the User who executed a Workflow in Dynamics 365 for Customer Engagement (C# Workflow Activity)

Sun, 26 Nov 2017 00:00:00 +0000

It’s sometimes useful to determine the name of the user account that executes a Workflow within Dynamics CRM/Dynamics 365 for Customer Engagement (CRM/D365CE). What can make this a somewhat fiendish task to accomplish is the default behaviour within the application, which exposes very little contextual information each time a Workflow is triggered. Take, for example, the following simplistic Workflow which creates an associated Note record whenever a new Lead record is created:

The Note record is set to be populated with the default values available to us regarding the Workflow execution session - Activity Count, Activity Count including Process and Execution Time:

We can verify that this Workflow works - and view the exact values of these details - by creating a new Lead record and refreshing the record page:

The Execution Time field is somewhat useful, but the Activity Count & Activity Count including Process values relate to Workflow execution sessions and are only arguably useful for diagnostic review - not something that end users of the application will generally be interested in. 🙂

Going back to the opening sentence of this post, if we were wanting to develop this example further to include the Name of the user who executed the Workflow in the note, we would have to look at deploying a Custom Workflow Assembly to extract the information out. The IWorkflowContext Interface is a veritable treasure trove of information that can be exposed to developers to retrieve not just the name of the user who triggers a Workflow, but the time when the corresponding system job was created, the Business Unit it is being executed within and information to determine whether the Workflow was triggered by a parent. There are three steps involved in deploying out custom code into the application for utilisation in this manner:

Develop a CodeActivity C# class file that performs the desired functionality.
Deploy the compiled .dll file into the application via the Plugin Registration Tool.
Modify the existing Workflow to include a step that accesses the custom Workflow Activity.

All of these steps will require ready access to Visual Studio, a C# class plugin project (either a new one or existing) and the CRM SDK that corresponds to your version for the application.

Developing the Class File

To begin with, make sure your project includes References to the following Frameworks:

System.Activities
Microsoft.Xrm.Sdk
Microsoft.Xrm.Sdk.Workflow

Add a new Class (.cs) file to your project and copy & paste the below code, overwriting any existing code in the window. Be sure to update the namespace value to reflect your project name:

using System.Activities;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Workflow;

namespace D365.Demo.Plugins
{
 public class GetWorkflowInitiatingUser : CodeActivity
 {
 protected override void Execute(CodeActivityContext executionContext)
 {
 IWorkflowContext workflowContext = executionContext.GetExtension<IWorkflowContext>();
 CurrentUser.Set(executionContext, new EntityReference("systemuser", workflowContext.InitiatingUserId));
 }

 [Output("Current User")]
 [ReferenceTarget("systemuser")]
 public OutArgument<EntityReference> CurrentUser { get; set; }
 }
}

Right-click your project and select Build. Verify that no errors are generated and, if so, then that’s the first step done and dusted 🙂

Deploy to CRM/D365CE

Open up the Plugin Registration Tool and connect to your desired instance. If you are deploying an existing, updated plugin class, then right-click it on the list of Registered Plugins & Custom Workflow Activities and click Update; otherwise, select Register -> Register New Assembly. The same window opens in any event. Load the newly built assembly from your project (can be located in the \bin\Debug\ folder by default) and ensure the Workflow Activity entry is ticked before selecting Register Selected Plugins:

After registration, the Workflow Activity becomes available for use within the application; so time to return to the Workflow we created earlier!

Adding the Custom Workflow Activity to a Process

By deactivating the Workflow Default Process Values Example Workflow and selecting Add Step, we can verify that the Custom Workflow Assembly is available for use:

Select the above, making sure first of all that the option Insert Before Step is toggled (to ensure it appears before the already configured Create Note for Lead step). It should look similar to the below if done correctly:

Now, when we go and edit the Create Note for Lead step, we will see a new option under Local Values which, when selected, bring up a whole range of different fields that correspond to fields from the User Entity. Modify the text within the Note to retrieve the Full Name value and save it onto the Note record, as indicated below:

After saving and reactivating the Workflow, we can verify its working by again creating a new Lead record and refreshing to review the Note text:

All working as expected!

The example shown in this post has very limited usefulness in a practical business scenario, but could be useful in different circumstances:

If your Workflow contains branching logic, then you can test to see if a Workflow has executed by a specific user and then perform bespoke logic based on this value.
Records can be assigned to other users/teams, based on who has triggered the Workflow.
User activity could be recorded in a separate entity for benchmarking/monitoring purposes.

It’s useful to know as well that the same kind of functionality can also be deployed when working with plugins as well in the application. We will take a look at how this works as part of next week’s blog post.

Modifying Default Lead Qualification Behaviour via C# (Dynamics CRM/Dynamics 365 for Customer Engagement)

Sun, 15 Oct 2017 00:00:00 +0000

Dynamics CRM/Dynamics 365 for Customer Engagement (CRM/D365CE) is an incredibly flexible application for the most part. Regardless of how your business operates, you can generally tailor the system to suit your requirements and extend it to your heart’s content; often to the point where it is completely unrecognisable from the base application. Notwithstanding this argument, you will come across aspects of the application that are (literally) hard-coded to behave a certain way and cannot be straightforwardly overridden via the application interface. The most recognisable example of this is the Lead Qualification process. You are heavily restricted in how this piece of functionality acts by default but, thankfully, there are ways in which it can be modified if you are comfortable working with C#, JScript and Ribbon development.

Before we can start to look at options for tailoring the Lead Qualification process, it is important to understand what occurs during the default action within the application. In developer-speak, this is generally referred to as the QualifyLead message and most typically executes when you click the button below on the Lead form:

When called by default, the following occurs:

The Status/Status Reason of the Lead is changed to Qualified, making the record inactive and read-only.
A new Opportunity, Contact and Account record is created and populated with (some) of the details entered on the Lead record. For example, the Contact record will have a First Name/Last Name value supplied on the preceding Lead record.
You are automatically redirected to the newly created Opportunity record.

This is all well and good if you are able to map your existing business processes to the application, but most organisations will typically differ from the applications B2B orientated focus. For example, if you are working within a B2C business process, creating an Account record may not make sense, given that this is typically used to represent a company/organisation. Or, conversely, you may want to jump straight from a Lead to a Quote record. Both of these scenarios would require bespoke development to accommodate currently within CRM/D365CE. This can be broadly categorised into two distinct pieces of work:

Modify the QualifyLead message during its execution to force the desired record creation behaviour.
Implement client-side logic to ensure that the user is redirected to the appropriate record after qualification.

The remaining sections of this post will demonstrate how you can go about achieving the above requirements in two different ways.

Our first step is to “intercept” the QualifyLead message at runtime and inject our own custom business logic instead

I have seen a few ways that this can be done. One way, demonstrated here by the always helpful Jason Lattimer, involves creating a custom JScript function and a button on the form to execute your desired logic. As part of this code, you can then specify your record creation preferences. A nice and effective solution, but one in its guise above will soon obsolete as a result of the SOAP endpoint deprecation. An alternative way is to instead deploy a simplistic C# plugin class that ensures your custom logic is obeyed across the application, and not just when you are working from within the Lead form (e.g. you could have a custom application that qualifies leads using the SDK). Heres how the code would look in practice:

public void Execute(IServiceProvider serviceProvider)
{
 //Obtain the execution context from the service provider.

 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

 if (context.MessageName != "QualifyLead")
 return;

 //Get a reference to the Organization service.

 IOrganizationServiceFactory factory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
 IOrganizationService service = factory.CreateOrganizationService(context.UserId);

 //Extract the tracing service for use in debugging sandboxed plug-ins

 ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));

 tracingService.Trace("Input parameters before:");
 foreach (var item in context.InputParameters)
 {
 tracingService.Trace("{0}: {1}", item.Key, item.Value);
 }

 //Modify the below input parameters to suit your requirements.
 //In this example, only a Contact record will be created

 context.InputParameters["CreateContact"] = true;
 context.InputParameters["CreateAccount"] = false;
 context.InputParameters["CreateOpportunity"] = false;

 tracingService.Trace("Input parameters after:");
 foreach (var item in context.InputParameters)
 {
 tracingService.Trace("{0}: {1}", item.Key, item.Value);
 }
}

To work correctly, you will need to ensure this is deployed out on the Pre-Operation stage, as by the time the message reaches the Post-Operation stage, you will be too late to modify the QualifyLead message.

The next challenge is to handle the redirect to your record of choice after Lead qualification

Jason’s code above handles this effectively, with a redirect after the QualifyLead request has completed successfully to the newly created Account (which can be tweaked to redirect to the Contact instead). The downside of the plugin approach is that this functionality is not supported. So, if you choose to disable the creation of an Opportunity record and then press the Qualify Lead button…nothing will happen. The record will qualify successfully (which you can confirm by refreshing the form) but you will then have to manually navigate to the record(s) that have been created.

The only way around this with the plugin approach is to look at implementing a similar solution to the above - a Web API request to retrieve your newly created Contact/Account record and then perform the necessary redirect to your chosen entity form:

function redirectOnQualify() {

 setTimeout(function(){

 var leadID = Xrm.Page.data.entity.getId();

 leadID = leadID.replace("{", "");
 leadID = leadID.replace("}", "");

 var req = new XMLHttpRequest();
 req.open("GET", Xrm.Page.context.getClientUrl() + "/api/data/v8.0/leads(" + leadID + ")?$select=_parentaccountid_value,_parentcontactid_value", true);
 req.setRequestHeader("OData-MaxVersion", "4.0");
 req.setRequestHeader("OData-Version", "4.0");
 req.setRequestHeader("Accept", "application/json");
 req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
 req.setRequestHeader("Prefer", "odata.include-annotations=\"OData.Community.Display.V1.FormattedValue\"");
 req.onreadystatechange = function () {
 if (this.readyState === 4) {
 req.onreadystatechange = null;
 if (this.status === 200) {
 var result = JSON.parse(this.response);

 //Uncomment based on which record you which to redirect to.
 //Currently, this will redirect to the newly created Account record
 var accountID = result["_parentaccountid_value"];
 Xrm.Utility.openEntityForm('account', accountID);

 //var contactID = result["_parentcontactid_value"];
 //Xrm.Utility.openEntityForm('contact', contactID);

 }
 else {
 alert(this.statusText);
 }
 }
 };
 req.send();

 }, 6000);
}

The code is set to execute the Web API call 6 seconds after the function triggers. This is to ensure adequate time for the QualifyLead request to finish and make the fields we need available for accessing.

To deploy out, we use the eternally useful Ribbon Workbench to access the existing Qualify Lead button and add on a custom command that will fire alongside the default one:

As this post has hopefully demonstrated, overcoming challenges within CRM/D365CE can often result in different - but no less preferred - approaches to achieve your desired outcome. Let me know in the comments below if you have found any other ways of modifying the default Lead Qualification process within the application.

What is Unsecure/Secure Configuration on a Dynamics CRM/365 for Enterprise Plugin?

Sun, 11 Jun 2017 00:00:00 +0000

When working with applications day in, day out, you sometimes overlook something that is sitting there, staring at you in the face. It may be an important feature or an inconsequential piece of functionality, but you never really take the time to fully understand either way just what it is and whether it can offer any distinct benefits or assistance. I realised a great example of this when recently deploying some new Plug-ins into Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E). When you are setting up a new Step for your Plug-in, you are given the option of specifying an Unsecure Configuration and Secure Configuration via a multi-line text box to the right of the window:

I was curious about just what these are and why it is not something that you ever really come across when you are first learning about Plug-in development with the application. I took a closer look at what these text boxes do and, as part of this week’s blog post, I wanted to share my findings and provide a demonstration of how they work in practice.

The Theoretical Bit: Unsecure/Secure Configuration Overview

Typically, when we want to get some juicy information relating to a piece of CRM/D365E functionality, we would turn to our good friends TechNet or MSDN. In this instance, however, there is no dedicated page that covers this topic in-depth. We must instead navigate to the Write a Plug-in Constructor page to find dedicated information about how these work:

The Microsoft Dynamics 365 platform supports an optional plug-in constructor that accepts either one or two string parameters. If you write a constructor like this, you can pass any strings of information to the plug-in at run time.

These “one or two” parameters are the multi-line text boxes indicated above. Information is exposed as string objects within you C# code and you enable this feature within your code by specifying the following, SDK adapted constructor within your Plug-in class:

public MyPlugin(string unsecureString, string secureString)
{
 if (String.IsNullOrWhiteSpace(unsecureString) ||
 String.IsNullOrWhiteSpace(secureString))
 {
 throw new InvalidPluginExecutionException("Unsecure and secure strings are required for this plugin to execute.");
 }
 _unsecureString = unsecureString;
 _secureString = secureString;
}

As with anything, there are a number of important caveats to bear in mind with this feature. These can be gleaned via additional online sources:

Secure configuration parameters can only be viewed by CRM/D365E Administrators, whereas unsecure can be viewed by any user of the application.
As highlighted on the above MSDN page, Secure Configuration text is not passed to any Plug-in executing offline via the CRM/D365E for Outlook client.
Secure configuration parameters are not transportable between environments via a solution export/import.

In terms of use cases, the above articles highlight some potential scenarios that they are best utilised within. Perhaps the best example is for an ISV solution that requires integration with external web services to retrieve data that is then consumed by CRM/D365E. Credentials for these web services can be stored securely when the Plug-in is deployed via the use of Secure configuration parameters. Other than that, if you are developing a Plug-in for internal use, that is unlikely to be deployed/managed across multiple environments, then it is probably not worthwhile to look at utilising configuration parameters when you can just as easily specify these within your code.

Practice Makes (for) Perfect (Understanding)!

The best way to see how something works is by getting hands-on and seeing how it works in action. Let’s assume you wish to deploy a plugin that executes whenever a record is opened/viewed by any user across the platform. The plugin should update the First Name (firstname) and Last Name (lastname) fields to match the value(s) in the Unsecure and Secure Configuration properties accordingly. The below plugin code will achieve these requirements:

using System;
using Microsoft.Xrm.Sdk;

namespace D365.BlogDemoAssets.Plugins
{
 public class PostContactRetrieve_PluginConfigurationTest : IPlugin
 {
 private readonly string _unsecureString;
 private readonly string _secureString;
 public PostContactRetrieve_PluginConfigurationTest(string unsecureString, string secureString)
 {
 if (String.IsNullOrWhiteSpace(unsecureString) ||
 String.IsNullOrWhiteSpace(secureString))
 {
 throw new InvalidPluginExecutionException("Unsecure and secure strings are required for this plugin to execute.");
 }

 _unsecureString = unsecureString;
 _secureString = secureString;
 }
 public void Execute(IServiceProvider serviceProvider)
 {
 // Obtain the execution context from the service provider.

 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

 // Obtain the organization service reference.
 IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
 IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

 // The InputParameters collection contains all the data passed in the message request.
 if (context.InputParameters.Contains("Target") &&
 context.InputParameters["Target"] is EntityReference)
 {
 Entity contact = new Entity("contact", ((EntityReference)context.InputParameters["Target"]).Id);

 contact["firstname"] = _unsecureString;
 contact["lastname"] = _secureString;
 service.Update(contact);
 }
 }
 }
}

When deploying the plug-in using the Plugin Registration Tool, we specify the step to execute on the Retrieve message and to execute in the Pre-Operation Stage (otherwise the form will need to be refreshed to see the updated values!). We also need to specify our desired values for the First Name and Last Name fields in the appropriate Configuration fields. The Register New Step window should look similar to the below if configured correctly:

When we navigate into the Jim Glynn (sample) Contact record within CRM/D365E, we can see that the Plug-in has triggered successfully and updated the fields to match against the values specified on Step above:

We can also confirm that the appropriate error is thrown when one of the configuration properties is missing a value, by modifying our Plug-in step and attempting to reload our sample Contact record:

By clicking Download Log File, we can view the error message specified as part of the InvalidPluginExecutionException call. Below is a modified excerpt of the ErrorDetails XML that is generated:

<InnerFault>
 <ActivityId>ed4a2021-9c87-4f06-a493-6d804676bf96</ActivityId>
 <ErrorCode>-2147220891</ErrorCode>
 <ErrorDetails xmlns:d3p1="http://schemas.datacontract.org/2004/07/System.Collections.Generic" />
 <Message>Unsecure and secure strings are required for this plugin to execute.</Message>
 <ExceptionSource i:nil="true" />
 <InnerFault i:nil="true" />
 <OriginalException i:nil="true" />
 <TraceText i:nil="true" />
</InnerFault>

Conclusions or Wot I Think

It is impossible to become what I would like to term a “pub quiz champion” in CRM/D365E; what I mean by this is that I would defy anyone to rattle off every little detail and fact about the entire platform. As with any pub-quiz, those that do may more than likely end up cheating by having their phone out. With this metaphor in mind, I think Plug-in configuration properties would be an excellent topic for a quiz of this nature. As mentioned previously, it is not something that I was ever made aware of when starting to learn about Plug-in development and is not a feature touted regularly within the online community. Perhaps this is because of its very specific and limited application - although it is handy to have at our disposal, I think its usage is really only targeted towards those who are developing solutions that are deployed across multiple environments AND require the need to store configuration properties for external URL’s/web services in a compact and secure manner. Therefore, if you are currently having to use a custom entity within the application to store this type of information, it would make sense to reduce the footprint of your solution within the application itself and make the appropriate changes to use Secure configuration parameters instead. Using a bit of ingenuity (such as XML configuration parameters), you can achieve the same requirements without the need to customise the application unnecessarily.

Automatically Populate Extended Amount Field When Using Custom Pricing (Dynamics CRM/365 for Enterprise)

Sun, 04 Jun 2017 00:00:00 +0000

Generally, when you are looking at adopting Dynamics CRM/Dynamics 365 for Enterprise (D365E) within your business, you can be reasonably satisfied that the majority of what is already configured within the system can be very quickly adapted to suit your business needs. Whether it’s the Lead to Opportunity sales process or the entire Case management module, the functionality at your disposal is suitable for many organisations across the globe. The great thing as well is that, should you wish to fine-tune things further, you have a broad range of options at your disposal that can help you achieve your objectives - sometimes in very specific and highly unique ways. I have previously looked at a good example of this on the blog - namely, how to override the systems built-in pricing engine in favour of your own - and, assuming you have a good understanding of C# and how to deploy plugins to the application, you can spin an important aspect of the systems functionality on its head to match how your business operates.

Having this ability is, undoubtedly, a real boon, but can present some odd behaviours. For example, you may start to notice that suddenly the Extended Amount field is no longer being populated with data after implementing your custom pricing engine. The example pictures below demonstrate a before and after example of adding a Product line item to the Quote entity, using the exact same sample Product:

The odd thing about this is that, as soon as you click into the record, you will suddenly see a value appear in this field. Very strange!

It is difficult to pinpoint exactly what is causing the problem, but I can do a “stab in the dark”. CRM/D365E uses the CalculatePrice message to determine the points when either a) the default price engine or b) a custom one is triggered to perform all necessary calculations. Although there is no official documentation to back this up, I suspect that this message is only triggered when you Update or Retrieve an existing Product line item record (regardless of whether it is an Opportunity Product, Quote Product etc.). This is proven by the fact that, as soon as we click into our Product record, the Extended Amount field is suddenly populated - the platform has triggered the Retrieve message as a result of you opening the record and then, as a next step, forces the CalculatePrice message to also fire. The important thing to clarify with this point is that you must have a custom pricing implemented successfully within the application for this to work. Otherwise, don’t be too surprised if the Extended Amount value remains at 0.

Whilst the workaround for this is somewhat tolerable if you are working with a small subset of records and do not rely on the Extended Amount as part of any existing reporting within the application, this could really start to cause problems for your end users in the long term and give an impression that the application does not “work” as it should do. Fortunately, there is a solution that we can look at implementing that will hopefully lead to some happy fingers from not needing to click into records anymore 🙂 Be sure to have the CRM/D365E SDK handy before you begin the below!

Open up the Plugin Registration Tool from within the SDK, and log into your CRM/D365E instance.
Scroll down to your Assembly and Plugin that contains your custom pricing engine. If already configured correctly, it should have a step configured for the CalculatePrice message on any entity, as a Synchronous, Post-Operation step.
Right click your plugin and click on Register New Step to open the window that lets you specify the required settings for your step. Populate the form as follows:
- Message: Create
- Primary Entity: Select one of the Product line item entities that your custom pricing engine uses. The list of accepted entities are invoicedetail, opportunityproduct, salesorderdetail or quotedetail.
- Event Pipeline Stage of Execution: Post-Operation
- Execution Mode: Synchronous

All other settings can be left as default. Your window should look similar to the below if configured correctly for the quotedetail entity:

Click on Register New Step to add the step to the application.
Repeat steps 3-4 for any additional Product line item entities that are using with your custom pricing engine

Now, when you go back into CRM/D36E, the Extended Amount values will start to be populated automatically as soon as you add a new Product onto the Product line item subgrid.

Conclusions or Wot I Think

Whilst the ability to override an important piece of CRM’s/D365E’s functionality is welcome, you do need to bear in mind the additional overhead and responsibility this leaves your organisation in ensuring that your custom pricing engine is correct and that you have adequately tested the solution to properly identify actions which are out of the ordinary, such as the one discussed in this post. What is slightly frustrating about this quirk, in particular, is the lack of clear documentation regarding the CalculatePrice message from Microsoft. Granted, the message is only exposed for minimal interaction from an SDK point of view and is, for all intents and purposes, an internal application message that we shouldn’t really mess with or care about. Having said this, even just a brief summary of when the message is triggered on the platform would have made it instantly more understandable why any custom pricing calculation engine will fail to provide you with an instant amount within your Extended Amount field. In the end, however, I am pleased that there is a straightforward workaround that can be put into place to ensure that things work as expected; hopefully to the extent that it becomes virtually impossible to determine easily whether your organisation is using the default or a custom pricing engine in the first place.

Automatically Publish Duplicate Detection Rules (Dynamics CRM/Dynamics 365 for Enterprise)

Sun, 12 Feb 2017 00:00:00 +0000

For those who are well versed in rolling out solution updates within Dynamics CRM/365 for Enterprise (CRM/D365E), the process will always have a certain familiarity to it, with a few surprises rolled in now and again. Often, the update will proceed as anticipated; sometimes, you may encounter bizarre issues. I can remember a particularly strange incident I had last year where a solution import would get to about 90-95% completion…and then the green progress bar would suddenly start rolling back to nothing. The import progress window would then hang with no further guidance or error message. To try and determine the root cause, we had to interrogate the importjob entity within the system, which ended up showing the import job progress stuck at 0.15846281% 😕 In the end, we had to escalate the issue to Microsoft for further investigation, but rest assured that if you have not yet witnessed your own curious solution import experience, it’s definitely in the post 🙂

Thankfully, if you are new to the whole “rolling out solution update” thing, you can be assured that the process is relatively straightforward, and mostly without issue. If you have been handed a set of solution import instructions for the first time, though, you may be wondering why something similar to the following step is included:

Go into the Data Management -> Duplicate Detection Rules page and click Publish on all Duplicate Detection Rules that have a Status Reason of Unpublished

Unfortunately, after importing a solution update, CRM/D365E will automatically unpublish all of your Duplicate Detection Rules automatically. You are therefore required to explicitly publish them again, lest you start to encounter a sudden increase in duplicate records and database storage within your system. The reason why this happens is both understandable and frustrating in equal measure. As outlined in the following MSDN article on the subject:

A duplicate rule condition specifies the name of a base attribute and the name of a matching attribute. For example, specify an account as a base entity and a contact as a matching entity to compare last names and addresses

As part of the above, explicit matchcodes are created for every record that the Duplicate Detection Rule is targeting, based on the current metadata of your CRM/D365E entities and attributes. Because your solution update can potentially alter significant aspects of this metadata, the system automatically unpublishes all Duplicate Detection Rules as a precaution.

The above is perhaps trivial in nature, as the actual process of re-publishing all Duplicate Detection Rules is somewhat negligible in effort terms. Where difficulties can arise is if someone innocently overlooks this part of the process or if your system has many different Duplicate Detection Rules, in a mixture of Unpublished/Published state. You would have to specifically make a note of which rules were Published before beginning your solution import so that you can ensure that the correct rules are published after the fact. I would have thought that after so many versions of the product, that something would be added to address this - for example, perhaps a checkbox at the start of the Solution Import Wizard that lets you specify whether all currently published rules should be reactivated after the import completes successfully.

If you find that the above is an annoyance that you can do without no longer, like with many things on the platform, there is a solution that can be deployed in code. The SDK exposes the PublishDuplicateRuleRequest class, which does exactly what it says on the tin - meaning that you can write a plugin that applies this functionality accordingly. The tricky bit comes in determining which Message (i.e. action) on the platform that you wish to run this against. CRM/D365E does not expose a SolutionUpdate or SolutionImport message that we can piggy-back onto, so we have to look at the PublishAll message instead - the action that is triggered when you press Publish All Customizations in the system. This is because this is generally the action you will always need to take when importing an (unmanaged) solution. As a result, we can write a plugin class that is triggered on the Post-Operation event of this entity to automatically publish all Unpublished Duplicate Detection Rules in the system!

The snippet below is adapted from the sample code provided by Microsoft, but has been tweaked as follows:

A QueryExpression is used as opposed to QueryByAttribute, since we need to query on two separate attributes and their values - statecode and statuscode. You also cannot return an easily accessible count on all results returned with QueryByAttribute. We will see why is useful in a few moments.
The code explicitly checks for if there are any Unpublished rules first before attempting to proceed further - no point in running code unnecessarily!
Instead of activating each rule one-by-one using an Execute request, all of the requests are collected together as part of an ExecuteMultipleRequest, given that we now know the performance benefits that this can have.
Tracing has been implemented in liberal amounts, to provide remote debugging from within CRM/D365E.

Here’s the code - just copy into an empty class file on your plugin project, modify the namespace to reflect the name of your project and you will be good to go!

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;
using Microsoft.Xrm.Sdk.Messages;
using Microsoft.Crm.Sdk.Messages;

namespace MyPlugin.Plugins
{
 public class PostPublishAll_PublishDuplicateDetectionRules : IPlugin
 {
 public void Execute(IServiceProvider serviceProvider)
 {
 //Obtain the execution context from the service provider. 
 IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

 //Get a reference to the Organization service. 
 IOrganizationServiceFactory factory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
 IOrganizationService service = factory.CreateOrganizationService(context.UserId);

 //Extract the tracing service for use in debugging sandboxed plug-ins
 ITracingService tracing = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
 tracing.Trace("Tracing implemented successfully!");

 if (context.MessageName == "PublishAll")
 {
 PublishRules(service, tracing);
 }
 }

 private void PublishRules(IOrganizationService service, ITracingService tracing)
 {
 EntityCollection rules = GetDuplicateDetectionRules(service);

 tracing.Trace("Obtained " + rules.TotalRecordCount.ToString() + " duplicate detection rules.");

 if (rules.TotalRecordCount >= 1)
 {
 // Create an ExecuteMultipleRequest object.
 ExecuteMultipleRequest request = new ExecuteMultipleRequest()
 {
 // Assign settings that define execution behavior: don't continue on error, don't return responses. 
 Settings = new ExecuteMultipleSettings()
 {
 ContinueOnError = false,
 ReturnResponses = false
 },
 // Create an empty organization request collection.
 Requests = new OrganizationRequestCollection()
 };

 //Create a collection of PublishDuplicateRuleRequests, and execute them in one batch
 foreach(Entity entity in rules.Entities)
 {
 PublishDuplicateRuleRequest publishReq = new PublishDuplicateRuleRequest { DuplicateRuleId = entity.Id };
 request.Requests.Add(publishReq);
 }

 service.Execute(request);
 }
 else
 {
 tracing.Trace("Plugin execution cancelled, as there are no duplicate detection rules to publish.");
 return;
 }
 }

 private EntityCollection GetDuplicateDetectionRules(IOrganizationService service)
 {
 QueryExpression qe = new QueryExpression("duplicaterule");

 qe.ColumnSet = new ColumnSet("duplicateruleid");

 ConditionExpression condition1 = new ConditionExpression();
 condition1.AttributeName = "statecode";
 condition1.Operator = ConditionOperator.Equal;
 condition1.Values.Add(0);

 ConditionExpression condition2 = new ConditionExpression();
 condition2.AttributeName = "statuscode";
 condition2.Operator = ConditionOperator.Equal;
 condition2.Values.Add(0);

 FilterExpression filter = new FilterExpression();
 filter.FilterOperator = LogicalOperator.And;
 filter.Conditions.Add(condition1);
 filter.Conditions.Add(condition2);

 qe.Criteria.AddFilter(filter);

 //Have to add this, otherwise the record count won't be returned correctly
 qe.PageInfo.ReturnTotalRecordCount = true;

 return service.RetrieveMultiple(qe);
 }
 }
}

The only caveat with the above is that it is arguably only useful for if you are regularly importing Unmanaged, as opposed to Managed solutions, as the Publish All Customizations option is not displayed on the import wizard for unmanaged solutions. Nevertheless, by rolling out the above into your environment, you no longer need to scrabble around for the mental note you have to make when performing a solution update.

Bulk Creating Dynamics CRM/365 for Enterprise Records in C#: Create Request vs. ExecuteMultipleRequest

Sun, 05 Feb 2017 00:00:00 +0000

It is often the case, as part of any application or database system, that certain record types will be well-suited towards duplication. Whilst this is generally a big no-no for individual customer records or invoice details, for example, there are other situations where the ability to duplicate and slightly modify an existing record becomes incredibly desirable. This is then expanded further to the point where end-users are given the ability to perform such duplication themselves.

A good example of this can be found within Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E). Email Templates are, in essence, a record type that is duplicated whenever a user selects the Template and creates a new Email record from within the application. Whilst there will always be details that need to be modified once the duplication is performed, having the ability to essentially “copy + paste” an existing record can generate the following benefits for a business:

Streamlining and adherence to business processes
Efficiency savings
Brand consistency

CRM/D365E does a pretty good job of making available a number of record types designed solely for this purpose, but a recent real-life example demonstrated a potential gap. A business I was working with was implementing the full sales process within the application - Lead to Opportunity to Quote etc. At the Quote stage, the businesses existing process would generally involve having a number of predefined “templates” for Quotes. This was due to the fact that the business would very regularly quote for the same kind of work, often with little or no variation. Out of the box with CRM/D365E, the sales team would have to create a new Quote record and add on every Quote Product line item each time a Quote was required - leading to little or no efficiency benefit of using the application.

To get around the issue, I was tasked with creating a means of setting up a number of “template” Quote records and then have the ability to quickly copy these template records, along with all of their associated Quote Product records, with some minor details changed in the process (for example, the Name value of the Quote). A workflow is immediately the best candidate for addressing the second requirement of this task but would require some additional development work to bring to fruition. I decided then to look, rather nervously, at creating a custom workflow assembly.

Why nervously? To be frank, although I have had plenty experience to date with writing plugins for CRM/D365E, I had not previously developed a custom workflow assembly. So I was a little concerned that the learning curve involved would be steep and take much longer than first anticipated. Fortunately, my fears were unfounded, and I was able to grasp the differences between a plugin and a custom workflow assembly very quickly:

Instead of inheriting from the IPlugin interface, your class instead needs to be set to the CodeActivity interface. As with plugins and, depending on Visual Studio version, you can then use CTRL + . to implement your Execute method.
Context (i.e. the information regarding the who, what and why of the execution; the User, the Entity and the action) is derived from the IWorkflowContext as opposed to the IPluginExecutionContext
Input/Output Parameters are specified within your Execute method and can be given a label, a target entity and then information regarding the data type that will be passed in/out. For example, to specify an Input Parameter for a Quote EntityReference, with the label Quote Record to Copy, you can use the following snippet:

[Input("Quote Record to Copy")]
[ReferenceTarget("quote")]
public InArgument<EntityReference> QuoteReference { get; set; }

The rest is as you would expect when writing a C# plugin. It is good to know that the jump across from plugins to custom workflow assemblies is not too large, so I would encourage anyone to try writing one if they haven’t done so already.

Back to the task at hand…

I implemented the appropriate logic within the custom workflow assembly to first create the Quote, using a Retrieve request to populate the quote variable with the Entity details and fields to copy over:

Entity newQuote = quote;
newQuote.Id = Guid.Empty;
newQuote.Attributes.Remove("quoteid");
newQuote.Attributes["name"] = "Copy of " + newQuote.GetAttributeValue<string>("quotenumber");
Guid newQuoteID = service.Create(newQuote);

The important thing to remember with this is that you must set the ID of the record to blank and then remove it from the newQuote - otherwise, your code will attempt to create the new record with the existing GUID of the copied record, resulting in an error.

Next, I performed a RetrieveMultiple request based off a QueryExpression to return all Quote Product records related to the existing records. Once I had my results in my qp EntityCollection, I then implemented my logic as follows:

foreach (Entity product in qp.Entities)
{
 Entity newProduct = product;
 newProduct.Id = Guid.Empty;
 newProduct.Attributes.Remove("quotedetailid");
 newProduct.Attributes["quoteid"] = new EntityReference("quote", newQuoteID);
 service.Create(newProduct);
}

After deploying to CRM and setting up the corresponding Workflow that referenced the assembly, I began testing. I noticed that the Workflow would occasionally fail on certain Quote records, with the following error message:

The plug-in execution failed because the operation has timed-out at the Sandbox Client.System.TimeoutException

The word Sandbox immediately made me think back to some of the key differences between CRM/D365E Online and On-Premise version, precisely the following detail pertaining to custom code deployed to Online versions of the application - it must always be deployed in Sandbox mode which, by default, only allows your code to process for 2 minutes maximum. If it exceeds this, the plugin/workflow will immediately fail and throw back the error message above. Upon closer investigation, the error was only being thrown for Quote records that had a lot of Quote Products assigned to them. I made the assumption that the reason why the workflow was taking longer than 2 minutes is because my code was performing a Create request into CRM for every Quote Product record and, as part of this, only proceeding to the next record once a success/failure response was returned from the application.

The challenge was therefore to find an alternative means of creating the Quote Product records without leading the Workflow to fail. After doing some research, I came across a useful MSDN article and code example that utilised the ExecuteMultipleRequest message:

You can use the ExecuteMultipleRequest message to support higher throughput bulk message passing scenarios in Microsoft Dynamics 365 (online & on-premises), particularly in the case of Microsoft Dynamics 365 (online) where Internet latency can be the largest limiting factor. ExecuteMultipleRequest accepts an input collection of message Requests, executes each of the message requests in the order they appear in the input collection, and optionally returns a collection of Responses containing each message’s response or the error that occurred.

Source: https://msdn.microsoft.com/en-us/library/jj863631.aspx

Throwing caution to the wind, I repurposed my code as follows, in this instance choosing not to return a response for each request:

// Create an ExecuteMultipleRequest object.
ExecuteMultipleRequest request = new ExecuteMultipleRequest()
{
 // Assign settings that define execution behavior: continue on error, return responses. 
 Settings = new ExecuteMultipleSettings()
 {
 ContinueOnError = false,
 ReturnResponses = false
 },
 // Create an empty organization request collection.
 Requests = new OrganizationRequestCollection()
};

foreach (Entity product in qp.Entities)
{
 Entity newProduct = product;
 newProduct.Id = Guid.Empty;
 newProduct.Attributes.Remove("quotedetailid");
 newProduct.Attributes["quoteid"] = new EntityReference("quote", newQuoteID);
 CreateRequest cr = new CreateRequest { Target = newProduct };
 request.Requests.Add(cr);
}

service.Execute(request);

Thankfully, after re-testing, we no longer encountered the same errors on our particularly large Quote test records.

As a learning experience, the above has been very useful in showcasing how straightforward custom workflow assemblies are when coming from a primarily plugin development background. In addition, the above has also presented an alternative method for creating batch records within CRM/D365E, in a way that will not cause severe performance detriment. I was surprised, however, that there is no out of the box means of quickly copying existing records, thereby requiring an approach using code to resolve. Quotes are an excellent example of an Entity that could benefit from Template-isation in the near future, in order to expedite common order scenarios and help prevent carpel tunnel syndrome from CRM users the world over. 🙂

Implementing Custom Calculations for Sales Entities (Dynamics CRM/Dynamics 365 for Enterprise)

Sun, 29 Jan 2017 00:00:00 +0000

Organisations that deploy Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E) can immediately take advantage of a number of inbuilt functionality, processes and data models that can be re-purposed with minimal effort. Whilst this approach can often lead to more streamlined deployment of your CRM/D365E solution, individuals customising the system should take care not to make the system fit around a business too much; rather, the opposite must be achieved where ever possible and careful analysis should be carried out in the outset to ensure that this balance is maintained. Sacrificing sensible business processes to accommodate for the quirks of a particular business system is a major pitfall that should be avoided as part of any major IT system deployment.

A good example of this can be found in the pricing calculation engine within CRM/D365E, which is utilised by the following entities within the system:

Opportunity
Opportunity Product
Quote
Quote Product
Order
Order Product
Invoice
Invoice Product

Rather than having to implement your own logic to generate prices for these entities, businesses can choose to utilise the pricing engine to automatically generate the net total for your Products, calculate appropriate Discounts and then figure out the final total at the end.

For those who are dissatisfied with how CRM performs this calculation, you will be pleased to hear that you have the option to override the default pricing engine and specify your own via a C# plugin. More information, and a very handy code example, can be found on our good friend MSDN:

The pricing engine in Microsoft Dynamics 365 supports a standard set of pricing and discounting methods, which might be limiting to your business depending on your specific requirements for applying taxation, discounts, and other pricing rules for your products. If you want to define custom pricing for your products in opportunities, quotes, orders and invoices, you can use the CalculatePrice message.

To use the custom pricing for your opportunities, quotes, orders, and invoices:

Set the value of the Organization.OOBPriceCalculationEnabled attribute to 0 (false). You can also use the Sales tab in the system settings area in Microsoft Dynamics 365 or Microsoft Dynamics 365 for Outlook to disable system pricing. More information: Configure product catalog information

Create a plug-in that contains your custom pricing code for calculating the price for your opportunity, quote, order, or invoice.

Register the plug-in on the CalculatePrice message.

Source: https://msdn.microsoft.com/en-us/library/dn817885.aspx

I think the most key thing as part of the above is not to overlook the simplest step - namely, modifying the setting within CRM/D365E that lets you specify your custom pricing engine in the first place. If this is not set, then you may spend many hours trying to figure out why your beautifully developed plugin is not working! It can be found very straightforwardly in Administration area of the application, on the System Settings page:

Whilst the code example provided by Microsoft gives you a good flavour of what you can potentially achieve with your own custom logic, I thought I would share two further examples that I recently was involved in developing, which may also prove useful when putting together your own custom pricing engine.

Calculating Custom Fields/Attributes

Arguably one of the biggest benefits of implementing your own custom pricing engine is being able to incorporate additional fields as part of the calculation. A recent real life example best demonstrates this. I was implementing a quoting solution for a business within Dynamics CRM 2015. The organisation was, fortunately, able to utilise much of the out of the box functionality within CRM as part of their existing processes. The only caveat was that they wanted the ability to add a Margin value at the Order level, in a similar vein to the Discount fields currently on the Quote entity - a Discount value and a Discount percentage value. The organisation wanted the option to do both, either or neither i.e. have the ability to specify a Margin value AND an additional percentage on top of that.

After configuring the appropriate fields within CRM to store both a currency value for the Margin and a decimal value for the Margin (%), we then proceeded to write some custom code that would achieve this aim. A snippet of this can be found below, which takes an existing total value of all Products on a Quote and then applies the correct calculation. It is worth explaining that the system returns NULL values if there is no data in the field when using the GetAttributeValue method (a fact I was already well aware of), which is why we have to specifically set the variables with a default value of 0 and perform the NULL check:

decimal margin = 0;
decimal marginPercent = 0;

if (quote.GetAttributeValue<Money>("new_mycustommarginamountfield") != null)
 margin = quote.GetAttributeValue<Money>("new_mycustommarginamountfield").Value;

if (quote.GetAttributeValue<Money>("new_mycustommarginpercentagefield"))
 marginPercent = quote.GetAttributeValue<decimal>("new_mycustommarginpercentagefield");

//Calculate margin amount based on the total amount

total = total + margin;
quote["totalamountlessfreight"] = new Money(total);
service.Update(quote);

//Calculate margin percentage based on the total amount

decimal marginPercentVal = marginPercent / 100 * total;
total = total + marginPercentVal;
quote["totalamountlessfreight"] = new Money(total);
service.Update(quote);

Calculating Sales Tax

CRM/D365E makes the assumption that tax will always be calculated on the Product Detail level. That’s why the Quote Product, Opportunity Product, Order Product and Invoice Product entities have a Tax field, demonstrated below on the Quote Product form:

There are a few problems with this, however:

You cannot set a default Tax for each Product in the system. What this means is that you have to drill down to every Product details entity and populate the Tax manually. Whilst you could look at a Business Rule, Workflow or some custom code to get around this issue, this seems like a rather complicated solution to something that you would expect to be easy to configure.
My experience indicates that most companies in the UK calculates tax on the gross amount of an order, and not at an individual Product level. Attempting to try and change a common practice to fit around a business system is a good example of what I spoke about in the introduction to this blog post.
Generally, most organisations will work with a flat rate of Tax for all Products (unless they are dealing with other countries). With this in mind, it seems a little crazy having to set this on an individual basis.

By using our own custom calculation logic, we can get around the above and implement a solution that best meets our need. For example, here is a code snippet that will take the total value of all Products on the Order entity and then calculate the VAT tax amount at 20%, saving the tax-only amount and the Net Total back to the system:

decimal vat = 0.20m;
decimal total = 0;
decimal tax - 0;

for (int i = 0; i < ec.Entities.Count; i++)
{
 total = total + ((decimal)ec.Entities[i]["quantity"] * ((Money)ec.Entities[i]["priceperunit"]).Value);
 (ec.Entities[i])["extendedamount"] = new Money(((decimal)ec.Entities[i]["quantity"] * ((Money)ec.Entities[i]["priceperunit"]).Value));
 service.Update(ec.Entities[i]);
}

//Calculate total from tax

tax = total * vat;
total = total + tax;
order["totaltax"] = new Money(tax);
order["totalamount"] = new Money(total);
service.Update(quote);

It would be disingenuous of me not to point out that the above solution has its own faults - the biggest one being that your code would require manually updating if the tax rate ever changes in the future. You can perhaps get around this issue by instead storing the current tax rate within a CRM entity, that can be updated in line with any future changes. Your plugin could then query this entity/attribute each time the plugin is executed.

Conclusions or Wot I Think

Whilst the ability to override a key feature within CRM/D365E is incredibly welcome and a great example of how you can leverage the system without compromising on your existing business processes, it is arguable that this process is hardly straightforward. A passing knowledge of C# is mandatory to even begin to start implementing your own custom pricing engine, as well as good awareness of how CRM/D365E plugins work. This is all stuff that an administrator of the application may struggle to grasp, thereby requiring dedicated resource or knowledge within the business to implement the desired solution. It would be nice to perhaps see, as part of a future version of D365E, the ability to specify a custom pricing engine within the application itself - similar to how Business Rules were introduced and reduced the need for form-level JScript functions to achieve common tasks. Nevertheless, it has been good to discover that the CalculatePricing message is exposed within the application and that the application has the flexibility for end users to modify (and perhaps improve upon 🙂) one of its key features.

Utilising Views with the CRM/Dynamics 365 for Enterprise Web API

Sun, 08 Jan 2017 00:00:00 +0000

I was recently showing a colleague how to use the rather excellent CRM REST Builder Managed Solution, in particular, its ability to generate code snippets for predefined query requests into Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E). During the demo, I noticed the following options under the Query Type drop-down with interest:

I did some further digging on MSDN to confirm that my suspicions were correct, and I was pleased to be able to confirm the following:

Microsoft Dynamics 365 allows you to define, save, and execute two types of queries as listed here.

Query type Description

Saved Query System-defined views for an entity. These views are stored in the savedquery EntityType. More information: Customize entity views

User Query Advanced Find searches saved by users for an entity. These views are stored in the userquery EntityType. More information: UserQuery (saved view) entity

Records for both of these types of entities contain the FetchXML definition for the data to return. You can query the respective entity type to retrieve the primary key value. With the primary key value, you can execute the query by passing the primary key value.

Query type	Description
Saved Query	System-defined views for an entity. These views are stored in the savedquery EntityType. More information: Customize entity views
User Query	Advanced Find searches saved by users for an entity. These views are stored in the userquery EntityType. More information: UserQuery (saved view) entity

Source: https://msdn.microsoft.com/en-gb/library/mt607533.aspx

So to clarify the above, there are 3 ways we can query CRM’s/D365’s Web Services with FetchXML based queries: either with a direct FetchXML query, by referencing a System View or by referencing a Personal View. The benefits of using a System/Personal view are significant, such as:

By having your Web API query setup as a view within CRM, you can utilise it within the application as part of a dashboard, entity view etc.
You can reduce the size of your request and obfuscate information relating to your CRM instance (such as entity and attribute names) by using a saved query.
Your FetchXML query can be stored within the application, meaning that you don’t need to worry about finding alternative means of backing up/storing your query.

Knowing the above would have been quite useful during my recent PowerBI exploits involving the CRM/D365 Web API, so this is definitely something that I will be reviewing again in future. If you want to get started using Saved/User queries in the application yourself, there are a few things to decide on in the first instance and slight hurdles to overcome initially, depending on the nature of your FetchXML query.

So first things first, how do I create my user/system query in CRM?

This will depend on the complexity of the query you are attempting to execute. To demonstrate this, let’s take a look at FetchXML Query # 1:

<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
 <entity name="phonecall">
 <attribute name="subject" />
 <attribute name="statecode" />
 <attribute name="prioritycode" />
 <attribute name="scheduledend" />
 <attribute name="createdby" />
 <attribute name="regardingobjectid" />
 <attribute name="activityid" />
 <order attribute="subject" descending="false" />
 <filter type="and">
 <condition attribute="directioncode" operator="eq" value="0" />
 </filter>
 </entity>
</fetch>

The above is a nice and straightforward query to return Phone Call records with a directioncode of “Incoming”, that can be built as an Advanced Find Personal View or System View very straightforwardly. But things change significantly when we take a look at FetchXML Query # 2 (an adapted query, provided courtesy of MSDN):

<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="true">
 <entity name="lead">
 <attribute name="fullname" />
 <link-entity name="task" from="regardingobjectid" to="leadid" alias="ab" link-type="outer" />
 <filter type="and">
 <condition entityname="ab" attribute="regardingobjectid" operator="null" />
 </filter>
 </entity>
</fetch>

There is no way that we can specify an outer join query within the CRM interface; so the only way in which we can get this query saved back into CRM is by writing a bespoke C# app that will add it in for us. Here is a code example for a method achieving this:

static void CreateSystemView(IOrganizationService service)
{
 Guid viewID;

 string layoutXML = @"<grid name='resultset' object='4' jump='fullname' select='1' preview='1' icon='1'>
 <row name='result' id='leadid'>
 <cell name='fullname' width='150' />
 </row>
 </grid>";

 string fetchXML = @"<fetch version='1.0' output-format='xml-platform' mapping='logical' distinct='true'>
 <entity name='lead'>
 <attribute name='fullname' />
 <link-entity name='task' from='regardingobjectid' to='leadid' alias='ab' link-type='outer' />
 <filter type='and'>
 <condition entityname='ab' attribute='regardingobjectid' operator='null' />
 </filter>
 </entity>
 </fetch>";
 Entity savedQuery = new Entity("savedquery");

 savedQuery["name"] = "Complex View Test";
 savedQuery["description"] = "Test view to demonstrate how to create a view with a complex FetchXML query";
 savedQuery["returnedtypecode"] = "lead";
 savedQuery["fetchxml"] = fetchXML;
 savedQuery["layoutxml"] = layoutXML;
 savedQuery["querytype"] = 0;

 viewID = service.Create(savedQuery);
 Console.WriteLine("Created system view " + viewID);
}

Two things to point out with the above:

For the layoutXML, be sure to modify the object value so that it is the correct value for the entity you are working with. Otherwise, although your view will be successfully created within the application, you will be unable to load it correctly from within the interface. You can find a list of all system Entity codes here. For custom Entity codes, you will need to use a tool like the Metadata Browser in the XRMToolBox to determine the correct value.
The above code example is using late-bound classes to generate the appropriate data to create the view, contrary to the official sample code provided by Microsoft. I was a little bit unsure initially whether views could be created in the manner, so I was pleased when I was able to confirm the opposite 🙂

With your view created, what’s next?

You’ll need to obtain the database GUID for the view record in CRM. If you have created your view for the complex example above, then you can very easily grab this value by setting a breakpoint in your application in Visual Studio and accessing the viewID value. An alternative way is via the application:

For System Views, navigate to the View within the solutions page and open it up as if you were about to edit it. Maximise the window to full screen by pressing the F11 key. The URL of the page should now be visible if you move your mouse to the top of the screen, and available for copying. It should look something like this:

http://mycrminstance/tools/vieweditor/viewManager.aspx?appSolutionId=%7bFD140AAF-4DF4-11DD-BD17-0019B9312238%7d&entityId=%7bDC6574CB-92CE-446C-A5D6-885A75107D52%7d&id=%7b6979F60B-D5D4-E611-80DC-00155D02DD0D%7d

The GUID of the view will be the last query parameter string, with the encoded curly braces values (%7b and %7d) removed. So, based on the above, the GUID is:

6979F60B-D5D4-E611-80DC-00155D02DD0D

Personal Views are a little more tricky. The most straightforward way I can think of obtaining this is by going to a Users list of Active Saved Views, exporting the list to Excel via the Static Worksheet (Page Only) button and then grabbing the GUID from the hidden Cell A in Excel:

This would obviously require you to have access to the Personal View, either via user login details or by having the user share the view to you. An alternative way to get this information would be via querying the Saved View entity via FetchXML/T-SQL.

Once you’ve got your GUID, you’re all set - you can now build your web service request in the language/format of your choosing. An example via XmlHttpRequest in JScript can be found below:

var req = new XMLHttpRequest();
req.open("GET", Xrm.Page.context.getClientUrl() + "/api/data/v8.1/leads?savedQuery=6979F60B-D5D4-E611-80DC-00155D02DD0D", true);
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Prefer", "odata.include-annotations=\"*\"");
req.onreadystatechange = function() {
 if (this.readyState === 4) {
 req.onreadystatechange = null;
 if (this.status === 200) {
 var results = JSON.parse(this.response);
 } else {
 Xrm.Utility.alertDialog(this.statusText);
 }
 }
};
req.send();

The actual request header should resemble the below:

GET /JG/api/data/v8.1/leads?savedQuery=6979F60B-D5D4-E611-80DC-00155D02DD0D HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Prefer: odata.include-annotations="*"
Accept-Language: en-GB
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
Cookie: ReqClientId=9f48373a-aa68-462c-aab0-15ebd9311ce4; persistentNavTourCookie=HideNavTour; dea5e364-6f18-e611-80b5-00155d02dd0d_08f6129c-ce5b-4b98-8861-b15d01523fe1=/Date(1472324901665)/; excelDownloadToken=-1

Encapsulating your CRM/D365E queries as part of a System or Personal View is an effective way of reducing the size of your web service requests and simplifying the contents of the request whilst in transit. I would argue that a System View is a far better candidate for this job compared to a Personal View. Unless you have a specific business requirement not to have the view available to all users within the application, utilising this could save on lots of troubleshooting and administrative headroom down the line compared with a Personal View (such as if, for example, the person who has created the view originally leaves the business).

Becoming a Dynamics CRM/365 for Enterprise Swiss Army Knife: Essential Study Areas

Sun, 18 Dec 2016 00:00:00 +0000

Getting to grips with how to use Dynamics CRM/365 for Enterprise (D365E) is no easy feat. You can imagine just how difficult it is for an end user to get to grips with how the application works and functions; with more detailed knowledge around customisation and development being an entirely different ball game altogether. Compounding this problem further is the fact that the product has evolved at an increasingly more rapid pace over recent years, to the point where it is literally impossible to become a master of everything that you can do within CRM/D365E. Those venturing into the product for the first time may find their learning journey significantly simplified if they already have a good general knowledge about some of the underlying technology that powers CRM/D365E. This was certainly true in my case; I had a good background already in managing Office 365, writing SQL queries/reports and some experience with C#. This is all incredibly useful knowledge to have in your arsenal and is all directly applicable towards CRM/D365E in some way. For those who are getting to grips with the product for the first time, either without this previous experience or as part of an apprentice/graduate type role, your journey may not be as swift and issue-free. With this in mind, here’s my list of essential knowledge that you can add to your own “swiss army knife” of personal knowledge. Experience and good knowledge of these technologies will not only help you greatly in working with CRM/D365E, but present an excellent learning opportunity for Microsoft technologies more generally and something that you can add to your CV with pride:

SQL Server

What is it? : SQL Server is Microsoft’s proprietary database knowledge, based on the ANSI standard. SQL stands for Structured Query Language and is one the most widely used database programming languages on the planet.

Why Knowing It Is Useful: The underlying database technology that CRM/D365E uses is SQL Server, so having a general awareness of relational database systems work and how SQL Server differs from the standard goes a long way in understanding what is capable from a customisation/development viewpoint. For example, you can very quickly grasp which data types the application supports, as they will all ultimately be based on a supported SQL Server column data type. If you are running on-premise versions of CRM/D365E, then knowledge of SQL Server immediately moves from being a nice bonus to an essential requirement. This is because administrators will need to have good knowledge of how to manage their Dynamics CRM database instance, perform backups and also, potentially, write transact-SQL (T-SQL) queries against your database for reporting or diagnostic work.

Recommended Area of Study: Focusing your attention towards SQL Server Reporting Services (SSRS) report writing will benefit you the most. Through this, you can begin to establish good knowledge of how SQL Server databases work generally, and be in a position to write FetchXML for Online/On-Premise deployments of the application or Transact-SQL (T-SQL) based reports for On-Premise only. Having a good awareness of what is capable via a standard SQL query will also hold your good stead when working with FetchXML, as you can immediately make a number of assumptions about what is possible with FetchXML (for example, filtering results using an IN block containing multiple values and performing grouping/aggregate actions on datasets)

Office 365

What is it? : Office 365 is Microsofts primary - and perhaps most popular - cloud offering for businesses, individuals or home users. Through a wide array of different subscription offers, home and business users can “pick ’n’ mix” the range of solutions they require - from Exchange-based email accounts to licenses for Microsoft Visio/Project, through to PowerBI.

Why Knowing It Is Useful: Although it is arguable that knowledge of Office 365 is not essential if you anticipate working with on-premises versions of the application, you may be doing yourself a disservice in the long term. Microsoft is increasingly incentivising organisations to move towards the equivalent cloud versions of their on-premise applications, meaning that as much knowledge as possible of how CRM/D365E Online works in the context of Office 365 is going to become increasingly more mandatory. If you are looking to secure a career change in the near future, and have not had much experience with Office 365, then this is definitely an area that you should focus on for future learning. From a day-to-day management point of view for the Online version of the product, some basic awareness of how to navigate around and use Office 365 is pretty much essential if you are going to succeed working with the product on a day-to-day basis.

Recommended Area of Study: Spin up a D365E trial, and you can very quickly start getting to grips with how the product sits within the Office 365 “ecosystem”. Practice licensing users, configuring security group level access to your D365E trial tenant and modify the details on Office 365 user accounts to see how these details are synced through into D365E. The Microsoft Virtual Academy also has a number of general courses related to Office 365 however, due to the frequent updates, it may not always be in-line with the current version. The official curriculum/certification paths for Office 365 may also suffer the same from this but are worthwhile in demonstrating your experience and ability to integrate D365E with the various related Office 365 services.

Active Directory

What is it? : For the rookie, intermediate and experienced IT admins, Active Directory needs no introduction. It is essentially Microsoft’s implementation of the Lightweight Directory Access Protocol (LDAP), having first being introduced in Windows Server 2000, providing a means of managing user, security and access rights for domain objects. There are now two distinct versions of Active Directory that are available - the more traditional, Windows server based, on-premise Active Directory and Azure Active Directory, which is utilised primarily by Office 365.

Why Knowing It Is Useful: User account records for both On-Premise and Online versions of CRM/D365E use Active Directory objects, with a number of important information synchronised between an Active Directory user and the equivalent User entity record. For example, as indicated in this MSDN article, the only way in which you can synchronise a user’s Job Title through to CRM/D365E is by updating the equivalent field on the Azure Active Directory. Active Directory objects are also the only way in which you can authenticate with the application via the Web Interface or other means, with no option to create a database user or other kind of authenticated user type.

Recommended Area of Study: It’s free to set up your own Azure Active Directory, so this is an excellent starting point for getting to grips with the technology. There’s also nothing preventing you from downloading a trial of Windows Server and installing the Active Directory server role on this machine. Once configured, you can then start to create users, update attributes, configure permissions and setup roles that contain collections of privileges. If you already have an Office 365 tenant with CRM/D365E Online, then you can use the Office 365 portal to manage your user accounts and test the synchronisation of attribute values from the Active Directory through to the application.

PowerShell

What is it? : A good way to remember what PowerShell is that it is essentially a blue command prompt window 🙂 . Traditionally only being relevant and important for those working extensively with Windows Server or Exchange, PowerShell is now increasingly important as part of administrating on-premise CRM/D365E, Office 365 and Azure, to name a few. Indeed, one of the major shock announcements this year was that PowerShell became open sourced and can be installed on Linux; representing the increasing demand and importance of Linux-based resources within the Microsoft cloud.

Why Knowing It is Useful: Similar to SQL Server, PowerShell is something that is instantly more applicable for on-premise CRM/D365E deployments. For example, the only way to modify the default number of Dashboard items is via executing the Get-CRMSetting cmdlet against your on-premise organisation. I would also, again, argue having a general awareness of PowerShell can help greatly when performing administration work against an Office 365 tenant that contains a CRM/D365E organisation, such as user provisioning or license assignment. If you are utilising the Azure Service Bus to integrate CRM/D365E for Azure-based applications, then PowerShell immediately becomes a desirable skill to have in your arsenal, allowing you to remotely administer, deploy or update Azure resources programmatically.

Recommended Area of Study: The fact that PowerShell is now open sourced means that there is a plethora of online tools and guides to refer to, and you can be assured that you can get it working on your platform of choice. The GitHub page for PowerShell is a great place to get started. Beyond that, you have a few options about how you can practice further. If you have spun up a D365E trial, then you can choose to hook up PowerShell to Office 365 to see what you can do from a remote management perspective (such as granting Send On Behalf permissions for a shared mailbox). Alternatively, you can run it from your local Windows machine, connect it up to a Windows Server instance or attempt to create new services in Azure and experiment that way.

Beware the AliasedValue Attribute (Dynamics CRM)

Sun, 04 Sep 2016 00:00:00 +0000

I was writing some code recently for a CRM plugin, that involved working with multiple link entity attributes as part of a QueryExpression. Accomplishing this is relatively straightforward, thanks to some of the code samples provided within the SDK. For example, the following sample code gives you everything you would need; how to build the query and, more importantly, include the attributes you would need to return as part of the request:

//Create a query expression specifying the link entity alias and the columns of the link entity that you want to return
QueryExpression qe = new QueryExpression();
qe.EntityName = "account";
qe.ColumnSet = new ColumnSet();
qe.ColumnSet.Columns.Add("name");

qe.LinkEntities.Add(new LinkEntity("account", "contact", "primarycontactid", "contactid", JoinOperator.Inner));
qe.LinkEntities[0].Columns.AddColumns("firstname", "lastname");
qe.LinkEntities[0].EntityAlias = "primarycontact";

EntityCollection ec = _orgService.RetrieveMultiple(qe);

Console.WriteLine("Retrieved {0} entities", ec.Entities.Count);
foreach (Entity act in ec.Entities)
{
 Console.WriteLine("account name:" + act["name"]);
 Console.WriteLine("primary contact first name:" + act["primarycontact.firstname"]);
 Console.WriteLine("primary contact last name:" + act["primarycontact.lastname"]);
}

Very handy! But there are two problems that you may encounter when attempting to run the code yourself:

The code snippet attempts to print out the value of the LinkEntity First Name and Last Name Contact fields to the console. So, for example, when your code retrieves the Fourth Coffee (sample) record, we would expect to see Rene Valdes (sample) printed out. Unfortunately, this doesn’t happen, and we are instead greeted with a value that may precipitate some serious head-scratching:

The issue lies in how the SDK handles link-entity attributes included as part of a query. Instead of returning the value in the data type we would expect and, despite appending the appropriate namespace within our code to indicate the link entity our attribute is from (in this case, primarycontact), CRM instead gives us the attribute as part of an AliasedValue object. The comforting thing to know is that the attribute value that we may (desperately!) want to grab is in this object somewhere, and we will look at the best way of accessing this later on in this post.

Putting aside the above issue, let’s assume that we weren’t working with an AliasedValue and just a standard CRM data type - for example, Single Line of Text/string. Our above code would work fine against all of the sample data records within CRM. But if we add a new Account record and add a Primary Contact record that doesn’t have a First Name value, we get an error thrown within our code when it attempts to output this value into the console:

Regular readers of the blog may be able to guess what is happening - as part of one of my previous posts looking at the GetAttributeValue method, we looked at the danger of accessing attributes via the Entity class, particularly when these attributes may end up containing blank values. In this particular example, there is another factor at play too - when a QueryExpression attempts to bring back all of the requested attributes, any attribute(s) that do not contain a value in the CRM database (i.e. are NULL) are not returned at all. This fact is useful in ensuring that our code can run as optimally as possible, but in this case, is our downfall - because our Entity object has no Contact attribute with a First Name value, no value is available to return, so our code panics and throws an error; for the simple reason that it is attempting to access something that does not exist.

So how can we get around both of these issues? First of all, we need to alter the code so that the actual value of the First Name and Last Name fields are displayed correctly. One way of executing this is to explicitly cast our attribute values as AliasedValues, access the inner properties of the object and then cast to string the value of the attribute. An updated version of our code would, therefore, look like this:

{
 Console.WriteLine("account name:" + act["name"]);
 Console.WriteLine("primary contact first name:" + ((AliasedValue)act["primarycontact.firstname"]).Value.ToString());
 Console.WriteLine("primary contact last name:" + ((AliasedValue)act["primarycontact.lastname"]).Value.ToString());
}

Running this against our Sample Account/Contact results returns what we expect, which is good 🙂

But, unfortunately, does not give us a complete solution to the above as we still hit a “The given key was not present in the dictionary.” error message as before, for the same reasons:

The above method is not satisfactory then, as we would need to include additional lines of code to handle the fact that the attribute value is not present - an if…else statement or a try…catch block. If we forget to put this in, then another issue surfaces in bad code potentially seeping into a Production environment - causing errors for end-users and hours of unnecessary debugging.

Our old friend GetAttributeValue has saved the day for us previously; can it do again? We can try by using the code snippet below - specifying the fact that we are returning an AliasedValue object and then getting the inner attribute Value:

Console.WriteLine("account name:" + act["name"]);
Console.WriteLine("primary contact first name:" + act.GetAttributeValue<AliasedValue>("primarycontact.firstname").Value);
Console.WriteLine("primary contact last name:" + act.GetAttributeValue<AliasedValue>("primarycontact.lastname").Value);

The code errors again, unfortunately, with a different error message, indicating that a NULL value is attempting to be accessed:

In this case, we must rely on our knowledge of C# to save the day, with a few options at our disposal. I’ve already suggested two possible options, but another could be considered, which would reduce the number of lines in our code. By using the conditional operator (?:), we can “test” for a NULL value in our GetAttributeValue and, if a NULL value is present, substitute it for an empty string or a value of our choice. Our final, error-free code, would look like this:

foreach (Entity act in ec.Entities)
{
 Console.WriteLine("account name:" + act["name"]);
 Console.WriteLine("primary contact first name:" + (act.GetAttributeValue<AliasedValue>("primarycontact.firstname") == null ? "" : act.GetAttributeValue<AliasedValue>("primarycontact.firstname").Value));
 Console.WriteLine("primary contact last name:" + (act.GetAttributeValue<AliasedValue>("primarycontact.lastname") == null ? "" : act.GetAttributeValue<AliasedValue>("primarycontact.lastname").Value));
}

Then, just to be sure, we run a quick test and confirm everything works as expected:

Now we can rejoice that our code is error free and that we’ve found another good example of how the GetAttributeValue method should always be used when working with CRM attributes. It is a shame though that the code above, provided by Microsoft as part of the SDK, has such a significant error within it. Hopefully, it will be addressed as part of a future version of the SDK and we should be thankful that we at least have all of the sample code in the SDK in the first place; it gives developers and CRM customisers a great starting point to start developing consistent and supported code.

What's the best way of learning CRM Development?

Sun, 28 Aug 2016 00:00:00 +0000

A colleague recently asked me this question, and I’ll admit that it took me a few minutes to think about the answer. Learning how to write code that extends functionality within or outside of CRM is not something that you can just pick up from scratch. You usually need to have good experience with coding first, before you can safely venture into writing your first plugin or form level JScript function. Fundamental, and arguably, crucial knowledge of the CRM platform is essential too, as this ensures that you don’t put forward solutions that the application can handle natively. In this week’s blog post, I will first clarify what CRM Development actually means, before outlining my “top tips” on how you can develop your skills to become a superstar CRM Developer.

So what is CRM Development, and is it the same as CRM Customisation?

It’s important that we first clarify what the difference is between these two types of activities, as although there is some cross-over, often they are split out into two distinct roles - a CRM Customiser and CRM Developer. Someone who occupies the first of these roles frequently spends the majority of their time working with CRM Solutions and the Customizations area of CRM. Customisers will commonly be involved in the creation of new entities, fields, system views, processes, business rule & workflows, to name a few. As a consequence, they will more often than not have a great deal knowledge of what the platform is capable of and are generally in the best position to offer support and mentoring to colleagues who are struggling with something in CRM (for example, how to create a personal view).

In comparison, a CRM Developer may spend very little time working with solutions and customisations; although they will be expected to have a general awareness of what the platform is capable of doing, they will mostly only ever be concerned with modifying plug-ins, plug-in steps and web resources from within solutions. CRM Development instead encompasses a broad canvas of work, all of which is geared towards extending the native functionality of the application. An example list may include:

Writing form level JScript, for scenarios where a Business Rule can’t achieve the desired results (we’ve already learned the importance of considering Business Rules as a first step option in these scenarios)
Developing custom plug-ins in C#/VB.NET to execute at specific trigger points within the underlying database transaction e.g. after a Contact record has been updated.
Building custom workflow assemblies in C#/VB.NET to further enhance the options available as part of a workflow or dialog.
Setting up custom Web Resources in HTML/Silverlight, that can be embedded within CRM forms or dashboards.

A good way of remembering the difference is to remember that CRM Customisation can all be done from within the application itself, whereas CRM Development involves work created outside the application to achieve specific business requirements.

Now that we’ve got that out of the way, here’s my top 5 list on how you can learn CRM Development:

Learn C# First

As well as providing you with everything you would ever need from a plug-in/custom workflow development perspective, having a good grasp of C# can make learning JScript a lot more easier. Both languages have a lot of similarity, with some important differences that require noting. First, JScript is largely indifferent when it comes to working with data types, whereas C# is very fussy when it comes to declaring and casting your data types correctly. Secondly, whereas C# development work can be assisted via the use of early-bound class files, JScript can be annoyingly unsympathetic when you write code, with errors only cropping up when you attempt to run your code. Putting aside these differences though, being able to say that you have a good grasp of C# on your C.V. can assist greatly when seeking out roles involving CRM, particularly given such roles will be looking for experience of integrating CRM with third party applications; C# is your Swiss army knife in these situations.

The SDK is your treasure trove.

There are countless number of code examples & snippets enclosed within the SDK, which include all of the languages that you would use to extend CRM - JScript, C# and even VB.NET! These are typically in a state where you can easily deploy them to a test CRM environment, execute them and then playback within Visual Studio via the Plugin Profiler, so you can understand what they are doing. The enclosed help file (which is replicated fully on the MSDN website) is also really detailed in explaining what you can do when developing for CRM. You can download the latest version of the SDK (updated recently for the 2016 Spring Wave) here.

Get an MSDN Subscription

I have extolled the virtues of what an MSDN subscription can provide to Microsoft professionals previously, so I won’t cover old ground. What I will highlight from this is that the Imagine Academy, included as part of a subscription, contains nearly all of the courses found on the Dynamics Learning Portal (available to CRM partners as a learning resource “hub” for all Dynamics products). It also gives you access to a number of important, developer-focused resources that you add to your arsenal and use to further enhance your knowledge of C#, JScript etc. If you’re fortunate enough to have enough money to obtain an Enterprise MSDN Subscription, or your employer has a few spare licenses, then you will be able to get your hands on a coveted CRM On-Premise license key as well. Working with the application in whatever capacity you can is the best and surest way to learn, as opposed to simply watching videos and reading online articles.

Pass those Exams

There are a wide plethora of different CRM exams available to take currently, and it can be quite confusing deciding which ones will benefit you best on your road to become a CRM Developer. I would suggest that the best exams to target a passing mark on would be the following:

The question you may be asking though is “How important are exams, compared with actual work experience?". I have heard many debates surrounding the importance of certification, on both sides of the argument; one criticism is that they are generally not a good way equipping candidates with the practical, real-life knowledge and experience that ultimately must come to the fore when working with CRM on a day-to-day basis. Another argument against them is that they can sometimes draw you towards focusing on features of a particular application that is either not very good or is done much better by an alternative product. Notwithstanding this, I think exams hold an important place in demonstrating to colleagues and potential recruiters just how serious you are about your career and in ensuring that you keep yourself up-to-date with the appropriate technology - in these modern times, staying off the ball for as little as a month can put you behind! Going back to the original purpose of this post, the curriculum on both of these exams will leave you in a position where you have achieved a good balance of knowledge: both of what CRM, as a platform, is capable of out of the box, and what you can do to develop further solutions for the application.

And finally, believe in yourself

This last tip may sound a little bit clichéd, but achieving your desire to become good at CRM Development is something that only you have control over. The journey may be hard, and you will often fail more than you succeed at first; but if you keep working at it, never give up and, most importantly, trust in yourself and your abilities, then you will succeed in increasing your knowledge and expertise in CRM.

Utilising Pre/Post Entity Images in a Dynamics CRM Plugin

Sun, 21 Aug 2016 00:00:00 +0000

One of the challenges when first working with CRM Plugins is understanding how the execution context works. To briefly summarise, this contains the information relating to how and when the plugin is executed. It can give you answers to some of the questions you may wish to “ask” your CRM - for example, what record has triggered this plugin? Which CRM User forced the plugin to execute? You may also assume that the context will contain all of the fields of that entity that you can then access. This is not always the case - typically, as part of an Update request, only the fields that triggered the update will be made available. Or consider an Associate/Disassociate request (i.e. when someone relates/unrelates two records in CRM). As part of a one-to-many (1:N) relationship, only one field has changed; so that is the only field that is contained within the execution context.

The above being the case, what options do you have if you need to access fields that are not included in the context? You have two choices available to you:

Obtain a reference to Organisation Service within your plugin, and then use a Retrieve request to return the fields you need from the plugin. As the context will always contain the GUID for the record that has changed, this is generally the most common way you will see this done.
Utilise either a Pre or Post Entity Image of the record, which contains the attributes that you need to access.

In the past, I would always end up going down the first route. Recently though, I have been evaluating Entity Images more and more, and have begun to actively use them as part of my plugins. Entity Images are, essentially, snapshots of the CRM record that are stored on the platform either before the database operation has completed or straight after - you can decide which one you want to use, depending on what your plugin is doing. They are configured as part of deploying your plugin to your target CRM instance, and the steps involved are actually quite simple - I think its generally the case that they are not well-understood or utilised by developers who are learning about CRM for the first time.

So why should you go to the extra effort to use them within your plugins?

As alluded to above, using Pre Entity Images means you can get a snapshot of your CRM data before the data was changed. This may prove to be particularly invaluable in cases where you need to perform a before/after comparison on a particular field, and then execute a specific action either way. The only non-entity image way of doing this within CRM would be via hidden field that stores the current value of your field in question, which is referenced and updated once your business logic has completed. A slightly in-elegant solution, and one that is questionable, given that we can utilise Entity Images instead. Having ready access to the attributes which may not necessarily be exposed to the plugin when it is executed is particularly invaluable, given that this avoids a scenario where you would have to go down option 1). Disadvantages of this approach is the potential for unnecessary delays in your plugin completing and problems with your CRM instance as a whole, if your CRM’s web services are already accessed to breaking point.

There must be a catch, surely…

On the whole, it doesn’t look like it, but you do need to aware of a few things. As you may have already guessed, if your plugin runs on the Create message, you won’t be able to access any pre-image of the record; likewise, for Delete message plugins, the post-image will not be available. It should be fairly obvious why this is the case. You are also restricted with the number of Messages that support Pre/Post Images. The full list can be found here, but to summarise the most important Message types, only Update, Assign, SetState & Merge support both Image types. Bear in mind too the additional “gotchas”, which this article touches upon. If in doubt, then boot up your sandbox CRM environment and cry havoc with your test code.

Lets take a closer look at how Pre and Post Images can be implemented as part of a CRM Plugin…

The below example will compare the Pre and Post Image values of the Lead Company Name field and, if they have changed, send an email message to a Sales Manager user to alert them of this fact. Be sure to add references to the Microsoft.Xrm.Sdk and Microsoft.Crm.Sdk.Proxy .dlls from the SDK:

//Extract the tracing service for use in debugging sandboxed plug-ins.

ITracingService tracingService = localContext.TracingService;
tracingService.Trace("Implemented tracing service succesfully!");

// Obtain the execution context from the service provider.
IPluginExecutionContext context = localContext.PluginExecutionContext;

// Get a reference to the Organization service.
IOrganizationService service = localContext.OrganizationService;

if (context.InputParameters.Contains("Target"))
{
 //Confirm that Target is actually an Entity
 if (context.InputParameters["Target"] is Entity)
 {
 Guid _userID = context.InitiatingUserId;

 //Retrieve the name of the user (used later)
 Entity user = service.Retrieve("systemuser", _userID, new ColumnSet("fullname"));

 string userName = user.GetAttributeValue<string>("fullname");

 Entity lead = (Entity)context.InputParameters["Target"];

 Entity preLead = (Entity)context.PreEntityImages["Image"];

 Entity postLead = (Entity)context.PostEntityImages["Image"];

 string preCompanyName = preLead.GetAttributeValue<string>("companyname");

 string postCompanyName = postLead.GetAttributeValue<string>("companyname");

 tracingService.Trace("Pre-Company Name: " + preCompanyName + " Post-Company Name: " + postCompanyName);

 if (preCompanyName != postCompanyName)
 {
 tracingService.Trace("Pre-Company Name does not match Post-Company Name, alerting sales manager...");

 //Queue ID for our Sales Manager
 Guid _salesManagerQueueID = new Guid("41b22ba9-c866-e611-80c9-00155d02dd0d");

 Entity fromParty = new Entity("activityparty");
 Entity toParty = new Entity("activityparty");

 //Email body text is in HTML
 string emailBody = "<html lang='en'><head><meta charset='UTF-8'></head><body><p>Hello,</p><p>Please be advised that I have just changed the Company Name of a Lead record in CRM:</p><p>Lead Record URL: <a href='http://mycrm/MyCrmInstance/main.aspx?etn=lead&pagetype=entityrecord&id=%7B" + lead.Id + "%7D'>" + postCompanyName + "</a></p><p>Old Company Name Value: " + preCompanyName + "</p><p>New Company Name Value: " + postCompanyName + "</p><p>Kind Regards</p><p>" + userName + "</p></body></html>";

 fromParty["partyid"] = new EntityReference("systemuser", _userID);
 toParty["partyid"] = new EntityReference("queue", _salesManagerQueueID);

 Entity email = new Entity("email");

 email["from"] = new Entity[] { fromParty };
 email["to"] = new Entity[] { toParty };
 email["subject"] = "Lead Company Name Changed";
 email["directioncode"] = true;
 email["description"] = emailBody;

 //This bit just creates the e-mail record and gives us the GUID for the new record...
 Guid _emailID = service.Create(email);

 tracingService.Trace("Email record " + _emailID + " succesfully created.");

 //...to actually send it, we need to use SendEmailRequest & SendEmailResponse, using the _emailID to reference the record
 SendEmailRequest sendEmailreq = new SendEmailRequest
 {
 EmailId = _emailID,
 TrackingToken = "",
 IssueSend = true
 };

 SendEmailResponse sendEmailResp = (SendEmailResponse)service.Execute(sendEmailreq);

 tracingService.Trace("Email record " + _emailID + " queued succesfully.");
 }
 else
 {
 tracingService.Trace("Company Name does not appear to have changed, is this correct?");
 return;
 }
 tracingService.Trace("Ending plugin execution.");
 }
}

Once we have written our code and built our solution, we deploy our plugin in the normal way via the Plugin Registration Tool - ensuring that we configure our step to fire on the correct message:

Next, we need to configure our Pre/Post Images manually. Just because we have referenced them in our code above doesn’t mean they will automatically become available to us as our plugin is executed. Fortunately, adding them on is not too difficult and we can do it directly within the Plugin Registration Tool. First, highlight our new plugin step and select Register New Image:

One good thing about this is that we can configure both our Pre and Post Images in the one screen. We just confirm that our intended plugin step is selected, tick both of the boxes and ensure that the following details are completed:

Name: Specify a name for this image. This can be anything you want it to be, but I would recommend using the same value as Entity Alias
Entity Alias: This is the name that is used in our code above to reference the image. This must match exactly against this in order for the code to work correctly.
Parameters: Here you specify which attributes will be made available within the image. By default, all attributes are included, but you should specify only the attributes you need to work with in your plugin. For our example plugin, we only need the Company Name field, so this is the only attribute we will select.

Your settings should look something like the below:

With everything setup, we can now test our plugin. In this case, I have changed one of the sample data leads to force the plugin to execute:

We can then see that our Email record is successfully created, which is able to reference the value of the Company Name field before the change:

Playing back the plugin within Visual Studio demonstrates that our Pre and Post images are Entity objects, meaning that we can interact with them the usual way - nothing new to learn or master, which is good 🙂

Conclusions - or Wot I Think

Like most things with CRM, Entity Images have a time and place. If you have a desire to query additional data concerning record relationship attributes etc. as part of your plugin, then a Retrieve request is still going to be the only way you can accomplish this. There is also some additional administrative head-room required when working with Images - if, for example, you forget to specify your Pre & Post Images when deploying your plugin, then you are going to encounter immediate problems within your CRM. Having said that, I think there is an excellent case to be made to using Entity Images as much as feasibly possible in your code. A Retrieve request on a particular busy CRM platform just to return one attribute value could store up problems for your CRM instance in the long-haul; having this one value stored as part of an entity Image seems a much more sensible and logical approach. I am further struck by how useful entity images can be if you need to reference data changes before and after a record change - going back to our example above, where we would instead look at creating custom field within CRM to store this value, having it made available as part of an Entity Image could score a major time saving. Finally, you are not just restricted to using the one Pre/Post Image - you can setup multiple ones that contain different fields from your entity, that are accessed in different parts of your code, depending on your logic. I think developers working with CRM definitely owe it to themselves to check out Entity Images at least once - I think they will be pleasantly surprised at their capabilities and, one would hope, the increased performance of their CRM instance as a consequence of using them!

The Benefits of Using GetAttributeValue to Access CRM Attributes (Late-Bound, C#)

Sun, 14 Aug 2016 00:00:00 +0000

When you first begin working with the Dynamics CRM SDK, there is a lot of specific terminology, concepts and methods that need to be grasped firmly. The importance of this is twofold: it enables you to judge the best approach when developing your bespoke solution that fits in within CRM and allows you to gain a very good understanding of the underlying CRM platform. The terms “early-bound” and “late-bound” are, arguably, the most important of these terms/concepts to fully understand, so it is useful to first explain what each of these refer to and the benefits & drawbacks of each, before we get into this weeks blog post properly:

Early Bound

Early bound refers to when you are using a generated class file to access all of the customization data for your CRM within your code. The SDK Bin folder contains an executable file called CrmSvcUtil, which can be used to generate this file. There is a great MSDN article that goes through the steps involved as part of this; once you’ve got the file, simply add it into your Visual Studio project and Intellisense will automatically detect your entity, relationship etc. names! Suffice to say, going down the early bound route can significantly ease your development work, as your strongly-typed class file will contain everything you would require regarding your CRM entities. As such, you will be able to ensure that your code is accessing the correct attributes, relationships and other objects within CRM at all times.

Given that it makes a developers jobs ten times easier, why wouldn’t you want to use Early Bound in your code all the time? Your strongly-typed class file is essentially a snapshot of your current CRM instance, at the date and time when you ran the CrmSvcUtil. As soon as someone makes a change within CRM, your class file may no longer be correct and you may encounter major problems when executing your code against your target CRM environment. This problem can also be compounded if you are developing an ISV solution that is executed against a varied number of environments, where there could be entities/attributes present that your code has no reasonable way to anticipate; in this case, it becomes absolutely essential for you to consider using late-binding instead within your code.

Late Bound

Late binding is the exact opposite of early binding. To access your CRM entities via the late-bound route, you use the Microsoft.Xrm.Sdk.Entity class to declare the new or existing entity that you wish to work with within your code. Typically, you will need to have your CRM Solution open in front of you as part of using late-binding, so that you can reference the logical names of your entities & attributes. You are therefore not “restricted” in the same way that you are with early-binding - you can declare any possible logical name for your CRM objects that you want, which, as mentioned already, is essential if you are blind to the CRM instance(s) in question. There is also a performance benefit to using the late-bound Entiy class, depending on the number of records your code is working with. According to the following Microsoft best practice article:

In addition, if your custom code works with thousands of entity records, use of the Entity class results in slightly better performance than the early-bound entity types.

One of the major drawbacks of using late binding is the increased chance of errors in your code, as you will need to ensure that your logical names are typed correctly; any such mistakes, as we will demonstrate further below, may cause your code to fall over straight away and lead to hours of frustrating debugging in order to resolve.

Now, to the heart of the matter…

I recently had a conversation with a developer colleague, who gave me some advice in relation to some plugin code I had written. Within my code, I had attempted to access the value of a Single Line of Text Entity attribute, using late-bound classes, in the following manner:

string myAttribute = myEntity["myattribute"].ToString();

They recommended instead that I look at using the GetAttributeValue method instead, which in this case, would be expressed in the following manner

string myAttribute = myEntity.GetAttributeValue<string>("myattribute");

My colleague elaborated on a few reasons why this approach is preferential (which I will discuss at the end of this post), but I was interested in dissecting this further myself, to see how it works in practice. In my test CRM instance, I created a plugin for the Contact entity, that would fire on the Post-Operation event of the Update Message, for the First Name field. The plugin very simply accesses the value of this field using the two different approaches, which can be done like so:

//First, initialize your Contact entity
Entity contact = (Entity)context.InputParameters["Target"];

//Now we can access our attributes - the first way is like this...
string contactField1 = contact["firstname"].ToString();

//The second way...
string contactField2 = contact.GetAttributeValue<string>("firstname");

When we play back the plugin execution in Visual Studio, we can see that this returns our expected values. In this particular example, we have attempted to rename our “Homer Simpson” Contact record to “Bart Simpson”:

So, at this stage, there does not appear to be a clear benefit of using one snippet over the other. But what happens if we attempt to access an attribute that does not exist? We can test this by adding the following lines of code to our plugin:

//Next, we test what happens if there is a typo - first, we try GetAttributeValue
string contactField3 = contact.GetAttributeValue<string>("thiswillerror");

//Then, the alternate way
string contactField4 = contact["thiswillerror"].ToString();

When we use our GetAttributeValue approach, our contactField3 returns a null value… :

Whereas our contactField4 instantly causes an error, which would also be returned to the user within CRM…

Where possible, we always want to try and prevent an Exception from being passed back to CRM and build in the appropriate error handling within our code, and this was one of the benefits that my colleague highlighted in this approach. So, for example, you can build in an if…else statement as part of the above example that checks whether the GetAttributeValue is Null and then perform the appropriate action, depending on the result. Having spent time working with the method more closely, I can also now see a clear benefit in relation to code readability - it is definitely more obvious what GetAttributeValue is doing within a code example, compared with the alternative approach, as well as making it obvious what the data type of the attribute is within CRM. Keep in mind however that you still need to ensure that you are using your correct Data Types, both when creating your C# variables and referencing your CRM attributes - for example, you cannot return the contactid field as a string, as this will generate an InvalidCastException.

To finish off, I would invite you to look through this excellent article from Guido Preite, that takes a deep-dive look at the GetAttributeValue method in a variety of different scenarios. Definitely one to save to your bookmarks 🙂

Implementing Tracing in your CRM Plug-ins

Sun, 31 Jul 2016 00:00:00 +0000

The ability to implement trace logging within CRM plug-ins has been around since CRM 2011, so it’s something that CRM developers should be well aware of. Writing to the trace log is useful for when a plug-in has failed or hit an exception, as within the ErrorDetails.txt file (available to download from the error message box window) will be a list of everything that has been written to the log, up to that point. One issue with this is, if a user encounters an error and does not choose to download this file, then this file is lost - not so much of an issue if the exception can be re-produced, but this may not always the case.

For those who are now working on CRM Online 2015 Update 1 or CRM 2016, then a new feature has been added which further expands this feature - the Plug-in Trace Log. Now, plug-in exceptions can be configured to write to a new system entity, containing full details of the exception, that can be accessed at any time in order to support retroactive debugging. The introduction of this feature means now is the best time to start using trace logging within your plugins, if you are not already. This weeks blog post will take a look at the feature in more detail, assessing its pros & cons and providing an example of how it works in practice.

So, before we begin, why you would want to implement tracing in the first place?

Using tracing as part of CRM Online deployments makes sense, given that your options from a debugging point of view are restricted compared to an On-Premise Deployment. It is also, potentially, a lot more straightforward then using the Plug-in Registration Tool to debug your plugins after the event, particularly if you do not have ready access to the SDK or to Visual Studio. Tracing is also useful in providing a degree of debugging from within CRM itself, by posting either your own custom error messages or feeding actual error messages through to the tracing service.

Just remember the following…

Writing to the tracing service does add an extra step that your plug-in has to overcome. Not so much of an issue if your plugin is relatively small, but the longer it gets, and more frequent you are writing to the service, means there is a potential performance impact. You should use your best judgement when writing to the service; not every time you do something within the plugin, but where there is a potential for an error to occur. Writing to the tracing log can also have an impact on your CRM storage capacity, something we will take a look at later on in this post.

Now that we have got that out of the way, lets begin by setting up an example plugin!

To start writing to the Tracing service depends on how you are implementing your plugin. If you have used the Visual Studio template, then simply use this line of code within the “TODO: Implement your custom Plug-In business logic.” section:

ITracingService tracingService = localContext.TracingService;

Otherwise, you will need to ensure that your plugin is calling the IServiceProvider, and then use a slightly longer code snippet to implement the service. An example of the code that you’d need to use to setup this is as follows:

using System;
//Be sure to add references to Microsoft.Xrm.Sdk in order to use this namespace!
using Microsoft.Xrm.Sdk;

namespace MyPluginProject
{
 public class MyPlugin : IPlugin
 {
 public void Execute(IServiceProvider serviceProvider)
 {
 //Extract the tracing service for use in debugging sandboxed plug-ins. 
 ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
 }
 }
}

Once you’ve implemented the ITracingService within your code, you can then write to Trace Log at any time in your code using the following snippet:

tracingService.Trace("Insert your text here...");

Activating Tracing

Even though we have configured our plugin for tracing, this does not automatically mean that our plugin will start writing to the log. First, we must configure the Plug-in and custom workflow activity tracing setting within the System Settings page:

You have three options that you can set:

Off - Nothing will be written to the trace log, even if the plugin encounters an exception.
Exception - When the plugin hits an exception, then a trace will be written to the log.
All - Whenever the plugin is executed and the trace log is called, then a trace log record will be created. This is equivalent to Verbose logging.

As mentioned earlier, individual records will be written to CRM whenever the tracing service is called. It is therefore recommended only to turn on ‘All’ for temporary periods; leaving it on for ‘Exception’ may be useful when attempting to initially diagnose plugin errors. Review the amount of storage available to you on your CRM Online/On-Premise deployment in order to determine the best course of action.

Tracing in Practice

Now that we’ve configured tracing on our CRM and we know how to use the Tracing, lets take a look at an example plugin. The below plugin will be set to fire on the Post-Operation event of the Update message on the Account entity. It will create a new contact record, associate this Contact record to the Account and then populate the Description field on the Contact with some information from the Account record:

protected void ExecutePostAccountUpdate(LocalPluginContext localContext)
{
 if (localContext == null)
 throw new ArgumentNullException("localContext");}

 //Extract the tracing service for use in debugging sandboxed plug-ins.
 ITracingService tracingService = localContext.TracingService;
 tracingService.Trace("Implemented tracing service succesfully!");

 // Obtain the execution context from the service provider.
 IPluginExecutionContext context = localContext.PluginExecutionContext;

 // Get a reference to the Organization service.
 IOrganizationService service = localContext.OrganizationService;

 if (context.InputParameters.Contains("Target"))
 {
 //Confirm that Target is actually an Entity
 if (context.InputParameters["Target"] is Entity)
 {
 Guid contactID;
 string phone;

 Entity account = (Entity)context.InputParameters["Target"];
 tracingService.Trace("Succesfully obtained Account record" + account.Id.ToString());

 try
 {
 tracingService.Trace("Attempting to obtain Phone value...");
 phone = account["telephone1"].ToString();
 }
 catch(Exception error)
 {
 tracingService.Trace("Failed to obtain Phone field. Error Details: " + error.ToString());
 throw new InvalidPluginExecutionException("A problem has occurred. Please press OK to continue using the application.");
 }
 if (phone != "")
 {
 //Build our contact record to create.
 Entity contact = new Entity("contact");
 contact["firstname"] = "Ned";
 contact["lastname"] = "Flanders";
 contact["parentcustomerid"] = new EntityReference("account", account.Id);
 contact["description"] = "Ned's work number is " + phone + ".";
 contactID = service.Create(contact);
 tracingService.Trace("Succesfully created Contact record " + contactID.ToString());
 tracingService.Trace("Done!");
 }
 else
 tracingService.Trace("Phone number was empty, Contact record was not created.");
 }
 }
}

After registering our plugin and with tracing configured for “All” in our CRM instance, we can now see our custom messages are being written to the Trace Log - when we both update the A. Datum Corporation (sample) record Phone field to a new value and when we clear the field value:

Most importantly, we can also see that our test Contact record is being created successfully when we populate the Phone field with data 🙂

Now, to see what happens when an error is invoked, I have modified the code above so that it is expecting a field that doesn’t exist on the Account entity:

Now, when we attempt to update our Account record, we receive a customised Business Process Error message and window:

And we can also see that the precise error message has been written to the trace log, at the point we specified:

Last, but not least, for On-Premise deployments…

One thing to point out is, if you are using On-Premise CRM 2016 (both 8.0 and 8.1), then for some reason the trace log will not work if you do not run you plugin within sandbox isolation mode. I’m not the only one experiencing this, according to this post on the Dynamics CRM Community forum. Switching my test plugin to sandbox isolation resolved this issue. A bit of a strange one, and as Srikanth mentions on the post, it is not clear if this a bug or not.

Conclusions or Wot I Think

Trace logging is one of those things where time and place matter greatly. Implementing them within your code obsessively does not return much benefit, and could actually be detrimental to your CRM deployment. Used prudently and effectively though, they can prove to be incredibly useful. The scenarios where I can see them returning the most benefit is if your plugin is making a call to an external system and, if an error is encountered during this process, you can use the Trace Log to capture and store the external application error message within CRM for further investigation. Trace logging can also prove useful in scenarios where an issue cannot be readily replicated within the system, by outputting error messages and the steps leading up to them within the Trace Log.

In summary, when used in conjunction with other debugging options available to you via the SDK, Trace Logging can be a powerful weapon to add to your arsenal when debugging your code issues in CRM.

Modifying System/Custom Views FetchXML Query in Dynamics CRM

Sun, 06 Mar 2016 00:00:00 +0000

Working with Dynamics CRM can present some interesting challenges. What you tend to find is that you can pretty much say “Yes!” when it comes to doing most things you would expect from a CRM/database system, but there is a learning curve involved in figuring out the best approach to take. Often, as well, you may over-complicate matters and overlook a much easier solution to achieve what you need.

Take, for example, modifying the FetchXML queries in a Public View that you have created programmatically. Let’s say you’ve created your own view within CRM using the following C# code snippet (adapted from the SDK sample):

SavedQuery sq = new SavedQuery
{
 Name = "My New View",
 Description = "My view created in C# for the Account entity",
 ReturnedTypeCode = "account",
 FetchXml = fetchXml,
 LayoutXml = layoutXml,
 QueryType = 0
};

_customViewId = _serviceProxy.Create(sq);
Console.WriteLine("A new view with the name {0} was created.", sq.Name);

A few things to point out first with the above:

In order for this code to work, you would need to declare System.String values for fetchXml and layoutXml, as well as first connecting to CRM using the OrganizationServiceProxy (_serviceProxy).
As well as specifying the FetchXML query you would like to use, you also have to specify a LayoutXML as a parameter in order to. Although Microsoft do have dedicated articles on MSDN that goes over the schema for this, there is a potential learning curve involved here for those who are unfamiliar with working with XML.
ReturnedTypeCode is your entity logical name, which will need changing depending on the entity you are attempting to query
Be sure to add in the appropriate namespace references, otherwise this code will not work.

The code example above is all very well and good if you are just wanting to create a brand new view. But what happens if you need to change it in the future? We can modify the base properties of a view (Name, Description etc.) as well as the column layout via the CRM GUI, but when we attempt to modify the filter criteria (i.e. the FetchXML query), we will notice that the option is not available to use:

The next logical step would therefore be to look at creating some C# code that would take the existing view and modify the fetchXML query property. Unfortunately, Microsoft have not provided code examples on how this can be done, although it is in theory possible via the many methods at your disposal through the SDK.

Rather then spend days and potentially weeks writing a bespoke piece of code to do the job, it was then that I realised that I was being a little dense (as tends to happen) and that the Solution was sitting right in front of me. See what I did there?

Whilst the general rule of thumb is “DON’T DO IT!!” when it comes to modifying an exported solution file, it is possible to do and pretty much anything within a solution file can be changed or modified to suit a particular requirement. And, as luck would have it, modifying Public Views (either ones created by yourself or system ones) is a supported task that you can perform on the solution file:

Definitions of views for entities are included in the customizations.xml file and may be manually edited. The view editor in the application is the most commonly used tool for this purpose. Editing customizations.xml is an alternative method

Source: https://msdn.microsoft.com/en-gb/library/gg328486.aspx

So, in order to modify a custom Public Views FetchXML query, all you would need to do is:

Create a temporary, unmanaged solution file containing the entity with the custom Public View you want to change.
Export as an unmanaged solution, unzip and open the customizations.xml file either in Notepad, Visual Studio or the XML editor program of your choice
Use Ctrl + F to locate the savedquery node of the view you wish to change. It should look like this:

<savedquery>
 <IsCustomizable>1</IsCustomizable>
 <CanBeDeleted>1</CanBeDeleted>
 <isquickfindquery>0</isquickfindquery>
 <isprivate>0</isprivate>
 <isdefault>0</isdefault>
 <returnedtypecode>1</returnedtypecode>
 <savedqueryid>{8e736028-47c7-e511-8107-3863bb345ac8}</savedqueryid>
 <layoutxml>
 <grid name="resultset" object="1" jump="firstname" select="1" preview="1" icon="1">
 <row name="result" id="accountid">
 <cell name="name" width="150" />
 <cell name="statecode" width="150" />
 <cell name="statuscode" width="150" />
 <cell name="ownerid" width="150" />
 <cell name="createdon" width="150" />
 </row>
 </grid>
 </layoutxml>
 <querytype>0</querytype>
 <fetchxml>
 <fetch version='1.0' output-format='xml-platform' mapping='logical' distinct='true'>
 <entity name='account'>
 <attribute name='createdon' />
 <attribute name='statuscode' />
 <attribute name='ownerid' />
 <attribute name='name' />
 <attribute name='statecode' />
 <attribute name='accountid' />
 <order attribute='name' descending='false' />
 <link-entity name='email' from='regardingobjectid' to='accountid' alias='ab' link-type='outer'>
 <attribute name='regardingobjectid' />
 </link-entity>
 <link-entity name='lead' from='parentaccountid' to='accountid' alias='al' link-type='outer'>
 <link-entity name='email' from='regardingobjectid' to='leadid' alias='lp' link-type='outer'>
 <attribute name='regardingobjectid' />
 </link-entity>
 </link-entity>
 <filter type='and'>
 <condition entityname='ab' attribute='regardingobjectid' operator='null' />
 <condition entityname='lp' attribute='regardingobjectid' operator='null' />
 <filter type='or'>
 <condition entityname='ab' attribute='createdon' operator='olderthan-x-weeks' value='1' />
 <condition entityname='ab' attribute='createdon' operator='null' />
 </filter>
 </filter>
 </entity>
 </fetch>
 </fetchxml>
 <IntroducedVersion>1.0</IntroducedVersion>
 <LocalizedNames>
 <LocalizedName description="My New View" languagecode="1033" />
 </LocalizedNames>
 <Descriptions>
 <Description description="My view created in C# for the Account entity" languagecode="1033" />
 </Descriptions>
</savedquery>

Modify the FetchXML query within the node to your updated query
(Optional) If your FetchXML query is simply making changes to the filter criteria, you can skip this step. Otherwise, if you have new fields that you would like to be displayed as part of the changes, you will also need to modify the node so that it contains your new fields.
Save the changes back into the solution file and then import the solution back into CRM.
Test your view by opening it within the application and confirm everything looks OK.

I’m sure you’ll agree that this is definitely a much easier and simple way to make changes to your view. Just be careful when working within the solution file that you don’t accidentally delete/overwrite something!