How to add icons to custom entities in CRM 2011
March 29, 2013 6 Comments
I discovered a couple of weeks ago that one of the things Microsoft did get right in the recent Polaris release was to finally fix the dialogue box for adding your own icons to custom entities in CRM. This prompted me to finally get round to writing a proper article about how to do this.
Why use custom entities which need new icons?
As you develop your CRM system there will very likely come a point where you decide to create your own custom entities (record types) to store business data which is specific to your needs. You might also choose to create a custom entity to store data which you need to control access to, separately from other records. A new entity allows you to control through security roles which users can do what with these records independently of their security privileges relating to other entities.
In fact this kind of customisation is very often a fundamental part of the original design plans for many new CRM systems. This extensibility and versatility of systems such as Microsoft Dynamics CRM is arguably the whole point of a so-called xRM platform rather than a locked-down application which only works in the way the original developer thought up.
In order to make your system as easy as possible to use, it is very helpful to use your own custom icons for these entities so that users learn to recognise them rather than having to read loads of text labels. I have seen CRM systems with several custom entities all just left with the original sad little picture of a gear wheel (or a notebook and gear wheel for custom activities). In CRM 4.0 this may have been because the people who had the rights to customise the system did not have direct access to the server to publish their own icons, in CRM 2011 On-Premise or Online the only reason is not having the know-how to do so.
Wasn’t this made easier in CRM 2011?
When CRM 2011 was released the requirements for the icons were simplified, but unfortunately the key dialogue in the process was inherited largely from CRM 4 which was highly misleading since the requirements had changed. This incorrect dialogue box is shown below for posterity (with corrections).
The new requirements were not very well documented either – MSDN had an incorrect article for ages, the MOC training course 80294A was wrong (corrected in the B version) and I have seen blog posts nearly a year and a half after the release date which had completely inaccurate information
Essentially the requirement was changed in several ways:
- You now only need 2 sizes of icon at 16 x 6 and 32 x 32. The old CRM 4.0 size of 66 x 48 is completely gone and does not show up anywhere in the application. This peculiar size was always a bit annoying and often shortcuts were taken such as stretching a 32 x 32 to be much bigger (horrible!) or padding it with white or transparent space (not much better). The dialogue in CRM 2011 up to UR12 still shows this third choice, but there is no point adding an icon here
- Both icons can be png, gif or jpg files (in CRM 4.0 the Outlook icon at 32 x 32 had to be a ico file – it still can be if you really want and already have a file to use, but don’t bother converting files to .ico especially). I always use png as the alpha transparency can give a much smoother finish against any background than just “on or off” transparency available in gif files.
- Icons are now published first as image file Web Resources then you select the web resource you want to use for each icon.
- Because they are Web Resources, they are “solution aware” so you can copy the files themselves in a CRM Solution and import them into another CRM system.
Updating Icons for a Custom Entity in CRM 2011
In my second post on this topic, I talk about where to get good icons and some tips about creating or customising images to suit your needs. For the purpose of this step-by-step guide I’ll assume you already have on hand two image files in png, gif or jpg format, one at 16 and the other at 32 pixels, and both smaller than 10kb.
Publish images as web resources
The first step usually is to publish your images as new web resources. So open up the solution you are working on which has your custom entities in. This really ought to be a separate solution rather than the “Default Solution” you will see when you simply hit “Customise the system”. A new solution means you can link this to a publisher with a unique prefix. Every new thing you publish in CRM, whether it be an entity, a field or in our case a web resource will inherit that prefix and make it much easier to find later, as well as see who created what customisations.
In the Solution editor, navigate down to Web Resources on the left, and hit “New”
Then fill out the necessary fields. Do include a description for completeness, and this is where you can give attribution if necessary and a link to the source. I tend to always use a naming convention to include the size at the end of the name, rather than the beginning so they two icons are listed together. You might want to prefix the name with something like img or png to get them all grouped in one place – the display name also supports a virtual directory style prefix such as img/IconName_32.
Notice in the screenshot below that the solution prefix of “mit” will form part of the schema name for this new image resource. Once you have browsed to your local image file, hit Save and Close. Because you have just created this, it will be published and available to use immediately, you only need to publish if you change some of the properties or upload a different file.
If you want to use your web resource for something other than an entity icon, such as a Ribbon button or in a HTML web resource for example, then after you Save you will see the URL in the last field which you can use to refer to this image uniquely and dynamically (so if you change the image in the resource, the URL won’t change and everything keeps working).
Repeat for the other sizes and icons that you need, so you end up with something like this in your solution:
Update icons for your custom entity
Next, navigate in your solution and select the entity you want to add icons to. Make sure to actually select it, don’t just twiddle the navigation arrow to expand the node. Now click on the toolbar button “Update Icons”.
Now the new dialogue box appears, and you use the lookups to link to the web resources you published – this is why keeping to a simple naming convention makes your life easier here. (Note I have made the dialogue window smaller before taking this screenshot but have not modified it in any way or removed the third icon option – that is now fixed in UR12 and you are no longer prompted for it).
Click OK and the new icons are immediately published and used in CRM since this is the first time you did this – you will see them in your Solution navigation and top of the screen, which is a handy preview to see how well your transparency is working against the standard CRM colour palette.
And now the “quick way”…
In reality, I tend to do this in a much more fluid, “on the fly” kind of way, so the steps then are more like this:
- Create new custom entity
- While Entity form is still open, click “Update icons”
- In the Select New Icons dialogue, hit the first lookup button to choose a web resource
- But the Web Resource does not exist yet, so click “New” to create it right here and now
- Once you have chosen your image file, click “Save and Close” – remember this also publishes the resource for immediate use.
- Back in the lookup dialogue the resource you just created will be selected already. Click OK.
- Repeat for the second icon
- Click OK to close the new icon dialogue
- Your entity is now using the custom icons you chose.
Where does each icon appear in CRM?
This is very simple:
The small icon is used wherever an entity is referred to in a Navigation pane (in the main “home” screen of CRM or within a parent entity form). It is also used in any lookup field, or on a grid where entity icons are shown (such as Activities or Queues which show records of mixed types). It is also used on the title bar of record windows opened from the Outlook CRM client, and therefore also on Windows taskbar buttons for these.
The large icon is only shown on individual forms for records (and in the Solution editor but users never see that).
The above is true for both Outlook client and any browser client you use. We will have to wait and see which icon is used where in any new tablet apps which are released, or for the new flatter Orion experience.
So, you’ve done it! You now have much more user-friendly and memorable icons for your custom entity – congratulations! If you have any thoughts or questions, please share them in the comments below.