Integrating Umbraco CMS with Microsoft Dynamics 365 - Marketing Forms

In July we announced a strategic partnership with Microsoft to extend the reach of the easy-to-use, flexible and open-source content management system built on Microsoft .NET. This new collaboration will provide all the tools necessary for Umbraco to boost its position in Microsoft’s Azure Marketplace, an online marketplace that comprises thousands of IT software apps and services for building new solutions and managing cloud infrastructures.

“Microsoft's secure, stable and scalable Azure cloud, and its extensive online marketplace, will enable even more companies to take advantage of our composable DXP designed around our user-friendly and highly flexible CMS, As a result, they can configure their digital experiences across their digital platforms just the way they want, creating their preferred tech stack without any limitations. We look forward to seeing new success cases enabled through this new partnership—and go to market together with Microsoft.” - Jesper Lyngbye, Technology Partner Manager

You can read more about the topic in this article published by Martech.

If you’ve followed along with our releases, you might have crossed paths with a similar integration built for HubSpot Forms, a key component of the Marketing Hub from HubSpot, for managing marketing tasks and allowing your team to dedicate time to generating inbound marketing campaigns and getting more leads. This blog post provides insight into the HubSpot ecosystem integration.
If you happen to use this already, we have an integration you might find useful, one that provides a form picker and a rendering component for marketing forms managed within your own Microsoft Dynamics 365 instance.

Dynamics 365 Overview

Microsoft Dynamics is specifically designed for customer engagement, offering a combined Customer Relationship Management (CRM) - Enterprise Resource Planning (ERP) solution product. Instead of having separate functions, you are provided with an automated, integrated, and intelligent solution to efficiently connect, prioritize and convert leads into paying customers. 

Dynamics 365 is consistent in four main areas:

1. Purpose-built apps for each business area
2. Adaptable and extendable solutions
3. Embedded intelligence that supports daily work
4. Productive use on all devices and with other Microsoft products.

If you want to read more about Dynamics, please check out their official website. The values of Dynamics 365 have also been recognized by industry experts, as you can see here.

Working with Dynamics 365 for Marketing Forms

Dynamics 365 for Marketing is the first dedicated marketing solution in Dynamics' history. Dynamics 365 Marketing makes it possible to orchestrate personalized journeys across all touchpoints to strengthen relationships and earn loyalty. The Dynamics 365 Marketing app works with Dynamic 365 Sales, Customer Insights, Microsoft Teams, and other products.

Read more about the two modules here:

• https://docs.microsoft.com/en-us/dynamics365/marketing/real-time-marketing-user-guide
• https://docs.microsoft.com/en-us/dynamics365/marketing/user-guide

A marketing form defines a set of input fields arranged into a form layout. To add a marketing form to a specific marketing page, you will need to use a form element to position the form and choose local settings for it, which apply to that page only. Read more about that here:
https://docs.microsoft.com/en-us/dynamics365/marketing/marketing-forms 

There are three different licenses the base license, additional instances, and additional capacity.  Read more about them here: Dynamics 365 Marketing pricing page

Integrating with Umbraco CMS

The new integration focuses on embedding Dynamics 365 Marketing Forms into an Umbraco web page, by providing a custom product picker and a rendering component. It comes complete with a strongly typed model and the necessary form properties for rendering the form using an iframe or custom JS scripts.

But before actually selecting a Dynamics form, there are a couple of steps that need to be followed, to ensure the form is accessible externally, and you can embed it. There are two important requirements to be met before being able to embed a form: publish the form to a Live status and host it within an authorized domain. A detailed step-by-step guide is available here.

Setup and Authorization

Access control to your instance of Dynamics 365 is managed by two pillars from Umbraco:

• One is the Umbraco Integrations Azure App registered within the Microsoft Identity platform,
• The second one is the 0Auth Proxy for Umbraco Integrations which is Umbraco’s custom solution for managing 0Auth-based access to different APIs. You can read more about it through this blog post.

The Microsoft Identity Platform is an authentication service, open-source libraries, and application management tools. You can create modern, standards-based authentication solutions, access and protect APIs, and add sign-in for your users and customers. You can learn more about it by going through this documentation.

To access the API, you will need to retrieve the HTTP REST API details of your Dynamics 365 instance following these steps:

• Go to your Dynamics 365 Marketing portal and choose Advanced Settings

• From the settings interface select Customizations, then Developer Settings

In the Developer Resources interface, search for the section Connect your apps to this instance of Dynamics 365.

In this section you will find your instance Web API URL which will have this format:    

https://[INSTANCE].api.crm4.dynamics.com/api/data/v9.2/

This value will be split in two and stored in the settings file of your website, no matter whether it’s an Umbraco 8, 9, or 10 website:

• HostUrl → https://[INSTANCE].api.crm4.dynamics.com/
• ApiPath → api/data/v9.2/

Working with the Property Editor

If you’ve reached this section and the package has been installed, then it means you’re ready to start working with the property editor.

Firstly, start by registering the data type in the Backoffice:

In the configuration section, you will be able to connect using your Microsoft account. Differently from previous integrations that used the 0Auth protocol, this one required a custom database table, due to the length of the access token that couldn’t be stored in the normal umbracoKeyValue table. The new table called dynamicsOAuthConfiguration will store the access token, as well as the ID and Full Name of the user who authenticated.

If you have used one of the similar packages from HubSpot or Shopify, you will notice a significant difference in the property editor - the inclusion of a custom directive for handling authorization directly from the property editor:

This came up following an update to the HubSpot CMS package, where Frans de Jong mentioned that editors working with the property editor could experience issues accessing the API because, due to their permissions, they would not have access to the authorization area present initially in the data type.

After connecting with your account, the list of forms from Dynamics 365 will be populated:

After selecting your form, you can select how you want it to be embedded, either as an iframe or through the JS script.

To render the form you will need to add this namespace

@using Umbraco.Cms.Integrations.Crm.Dynamics.Helpers;

Then use the helper method to display the form

@Html.RenderDynamicsForm(Model.MsDynForm)

The helper method allows the developer to specify a view of its own, in case somebody will be interested in using a different code for embedding.

Conclusions

On a final note, the integration is open-sourced and the current release targets Umbraco versions 8,  9, and 10.

A minimum set of requirements for the CMS would be:

• Umbraco CMS version 8.4.0 or
• Umbraco CMS version 9.0.1 or
• Umbraco CMS version 10.1.0

If you want to see it in action, you can reference and use the integration in your own project, as the project is available both on NuGet and on the package page on Our Umbraco.

The full source code is open-sourced on GitHub , and you are more than welcome to submit PRs or respond to issues.