In this article we would like to show how to kick start a custom ReactJS UI implementation within Dynamics 365 Customer Engagement using an existing ReactJS template.
- Dynamics 365 Central
- Dynamics 365 Certification
- Dynamics 365 Center Of Excellence
- Dynamics 365 Security Group
- Dynamics 365 Ce Sla
Microsoft Dynamics 365 Customer Engagement (CE) (formerly known as Microsoft Dynamics 365 Customer Relationship Management – CRM) is designed to help you manage your client relationships by streamlining your processes, centralizing client information, providing analysis, and enabling responsive customer service. What is Dynamics 365? It’s how you become more agile to delight your customers. With Dynamics 365, you’ll have the only portfolio of intelligent business applications that empowers everyone to deliver operational excellence and create more engaging customer experiences.
In a nutshell
At PowerObjects, our consultants are 100% dedicated to Dynamics 365 and Microsoft Business Applications. In this blog, we would like to highlight a lesson learned from a project when we used Dynamics 365 Customer Engagement (CE) online data source connector, called Instance Web API, for Power BI reports. Business Central. Business Central is the end-to-end business management cloud solution for small and medium-sized businesses. Aug 20, 2019 The Create Quote PDF capability and the option to enable PDF generation was introduced in version 9.0.1905.2010 of Dynamics 365 CE. It can be enabled in the App Settings of the Sales Hub and it will add two buttons to the ribbon of the Quote form: ‘Create PDF’ and ‘Email as PDF’ of a selected Word template.
We licensed the Light Bootstrap Dashboard PRO React Template by Creative Tim for our customer and integrated the template into Dynamics 365 CE to develop a custom UI upon that using Web Resources (IFRAME). In this post we’d like to show the first steps how to get started and set that up.
Background
The user interface of Dynamics 365 CE improves steadily. Especially with the release of the Unified Interface. Nevertheless, there are moments when you encounter the limits of the Dynamics 365 CE UI capabilities and you need to think about different means how to provide great usability. One of the means, is the now available possibility to develop custom Canvas Apps. Another one is the future possibility of the Custom Control Framework (which is not yet available, but will be soon). In the meantime, the best option to provide a custom user interface within Dynamics 365 CE is a custom UI implementation using frameworks like ReactJS or Angular. For both options we have implemented several implementations. For ReactJS we would hereby like to provide a simple guide how to get that started.
Hosting of the UI
For every custom implementation of a web interface you have to think about hosting. Using SPA (single page application) design you have to worry about two different questions:
- A server that provides download of the HTML and JavaScript files
- A back-end to provide an API that exposes the data
Regarding the hosting of your client side resources (HTML, CSS, JavaScript, images) in combination with Dynamics 365 CE exist basically the following two options:
- Using Dynamics 365 CE as your host (meaning you deploy the HTML, CSS, images and JavaScripts as Web Resources to Dynamics 365 CE)
- Hosting your HTML and Web Resources on a custom server (e.g. a custom .NET Web App that is hosted on Azure or on premise within IIS). You’d like to do that when your user interface should be also available outside of Dynamics 365 CE.
Regarding the back-end you could:
- Use the web api of Dynamics 365 CE (if you access Dynamics 365 CE data only) and expose custom actions (also exposed over the web api)
- Additionally expose a custom API using .NET Web API hosted on Azure for example (secured e.g. with OAUTH2 using Azure AD and ADAL.js on client side)
In this article we would like to focus on the ReactJS part. Due to this we will show how to host ReactJS as Web Resource within Dynamics 365 CE (you could then use Xrm Tooling to access the Dynamics 365 Web Api from within the ReactJS application). In a future post we will show to put ADAL.js on top of it to handle authentication against a custom .NET Web API using OAUTH2.
Getting started
After licensing the template and downloading and extracting it you should end up with a folder structure as following:
First thing to mention here is that the template we chose was created with one of the most popular starter kits, the Create React App starter kit.
Looking at the package.json you’ll see that it looks quite simple. Well, that’s actually why the Create React App starter kit is so popular. Most of the logic is handled actually within the react-scripts and is not visible for the developer. If you want to see the details, you could create a copy and eject to see the details. We would recommend that only on a copy, since it’s a one way action where you cannot get back (except with the help of source control and undo). Ejecting from the simple version of the Create React App starter kit should be the last option if you really cannot handle something . In this guide we will not eject and stay on the simple version that uses react-scripts.
To run the ReactJS app you will need to install NodeJS and Python (add python executable to path or check it in the installer). Afterwards run the following script to install the necessary modules.
If you encounter problems during installation, have a look here and here.
Having the dependencies downloaded and installed, you can start the app:
This will start the webpack server and should bring up the following browser window with the following url: http://localhost:3000/#/dashboard
Integration into Dynamics 365 CE
When working locally, npm run start will start the webpack server and this will serve the files from memory. For deploying the first draft of the template to Dynamics 365 CE we first need to generate the build files so we can then try to upload them to Dynamics as web resource. To do that, execute the following command:
This will generate bundled and minified JavaScript and CSS files as well as media file in the folder build/static.
- buildindex.html
- buildstaticjsmain.fd363da8.js
- buildstaticjsmain.fd363da8.js.map
- buildstaticmediaPe–icon–7–stroke.01798bc1.ttf
- buildstaticmediaPe–icon–7–stroke.b38ef310.woff
- buildstaticcssmain.1cfbe954.css
- buildstaticcssmain.1cfbe954.css.map
Challenges
Looking at the generated files you might notice that a random build number is used for the output files. Moreover some icon files are used, where we currently will only handle the Pe-icon-7 files as an example.
To upload those files to Dynamics 365 CE we would actually need something more or less in the form of the following (depending on the tooling). In our case, we are using Microsoft Dynamics 365 Developer Toolkit at this customer. You could also upload your resources using spkl as we do at other projects. “pre” represents some prefix for your solution publisher. Depending on your tooling you could replace the “_” with “” and a folder structure (we do so in Visual Studio in the properties of the files, see below). Please note that for some files we had to add the the extension “.js” or “.css“. To upload those files we have to trick Dynamics and make it think it was actually a .js or .css file. Furthermore look closely, that for the Pe-icon-7 files we had to replace “–” with “_“. All due to some Dynamics 365 CE requirements for the file names that are allowed for web resources and that can be uploaded.
- WebResourcesWeb Page (HTML)pre_sample_index.html
- WebResourcesScript (JScript)pre_sample_static_js_bundle.js
- WebResourcesScript (JScript)pre_sample_static_js_bundle.js.map.js
- WebResourcesScript (JScript)pre_sample_static_media_Pe_icon_7_stroke.01798bc1.ttf.js
- WebResourcesScript (JScript)pre_sample_static_media_Pe_icon_7_stroke.b38ef310.woff.js
- WebResourcesStyle Sheet (CSS)pre_sample_static_css_styles.css
- WebResourcesStyle Sheet (CSS)pre_sample_static_css_styles.css.map.css
Using the Microsoft Dynamics 365 Developer Toolkit the files are then represented as following to form a nice folder structure within Dynamics 365 CE:
So the challenges are:
- a random build number that makes deployment to a web resource tricky
- the generated .js file and .css file contain references to the corresponding .map files (to see that open the files and look at the end of the file) also containing the random build number
- we have to change the file extension to be able to upload the resources to Dynamics 365 CE (at least when we do it manually)
- The file name of the icon files would need to be changed, so also the references to those files within the icon font .css file
The missing link
Looking at what the Create React App currently provides and what we would actually need, a simple script would be great that would take care of those transformations. And that is actually what we provide here by first changing the package.json the following way:
For the build command, we added the execution of our own scrips after the build, that first process the output files (processBuildFilesForDeployment) and then copy over the processed files to the WebResources folder that we use for deployment to Dynamics 365 CE. Let’s have a closer look to this custom processBuildFilesForDeployment.js then.
The code above takes care of the following
- changing source map references within the bundled .js and .css file
- renaming the bundled .js and .css files to get rid of the random build number
- adding the necessary file endings that we need for upload to Dynamics 365 CE
- Changing the reference for the icon files since in the file name we replaced ‘-‘ with ‘_’
In the scripts “copyJSFiles” and “copyCSSFiles” within the package.json we copy over the resulting files. Since the icons files (Pe-icon-7) do not change very frequently we just copy them over into the Web Resources folder once manually and rename them to “Pe_icon_7“.
Entry point
Dynamics 365 Central
The part missing until now is the index.html. For this we also just create a static version within the Web Resources folder (that is not copied over automatically). We took the index.html from ReactJS as a reference and then we changed the references to the .css and .js files. The outcome looks similar to this (simplified version):
Putting it all together
- Execute “npm run start” to start the local webpack server for development
- Upload at least the index.html as web resource once, so you can include it as a web resource (IFRAME) on some form
- Use Fiddler and AutoResponder for local development (this redirects your browser requests that would normally be served by the Dynamics 365 CE server to your local webpack server). This way you can open Dynamics 365 CE user interface, which will load the form, but then the IFRAME contents (so your ReactJS App) is served from your local development server. Since for the browser it appears as if the files were served by the Dynamics 365 CE server, you can even access the Dynamics 365 CE Web Api without any authentication (since cookies are automatically passed, as for the browser it appears as the Dynamics domain)
- When you are done, execute “npm run build“. This will create the minified bundles. Source map references will be exchanged, font icon file references changed, files renamed and copied over to the Web Resources folder.
- Then deploy and publish the just built bundled and minified files to the Dynamics 365 CE server
The rest is then ReactJS web development and design, accessing probably the Dynamics 365 CE Web Api or some custom REST Api to retrieve some data, transform it and present it nicely.
Summary
We showed how to use a ReactJS template (one that is implemented by means of the Create React App starter kit) and how to modify it just a little bit to make it Dynamics 365 CE Web Resource deployment ready. This way no manual modification is anymore necessary and the development and build process is actually quite smooth and time saving. Starting with the licensing of an existing template saves lot of manual design and coding time.
In this post we would like to discuss, whether Dynamics 365 CE can be used and connected to an online shop and Navision as a microservice. We think it can and we would like to present an example, how we were able to leverage Dynamics 365 CE Online as validation service (a lightweight master data management service – MDM) using Azure Service Bus.
Microservices
Concerning the explication of microservices we would like to refer to the description of Martin Fowler which can be found here. For the German speaking audience we would recommend the following talk of Rainer Stropek at the Vienna Tech Conference about Cloud Native and microservices.
The key attributes of microservices we refer to are:
- loosely coupled services/components
- organized around business capabilities
- smart endpoints and dumb pipes
- decentralized data management
Requirements
The customer approached us with the need to upgrade MS CRM 2011, move it to the cloud, and connect it to a custom shop implementation as well as to Microsoft Navision (NAV) (on premise – upgraded as well). One of the most challenging requirements for the new system architecture was to connect those services but to send only validated data to Navision (for billing and order processing).
Solution in a nutshell
The new system architecture, that we recommended, was built upon the usage of Azure Service Bus as messaging bus for decoupling the systems (CRM, Shop, ERP, and future systems to be connected). Dynamics 365 CE for Sales (formerly known as Microsoft Dynamics Customer Relationship Management – MS CRM) was set up for managing master data and to handle the validation of data before being sent to Navision for billing. Data responsibility for master data is split, and lies in Dynamics 365 (if no customer yet) or in Navision (if already customer). During the first order processing the responsibility is handed over from CRM to NAV. CRM always distributes data changes (no matter if caused by the customer in the self service portal in the shop, in Navision or in CRM), hence it serves as a lightweight MDM service. If the customer changes data in the online shop, it’s not directly sent to Navision, but first has to be validated in CRM. Purchases in the online shop are furthermore either sent directly to Navision (if the customer is validated) or kept in CRM and delayed until a successful validation, if a data change is pending and the customer’s data is currently not valid.
Why Azure Service Bus?
Azure Services Bus is easy to set up and Dynamics 365 CE comes with an integration out of the box (Azure-Aware out of the box (OOB) plugin). For the basic idea have a look here. Using the plugin registration tool it’s possible to register a service endpoint.
Having registered the endpoint it is very similar to registering a plugin. Just define the event and entity and use it asynchronous. The reason why it is called out of the box (OOB) plugin is, because you do not have to code anything. The azure aware out of the box plugin is already shipped with Dynamics 365 and it makes it quite easy to pass the execution context onto Azure Service Bus. For every event that now triggers on the defined event, a message will be sent to the queue/topic that you used in the registration of the service endpoint above. Of course you need to create the queue/topic in Azure beforehand and pass the SAS key above. This we will describe in a separate blog post where we focus on the technical part only.
We chose Azure Service Bus in our projects for several reasons:
- loosely coupling of systems
- asynchronous communication -> less impacts on other systems on deployments, upgrades
- systems can be more easily replaced with solutions of other providers
- hiding implementation details -> other systems do not need to know anything about the Dynamics 365 APIs
- fairly easy to connect new systems -> creating new subscriptions and resend messages for existing data
- AMQP standard -> makes it easy to switch to another messaging bus provider if necessary
- low cost for set up -> platform as a service (PAAS)
Dynamics 365 Certification
The main advantage of Azure Service Bus over other messaging bus providers is the out of the box integration with Dynamics 365 CE. Furthermore the Azure Service Bus is no full blown Enterprise Service Bus. Experience in many projects over the last 10 years has shown that usage of an Enterprise Service Bus (with orchestration, transformation, etc.) often results in a very difficult set up for those projects since this part of the projects tends to become the most complex one where lots of integration problems have to be solved by only one team. This is why it’s one of the principles of the microservices architecture (smart endpoints and dumb pipes). Of course any other messaging technology (Apache MQ, IBM MQ, Amazon SQS, etc.) will do its job quite as good (apart from the integration to Dynamics 365).
Decoupling Shop and Navision – Registration
The above graphic shows the registration process of a new customer in the custom online shop. It consists of:
- Registration in the online shop and sending a message to Dynamics 365 CE. This is done in the topic “masterData_fromWeb”.
- Dynamics 365 CE receives the message and sends on its own a message on the topic “masterData”. This is done because Dynamics 365 serves as master data service and Navision only excepts messages from Dynamics 365. Same is true for the online shop.
The message in 2) during the registration is basically the same as sent by the shop, except for the customer number which is generated within CRM (another microserivce CRM provides here). But the important thing to note here is, that it does not have to be, since we decoupled it. When a new customer is registered it is in an invalid state and although sent to Navision, it cannot be used for billing there yet. In case a new customer is entered directly within CRM, only 2) would be sent and the online shop would be informed about the new account.
Upon data manipulation by the customer in online shop the messages 1) and 2) are sent. If data is changed by a CRM user then only 2) will take effect.
The validation of the account data can now happen at this stage within CRM, but probably won’t, since the customer did not buy anything yet, so no need to take the effort of validation.
Decoupling Shop and Navision – Purchase in Online Shop
Upon a customer ordering a product in the online shop, the following steps happen:
Dynamics 365 Center Of Excellence
- Online Shop sends a message in the topic “webPurchase” to Dynamics 365 CE. Navision does not listen onto this message – so no subscription existing for NAV (again for decoupling purposes).
- Dynamics 365 receives the web purchase and proceeds depending on the validation status of the account.
- if valid, the web purchase is directly forwarded to Navision and the process continues below at 3). In the background an opportunity record is created with Dynamics 365 CE (see below) that contains the order details. Communication here happens directly using SOAP service (see below for the reason).
- if not valid, the web purchase is not directly forwarded to Navision. An opportunity is created in Dynamics 365 CE that holds the detail of the online shop purchase. Dynamics 365 CE queues and activities are used to inform the CRM validation team that a validation is necessary, since a web purchase is pending validation for being executed and being billed. This validation step can here take some minutes or hours. Since the process is decoupled, the customer in the shop will not notice anything about this validation process.
- Upon receiving the first web purchase of a customer, Navision takes over data responsibility. To do this, a synchronous REST call from Navision to Dynamics 365 CE is executed, which locks the fields in CRM. This is done synchronously, since it is important that data responsibility handover actually worked.
- Navision sends an order message in the topic “orders” to inform Dynamics 365 of the processed / billed order, which Dynamics 365 can use to close the opportunity and to store further details that then can be used in segmentation for marketing.
Dynamics 365 Security Group
Sending the web purchase from Dynamics 365 CE to Navision is not implemented via the Azure Service bus and asynchronous messaging but with a synchronous SOAP call. The reason is, that in the manual process of creating a quotation, the CRM user is waiting in the CRM user interface and this step needs to be fast and needs immediate response from Navision to provide feedback to the user and open the Navision URL to the just created quote in NAV. The same SOAP call is called automatically in the background when an online purchase occurs and the customer account is already validated.
Opportunities in CRM / Quotes in NAV
Using the Dynamics 365 CE business process and JavaScript it was quite easy to trigger the SOAP call from within the business process stage change (details upon that following in a future post). In this SOAP call, executed from a custom workflow activity, Navision returns the URL and ID of the quote in NAV. The URL is then opened in a new tab and the CRM user can continue in Navision to fill in the products to offer, etc. The same process is used for online purchases where the validation was still pending and the web purchases could not be automatically forwarded to Navision.
Dynamics 365 Ce Sla
Data responsibility handover to NAV
As mentioned above Buy Acimox Amoxil , data responsibility is handed over to NAV, once a customer becomes a debtor. The fields in CRM are then locked and data required for billing can be changed in NAV only. Since not all CRM users have access to NAV and only accounting team is allowed to change billing critical master data, writable fields are provided where CRM users can enter their changes (see below the writable fields on the right – where CRM users can enter change “wishes” – and the locked fields to the left that can only be changed in NAV). Upon entering change wishes the account loses validation status and the validation team gets informed using CRM workflows, queues and activities. The same is true if the customer wants to change its data in the online shop. Also in this case the data is actually written into the change fields and validation status is lost.
Changing the data in NAV, the process looks as following:
- Navision sends message with the changed master data in the topic “masterData_fromNav”
- Dynamics 365 updates the values in the locked fields and spreads message to shop and back to Navision using the topic “masterData”
Advantages of the chosen solution
- Only validated account data is used for billing
- Navision holds those accounts for billing as debtors that it really needs (not all accounts of Dynamics 365 CE)
- Upon data changes by the customer in the online shop, validation status is lost again, and further web purchases have to wait until the data change request (validation) is done before the order processing proceeds
- Exact same process flow for manual quotes and online web purchases (which anyway just represent already accepted quotes). For the CRM users and the validation team it makes no difference. Only difference is the entry point into the process (online shop or CRM).
Conclusion
In the above mentioned solution we accomplished to decouple the web shop and Navision by using Dynamics 365 CE as validation service (a lightweight MDM). By choosing Azure Service Bus we fulfilled the principles of loosely coupling and the smart endpoints and dumb pipes. Dynamics 365 CE has been chosen for the validation, since it can serve that well with its workflow engine, hence fulfilling organized around business capabilities. Concerning decentralized data management CRM does a good job as well, when we see it in the context of the entire system architecture, where every service (shop, CRM, ERP) works upon its own data store.
Nevertheless, obvious, here we have to mention that CRM will comprise much more services (marketing, service, email sending, etc.) which are working on the same data set within Dynamics 365 CE and where those micro/macroservices share the same environment. So if we would look at Dynamics 365 CE like this, then it would not fulfill the principles of microservices. Having a look onto the future of Dynamics 365 CE Online and especially the use of the Common Data Service (CDS) CRM would never be able to be a microservice where all the services are decoupled. Nevertheless, we would like to emphasize that it still makes sense to thrive towards this goal, even though some services share the same data. No matter if it’s then a real microservice or if it’s more like service oriented architecture (SOA), it does not matter as long as we are able to benefit from some of the advantages of that type of architecture. And the benefits can be clearly seen by the customer and us, since lately we were able to connect a fourth system easily by setting up new subscriptions and using Logic Apps to handle the messages and save them to the new application. This we will then describe in a future post. Moreover in one of the next posts we will show more of the technical details concerning this set up, since this post was meant to describe the general architecture.