Integrating BizTalk Server and Microsoft Dynamics CRM

Exclusive offer: get 50% off this eBook here
Microsoft BizTalk 2010: Line of Business Systems Integration

Microsoft BizTalk 2010: Line of Business Systems Integration — Save 50%

A practical guide to integrating Line of Business systems with Microsoft BizTalk Server 2010 in this book and eBook

$35.99    $18.00
by Richard Seroter | July 2011 | Enterprise Articles Microsoft

Microsoft Dynamics CRM 2011 is the latest and greatest relationship management software from Microsoft. This release of the product introduced a wide range of improvements to the user interface, a new WCF programming model, role-based forms, data analysis dashboards, tight integration with SharePoint 2010, Windows Azure integration, and much more. Dynamics CRM 2011 should be considered by anyone evaluating small or large CRM projects. But how do we make Dynamics CRM an integrated part of our enterprise landscape? This article focuses on that question.

In this article by Richard Seroter, author of Microsoft BizTalk 2010: Line of Business Systems Integration, we will cover:

  • What is Microsoft Dynamics CRM and what problems does it solve?
  • Why you should integrate Dynamics CRM with BizTalk Server
  • How BizTalk Server makes requests to Dynamics CRM

 

Microsoft BizTalk 2010: Line of Business Systems Integration

Microsoft BizTalk 2010: Line of Business Systems Integration

A practical guide to integrating Line of Business systems with BizTalk Server 2010

        Read more about this book      

(For more resources on BizTalk, see here.)

What is Microsoft Dynamics CRM?

Customer relationship management is a critical part of virtually every business. Dynamics CRM 2011 offers a solution for the three traditional areas of CRM: sales, marketing, and customer service.

For customers interested in managing a sales team, Dynamics CRM 2011 has a strong set of features. This includes organizing teams into territories, defining price lists, managing opportunities, maintaining organization structures, tracking sales pipelines, enabling mobile access, and much more.

If you are using Dynamics CRM 2011 for marketing efforts, then you have the ability to import data from multiple sources, plan campaigns and set up target lists, create mass communications, track responses to campaigns, share leads with the sales team, and analyze the success of a marketing program.

Dynamics CRM 2011 also serves as a powerful hub for customer service scenarios. Features include rich account management, case routing and management, a built-in knowledge base, scheduling of call center resources, scripted Q&A workflows called Dialogs, contract management, and more.

Besides these three areas, Microsoft pitches Dynamics CRM as a general purpose application platform called xRM, where the "X" stands for any sort of relationship management. Dynamics CRM has a robust underlying framework for screen design, security roles, data auditing, entity definition, workflow, and mobility, among others. Instead of building these foundational aspects into every application, we can build our data-driven applications within Dynamics CRM.

Microsoft has made a big move into the cloud with this release of Dynamics CRM 2011. For the first time in company history, a product was released online (Dynamics CRM Online) prior to on-premises software. The hosted version of the application runs an identical codebase to the on-premises version meaning that code built to support a local instance will work just fine in the cloud. In addition to the big play in CRM hosting, Microsoft has also baked Windows Azure integration into Dynamics CRM 2011. Specifically, we now have the ability to configure a call-out to an Azure AppFabric Service Bus endpoint. To do this, the downstream service must implement a specific WCF interface and within CRM, the Azure AppFabric plugin is configured to call that downstream service through the Azure AppFabric Service Bus relay service. For BizTalk Server to accommodate this pattern, we would want to build a proxy service that implements the required Dynamics CRM 2011 interface and forwards requests into a BizTalk Server endpoint. This article will not demonstrate this scenario, however, as the focus will be on integrating with an onpremises instance only.

 

Why Integrate Dynamics CRM and BizTalk Server?

There are numerous reasons to tie these two technologies together. Recall that BizTalk Server is an enterprise integration bus that connects disparate applications. There can be a natural inclination to hoard data within a particular application, but if we embrace real-time message exchange, we can actually have a more agile enterprise.

Consider a scenario when a customer's full "contact history" resides in multiple systems. The Dynamics CRM 2011 contact center may only serve a specific audience, and other systems within the company hold additional details about the company's customers. One design choice could be to bulk load that information into Dynamics CRM 2011 on a scheduled interval. However, it may be more effective to call out to a BizTalk Server service that aggregates data across systems and returns a composite view of a customer's history with a company.

In a similar manner, think about how information is shared between systems. A public website for a company may include a registration page where visitors sign up for more information and deeper access to content. That registration event is relevant to multiple systems within the company. We could send that initial registration message to BizTalk Server and then broadcast that message to the multiple systems that want to know about that customer. A marketing application may want to respond with a personalized email welcoming that person to the website. The sales team may decide to follow up with that person if they expressed interest in purchasing products. Our Dynamics CRM 2011 customer service center could choose to automatically add the registration event so that it is ready whenever that customer calls in. In this case, BizTalk Server acts as a central router of data and invokes the exposed Dynamics CRM services to create customers and transactions.

 

Communicating from BizTalk Server to Dynamics CRM

The way that you send requests from BizTalk Server to Dynamics CRM 2011 has changed significantly in this release. In the previous versions of Dynamics CRM, a BizTalk "send" adapter was available for communicating with the platform. Dynamics CRM 2011 no longer ships with an adapter and developers are encouraged to use the WCF endpoints exposed by the product.

Dynamics CRM has both a WCF REST and SOAP endpoint. The REST endpoint can only be used within the CRM application itself. For instance, you can build what is called a web resource that is embedded in a Dynamics CRM page. This resource could be a Microsoft Silverlight or HTML page that looks up data from three different Dynamics CRM entities and aggregates them on the page. This web resource can communicate with the Dynamics CRM REST API, which is friendly to JavaScript clients. Unfortunately, you cannot use the REST endpoint from outside of the Dynamics CRM environment, but because BizTalk cannot communicate with REST services, this has little impact on the BizTalk integration story.

The Dynamics CRM SOAP API, unlike its ASMX web service predecessor, is static and operates with a generic Entity data structure. Instead of having a dynamic WSDL that exposes typed definitions for all of the standard and custom entities in the system, the Dynamics CRM 2011 SOAP API has a set of operations (for example, Create, Retrieve) that function with a single object type. The Entity object has a property identifying which concrete object it represents (for example, Account or Contract), and a name/value pair collection that represents the columns and values in the object it represents. For instance, an Entity may have a LogicalName set to "Account" and columns for "telephone1", "emailaddress", and "websiteurl."

In essence, this means that we have two choices when interacting with Dynamics CRM 2011 from BizTalk Server. Our first option is to directly consume and invoke the untyped SOAP API. Doing this involves creating maps from a canonical schema to the type-less Entity schema. In the case of doing a Retrieve operation, we may also have to map the type-less Entity message back to a structured message for more processing. Below, we will walk through an example of this.

Microsoft BizTalk 2010: Line of Business Systems Integration

The second option involves creating a typed proxy service for BizTalk Server to invoke. Dynamics CRM has a feature-rich Solution Development Kit (SDK) that allows us to create typed objects and send them to the Dynamics CRM SOAP endpoint. This proxy service will then expose a typed interface to BizTalk that operates as desired with a strongly typed schema. An upcoming exercise demonstrates this scenario.

Microsoft BizTalk 2010: Line of Business Systems Integration

Which choice is best? For simple solutions, it may be fine to interact directly with the Dynamics CRM 2011 SOAP API. If you are updating a couple fields on an entity, or retrieving a pair of data values, the messiness of the untyped schema is worth the straightforward solution. However, if you are making large scale changes to entities, or getting back an entire entity and publishing to the BizTalk bus for more subscribers to receive, then working strictly with a typed proxy service is the best route. However, we will look at both scenarios below, and you can make that choice for yourself.

Integrating Directly with the Dynamics CRM 2011 SOAP API

In the following series of steps, we will look at how to consume the native Dynamics CRM SOAP interface in BizTalk Server. We will first look at how to query Dynamics CRM to return an Entity. After that, we will see the steps for creating a new Entity in Dynamics CRM.

Querying Dynamics CRM from BizTalk Server

In this scenario, BizTalk Server will request details about a specific Dynamics CRM "contact" record and send the result of that inquiry to another system.

 

Microsoft BizTalk 2010: Line of Business Systems Integration A practical guide to integrating Line of Business systems with Microsoft BizTalk Server 2010 in this book and eBook
Published: July 2011
eBook Price: $35.99
Book Price: $59.99
See more
Select your format and quantity:

 

        Read more about this book      

(For more resources on BizTalk, see here.)

Building the BizTalk components

In this first set of steps, we define the canonical BizTalk schema, add the Dynamics CRM schemas, create a mapping between the formats, and build an orchestration that ties all the pieces together:

  1. Go to the code package and navigate to C:\LOBIntegration\Chapter3-DynamicsCrm and open the Visual Studio 2010 solution file named Chapter3-DynamicsCrm.sln.
  2. In Visual Studio 2010, create a new BizTalk project named Chapter3-DynamicsCRM.AccountInt. This project will hold all the BizTalk artifacts for this solution. Right-click the project, choose Properties, and set the strong name key, and the deployment application to Chapter3.
  3. Right-click the BizTalk project and choose to add a new item. Select the (XML) schema item type and name the schema Customer_XML.xsd.
  4. This schema reflects our organization's internal definition of a customer. The result of our query to Dynamics CRM should be mapped to this structure. Our customers are defined by an identifier, name, set of addresses, set of phone numbers, and an email address. The following image reflects the structure of the schema:

    Microsoft BizTalk 2010: Line of Business Systems Integration

  5. Add a reference to the Dynamics CRM SOAP endpoint in order to generate the artifacts that we need to consume the service. The WCF SOAP endpoint for a Dynamics CRM 2011 instance takes the form of: http://<server name>/<instance name>/XRMServices/2011/Organization.svc
  6. Right-click the BizTalk project and choose Add and then Add Generated Items. Select Consume WCF Service. On the Metadata source page of the BizTalk WCF Service Consuming Wizard, choose the source of the metadata to be the Metadata Exchange (MEX) endpoint. On the Metadata Endpoint page of the wizard, enter the URL of your Dynamics CRM SOAP endpoint. After clicking the Get button next to the Metadata Address (URL), move to the next page of the wizard and click Import.
  7. The wizard adds a host of files to the BizTalk project. This includes two binding files, an orchestration (that includes message and orchestration port definitions), and seven schemas that represent the data types used by this service.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  8. Unfortunately, the schemas generated for this endpoint are not considered valid. They do not have the proper links between each other and an error is shown when you open one. You could either manually correct each schema, or, better yet, leverage the valid BizTalk schemas included in the Dynamics CRM SDK that can be downloaded from the Microsoft website.
  9. Delete the seven XSD schemas added by the service reference.
  10. Right click the BizTalk project and choose Add then Existing Item. Navigate to where you have unpacked the Dynamics CRM SDK package and find the sdk\schemas\crmbiztalkintegration folder and choose the seven "organizationservice" schemas and click Add.
  11. Unfortunately, the orchestration that was generated by the Dynamics CRM service reference will now contain errors due to small changes in the type names of the new schemas compared to the generated ones. So why go through the effort of adding the service reference at all if we are just going to replace all the schemas and end up with a broken orchestration? One benefit of still adding the service reference is acquiring the binding files. The Dynamics CRM endpoint has specific configurations that do not exactly match the standard BizTalk WCF bindings. These binding files make it simpler to get our Dynamics CRM send port correct the first time. Note that in real life, it is best to build a single project that contains the Dynamics CRM schemas and reference it in future projects.
  12. Exclude the generated orchestration from the BizTalk project and build the project to confirm that the added schemas are valid.
  13. Right-click the BizTalk project and choose to add a new item. Select the Map type and name it Customer_To_CrmContactQuery.btm and click Add.
  14. For the source schema, select the Chapter3-DynamicsCRM.AccountInt.Customer_XML message type. This map takes in the Customer message type which initially only contains a value in the ID field. When a response is received from Dynamics CRM, we will populate the rest of the Customer message's nodes.
  15. For the destination schema, select the Chapter3-DynamicsCRM.AccountInt.organizationservice_schemas_microsoft_com_xrm_2011_contracts_ services message type. When prompted, select Retrieve as the root node. Our map now looks like the following image:

    Microsoft BizTalk 2010: Line of Business Systems Integration

  16. The Retrieve schema for Dynamics CRM is untyped, as mentioned earlier. Provide the name of the entity being queried (entityName), the unique ID of the target record (id), and either a list of which specific attributes we want (Columns) or request every attribute of the record (AllColumns).
  17. We could hard-code the entityName value by setting the value attribute of the node from the Properties window of the BizTalk Mapper, but those settings can be difficult to locate later on. One way to visually indicate a default node value is through a functoid. From the Visual Studio 2010 toolbox, open the Advanced Functoids tab and drag a Value Mapping functoid to the mapping grid. Open the functoid by double-clicking it and set the value of the first parameter to true (so that it always applies) and set the Result value to contact (which is the formal name of the Dynamics CRM entity). Finally, drag the output of the functoid to the entityName node in the destination schema.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  18. As mentioned above, the only field in the source schema that initially contains a value is the ID field. Map that source field to the id field in the destination. Note that because the destination fieldid has a pattern attached to it that looks for a GUID format, set the Value property of the source node to a valid GUID so that the map can be tested successfully. Do not worry about introducing side effects at runtime as any Value set on a source schema node is ignored outside of Visual Studio 2010. However, be aware that setting the Value property of a destination schema node does result in that value being pushed to the mapped message at runtime.
  19. There are 146 fields in the Dynamics CRM contact object, so choosing to return all columns may be excessive. If you do want to retrieve all columns, simply set the destination schema's AllColumns node to true. However, in this case, we will only request specific columns. To generate the repeating elements under the Columns node, write some custom XSLT. From the Visual Studio 2010 toolbox, under Advanced Functoids, drag the Scripting functoid to the mapping grid.
  20. Double-click the functoid and switch to the Script Functoid Configuration tab. Choose the Inline XSLT option since there is no source schema input to this custom XSLT and the objective is to emit a set of XML elements. Enter the following XML to retrieve just the desired columns. Notice the explicit namespace declaration to properly "type" the string and prevent errors during service invocation:
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">salutation</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">firstname</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">middlename</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">lastname</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">address1_addresstypecode</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">address1_line1</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">address1_city</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">address1_stateorprovince</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">address1_postalcode</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">telephone1</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/
    Serialization/Arrays">emailaddress1</string>
  21. Save and close the map.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  22. Right-click the BizTalk project and add a new item. Select the Map type, set the name to CrmContact_To_Customer.btm.
  23. For the source schema, select the Chapter3-DynamicsCRM.AccountInt.organizationservice_schemas_microsoft_com_xrm_2011_contracts_ services type and choose RetrieveResponse as the root.
  24. For the destination schema, select the Chapter3-DynamicsCRM.AccountIntCustomer_XML message type. The resulting map will look like this:

    Microsoft BizTalk 2010: Line of Business Systems Integration

  25. The message coming back from Dynamics CRM (which is the source of this map) contains an array of fields and values for the returned entity. The Attributes node contains all of the entity values. When there is an option set, or list of values, involved (e.g. addresstypecode) the Attributes value would be "1" while the FormattedValues node, which contains friendlier representations for option set values, would have an entry for addresstypecodewhere the value would be "Default Value".
  26. To map the repeating KeyValuePairOfstringanyType to the structured destination fields, we can either build one long custom XSLT block, individual XSLT blocks for each section, or try and use other functoids (for example, Logical functoids with Value Mapping) to match the repeating source nodes to the destination node. In this example, build individual blocks of XSLT necessary to populate the entire destination schema.
  27. Drag a Scripting functoid to the mapping surface and set it to use Inline XSLT. This functoid connects to the destination ID node and has no link from a source field. The XSLT for this functoid looks for the value node associated with the key node that holds the contactid value.
    <ID>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstringanyTy
    pe'][*[local-name()='key']='contactid']/*[local-name()='value']"/>
    </ID>
  28. Next, drag another Scripting functoid to the mapping surface and set it to also use Inline XSLT. Connect it to the Name destination node. Much like the previous functoid, it will find the value nodes corresponding to the key nodes for each element under the Name. Highlighted here are the portions of the XSLT that retrieve the requested values.
    <Name>
    <Prefix>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstr
    inganyType'][*[local-name()='key']='salutation']/*[localname()='
    value']"/>
    </Prefix>
    <FirstName>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstringanyTy
    pe'][*[local-name()='key']='firstname']/*[local-name()='value']"/>
    </FirstName>
    <MiddleName>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstr
    inganyType'][*[local-name()='key']='middlename']/*[localname()='
    value']"/>
    </MiddleName>
    <LastName>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstringanyTy
    pe'][*[local-name()='key']='lastname']/*[local-name()='value']"/>
    </LastName>
    </Name>
  29. Add another Scripting functoid that uses Inline XSLT and connects to the destination node named Addresses:
    <Addresses>
    <Address>
    <Type>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstringstri
    ng'][*[local-name()='key']='address1_addresstypecode']/*[localname()='
    value']"/>
    </Type>
    <Street>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstrin
    ganyType'][*[local-name()='key']='address1_line1']/*[localname()='
    value']"/>
    </Street>
    <City>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstri
    nganyType'][*[local-name()='key']='address1_city']/*[localname()='
    value']"/>
    </City>
    <State>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstringanyT
    ype'][*[local-name()='key']='address1_stateorprovince']/*[localname()='
    value']"/>
    </State>
    <PostalCode>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstringan
    yType'][*[local-name()='key']='address1_postalcode']/*[localname()='
    value']"/>
    </PostalCode>
    </Address>
    </Addresses>
  30. Next, add a Scripting functoid that leverages Inline XSLT and connects to the PhoneNumbers node:
    <PhoneNumbers>
    <PhoneNumber>
    <Type>Business</Type>
    <Number>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstr
    inganyType'][*[local-name()='key']='telephone1']/*[localname()='
    value']"/>
    </Number>
    </PhoneNumber>
    </PhoneNumbers>
  31. Finally, add one more Scripting functoid that uses Inline XSLT and connects to the EmailAddress node in the destination schema:
    <EmailAddress>
    <xsl:value-of select="//*[local-name()='KeyValuePairOfstri
    nganyType'][*[local-name()='key']='emailaddress1']/*[localname()='
    value']"/>
    </EmailAddress>
  32. The final map looks like the following image:

    Microsoft BizTalk 2010: Line of Business Systems Integration

  33. This service will be consumed by a BizTalk orchestration, so right-click the BizTalk project and add a new item. Select orchestration and set the name to QueryCrmCustomer.odx. This solution could consume the service directly through messaging (without orchestration), but because the generated BizTalk send port will have multiple possible operations to invoke (for example, Create, Retrieve, Update), an orchestration is the easiest way to set that target operation.
  34. Create four orchestration messages: Customer_Input of type Chapter3-DynamicsCRM.AccountInt.Customer_XML, Customer_Output of type Chapter3-DynamicsCRM.AccountInt.Customer_XML,ContactRetrieve_Request of type Chapter3-DynamicsCRM.AccountInt.organizationservice_schemas_microsoft_com_xrm_2011_contracts_ services.Retrieve and ContactRetrieve_Response of type Chapter3-DynamicsCRM.AccountInt.organizationservice_schemas_microsoft_com_xrm_2011_contracts_ services.RetrieveResponse.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  35. Sketch out an orchestration flow that receives a message, transforms a message, sends a request to a service, receives a response, transforms the response, and sends out a final message. The top Receive shape, named Receive Request, is associated with the Customer_Input message. The Construct shape, named Construct Query, builds the ContactRetrieve_Request message. The Transform shape uses the Customer_To_CrmContactQuery map that was built earlier. The next Send shape, named Send Request, uses the ContactRetrieve_Request message while the Receive shape that follows, named Receive Result, gets back the ContactRetrieve_Response message. The next Construct shape, named Construct Output, builds the Customer_Output message. Its Transform shape uses the CrmContact_To_Customer map where the Transform destination is set to Customer_Output. Finally, the last Send shape, named Send Result is tied to the Customer_Output message.
  36. Add a one-way orchestration port that receives messages and is tied to the Receive Request shape.
  37. Add a one-way orchestration port that sends messages and connects to the Send Result shape.
  38. Create a two-way orchestration port that sends a message and receives a response. Be sure to set the Operation name of this port to Retrieve. The operation name here must correspond to the operation name of the Dynamics CRM web service method that is being called.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  39. Build and deploy the BizTalk project.

We now have the components necessary to configure the messaging ports that complete the solution.

 

Microsoft BizTalk 2010: Line of Business Systems Integration A practical guide to integrating Line of Business systems with Microsoft BizTalk Server 2010 in this book and eBook
Published: July 2011
eBook Price: $35.99
Book Price: $59.99
See more
Select your format and quantity:

 

        Read more about this book      

(For more resources on BizTalk, see here.)

Configuring the BizTalk endpoints

In this part of the exercise, we will configure the BizTalk messaging ports that receive the query request, call Dynamics CRM 2011, transform the response message, and emit the canonical Customer message to disk via a FILE adapter.

  1. Open the BizTalk Administration Console and find the Chapter3 application.
  2. Add a new Receive Port (Chapter3.PickupCustomerQuery) and Receive Location (Chapter3.PickupCustomerQuery.FILE) to the application which will pick up a "query request" message from the file system.
  3. Right-click the Chapter3 application and choose Import and then Bindings. Point to the OrganizationService_Custom.BindingInfo.xml binding file that was generated by referencing the Dynamics CRM web service and now sits inside the BizTalk project in Visual Studio. When the import is complete, a new send port is displayed.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  4. Double-click the new send port to observe its settings. Notice that it uses the WCF-Custom adapter and applies a custom WCF binding. The service is called using the credentials of the send port's host instance, so we do not need to add credentials to the send port itself.
  5. Add a new send port that will emit Dynamics CRM response message. This one-way send port uses the FILE adapter and sends a message to the file system.
  6. With the messaging ports in place, we now bind the orchestration to these ports. View the Orchestrations folder in the Chapter3 application and double-click the QueryCrmCustomer orchestration.
  7. Bind the orchestration to the host, the newly created receive port, the generated send port, and the FILE send port.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  8. Start the receive location, send port, and orchestration.

We now have a channel for picking up the "query" message, a send port that calls Dynamics CRM 2011, and a send port that sends out the service result.

Recall that the primary field in the query message into Dynamics CRM is the ID of the record. Therefore, an XML instance is needed for the Customer message with only the ID value populated.

  1. Navigate to your Dynamics CRM 2011 instance and open up the customer record you wish to query. Look at the address in your browser and retrieve the record's GUID and remove the URL encoding.

    (Move the mouse over the image to enlarge.)

  2. Add the record ID to the ID field of the generated instance of a Customer_XML message.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  3. Copy the XML instance file to the folder being polled by the BizTalk receive location.
  4. Observe the file folder where the send port transmits the final message. We should see a message containing the values from Dynamics CRM formatted in the Customer_XML message.

    Microsoft BizTalk 2010: Line of Business Systems Integration

What we saw here was how to create mappings to the Dynamics CRM "retrieve" message, how to put the unstructured results of that query into a structured format, and how to set up the BizTalk components necessary to route and invoke the request. Next up, we will see how to add records to Dynamics CRM from BizTalk Server.

Adding New Records to Dynamics CRM from BizTalk Server

We have already seen how the untyped schemas associated with the Dynamics CRM 2011 SOAP endpoint can make mapping a challenge. Specifically, we just saw how to take the untyped message from DynamicsCRM and convert it to a structured, canonical schema. But what about taking a canonical schema and mapping it to an untyped message? In this exercise, we will take the Customer_XML message and map it to the Dynamics CRM Create message and add a record to our DynamicsCRM instance.

Building the BizTalk components

This exercise builds upon the previous one. In this step, we will define a new mapping and build an orchestration that calls the Dynamics CRM Create operation:

  1. Right-click the BizTalk project and add a new item. Choose the Map type and name the map Customer_To_CrmContactCreate.btm.
  2. Set the source of the map to the Customer_XML message type. For the destination schema, select the organizationservice_schemas_microsoft_com_xrm_2011_contracts_services type and pick the Create message.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  3. In this case, we have to get each source field copied over to the repeating KeyValuePairOfstringanyType node. We will leverage the feature of BizTalk Server 2010 that lets you neatly segment map aspects into logical containers called pages. Rename the first page to Entity Name.
    Drag a Value Mapping functoid from the Advanced Functoids tab on the mapping surface. Double click the Value Mapping functoid and manually set the value of the first parameter (Condition) to true, and manually set the Result parameter to contact.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  4. Create a new page in the map and name the page Looping. While we could choose to build up the destination schema using nothing but custom XSLT, this exercise shows you how to use the BizTalk functoids to make that task a bit easier. If you connect a set of nodes to a Looping functoid, and then connect the output of the Looping functoid to a target node, you create an environment that lets us copy the individual nodes from the source into the repeating node of the destination. Drag a Looping functoid from the Advanced Functoids section of the Toolbox onto the map. Connect the following nodes to it: Prefix, FirstName, MiddleName, LastName, [Address] Type, Street, City, State, PostalCode, Number, EmailAddress.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  5. Create another map page named Any Pairs. On this page, connect the individual nodes to the repeating destination node. However, there are a few caveats. First, the key node underneath KeyValuePairOfstringanyType expects to hold the name of the Dynamics CRM entity attributes. Our canonical schema does not exactly match the names of the Dynamics CRM entity attributes. Therefore, we have to do a bit of translation to set the right value. In addition, because the KeyValuePairOfstringanType can hold any data type as the column value, we must explicitly "type" the value node when it is created. For instance, we must add a "string" attribute for string values.
  6. Drag the Scripting functoid onto the mapping surface and connect it to the Prefix source node and key destination node. Set the Script type to Inline XSLT Call Template. Add the XSLT found below. Note that the xsi:type attribute is added to the value node and the type is set as xs:string:
    <xsl:template name="SetPrefixValue">
    <xsl:param name="param1" />
    <key xmlns="http://schemas.datacontract.org/2004/07/System.
    Collections.Generic">salutation</key>
    <value xmlns="http://schemas.datacontract.org/2004/07/System.
    Collections.Generic" xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <xsl:attribute name="xsi:type">
    <xsl:value-of select="'xs:string'" />
    </xsl:attribute>
    <xsl:value-of select="$param1" />
    </value>
    </xsl:template>
  7. Repeat this process for every source node that previously connected to the looping functoid and make sure to use a different XSLT template name for each script. Excluded from the list is the [Address] Type node which must be handled differently, as we will see shortly. Note that my mapping is as follows:
    Source Node XSLT Template Name CRM Key Name
    Prefix SetPrefixValue salutation
    FirstName SetFNameValue firstname
    MiddleName SetMNameValue middlename
    LastName SetLNameValue lastname
    Street SetStreetValue address1_line1
    City SetCityValue address1_city
    State SetStateValue address1_stateorprovince
    PostalCode SetPostalValue address1_postalcode
    Number SetPhoneValue telephone1
    EmailAddress SetEmailValue emailaddress1

    Microsoft BizTalk 2010: Line of Business Systems Integration

  8. Now we are ready to tackle the Address Type attribute which is not a string, but rather an entry within a list of values (called Option Sets). Drag a new Scripting functoid to the mapping surface and set it to use Inline XSLT Call Template. Add the following XSLT:
    <xsl:template name="SetAddrTypeValue">
    <xsl:param name="param1" />
    <key xmlns="http://schemas.datacontract.org/2004/07/System.
    Collections.Generic">address1_addresstypecode</key>
    <value xmlns="http://schemas.datacontract.org/2004/07/System.
    Collections.Generic"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:a="http://schemas.microsoft.com/xrm/2011/Contracts">
    <xsl:attribute name="xsi:type"><xsl:value-of
    select="'a:OptionSetValue'" /></xsl:attribute>
    <Value xmlns="http://schemas.microsoft.com/xrm/2011/
    Contracts"><xsl:value-of select="$param1" /></Value>
    </value>
    </xsl:template>
  9. Connect the Type node under the Address node to this functoid and connect the other end of the functoid to the key node under the KeyValuePairofstringanyType.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  10. With the map complete, the final task is to build an orchestration that consumes the Dynamics CRM service and emits the result. In this case, the result of a call to the Create operation is a GUID representing the new record's unique ID. Add a new orchestration named CreateCrmCustomer.odx to this BizTalk project.
  11. Create three orchestration messages: Customer_Input of type Chapter3-DynamicsCRM.AccountInt.Customer_XML, ContactCreate_Requestof type Chapter3-DynamicsCRM.AccountInt.organizationservice_schemas_microsoft_com_xrm_2011_contracts_ services.Create, and ContractCreate_Responseof type Chapter3-DynamicsCRM.AccountInt.organizationservice_schemas_microsoft_com_xrm_2011_contracts_ services.CreateResponse.
  12. Build an orchestration flow that receives a message, transforms a message, sends a request to a service, receives a response, and sends out a final message. The top Receive shape, named Receive Request, is associated with the Customer_Input message. The Construct shape, named Construct Create, builds the ContactCreate_Request message. The Transform shape uses the Customer_To_CrmContactCreate map that was just built. The next Send shape, named Send Request, uses the ContactCreate_Request message while the Receive shape that follows, named Receive Result, gets back the ContactCreate_Response message. The last Send shape, named Send Result also uses the ContactCreate_Response message.
  13. Add a one-way orchestration port that receives messages and is tied to the Receive Request shape.
  14. Add a one-way orchestration port that sends messages and connects to the Send Result shape.
  15. Create a two-way orchestration port that sends a message and receives a response. Set the Operation name of this port to Create. Recall that the operation name here must correspond to the operation name of the Dynamics CRM web service method being called.
  16. Build and deploy the BizTalk project.

We have now built the map and orchestration necessary to successfully call this service.

Configuring the BizTalk endpoints

Our final task is to configure the BizTalk messaging components to send a message to the Dynamics CRM service. We already have a series of reusable ports configured as a result of our last exercise and can leverage those this time around.

  1. Open the BizTalk Administration Console and confirm that the updates to our application were successfully deployed. This can be confirmed by looking for our new orchestration under the Orchestrations folder beneath the Chapter3 application.
  2. Double-click the orchestration to bind it to messaging ports.
  3. Set the host value, and for the initial receive port, reuse the port created in the previous exercise. When a receive port is bound to an orchestration, the resulting subscription looks at both the name of the port and the message type coming in. So, in this case, because we are using a Customer_XML message input for both types, we have to un-enlist the previous orchestration to prevent it from picking up this message as well.
  4. Set the orchestration to also reuse the send ports from the previous exercise. This includes the generated send port which calls Dynamics CRM, and the port that sends the service result message to the file system.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  5. Start the orchestration, and ensure that the receive location, send ports, and host are also started. Remember to un-enlist the previous orchestration so that it does not pick up the message as well.
  6. Create an XML instance file for the Customer_XML message type and populate it with details of a new contact that does not yet exist in Dynamics CRM.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  7. Drop this file into a folder being monitored by our FILE receive location.
  8. If everything is configured correctly, we should see both a new record in our Dynamics CRM instance, and a file that holds the unique ID of that new record.

In this exercise, we saw how to create the untyped service request message from a canonical schema and successfully create a record in Dynamics CRM from BizTalk Server.

Summary

Microsoft Dynamics CRM 2011 offers a host of options for integration. While it no longer provides a strongly-typed SOAP interface for BizTalk to consume, we have multiple ways to send messages to Dynamics CRM.


Further resources on this subject:


About the Author :


Richard Seroter

Richard Seroter is a solutions architect for an industry-leading biotechnology company, a Microsoft MVP for BizTalk Server, and a Microsoft Connected Systems Advisor. He has spent the majority of his career consulting with customers as they planned and implemented their enterprise software solutions. Richard worked first for two global IT consulting firms, which gave him exposure to a diverse range of industries, technologies, and business challenges. Richard then joined Microsoft as a SOA/BPM technology specialist where his sole objective was to educate and collaborate with customers as they considered, designed, and architected BizTalk solutions. One of those customers liked him enough to bring him onboard full time as an architect after they committed to using BizTalk Server as their enterprise service bus. Once the BizTalk environment was successfully established, Richard transitioned into a solutions architect role where he now helps identify enterprise best practices and applies good architectural principles to a wide set of IT initiatives.

Richard maintains a semi-popular blog of his exploits, pitfalls, and musings with BizTalk Server and enterprise architecture at http://seroter.wordpress.com.

The authors have provided a website with further information about the book here: http://appliedarchitecturepatterns.com/

 

Books From Packt


Applied Architecture Patterns on the Microsoft Platform
Applied Architecture Patterns on the Microsoft Platform

Microsoft Data Protection Manager 2010
Microsoft Data Protection Manager 2010

Microsoft Silverlight 4 Data and Services Cookbook
Microsoft Silverlight 4 Data and Services Cookbook

Microsoft SharePoint 2010 Administration Cookbook
Microsoft SharePoint 2010 Administration Cookbook

Microsoft Dynamics AX 2009 Administration
Microsoft Dynamics AX 2009 Administration

Microsoft Enterprise Library 5.0
Microsoft Enterprise Library 5.0

Microsoft Dynamics Sure Step 2010
Microsoft Dynamics Sure Step 2010

Least Privilege Security for Windows 7, Vista and XP
Least Privilege Security for Windows 7, Vista and XP


Your rating: None Average: 4 (1 vote)

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
4
1
P
y
3
U
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software