I was recently asked what the .data property is on a client-side CRM PartyList Item.  The SDK has this to say “Any other data. Optional for set.”  That of course is not much help.

If we dig a bit deeper into the code we find that the Lookup data property is rarely used.  In fact 98% of the time it is blindly copied about and rarely if ever parsed.  So what is it used for?

My memory is hazy as to why we added this one upon a time, but I vaguely recall it was added for special cases where we just needed a nip of “data” to be preserved.  One of those cases is with the Resolve Email Address feature of CRM.

In Microsoft Dynamics CRM users can type into a Lookup control and have the system attempt to resolve the name to a record in the system.  If you type “Mr. Data” it will look for Party Members (Accounts, Contacts, Leads, Users or Queues) with that name.  If it finds one, it links it up... if not you get a red warning.

A red X means the item could not be resolved. 

If you type in an email address however, it does a similar search except it looks by email address.  If your system is so configured, you can even use the unresolved email address “as is” otherwise users are required to resolve it.  When a matching record is not found, you can click on the link / question mark and use the Resolve Address dialog to match the email address to a new or existing recording.

A red question mark means it could not find a match via an email lookup.

 
 The Resolve Account Dialog

From a client-side SDK standpoint, there are some important behaviors to notice:

• When a lookup item is found – you can access the .DataValue property normally as an array of Lookups.
  
• When a lookup item is not found by name ( ) – the .DataValue property is NULL.  Since this is a PartyLookup and you might have three items in it… 2 found and 1 not found, your array will only have 2 items in it and the unresolved item will NOT show up in the array.
  
• When a lookup item is not found by email ( ) – the .DataValue property is available and the item is accessible.  The “.data” property is now populated with the string of the original email addressed searched on.  Its silly, but the “name” property is as well.

Here is an example:

In this case, the following code returns “2”:

crmForm.all.to.DataValue.length

And this code returns a STRING of “mr.data@trek.com”

crmForm.all.to.DataValue[1].data

Notice that my array index is 1, this is because JavaScript arrays are zero-based and the “asdfasd” item is not resolved and as such is not in the array.

There may be other cases where the .data property is set, but they are not obvious.

Disclaimer: This posting is provided "AS IS" with no warranties, and confers no rights.