Dynamics 365 Customer Engagement: Advanced developer Topics

What is Web Resources?

This chapter talks about the basics of web resources - you will learn about web resources, why and where you can utilize web resources in the application.  What are the uses of web resources in customizing  the UI of Dynamics 365.

Embed HTML web resource

There are situations you might need to embed an HTML page(s) on your Dynamics 365 forms, for example if you want to display the content of your legacy static application on Dynamics 365 as you have recently moved to the application. In such situation web resources will come handy.

This chapter includes a practice that will walk through the process of creating an HTML web resource and embedding that on your Dynamics RM form.

For more reference: https://crmbook.powerobjects.com/extending-crm/javascript/html-web-resources/

What is a Web Service?

Web services are self-contained, modular, distributed, dynamic applications that can be described, published, located, or invoked over the network to create products, processes, and supply chains. These applications can be local, distributed, or web-based. Web services are built on top of open standards such as TCP/IP, HTTP, Java, HTML, and XML. 

This chapter is on Dynamics 365 Customer Engagement (CRM) web services and how to use these web services to extend the functionality of the application. The chapter also talks about the different web services available such as OrganizationService, OrganizationDataService, Deployment service, Discovery services and their use.

What is JScript?

Definition: JScript is Microsoft's dialect of the ECMAScript standard that is used in Microsoft's Internet Explorer. JScript is implemented as an Active Scripting engine. In other words it is an updated version of Javascript for Microsoft Dynamics 365/CRM application.  Using Jscript you can implement event handlers for forms on Dynamics 365 so they developers can handle the events using these event handlers.

This chapter going to give a detailed introduction and the basics on JavaScript( JScript) for Dynamics 365 Customer Engagement (CRM), when and where it useful when you try to extend the fucntiona The chapter talks about the areas where you can use JScript functions to customize your application, benefits of using Jscript etc.

What is OnLoad and OnSave events

Basically there are 4 form events on Dynamics 365 forms and form components such as onLoad, OnSave, OnChange and TabStateChange. On these OnLoad and OnSave events are available on the forms and they trigger when the particular form is loaded or saved.

This chapter talks about the basics of form events. Also explains in detail about OnLoad and OnSave events of Dynamics 365 CE forms and how to use JScript functions on these events.

OnChanage and TabStateChange Events

OnChange event is available for every fields of a particular form which trigger when the value of the field is changed. This will trigger when we click on a field and change the value. Developers can develop JScript functions and register on this event so that we can perform operations when the event is triggered.

TabStateChange event on the other hand similar but triggers when the status of the tab changes, when the tab is collapsed and expanded.

This chapter talks about the basics of form events. Explains in detail about OnChanage event on CRM fields and OnTabState event on tabs and how to use JScript functions on these events.

This chapter walk you through the process of how to register JScript functions on CRM form events and event handlers.

This chapter is on Xrm.Page object model which is a framework for Dynamics 365 CRM forms and how to customize it using JScript. The chapter talks about how to utilize Xrm.Page object model to manipulate data, change form object properties, or analyze the current state of the form or data within the form.

This chapter includes a practice where we implement a JScript file from scratch, create a web resource out of it, implement the web resource on Account form and trigger it on the OnLoad/OnSave event of the form.

In this chapter we continue the practice from the previous chapter where we update the JScript function. The function will verify if the phone number is given on Account form, if not then the user cannot simply save the form. The script will cancel the standard behavior of the form ( Save function) if the validation fails.

This lecture talks about the differences coming up in Javascript in Dynamics 365 v9.0.  What are the main namespaces in Javascript is going to change and what are the new ones.

Finally we need to learn about debugging Javascript for Dynamics 365 CE too. Once you have your scripts added for the forms and if your scripts are not working as expected then we need to debug the scripts. Debugging scripts is different for different browsers. In this chapter we talk about debugging scripts on IE, Chrome and firefox.

This chapter is on an intro to Plugin development.  Plugins are custom business logic which can be integrated with  Dynamics 365 server to augment the standard behavior of the platform. In other word plugins are custom event handlers to Dynamics 365 CE events.  We are talking to Dynamics 365 events in a different chapter in detail.

Microsoft Dynamics 365 CE Plugins are one of the most commonly used and powerful approaches to extending the application. A Plugin is a piece of code written and compiled in .Net, that is “triggered” when a specific event takes place within a specified Dynamics 365 CE entity. The objective of custom plug-in code is to enhance or modify the standard features/behavior of Dynamics 365 CE by injecting custom business logic into the execution of nearly any task a user performs in Dynamics 365 CE.

As a Dynamics 365 developer you need to be well versed with Plugin development. The following chapters are going to cover plugin development in details, also on plugin DLL registration using Plugin registration tool, and also debugging on Plugin code once the code is not functioning as it supposed to.

Plugin Event pipeline:

The Microsoft Dynamics 365 CE event processing subsystem executes Plugins based on a message pipeline execution model. A user action in the Microsoft Dynamics 365 CE web application or an SDK method call by a plug-in or other application results in a message being sent to the organization Web service. The message contains business entity information and core operation information.

 The message is passed through the event execution pipeline where it can be read or modified by the platform core operation and any registered plug-ins.

The plugin event execution pipeline allows you to configure when in the event the plug-in code will execute. The event pipeline is divided into the following events:

Pre-Validation
This stage executes before basic the validation ( event before the pre-event happens). Therefore, it is quite possible to trigger a Plugin even without actually having permission to do so.  Also, execution in this stage might not be part of the database transaction.

this step is also called Pre-event event.

Pre-event
This stage executes after validation, but before the changes has been committed to database. This is one of the most commonly used stages. Developers can register one or more Plugins in the Pre-event so that those will trigger before the core-operation in the order given.

This is step is also called Pre-Operation as it happens before Dynamics 365 CE core operations.

Platform Core operation:

This stage is the main stage ( or event) of Dynamics 365 CE system such as Create, Update, Delete, Retrieve etc. These are in-transaction events are are reserved for system and we cannot register any Plugin (or custom code) in this stage.  We talk about the complete list of events of Dynamics 365 CE in chapter 7.

Note: The complete list of events of each of Dynamics 365 CE is given in an spreasheet as part of Dynamics 365 8.2 SDK. Remember in the SDK for Dynamics 365 CE/CRM version 8.2, it is not included in the present version that is Dynamics 365 V9.0.

Post Event:

Once the core event is executed and the result of the operation is updated in Dynamics 365 CE database then the post-event will trigger.  Developers can register one or more Plugins in the Post-event as well so that those will trigger after the core-operation in the order given.

So now we know what is a Plugin and it can do in your Dynamics 365 CE environment. Its time to learn how to develop a Plugin from Scratch.

In this chapter you will learn about the basics of Plugin development step-by-step and in the next chapter you will learn do the practice. The practice is to develop a simple Plugin to create a Task record to followup a customer with a particular deadline when an Account record is created .

Plugin development steps:

1. Create a VS project. Project type ="Class Library"

2. Set plugin class name="FollowupTaskPlugin' by copying the code from SDK/SampleCode folder from Dynamics 365 SDK 8.2

3. Add the references from Dynamics 365 SDK 9.0

4. Sign the assembly

5. Set the correct dot Net framework

6. Build the assembly

Plugin development in detailed steps:

1. Create a visual studio project. Select the language = Visual C#, Project Type = Class Library

2. Refer assemblies from Dynamics 365 SDK 9.0

  2.1. Microsoft.Xrm.Sdk.dll

  2.2. Microsoft.Crm.sdk.proxy.dll

  2.3. System.ServiceModel.dll

  2.4. System.Runtime.Serialization

3. Add references into the project ( SDK for V9.0).

4. Set the properties for the .net project. set .NET version = 4.5.2 or above, Verify Assembly name

5. Sign the assembly. Create a key file name ="KeyFile" or something like that, set password for the key if needed.

6. Build the DLL by clicking 'build' in the ribbon and check if the build status = succeeded.

7. Verify if DLL and PDB files are created in the bin\debug folder of the VS project.

Develop a Plugin to create a Task to followup with a customer when an Account is created. 

This chapter explains you how to develop  this particular Plugin line-by-line.  The code is basically taken from SDK for Dynamics 365 CRM 8.2 ( look for folder 'SampleCode\CS\Plulgins'). 

Here also talk about the elements used in writing the Plugin:

1. IServiceProvider

2. IPluginExecutionContext

3. IOrganizationService and IOrganizationServiceFactory

4. InvalidPluginExecutionException

5. ITracingService

6. Input and Output Parameters

1. The IServiceProvider parameter of Execute method is a container for several service useful objects contains instance references to execution context, IOrganizationServiceFactory, ITracingService, and more.

2. IPluginExecutionContext contains information that describes the run-time environment that  Plugin executes, information related to the execution pipeline, and entity business information. The context is contained in the System.IServiceProvider parameter that is passed at run time to a plug-in through its Execute method.

//IPluginExecutionContext context = (IPluginExecutionContext)

//serviceProvider.GetService(typeof(IPluginExecutionContext));

3. IOrganization service and IOrganizationServiceFactory

To access Dynamics 365 CE organization service, it is required that plug-in code create an instance of the service through the ServiceProvider.GetService method.

// Obtain the organization service reference.

IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));

IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

4.InvalidPluginExecutionException

As the name indicates its the exception that Plugin throws which can be used to interrupt the Plugin execution. It basically does two jobs: one is the exception of the Plugin and the second is showing a 'Business Process Error' once the exception is happened.

We normally throw InvalidPluginExecutionException when any connection or fatal error happens during Plugin execution.

Example:

//  Here we use InvalidPluginExecutionException to show the that Plugin connect to Dynamics 365 server

catch (FaultException<OrganizationServiceFault> ex)

{

throw new InvalidPluginExecutionException("Error in connecting to the Dynamics 365 Server.", ex);

}

5. ITracingService

ITracingService helps to debug "sandboxed" plug-ins. If you are not registering the plug-in in the sandbox, then you do not have to add any tracing service related code. Using this service you can log your Plugin activities before or after important actions so that they can verified during testing and debugging.

ITracingService tracingService =

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

7. Input and Output Parameters

The InputParameters contains the data that is in the request message which is being passed to the event execution pipeline. Your plug-in code can access this data. Its one of the parameters in the IPluginExeuctionContext. 

// The InputParameters collection contains all the data passed in the message request.

if (context.InputParameters.Contains("Target") &amp;&amp;

context.InputParameters["Target"] is Entity)

{

// Obtain the target entity from the input parameters.

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

OutputParameters contains  data that is in the response message, that is the data processed by the Dynamics 365 CE event. However, only synchronous post-event and asynchronous registered plug-ins have OutputParameters populated as a result of the core platform operation. The property is of type ParameterCollection where the keys to access the response data are the names of the actual public properties in the response.

Build your Plugin Assembly.

Once Plugin code is developed you have to build an Assembly or Dynamics Linking Library ( DLL) from your code. This is the very reason we set the project type as "Class Library" while we created the Visual studio project.  Once the DLL is built then it can be registered with your Dynamics 365 server to trigger as an event handler.

Build the plugin DLL involves steps:

1. Sign the assembly. Create a key file, set password if needed.

2.  Set the name of the Assembly.  By default it will be name of the namespace of VS project.

4..  Build the DLL by clicking 'build' in the ribbon and check if the build status = succeeded.

5. Go to your Visual Studio project folder and find the DLL in folder ..\bin\debug or ..\bin\release\ depends on the mode that you set in Visual Studio.

When you build your Plugin DLL you basically get two files generated, one is your DLL( Assembly ) itself and the second is a PDB file ( Program Database) that helps you for d your debug Plugin assemblies on Dynamics 365 on-Premise version.

We talk about Debugging Plugins in detail in Section 6 of this course.

Once your Plugin assembly is created you have to register the same with your Dynamics 365 CE Server.  This can be done in different ways - using Solutions as well as using Plugin Registration tool. 

Plug-in registration tool:

Plugin registration tool is a UI based tool which can be used to register your Plugin and custom workflow activity Assemblies( DLLs) with Dynamics 365 CE server. This tool is free and can be downloaded as part of Software Development Kit( SDK) of Dynamics 365.

This chapter is going to give a beginner level understanding of Plugin Registration tool for Dynamics 365.

What you mean by register your plugin?

Plug-ins and custom workflow activities are custom code that you develop to extend the existing functionality of Microsoft Dynamics 365 CE. Before a plug-in or custom workflow activity can be used, it must be registered with the server.     

Once your Plugin Dynamics Linking Library ( DLL) is built you have to register with your Dynamics 365 server to trigger for the events.   Plug-ins can be registered to execute before or after the core platform operation. 

Register your Plugin Assembly:  

Because a single Microsoft Dynamics 365 CE server can host more than one organization, the execution pipeline is organization specific. There is a virtual pipeline for every organization. Plug-ins registered with the pipeline can only process business data for a single organization. A plug-in that is designed to work with multiple organizations must be registered with each organization's execution pipeline.

Plugin registration involves two steps:

1. Register Plugin assembly

2. Register Plugin step.

This chapter is going to talk about the process of registering your Plugin assembly with Dynamics 365 CE server. Once the assembly it can be registered again different system events, that is the topic for the next chapter.

Register a Plugin Step:

Once the Plugin DLL is registered it can be executed before or after of any Dynamics 365 CE event. To achieve that we have the register the "plugin step" or in other words registering the plugin to execute for a particular event. Plugin step can be registered using the same Plugin registration tool that we used to register the plugin Assembly.

This chapter will walk you through process of registering a Plugin step and all the sub-steps involved in the process. We also  demonstrate registering the Plugin that we developed in the last section ( ie; 'Followup Plugin') on the Post-event of Account Create.

What is the basic usage of Plugin Registration tool:

We have see that Plugin registration tool is primarily used for registering Plugin and Custom Workflow Activities. In addition to this, the tool can also be used for many other purposes:

1. Debugging Plugin registered with Dynamics 365 CE online

2. Register Plugin entity images

3.  Un-register Plugin assemblies and Plugin steps

4.  Update assemblies

5. Organize assemblies as per Assembly, Entity or Messages.

This chapter  demonstrate you what are the more options that Plugin Registration Tool to offer to a developer to help in the job.

How to a Plugin?

So that now we have registered the Plugin assembly, it is time to test the functionality of the Plugin. We registered the plugin on Post-event of Account create.

To test the plugin that we developed, we have to do the following:

1. Login to Dynamics 365 CE

2. Navigate to Sales - >  Account.

3. Create a new Account record by clicking the '+' new button.

4. Navigate to the 'Activities' ares from the navigation ( or on the personal wall of Account form).

5. Verify if a Task record is created for the Account record.

Update a Plugin Assembly and steps

Once a Plugin assembly is registered we often need to update the logic later or just need to fix an error in the code. Or an upgrade in the business process is required after many years.

Whatever be the reason, we have to update the Plugin Assembly which is a tricky task I would say. While we update the plugin we shouldn't try to un-register and then re-register the Plugin assembly, that is the not process. If you do un-register a Plugin it will delete the Plugin as well as its Plugin steps, and the Plugin steps are difficult to remember to recreate. This will create a serious damage to your business as many functionality of the application is not running or corrupted. The situation will be even more painful if you dont have a proper release note( documentation) in place for your Plugin assembly deployment.

Like Plugin assembly, Plugin steps can be updated too. For example, if you want to update the triggering criteria for  'Followup Plugin' from Account create to Account update, then we just need to update the plugin step,  not the entire plugin assembly.

Steps to update plugin step:

1. Open plugin registration tool. Connect to Dynamics 365 CE Server.

2. Navigate to the assembly that you want to update.

3. Select the plugin from assembly, and then select the plugin step.

4. On the ribbon click update, that will open up the Plugin step window.

5. Update Plugin step details like triggering criteria, secure/un-secure configuration etc.