Entity Image: Adding Images to Dynamics CRM Data Types

Microsoft Dynamics CRM 2013 is coming very soon to a server near you, and although the majority of attention has been focused on specific new features (such as the Process Manager) and the sweet UI re-design, I’d like to focus on another infrastructure change that’s bringing with it a world of potential.

I would like to introduce… the Image data type known as EntityImage. In this post, I’ll talk about why I’m interested in the new data type, limitations in how it can be used, and share some potential ways I see it being used in customer applications.

What’s The Hub-Bub About?
All of the data types previously available in Dynamics CRM 2011 have been carried over to Dynamics CRM 2013. The list is near and dear to all who customize: single/multiple lines of text, option sets, numbers (whole/floating/decimal), currency, date/time, and lookups. These are all effective containers to capture data without a face. With Entity Image, we now have an additional field that can visually represent the data being entered.

The vision for the Dynamics CRM image data type is clear: mimic what Outlook does with Contacts. In the Outlook Contact form, you can elect to upload an image of your contact. The image is typically a head shot, and is meant to be a visual cue when meeting with a person. This is a popular option among those who use their cell phones, as well as those connecting their contacts to services such as Facebook or LinkedIn.  Dynamics CRM 2013 wants you to use this feature in a similar fashion. (For example, you can use the image as a reference within your sales team after a client meeting, so you don’t have to ask, “Who was that person sitting in the third chair?”)

Image Limitations in Dynamics CRM 2013
Before we go too far into the possibilities of this new feature, there are some limitations to the image data type as of the time of this article.

  1. You can only have one image per entity form out of the box. For those that were instantly thinking about a visual product catalog, you can still represent your products, as long as you can do it with one image per product (I’ll illustrate a way to accomplish this later in this post). Trying to add more than one image to an entity’s field list will not work, as CRM will rename any image field name to entityimage and presents you with a duplicate id error when you try to save.
  2. When adding an image field to a form, there is only one location where it can be displayed: top left of the form, just left of the form title. Nope, you don’t get to move it around the form as you desire.
  3. Images are not an available column for view columns and cannot be displayed as a column of a view, unless you write your own client to view records.
  4. Images cannot be modified via the new Business Rules feature in Dynamics CRM 2013. There is no way to manipulate the value of the associated image through the UI, and I’ve tried.
  5. Image file types are limited in a similar manner to file attachments. Dynamics CRM 2013 continues on the path of its older brethren, restricting file types to image’s big 4: JPG, PNG, GIF, and ICO.
  6. Dynamics CRM restricts the size of images to a maximum of 144px x 144px.  I use the word “maximum” because of the way that Dynamics CRM “crops” photos.
    – If both width and height exceed 144 pixels, the image will be resized, preserving the display ratio, so that the shorter side is 144 pixels. The longer size will be center cropped to 144 pixels, creating the 144 x 144 maximum size.
    – If one or both of the sides is less than 144 pixels, the longer side will be center cropped to match the size of the shorter side, creating a square image. So if you have a 92w x 160h image, the 160h will be center cropped to 92, creating a 92×92 image.

Creative Uses For Images
By default, Dynamics CRM 2013 adds the Image field out-of-the-box to 24 entities and enables it by default on 8 of these entity forms (source: Dynamics CRM 2013 SDK):

Entity

Includes
Image Field

Enabled On
Entity Form

Account

Y

Y

KbArticle

Y

Campaign

Y

Incident

Y

Competitor

Y

Y

Connection

Y

Contact

Y

Y

Contract

Y

TransactionCurrency

Y

EmailServerProfile

Y

Goal

Y

Invoice

Y

Lead

Y

Y

Mailbox

Y

OpportunityProduct

Y

SalesOrder

Y

Organization

Y

Product

Y

Y

Publisher

Y

Y

Queue

Y

Resource

Y

Y

SalesLiterature

Y

Territory

Y

SystemUser

Y

Y

Why these particular entities? People may have called me Nostradamus for my ability to predict that account, contact, and lead made this list, but for the others, I would have called myself ignorant at first glance.  Why would a SalesOrder need an image, and why the heck is EmailServerProfile even included in this list?  After thinking about this, there are some compelling reasons to include images to entities.

  •   The most obvious of the categories are people entities such as Contacts and SystemUser, as they can contain an image of the person related to the entity.
  •   Business-related entities such as Organization or Publisher can use this field to display the logo of the related record.
  •   Products can contain a thumbnail of the actual product in stock, or a standard out of stock image if inventory runs out.
  •   SalesOrders or Incident can use the image field as a status-reporting tool to mirror the item state, displaying a red icon for open (active) items, or green/grey to show completed (resolved/closed) items.

Code Sample for Manipulating Entity Images
If you have a primal fear of Dynamics CRM plugins, this next part isn’t for you! When adding an Image  to an entity’s field list, there are three fields added to the programmatic reference for images.

  •   EntityImage_Timestamp allows Dynamics CRM to validate that it is using the last version of the image added to the entity.
  •   EntityImage_URL allows for an externally available reference URL for customization applications. The image returns a fairly well-formatted URL that references 5 values to ensure the image is unique.
  •   EntityImageId is the identifier for the associated image.

Using these fields, you can leverage the image data type to manipulate the image associated to a record. In order to update the image programmatically, you can update the EntityImage.Value property with a byte array (byte]) that represents the binary value of the image. Note that the resizing rules above are all applied server-side prior to the image being stored in the database.

The example I am using entails taking a plugin to fire on a case’s update post-operation. We want to detect the status of the case (active or resolved) and change the image to either red or green depending on the statecode value. This image will be a visual indicator when deploying a custom client or using the Windows 8 Dynamics CRM 2013 client.

In my Case plugin’s Execute method, I am going to make the following assumptions:

  •   I’ve added an image to the Incident (Case) entity and chose to display the image via the Incident form properties (Display tab)
  •   I’ve got my service context
  •   I’ve validated that I am working with a Case entity
  •   I’m executing my code path for the PostOperation event
  •   The images reside on disk at the path found in the string variables

stringm_statusImageRed = @”C:\\Images\\Incident\\status_red.jpg”;
stringm_statusImageGrey = @”C:\\Images\\Incident\\status_grey.jpg”;

if(entity.Attributes.Contains(“statecode”))

{    OptionSetValue stateCodeValue = entity.Attributes[“statecode”] as OptionSetValue;
byte[] imageBytes = null;
switch (stateCodeValue.Value.ToString())

{       case “0”: // active
if (File.Exists(m_statusImageRed))
{
imageBytes = File.ReadAllBytes(m_statusImageRed);
entity.Attributes[“entityimage”] = imageBytes;
}

break;

case “1”: // resolved
if (File.Exists(m_statusImageGrey))

{
imageBytes = File.ReadAllBytes(m_statusImageGrey);
entity.Attributes[“entityimage”] = imageBytes;
}

break;
}
service.Update(entity);
}

Now, when I update my Origin dropdown value for my demo case, the plugin runs and scans the statecode of the incident. If the statecode is found, it will look up the image and replace it with the image I have on disk. To minimize duplicate image writes, I tried to do a comparison of the image on disk versus the image retrieved from the entity, but I hit the image cropping issue when comparing the array of bytes (the server version was a smaller size).  Keep this in mind as you optimize your code.  You can see the proof in the case screenshot below (just left of the case title).

How do you plan on using images, given this information?  Let me know! Leave your feedback below, or email us directly with your thoughts at marketing@westmonroepartners.com

Phone: 312-602-4000
Email: marketing@westmonroepartners.com
222 W. Adams
Chicago, IL 60606
Show Buttons
Share On Facebook
Share On Twitter
Share on LinkedIn
Hide Buttons