Using Microsoft BizTalk Dynamics CRM Adapter – Part 2

[アーティクル]
05/30/2007

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 @ https://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 https://<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="https://schemas.microsoft.com/crm/BizTalkAdapter/Response">

</Header>

<Body>

</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

Comments

Anonymous
May 31, 2007
Thanks for the second part.in our project we are trying to create a record based on the external schema.that means in source there is an external schema and in destination crm schema. we are mapping this two schemas and the we are creating an orchestraion for the external schema.so will you give an example for the external schma to the crm schema.if you give your email id i will send the Orchestration plan of our project.waiting for your reply.
Anonymous
May 31, 2007
hiin our application you selected in the adapter (Microsoft Dynamics CRM Actions and Entities)in CRMActions you selected "create" action and in Entities you selected "contact".but in mapping and in orchestration you are not using "create"(Create_CreateRequest.xsd) action schema.even your not using in messages of the orchestraion also.so why you are using this schema.
Anonymous
May 31, 2007
Hi sapthagiriRegarding first comment, if you download sample attached with current part of the article, I am using one external xml message to create a CRM contact message. In the same fashion, you can create CRM schema based on some external schema. Please let me know if it makes sense. "Create_CreateRequest.xsd" schema more or less works as container to hold properties of one or more entities. To create any particular entity, you need to pass entity specific xml message. Like in this case, I am passing "contact_entities.xsd" based xml message to create contact. I am trying to explore possibilities of creating one or more entities using this "Create_CreateRequest.xsd" type message but currently I am not sure about it. If find success, I will let people know about it.
Anonymous
June 27, 2007
Hi,My question is: how can I insert the data from SQL Server DB remotely to the Microsoft CRM contact entity?If you can please guide me how to deal the above problem b/c when I deployed the Orchestration it gave me the error.waiting for your reply.
Anonymous
June 28, 2007
Hi Zeeshanyou can use SQL adapter to pool data out for entity. Then use map to construct CRM contact request data from SQL server data.Finally, use CRM adapter and send CRM contact request to CRM server. What is your current approach and what error you are getting.
Anonymous
June 29, 2007
Hi Rajens,I exactly did the same as you explained but I think I didn't use the transform message shape properly. Also I used the stored procedure to pool data from SQL Server DB, after that it creates a multi-type message named 'procedureRequest' what do I do with that. Also can you explain why did you connect 'CrmContact' message to 'contactrequest' multi-type message 'contactRequest' in your exmaple? what is the use of it here?After building the project I got the following error:Error: 'CRMContact': can only modify a message specified in the construct statementC:Documents and SettingsabamfordMy DocumentsVisual Studio 2005ProjectsBizTalkCrmInsertBizTalkCrmInsertBizTalk Orchestration.odxIf you have any idea about that, it would be a great help b/c I am stuck here and can't do anything.Thank you very much.Regards,Zeeshan.
Anonymous
June 29, 2007
In previous articles, we talked about – · Installing and configuring BizTalk CRM Adapter · Basics of
Anonymous
July 04, 2007
Hi Rajens,I managed to insert the SQL Server DB record through Biztalk Orchestration but I can't be able to insert more than one record at a time. The store procedure I am using which captured 20 records and I use this in to transform message so it should send 20 records instead of 1 record at a time.If you have any clue regarding my problem it would be highly appritiatable.Thanks.
Anonymous
July 04, 2007
Hi Rajens,I managed to move some data from SQL Server DB into MS CRM Server DB through Biztalk Orchestration but it only insert one record at a time instead of inserting 20 records b/c the stored procedure I am using, fetched 20 records at a time.Could you tell me how can I insert more than 1 recored into CRM DB or any option which you thing i need to change in my schema or CRM schema???Thank in advance.Zeeshan.
Anonymous
July 10, 2007
Hi ZeeshanSorry for late reply.SQL schema must be having multiple records. What you can do is that loop (for each record) into SQL schema using XPATH.In each loop for records, create CRM schema message from record data. And then send CRM schema message using CRM adapter.Hope it helps.
Anonymous
July 29, 2007
I found this nice blog posts about BizTalk Crm Adapter. Check it out.
Anonymous
July 30, 2007
Hi Rajens,Hope you'd be fine. Thanks for the reply of my previous message.As I explained you earlier that I am inserting more than 1 records into CRM through SQL. I map source schema (sqlservice.xsd) to destination schema (contact_entities.xsd), for testing the map my input instance file has 10 records but test Map result only shows one record which I don't understand why???Do you have any clue why it does that? Is it something that I need to change the properties of contact_entities.xsd schema to be able to produce exactly the same no. of record as in input schema.Thanks in advance.Regards.
Anonymous
July 30, 2007
Hi Rajens,Hope you'd be fine. Thanks for the reply of my previous message.As I explained you earlier that I am inserting more than 1 records into CRM through SQL. I map source schema (sqlservice.xsd) to destination schema (contact_entities.xsd), for testing the map my input instance file has 10 records but test Map result only shows one record which I don't understand why???Do you have any clue why it does that? Is it something that I need to change the properties of contact_entities.xsd schema to be able to produce exactly the same no. of record as in input schema.Thanks in advance.Regards.
Anonymous
August 08, 2007
Hi,After picking up the xml file from file drop location it gives this error:The adapter failed to transmit message going to send port "CRMReqRespPort" with URL "http://10.136.145.191/mscrmservices/2006". It will be retransmitted after the retry interval specified for this Send Port. Details:"The request failed with HTTP status 401: Unauthorized.".
Anonymous
November 22, 2007
The comment has been removed
Anonymous
April 03, 2009
Here are a great series of articles on integrating BizTalk Server with Dynamics CRM: 1. Using Microsoft
Anonymous
April 29, 2009
VaasuEvent Type: WarningEvent Source: BizTalk Server 2006Event Category: BizTalk Server 2006Event ID: 5743Date: 4/29/2009Time: 2:34:34 PMUser: N/AComputer: VAASUDescription:The adapter failed to transmit message going to send port "SP_CRMCREATE" with URL "http://<machinename>/mscrmservices/2007". It will be retransmitted after the retry interval specified for this Send Port. Details:"The request failed with HTTP status 401: Unauthorized.".For more information, see Help and Support Center at http://go.microsoft.com/fwlink/events.asp.
Anonymous
April 29, 2009
Hi RajensI am purely working on Biztalk and I new to the MS CRM. I am trying to integrate the web site which is exposing the Web service with MS CRM tool by using the BIZTALk 2006 R2 server.I tried using the sample provided with the above Create contact article, but for ony first time it works and if i copy the same file again with the different values, it is not working at all. It always gives the below errorEvent Type: WarningEvent Source: BizTalk Server 2006Event Category: BizTalk Server 2006Event ID: 5743Date: 4/29/2009Time: 2:34:34 PMUser: N/AComputer: VAASUDescription:The adapter failed to transmit message going to send port "SP_CRMCREATE" with URL"http://<machinename>/mscrmservices/2007". It will be retransmitted after the retryinterval specified for this Send Port. Details:"The request failed with HTTP status401: Unauthorized.".For more information, see Help and Support Center athttp://go.microsoft.com/fwlink/events.asp.One more thing which I found was, when I run the application for the first time,with the given input xml file, it has given me the response with the same GUIDwhich is shown in the above example, How is it possible?I tried by creating the send port with the different options for the URL path as given below and also with the virutal directory as given below.Option1 : http://<CRM-Server name>/MSCRMServices/2006/CrmService.asmxOption2 : http://<CRM-Servername>/MSCRMServices/2006Option3 : http://<CRM-Servername>/MSCRMServices/2007/CrmService.asmxOption4 : http://<CRM-Servername>/MSCRMServices/2007And also, please let me know , where I can see the inserted record in the CRM Tool inserted with the above sample. Please let me know which version of MS CRM has been used in the above example.Please respond to me ASAP. Thanks in adavance.Vaasu K
Anonymous
April 30, 2009
Hi RajensI got it, I did some R & D and now I am able to create the record in the crm tool and also I am able to see that in the CRM tool,I just need one clarification,Will the CRM adapter supports batch processing, will it support inserting the entity records in batch. Say for ex. take the Lead Entity, If i map the source to the Entity Request schema, will it create all the records (from Source xml ) in one shot.Thanks in AdvanceVaasu LK

次の方法で共有

Using Microsoft BizTalk Dynamics CRM Adapter – Part 2

Comments

その他のリソース