Microsoft Dynamics CRM uses a number of special fields for special purpose, those fields used to require using special SOAP messages in order to update them.
For instance, almost every CRM entity has statecode and statuscode fields which represent the status of CRM records. In order to update a CRM record's status, you would have to use SetStateRequest message. Another example is the ownerid field which is available to all entities that are setup as a user-owned entity. In order to update ownerid field, you would have to use AssignRequest. The list goes on including similar fields such as:
- systemuser entity's parentsystemuserid field (requires SetParentSystemUserRequest message to update the field)
- systemuser entity's businessunitId (requires SetBusinessSystemUserRequest message to update the field)
- team entity's businessunitid (requires SetParentTeamRequest message to update the field)
- businessunit entity's parentbusinessunitid field (requires SetParentBusinessUnitRequest message to update the field)
- equipment entity's businessunitid field (requires SetBusinessEquipmentRequest message to update the field)
This has made writing data integration code unpleasantly difficult, your integration solution will break if you don't handle those fields specifically. This has also caused some performance issues. In a data migration/integration project, it is very common that you have to make three service calls to make an update to one CRM record, which include the first service call to update all regular fields of the CRM record, a second one to assign the ownership using AssignRequest, and a third one to update the record's status using SetStateRequest. The following snippet shows the typical code pattern that you would use when you need to update a CRM record.
using (var service = new OrganizationService(crmConnection))
{
Entity account = new Entity("account");
account["accountid"] = new Guid("0C2D5AC7-B7E4-E411-80E9-C4346BAC7DA8");
account["name"] = "Adventure Works Inc.";
account["creditlimit"] = new Money(100000);
// Service call 1 - Update all regular fields
var updateRequest = new UpdateRequest() { Target = account };
var updateResponse = (UpdateResponse)service.Execute(updateRequest);
// Service call 2 - Assign the record's ownership
var assignRequest = new AssignRequest()
{
Assignee = new EntityReference
{
LogicalName = "team",
Id = new Guid("042d5707-6fe5-e411-80e5-fc15b428fa14")
},
Target = new EntityReference
{
LogicalName = "account",
Id = new Guid("0C2D5AC7-B7E4-E411-80E9-C4346BAC7DA8")
},
};
var assignResponse = (AssignResponse)service.Execute(assignRequest);
// Service call 3 - Update the record's status by setting its statecode, statuscode fields
var setStateRequest = new SetStateRequest()
{
EntityMoniker = new EntityReference
{
LogicalName = "account",
Id = new Guid("0C2D5AC7-B7E4-E411-80E9-C4346BAC7DA8")
},
State = new OptionSetValue(1), //inactive
Status = new OptionSetValue(2) //inactive
};
var setStateResponse = (SetStateResponse)service.Execute(setStateRequest);
}
The Good News
With CRM online 2015 Update 1 release, you no longer have to make special service calls to update those fields, you can simply put all special fields in the same property bag and use one service call to update the CRM record. This makes it significantly easier to write integration code, and at the same time it now offers a much better performance due to the reduced service calls. The following is the code that you can use for the same purpose as above if you are on CRM Online 2015 Update 1.
using (var service = new OrganizationService(crmConnection))
{
Entity account = new Entity("account");
account["accountid"] = new Guid("0C2D5AC7-B7E4-E411-80E9-C4346BAC7DA8");
account["name"] = "Adventure Works Inc.";
account["creditlimit"] = new Money(100000);
account["statecode"] = new OptionSetValue(1); //inactive
account["statuscode"] = new OptionSetValue(2); //inactive
account["ownerid"] = new EntityReference { LogicalName = "team", Id = new Guid("042d5707-6fe5-e411-80e5-fc15b428fa14") };
var request = new UpdateRequest() { Target = account };
var response = (UpdateResponse)service.Execute(request);
}
Hope you can see the benefits by comparing the above two code snippets that actually do the exactly same thing.
Some Final Thoughts
- Unfortunately CreateRequest does not include this enhancement as of this release, which could benefit from this capability by saving a service call for statecode and statuscode fields. CreateRequest does support including ownerid field directly. However, if you need to work with statecode, statuscode fields when creating CRM records, you will have to send in an additional service call (SetStateRequest) if the statecode is not the default statecode (Active for most entities). I will create a feature request for this particular issue on Microsoft connect site. I will share the URL here once that becomes available, so you can help vote up. (Update - May 20, 2015, here is the link of the Connection item).
- Consider that the above special messages are deprecated as per CRM online documentation page, which means that you should start moving away from using those messages.
- Watch those plugin pipeline changes mentioned in the CRM online documentation page: Perform specialized operations using Update.
- Your CRM plugin registered under SetState message should be registered under Update message as well in order to capture the status change if you take the new Update approach.
The less special messages to deal with, the better. Do you agree?
Read the full New SDK Capabilities Blog Series:
- Part 1 - Alternate Keys
- Part 2 - Upsert
- Part 3 - No more special messages for special fields
- Part 4 - Plugin Trace Logging
- Part 5 - Entity Change Tracking
- Part 6 - Transactional Batching
- Part 7 - Optimistic Concurrency
- Part 8 - New Query Operators
- Part 9 - Detect SDK Capabilities by Checking CRM Server Version