Using Microsoft BizTalk Dynamics CRM Adapter – Part 2

In previous part of the article, we had initial talks about integration between BizTalk and CRM using Dynamics CRM Adapter. We discussed –

· Installing and configuring BizTalk CRM Adapter

· Basics of CRM System

· How to perform query operation using BizTalk adapter

In this part of article of the article, I am going to take next baby step and talk about another operation “Create Data” in CRM System.

To take absolute advantage and context of this article, I suggest readers to go through previous part of the article @ http://blogs.msdn.com/brajens/archive/2007/05/27/using-microsoft-biztalk-dynamics-crm-adapter-part-1.aspx

How to perform Create Data with CRM Adapter

Using BizTalk CRM adapter, developers can create any entity (like account, contact, case, product etc.) inside CRM System. Before creating any entity, it is suggested to get following information about entity for CRM implementation at client site –

1. What attributes of the entity are supported? (you have to populate data for those attributes)

2. What attributes of the entity are required? Like “Title” is required field for entity “incident” or “case”. (you just cannot afford to miss populating data for these attributes; it will give error otherwise)

3. How many attributes of the entity are Pick List types (take options as value)? For example, “Priority” field of “incident” entity is Pick List type and it accepts Low, Normal and High as values. (there is a special way to populate Pick List type attributes)

4. Is this entity linked (has relationship) with other entities? If yes then what are the linking attributes? These fields are called “Lookup” fields. For example, “incident” is linked to “account” entity where “account” has parent entity role. An incident cannot be created unless linked to an account. “Incident” entity has a field as “Customer” where is shows parent account name information. Now, when you create an incident, it is must to provide parent account information because account-incident entities are linked as Parent-Child relationship.(there is a special way to populate Lookup type attributes)

5. Is this a custom entity? (there is a special way to populate custom entities)

6. What attributes of the entity are custom created? (there is a special way to populate custom attributes)

In this article, I will talk about out of box entities and their attributes. To reduce complexity, I will leave Pick List type attributes, Lookup type attributes, custom entities and custom attributes. But I promise to address this specifically in very next parts of the article.

1. Example Scenario

I am taking very simple scenario where I am creating new “contact” entity instance in CRM system. I have tried to keep it simple. The “contact” entity lies under “Service” sub module. Following are answers to my questions above –

1. What attributes of the entity are supported?

For this article, I am assuming that client CRM implementation supports following attributes of “contact” entity – “Last Name”, “First Name”, “Salutation”, “Job Title”, “Business Phone” and “Email”.

2. What attributes of the entity are required?

“Last Name” is only required attribute.

3. How many attributes of the entity are Pick List types?

“contact” entity has Pick List type attributes (like “Address Type”) but I am leaving it for next part of article.

4. Is this entity linked (has relationship) with other entities?

“contact” entity is linked to “account” entity and has a Lookup type attribute ( “Parent Customer”) but I am leaving it for next part of the article.

5. Is this a custom entity?

No, this entity is out of box provided by CRM System.

6. What attributes of the entity are custom created?

None so far. We will cover it in next part of article.

It’s coding time again.

2. Perform “Create Contact Entity” instance using .net code (calling CRM web service)

I added CRM web service as web reference and named it “CRMServer”. Following is code to create contact instance in CRM system.

 CRMServer.CrmService service = new CRMWSTest.CRMServer.CrmService();

 service.Credentials = System.Net.CredentialCache.DefaultCredentials;

CRMServer.contact contact = new CRMServer.contact();

contact.firstname = "Brajendra";

contact.lastname = "Singh";

contact.salutation = "Mr.";

contact.jobtitle = "Consultant";

contact.telephone1 = "111-111-1111";

contact.emailaddress1 = "test@microsoft.com";

Guid newContactId = service.Create(contact);

Code is fairly simple. I first created an instance of CRM web service client.

CRMServer.contact contact = new CRMServer.contact();

contact.firstname = "Brajendra";

contact.lastname = "Singh";

contact.salutation = "Mr.";

contact.jobtitle = "Consultant";

contact.telephone1 = "111-111-1111";

contact.emailaddress1 = "test@microsoft.com";

Then I created an instance of “contact” class and set values for attributes. Few things need attention here –

· You will get error if you don’t populate “lastname” property because it is a required field for “contact” entity.

· If you see scenario above, we talked about “Business Phone” and “Email” attributes. But here I am populating “telephone1” and “emailaddress1” properties. This mean, In CRM system, for contact entity, “Business Phone” is display name for schema name “telephone1” and “Email” is display name for “emailaddress1”. You can check all these details on customization section of CRM application and please refer part-1 of article for more information on it.

Guid newContactId = service.Create(contact);

Finally, you call create method for service. “Create” method is service takes “BusinessEntity” type as parameter. All entities in CRM system inherits from “BusinessEntity” class. This makes “Create” a generic method to create all entities inside CRM system.

When you create an entity; you get a GUID as return value and it contains internal id (primary key) of that entity instance inside CRM system. Guid returned in this example is internal id of created new contact in CRM system and it is hold by “contactid” attribute of contact entity.

So far so good, let’s implement the same code in BizTalk using BizTalk adapter.

1. Perform “Create Contact Entity” instance using BizTalk orchestration (using Dynamics CRM Adapter)

Following are the steps to perform same create contact operation in orchestration using BizTalk Dynamics CRM adapter.

· To create a new contact, we send contact information in XML message and get response XML back containing internal id (primary key) of created contact. We need solicit-response send port for this purpose. Create a new static solicit-response send port in BizTalk Administration Console. Give a name to it (say “CRMSendPort”) and select type as “Microsoft Dynamics CRM” to make it use CRM adapter. Go to “Configure” and put “Web Service URL” as http://<CRM-Server>/mscrmservices/2006.

In send handler, select send handler created as per CRM specific host. Configure “Send Pipeline” as “Xml Transmit” and “Receive Pipeline” as “Xml Receive”. Save and close things.

· Create a BizTalk project and assign a strong name key to it.

· We have to generate schema for create operation. Right click Project Name >> Select Add Menu >> Select Add Generated Items Menu>> Select Add Adapter Metadata Option>> Press Add Button >> Select Microsoft Dynamics CRM Option>> Select Port (same port created in above steps say “CRMSendPort”) >> Press Next Button. “Microsoft Dynamics CRM User Credentials” screen opens up. Enter user name and password for CRM system. Remember this user name and password should have adequate access to fetch entity and their schema information from CRM system. Press Ok button after entering credentials.

· “Microsoft Dynamics CRM Actions and Entities” screen opens up. As we already discussed, CRM sub-systems are made of entities. At this point we select entity which we want to deal with and action which we want to perform on selected entity. Since we want to create an instance of contact, select “Create” as action and “contact” as entity. If required, in some implementation, you can also select multiple actions and multiple entities. When selection is done, press next button. It would take few seconds to generate all schemas related to fetch operation in BizTalk project.

· In generated artifacts, it has lots of schemas and one BizTalk orchestration file. Open orchestration file and delete all port types and multi-part message types generated by default. Well, these are useful but I am asking to clean them so that we can create and understand things from scratch.

· It generates quite a number of schemas in project. These schemas contain type definition and are included in each other. We are interested in two schemas only – one request schema (to send contact details) and one response schema (containing internal id or primary key of created contact).

· “contact_Entities.xsd” serves purpose of request schema. You expand to see details of this schema; it contains all supported properties of contact entity and “crm_action” attribute.

Note: Whenever, you want to create instance of any entity, it generates a schema with name “ <entity_name> _Entities.xsd”. And this schema is used to form request message.

· Response is tricky again. Developers think that “Create_CreateResponse.xsd” is response schema but it is NOT. Every response using CRM adapter follows a fix and common schema and this schema is not generated. You can find this schema @ “C:\Program Files\BizTalkAdapter\Schemas\Response.xsd” depending upon adapter installation location. You have to include this Response.xsd in project.

· We are now all set to implement logic. Create two messages of type request and response schemas. Hook these messages to a static solicit-response send logical port using send and receive shape. Use map (with transform shape) or message assignment shapes to create request xml and send it via solicit-response port. When response comes consume it as per requirement. I am leaving this logic development part to readers. If you face any issue, please refer sample application attached with this article or feel free to message me.

· When creating xml request (using map or message assignment), take care of following things. Set “crm_action” attribute value to “create”. We are doing this because we are performing create operation on CRM system. Set values for all the contact attributes discussed above. Please do not forget to set value for “lastname” attribute because it is required attribute. In attached sample, I have used another XML schema in map to prepare request XML. This same XML schema based message is copied at a file based receive location to kick start sample orchestration. I have implemented in crude way to keep things simple but you can have implementation as per your requirement.

Note: Few words about setting “crm_action” attribute. When performing create operation, it is always safe and good to provide “create” as value in “crm_action” attribute. However, if “crm_action” value is not provided then it uses following logic to take decision –

o If the primary key node of the entity (in this case contactid) is not present in the XML or if the node has an empty value, the adapter assumes this is a “create” action.

o If the primary key node of the entity has a correct GUID value, the adapter assumes the action to be “update”.

· When you are done with coding, compile project and deploy it. After deployment, bind solicit-response orchestration ports with physical solicit-response port (“CRMSendPort”) created in above steps. Enlist and start orchestration. Finally trigger orchestration to test query operation.

· You will find that response message comes in following format –

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

<ns0:Response xmlns:ns0="http://schemas.microsoft.com/crm/BizTalkAdapter/Response">

<Header>

  <ReturnCode>1</ReturnCode>

  <ErrorCode />

  <ErrorString />

  <Retryable />

</Header>

<Body>

  <Message><prefix:CreateResponse xmlns:prefix="http://localhost/schemas.microsoft.com/crm/2006/CreateResponse"><id>84bc5a78-22c6-4cc9-88e6-3043c558bf37</id></prefix:CreateResponse></Message>

</Body>

</ns0:Response>

“Message” element contains response (xml format) and it follows schema type “Create_CreateResponse.xsd”. You will find that response XML contains internal id (primary key) of created contact entity instance. You need to employ some parsing technique to fetch id out of response xml.

Rest of the return message contains error handling mechanism which can be used as required.

· That’s it.

Conclusion

We have seen query and create operation in part 1 and 2 of the article. I am going to take complex scenario of create operation in next article. If required, please download sample project attached with article for further reference. If you face any issue please feel free to ping me on this article. Hope article was useful to you and your comments are always welcome.

CreateContactOrch.zip