Custom Entity Icons in Dynamics CRM

Printer-friendly version

Recently, I had been making some seemingly simple adjustments to a CRM environment and ended up uncovering a lot of useful (but not very well-documented) information on icon usage in MSCRM - here is how it all played out.

Users are mentioning that the icons for custom entities in CRM for Outlook all look the same, and don't reflect what they see in the Web UI. Here is what they see:

As you can see, the icon for an OOB entity, such as Accounts, shows up just fine, but custom entities do in fact all use the same icon. From looking at it, I can tell that the icon being used is that of the "Multiple Prospects" entity. So, why are they all using the same icon? I double-checked the "Update Icons" dialog for each of the entities and could verify that they all were pointing to different Web Resource icons. I decided I would look at the SiteMap and see if I could find any differences between the OOB and custom entities in the XML. That is where I saw some of the elements were referencing an Icon attribute like the Dashboards SubArea:

I haven't really done a lot of SiteMap changes outside of the basic addition of a custom entity, so I just started experimenting with this Icon attribute to see if I could get a different image to show up in Outlook. I added an Icon attribute to the Multiple Prospects entity and referenced a different Web Resource image, published and went back to Outlook. While testing, opening and closing Outlook, rebooting my environment, I finally got this new image to show up - which led me to believe that there was some image caching going on. A quick search online and I was able to determine that the CRM for Outlook Icon Cache is located at C:\Users\[YourUserName]\AppData\Local\Microsoft\MSCRM\Client\IconCache, so I deleted the folder's contents and restarted Outlook again which seemed to do the trick for refreshing the icons.

Ok, great news, I see the icon! There's only one problem... all of the custom entities now have this new icon. I only specified the new Icon attribute for the first custom entity "Multiple Prospects," so why now am I still having the same problem, but this time with a new image? I did some searching online and really didn't come up with much, until I finally stumbled across this Microsoft Connect post. The main description discusses using the Icon attribute in a SubArea and not seeing the icon displayed. The post is marked as resolved with no real explanation and all the commenters still sound confused, but then I checked out the "Workarounds" tab and that is where I found the information I was looking for. A user named Jeff_Woodard has a workaround describing an issue with simulated paths in Web Resource names. For example, if you have an image new_/images/navImage32.png it won't be displayed, but if you reference it as new_navImage32.png, you will see the correct image. So I looked at our Web Resources and saw that all of them used a simulated path similar to new_/img/new_multipleprospects/icon16x16.gif. If only the last portion of that name is used as a reference, we have a problem because all of our Web Resources are named icon16x16.gif, the only difference being the simulated path prefix. I went back to the IconCache folder for Outlook and my suspicions were confirmed when I saw this file:

There was my icon in the cache... or one of them at least. Since the first icon had this name, and was being cached, all of the other entities (who also referenced an icon16x16.gif) just kept using the same icon from the cache. So I went through and renamed our Web Resources to have unique names (after the simulated path), cleared my Outlook icon cache, and success!

Each custom entity, now displayed its correct icon... but we're not done with our weird image problems yet. As you can see from the last image, our icons are a little hard to see. We opted for a gray icon to match the lookup icons for OOB entities in the Web UI, but as you can see, they get a little lost in Outlook when you are using the "Black" color scheme. When you define icons on an entity you select a 32x32 image for the SiteMap, and a 16x16 for smaller icons, but the OOB entities seem to have their own icon set in Outlook. If we change our 16x16 to match the appearance of Outlook, they will no longer match in the Web UI - so what now? We decided that since the Web UI is on a white background, we will just forget the transparency and put a white background on our images, that way the Web UI images still match, but the icons will become more visible in Outlook. We updated the images, and here is our result:

What? Now the images just look grainy and terrible. I recalled that once while testing I tried using an image that was just a solid red square, and it showed up as completely transparent in Outlook. Outlook must be attempting to strip out a solid color in the background of the icon to make it appear more transparent, but unfortunately for our eyes it is not very successful. I'm not sure how Outlook determines where the background starts and ends, so I tried just adding a dark 1-pixel border around my white-background image, and luckily that seemed to fix the problem (see "Bidders"):

If I change my Outlook color scheme, I can more easily see that Outlook as just stripped the 1 pixel border, but the remaining white background is intact.

Great, but we have yet another issue. Our icons have a dark border around them, which is now visible in the Web UI, so our icons no longer match the OOB entity icons. I won't get into detail about my trial-and-error testing, but after a lot of experimentation, I found that we could revert our icons in the "Update Icons" dialog of the custom entities back to the original grey transparent icons, and specify our Outlook-specific icons in the SiteMap using the SubArea element's Icon attribute. So really we are now utilizing three sets of icons (32x32, 16x16, Outlook-specific) - just like the OOB entities. 

In summary:

  • Make sure your Web Resource images have unique names, aside from any simulated path you may be using.
  • If you want to have Outlook-specific icons, utilize the Icon attribute in the SiteMap.
  • Clear your Outlook icon cache before restarting Outlook and looking for your new images. Sometimes it takes a minute to retrieve the new images from CRM, so wait until the CRM data is done loading.
  • As a side note, I also took a look at the SiteMap XML documentation and found that the SubArea element actually has an attribute called "OutlookShortcutIcon." I tried using this instead of the Icon attribute, but it did not display the new image. I'm not sure if this is because of my version of Outlook, CRM, etc., and unfortunately I didn’t find any additional information on this attribute to explain why it didn't work for me.

About the Author:

TopLine Strategies delivers the complete integration and development of sales, marketing and customer service technologies that enable corporate clientele to improve revenue streams and strengthen customer interactions. Our project management and consulting is designed to achieve timely delivery, 100 percent user adoption of the technologies we implement and deliver measurable returns on investments for our clients.

Comments (0)

Related Blogs

TheReact Native Open Source roadmap was announced in Q4 2018 after they decided to invest more in the React Native open source community.

October is not just about pumpkins, fall foliage, and cooler temps anymore. October 2018 also means the exciting introduction of Microsoft Dynamics 365 for Customer Engagement.

Back in 2016, Microsoft introduced its intentions to refresh its CRM and ERP strategy with Dynamics 365. At the heart of its services was the Common Data Model (CDM).