My current project integrates with the Microsoft Dynamics CRM system for managing customer records. We already spiked out authenticating and our next step was attempting to update a record via its “REST Endpoint“.

On retrieving a record, you follow the OData style for finding something of relevant. Updating a record is interesting as we only want to send the fields that need to change remotely. Looking at their sample code, you need to:

  • Create an authenticated POST request
  • Set the X-HTTP-Method to MERGE
  • Set the appropriate content type for the content you intend on sending. In our case, set the header Accept to application/json and the Content-Type to application/json; charset=utf-8

Our end point for a contact looked something like:

https://crm.thekua.com/xrmservices/2011/organizationdata.svc/ContactSet(guid'867dc3f2-909e-e111-9912-0050569c2d72')

.

Updating simple fields off a contact is easy. We post something like: 

{
  "EMailAddress1":"spike.jones4@gmail.com",
  "MobilePhone":"33335"
}

We receive a HTTP 204 (No Content) on a success. Posting an invalid attribute (i.e. one that does not exist on the ContactSet such as “EMailAddreXXXs1”) results in a HTTP 400 (Bad request) and a nice description about what’s wrong. You will also get a HTTP 400 if you post the wrong datatype such as sending a string where they expect a number. If you pass invalid values (but of the correct datatype) for a field, your response is a HTTP 500 with a message like The value of 'gendercode' on record of type 'contact' is outside the valid range."

Updating Option Set Values

Updating simple datatypes is easy and obvious from a JSON point of view. You have a couple of complex datatypes, such as the standard GenderCode. When you query for a record, you get back something that looks like 

{"GenderCode"=>{"__metadata"=>{"type"=>"Microsoft.Crm.Sdk.Data.Services.OptionSetValue"}, "Value"=>1}}

To update something like this, you need to send a nested JSON object. The example follows 

{
  "EMailAddress1":"spike.jones4@gmail.com",
  "MobilePhone":"33335",
  "GenderCode": { 
    "Value" : "1"
  }
}

A HTTP 204 (No Content) response indicates a success. Viola!