Using Microsoft BizTalk Dynamics CRM Adapter – Part 5

Welcome to last article of this series. Today, we are going to talk about using some CRM specific field types such as “Lookup” and “Picklist”. We will also have little talk about using custom entities/attributes.

“Lookup” field is used to link two entities together. For example, when we create an account, we link account entity instance to a contact entity instance where contact is primary contact person for account. In this case, “lookup” type field is used to link account and contact entities. When you see account entity details and screen, you will find “Primary Contact” field as “Lookup” type.

“Picklist” is similar to options/combo control where user can select a value from existing set of values. For example, “Address Type” field of account entity is “Picklist” type with option values as “Bill To”, “Ship To”, “Primary” and “Other”. Picklist type fields can be displayed as combo box or radio buttons on entity form.

I strongly suggest checking my previous articles for complete context as I am keeping this article very short and to the point.

Using “Picklist” and “Lookup” fields in .net code (calling CRM web service)

I am going to create an account instance and would use both “Lookup” and “Picklist” type fields in code.

Procedure is the same; I added CRM web service as web reference and named it “CRMServer”. Following is code to update contact instance in CRM system.

CrmServer.CrmService service = new CrmServer.CrmService();

CRMServer.account myaccount = new CRMServer.account();

myaccount.name = "my account";

//Handling Lookup type field

CRMServer.Lookup primaryContactLookup = new CRMServer.Lookup();

primaryContactLookup.Value = new Guid("23e923d8-5cc6-4574-bd34-f1c43130a4bb");

primaryContactLookup.type = CRMServer.EntityName.contact.ToString();

myaccount.primarycontactid = primaryContactLookup;

 //Handling picklist type field

CRMServer.Picklist addressTypePicklist = new CRMServer.Picklist();

addressTypePicklist.name = "address1_addresstypecode";

addressTypePicklist.Value = 2;

myaccount.address1_addresstypecode = addressTypePicklist;

System.Guid newAccountId = service.Create(myaccount);

I first created an instance of CRM web service client.

CrmServer.CrmService service = new CrmServer.CrmService();

Then I created instance of account entity and supplied name field which is required.

CRMServer.account myaccount = new CRMServer.account();

myaccount.name = "my account";

Next I am handling “Lookup” type field and linking account and contact entity instances. First, create a new instance of lookup type then assign value to “Value” and “Type” fields.
“Value” field is assigned value of “contactid” (primary key GUID) for contact to be linked. In your implementation, you can run query over contacts using “Fetch” or “Retrieve” method to get required contact and its internal id field “contactid” (primary key value). In “Type” field, we assign name of the entity we are linking to account entity. In our example, it is “contact” entity. You can use “EntityName” enumeration class to get contact entity name or can hard code to “contact” string value. However, first method is preferred. When lookup data is ready, we assign it to appropriate field in account entity.

//Handling Lookup type field

CRMServer.Lookup primaryContactLookup = new CRMServer.Lookup();

primaryContactLookup.Value = new Guid("23e923d8-5cc6-4574-bd34-f1c43130a4bb");

primaryContactLookup.type = CRMServer.EntityName.contact.ToString();

myaccount.primarycontactid = primaryContactLookup;

Now “Picklist” type. Coding is similar to lookup type field. Create an instance of “Picklist” type and then assign values for “name” and “value” fields. Each option provided by pick list has a numeric value assigned to it. For example in our case of “Address Type” field; following are numeric values assigned to text options - “Bill To” = 1, “Ship To” = 2, “Primary” = 3 and “Other” = 4.

In my sample, I selected option number 2 (text value “Ship To”). Name field contains schema name of “Address Type” field which in our case is "address1_addresstypecode”. Finally when pick list is populated; assign it to appropriate field in account entity.

//Handling picklist type field

CRMServer.Picklist addressTypePicklist = new CRMServer.Picklist();

addressTypePicklist.name = "address1_addresstypecode";

addressTypePicklist.Value = 2;

myaccount.address1_addresstypecode = addressTypePicklist;

Good, now time to call create method to create a new account.

System.Guid newAccountId = service.Create(myaccount);

Job Done.

Using “Picklist” and “Lookup” fields in BizTalk Orchestration (CRM Adapter)

Process is the same as we did in previous articles. Create BizTalk project and generate CRM entity schema using send port (CRM adapter based) and web service.

When you generate account schema for “create” operation, it generates a schema named “account_Entities.xsd” which is used to create request message for create account operation.

If you check “Primary Contact” (lookup type) and “Address Type” (pick list type) fields of account schema, it looks similar to what we did in .net code above.

“Primary Contact” field looks like following –

primaryaccountid

          |__ IsNull

          |__ name

          |__ type

          |__ dsc

We assign value similar to .net code –

Primaryaccountid ------------ assign value = "23e923d8-5cc6-4574-bd34-f1c43130a4bb" ---

          |__ IsNull

          |__ name

          |__ type ---------------- assign value= “contact” ---

          |__ dsc

“IsNull”, “name” and “dsc” fields are optional. Set “IsNull” field to true if lookup field is optional and you don’t want to populate this field. “Name” can hold schema name of lookup type field. And “dsc” can hold brief description about usage of this field. You can use some other message field or script functoid in map to assign these fields.

When we check “Address Type” field, it looks like following –

address1_addresstypecode

          |__ IsNull

          |__ name

Again, value assignment is similar to .net code -

address1_addresstypecode ------------ assign value = 2   --

          |__ IsNull

          |__ name ---------------- assign value= “address1_addresstypecode” ---

“name” and “IsNull” fields are optional. Set “IsNull” field to true if “Picklist” type field is optional and you don’t want to populate this field. “name” field is populated with schema name of the field.

Populate request message as directed above and you are all set to perform create account operation. Please refer previous articles to understand other required things as I have focused on populating “Lookup” and “Picklist” type fields only.

Using Custom Entities/Attributes

Using custom entities/attributes are no different than CRM system entities and attributes. Thanks to metadata driven approach used by CRM system which gives CRM extensibility to a new dimension. Once you create and publish a custom entity or custom attribute, it is ready for use in CRM web service and CRM adapter.

When using CRM adapter, you will see custom entities listed in schema generation process. Similarly, you will also find custom attributes listed in generated schema.

Similarly, when you use reference web service, you will find custom entities and attributes generate as part of proxy code.

In both of the scenarios mentioned above, it uses CRM metadata web service to fetch latest CRM schema and generate proxy code/schema based on that.

If you have already created one application using CRM web service and then updating CRM schema with custom entities/attributes then you need to update web service reference in application to get hold of updated entities/attributes.

On similar lines, if you already have a BizTalk application using CRM adapter and you make any change in CRM schema for custom entities and attributes, then you have to regenerate schema for consuming them.

Conclusion

You would have seen that “Lookup” and “Picklist” data types are little tricky but simple to use. Nice part is that custom entities/attributes do not make any difference to programming CRM. You just need to update web service reference or regenerate schema in case of BizTalk programming to get hold of changes.