Custom Microsoft Dynamics CRM Messaging Integration

 

Editor’s note: The following post was written by Dynamics CRM MVP Ramon Tebar

Custom Microsoft Dynamics CRM Messaging Integration

Messaging integrations are very common in enterprise deployments, where reliability and scalability are highly demanded. This article describes how to implement a simple custom messaging solution in Microsoft Dynamics CRM using the standard development components of this platform. The source code of this article can be found in the next Codeplex project:

https://dyncrmmessagingintegration.codeplex.com/

Architecture Overview

As our initial technical requirement, we have assumed that the Microsoft Dynamics CRM application needs to send the new customers to “System X” and “System X” is going to send the new competitors to CRM.

These operations have been implemented with the XML messages “NewCustomer” and “NewCompetitor” , see below the schema definition (XSD).

Between CRM and “System X”, we assume there would be another system which acts as the channel to transport these messages. This articles doesn’t cover the details of how this middle tier should be implemented, since we could write a book only about that. Ideally, I would recommend a message queue platform.

With those elements in mind, we have the next picture:

 

Messages definition (see “IntegrationMessagesDefinition.xsd” in the Codeplex solution):

<xs:complexType name="Message">

    <xs:sequence>

      <xs:element  name="MessageName" minOccurs="1" maxOccurs="1" nillable="false"

 type="xs:string" />

    </xs:sequence>

  </xs:complexType>

 

  <xs:complexType name="NewCustomer">

    <xs:complexContent>

      <xs:extension base="tns:Message">

        <xs:sequence>

          <xs:element minOccurs="1" maxOccurs="1" name="FirstName" nillable="false"

type="xs:string" />

          <xs:element minOccurs="1" maxOccurs="1" name="LastName" nillable="false"

type="xs:string" />

          <xs:element minOccurs="1" maxOccurs="1" name="MobilePhone" nillable="false"

 type="xs:string" />

          <xs:element minOccurs="1" maxOccurs="1" name="Email" nillable="false"

type="xs:string" />

        </xs:sequence>

      </xs:extension>

    </xs:complexContent>

  </xs:complexType>

 

  <xs:complexType name="NewCompetitor">

    <xs:complexContent>

      <xs:extension base="tns:Message">

        <xs:sequence>

          <xs:element minOccurs="1" maxOccurs="1" name="Name" nillable="false"

type="xs:string" />

          <xs:element minOccurs="1" maxOccurs="1" name="WebSiteURL" nillable="false"

type="xs:string" />

        </xs:sequence>

      </xs:extension>

    </xs:complexContent>

  </xs:complexType>

 

Now that we have defined our general scenario, the next section zooms into the CRM side and it describes how it has been developed.

CRM Solution Components

Microsoft Dynamics CRM is a flexible platform which allows client and server extensions based on standard technologies such as JavaScript, WCF services, WF workflows and .NET libraries. These extensions are called solution components, and they are grouped in a solution package, which can be exported and imported between environments as a ZIP file.

In our current implementation, the CRM solution package contains the next main components:

  • ·         “Message” entity. The Message entity holds the XML message to be sent or received. “Message Direction” is a custom attribute to indicate the message direction (IN/OUT)

Notes: Microsoft Dynamics CRM implements a relational data model based on SQL server, where each entity is a SQL table.

  • ·         “Message Processor” workflow. When a new message record is created, this workflow is run and it processes the message, reading the XML message and triggering the corresponding actions.
  • ·          “Process Message” custom Workflow Activity. The “Message Processor” workflow above described uses this customer workflow activity to instantiate the corresponding actions. This custom workflow activity is part of the assembly “DynCRMMessaginIntegration.Workflow

The next screenshot shows the actual CRM solution that you can download from Codeplex. As you can see, it contains another workflow “Send New Contact-Customer Message”. This workflow creates a new message record after a new CRM contact has been created.

 

Send New Contact-Customer Message” workflow:

 

Message properties:

 

Send New Contact-Customer Message” workflow is just an example of how you can create new CRM integration messages, however you should understand it can be easily extended to any other CRM interface. That said, the “NewCompetitor” message could be created in CRM by an external process that read message from the queue “SystemX.To.CRM” and call the CRM Web services. As I mentioned at the beginning, that part is not in the scope of this article.

CRM Development

For the CRM development I have used the CRM Developer toolkit, which provides some facilities within Visual Studio 2012. As you can see in the screenshot below, the Visual Studio solution is composed by three projects:

  • ·         Common: library with the main logic to instantiate the message processors. It also contains the XSD file “IntegrationMessagesDefinition.xsd” with the messages definition. Using this XSD file and the utility XSD.exe, I have generated the corresponding code to easily serialize and de-serialize the XML messages. You can find the required command in the file “GenerateIntegrationMessagesClasses.bat” and its result in “IntegrationMessagesDefinition.cs
  • ·         Workflow: library with custom workflow activities . It contains“ProcessMessageActivity.cs” and its base class “BaseCodeActivity.cs”, which inherits from “CodeActivity”. This assembly uses the Common library, which is merged using ILMerge before being deployed in the CRM environment.
  • ·         CrmPackage: helper project to deploy the CRM customisations into the CRM environment. It contains references to Common and Workflow project.

 

The most interesting part of this development is the Message Processor Factory. “ProcessMessageActivity” uses “MessageProcessorFactory” to get the specific “BaseMessageProcessor”, which is instantiated using reflection. This way, the “ProcessMessageActivity” doesn’t need to know how to process each message . See below a class diagram with more details.

 

Try it on your own

I have prepared a CRM trial environment where you can play with the implementation described in the article. Bear in mind this environments expires in October 21, 2013, but remember you can download the source code and the CRM solution from Codeplex any time ( https://dyncrmmessagingintegration.codeplex.com/) and deploy it in your own environment.

Dynamics CRM Trial Environment

CRM URL:

https://mycompany1001.crm4.dynamics.com

User:

MessagingTester\@MyCompany1001.onmicrosoft.com

Password:

dyncrm1001!

 

Test “NewCustomer” message:

Create a new contact in CRM and wait until the “Send New Contact-Customer Message” workflow is executed. Then you can see how a new message have been created and its status is “Processed”

 

Workflow instance:

 

 

Test “NewCompetitor” message:

Create manually a new message record in CRM (“Settings” area in Sitemap) with the next XML message body:

<?xml version="1.0" encoding="utf-8"?>

<NewCompetitor xmlns="https://dyncrmmessagingintegration.codeplex.com/2013/Messages">

  <MessageName>NewCompetitor</MessageName>

  <Name>Marks And Spencer</Name>

  <WebSiteURL>https://marksandspencer.com</WebSiteURL>

</NewCompetitor>

 

After this message has been saved, a new competitor should be created in CRM.

 

About the author

Ramon Tebar is a Software Engineer specialised on Microsoft Technologies with experience in worldwide projects for different industrial sectors as consultant and developer. Pragmatic and disciplined professional concerned about design and develop reusable enterprise applications, following the best practices and design patterns over the whole development life cycle. Broad experience in Microsoft Dynamics CRM, customising and extending the platform to provide tailored solutions and integrations based on service-oriented architectures and messages queuing. Motivated by community events and contributor in blogs, technical books, open source projects and forums. Awarded by Microsoft as Most Valuable Professional (MVP) on Dynamics CRM in 2012. Participated as a speaker in several technical international events including Extreme CRM 2012 and CRM Deep Dive Technical Bootcamp. Follow him on Twitter.

 

The MVP Monday Series is created by Melissa Travers. In this series we work to provide readers with a guest post from an MVP every Monday. Melissa is a Community Program Manager, formerly known as MVP Lead, for Messaging and Collaboration (Exchange, Lync, Office 365 and SharePoint) and Microsoft Dynamics in the US. She began her career at Microsoft as an Exchange Support Engineer and has been working with the technical community in some capacity for almost a decade. In her spare time she enjoys going to the gym, shopping for handbags, watching period and fantasy dramas, and spending time with her children and miniature Dachshund. Melissa lives in North Carolina and works out of the Microsoft Charlotte office.