Best Practices – Display Names

Adding to the best practices category, I will discuss the entity display name.

Note: Check back if you find yourself thinking about this stuff later, because I may update these pages at any time!

 

Entity Display Name

 

The first time I realized entity display name was so important was when I was authoring a monitoring pack some time ago, and while testing some monitors I noticed the alerts had a source of the class system name. I wrote about my experience in a previous article.

I learned a valuable lesson by not assigning a value to entity display name, and it got me thinking about so many other monitoring packs that have the same issue – and some of these packs are from Microsoft, by the way.

The biggest offenders to me are the Windows Operating System packs. There are many monitors in those packs that target types with entity display names of something like "Microsoft Windows Operating System XXX".

Ever notice all the Windows alerts in the Operations console that have a source of "Microsoft Windows Operating System XXX?" When a Windows server is low on free memory, is it useful in any way to draw focus of the operator to the version Windows? I don’t think so – and the source column is the all important default focus column in the console.

The point here is, ALWAYS assign computer name (PrincipalName is preferable in most cases) to entity display name whenever possible – and this is accomplished in the discovery of that object, not in the monitor. I’m not sure why Microsoft and some others haven’t fixed this problem, but I have a hunch it has something to do with versioning – in other words, it was baked into the pack from the beginning, and changing this would break upgrade compatibility for future packs.

I say "whenever possible" because sometimes it’s really not very possible. But 99% of the time, it is. The only time it can be a real challenge, is when we’re dealing with distributed applications, client side monitoring (perspectives) or a connector-based management pack – even still there are ways, but I won’t get into that here.

 

The nuts and bolts of a good system entity display name looks like this.

 

Define entity display name for the class type (not required)

<DiscoveryTypes>
  <
DiscoveryClass TypeID="YourPack.YourClass">
    <
Property TypeID="System!System.Entity" PropertyID="DisplayName"/>
  </
DiscoveryClass>
</
DiscoveryTypes>

 
Set entity display name property in a registry discovery (suggesting PrincipalName)

<InstanceSettings>
  <
Settings>
    <
Setting>
      <
Name>$MPElement[Name="System!System.Entity"]/DisplayName$</Name>
      <
Value>$Target/Host/Property[Type="Windows!Microsoft.Windows.Computer"]/PrincipalName$</Value>
    </
Setting>
  </
Settings>
</
InstanceSettings>

 
Set entity display name property in a script (programmatically passing a name)

call oInst.AddProperty("$MPElement[Name=’System!System.Entity’]/DisplayName$", PrincipalName)

 
Set entity display name property in a script (auto-assign a name – netbios example)

oInstance.AddProperty "$MPElement[Name=’System!System.Entity’]/DisplayName$", "$Target/Property[Type=’Windows!Microsoft.Windows.Computer’]/NetbiosComputerName$"

 

Moving on to other types of display names…

 

Regular Display Names

 

Other types of display names are pretty straight forward throughout the pack – these are just user friendly names your operators and administrators see in the UI. These display names do effect user experience, and are just as important as the entity display name.

Be sure you are familiar with namespaces before getting into display names, because namespace is equally important.

Display names are pretty easy to understand. It’s a short snippet in the pack that assigns a user friendly name to any element. It looks like this:

 

<DisplayString ElementID="YourPack.YourElement">
  <Name>I'm a display name!</Name>
  <Description>I'm a description of this thing!</Description>
</DisplayString>

 

It’s simple. In the LanguagePacks section of the pack (or fragment), just add a few lines to give a user friendly name to the elements that you’ve created – right? Don’t forget a description, because that’s always helpful for others that may be looking at your stuff – don’t pull a "superwall" (inside joke).

For the name – be succinct. 2 to 5 words to briefly describe the discovery, rule, or monitor.

For the description – go to town on what that particular workflow does. This is an opportunity to document what the workflow does, and it’s always good to be verbose here.

At a minimum, ALWAYS provide a display string for classes, discoveries, rules, and monitors. Classes – be minimalistic with 3 or less words, if possible. Pay attention to the fact that classes in other packs might have the same name, so differentiate your class display name from those other classes. An example of a poor name is "Logical Disk", because this name is already assigned to a base class in the Microsoft packs.

Other elements, like relationships, data sources, and monitor types – these things aren’t quite as visible to most operators or administrators. Although it is still imperative to user proper namespace, missing a display name on these elements probably will not degrade usability much, if at all.

 

This is an open forum – your comments are welcome. I do not check or moderate comments (I support freedom of speech).

If you have a particular subject you’d like me to talk about, or to call me out on anything I write, send me a message at https://projects.scomskills.com/messenger/suggestion.

 

😉

11 thoughts on “Best Practices – Display Names”

  1. Thanks for sharing a great post! I couldn’t agree more with the Windows OS example. This really comes into play in Reporting (you ever try to search for an OS object in a report when they are all named the same and part of a large environment?) and in Distributed Application models (the display name gets cut off, so all objects look the same until you click on them).

    In regards to naming class objects, I have been utilizing a pattern of _. This helps alleviates issues with reporting and DA models AS WELL as making it a little easier to track down the appropriate path to a monitor within Health Explorer (if you happen to be looking at it for a parent object). Regardless, the display names make a world of difference when used correctly.

    One last note regarding display names for any object, whether it be the MP itself, monitors, rules, classes, groups, etc., is that you really need to NOT re-use display names if there are separate MPs related to versions. The BizTalk MP drives me insane with the majority of objects, including the MP, all using the same, exact name. This makes it very difficult for scoping, applying overrides, etc., since their is no distinction. Sadly, we ran into this when we had to run the BT Server 2006 and BT Server 2010 MPs together for some time.

  2. Yes – I understand what you mean about including additional identifiable information in a display name when their might be different versions of the pack in your environment (or even completely different applications with similar types). For instance, Logical Disk – you don’t know what you’re getting, because there are several Logical Disk classes.

  3. Jonathan, imho this approach doesn’t work well in many cases. Let’s take a databse file orany other deep-nested object. How long the display name will be?

    1. … continuation 🙂 …

      The practice of using principal name for object’s display name may be good for singletons but is insufficient for multiple child objects. I recall that when I was doing monitoring, looking into the console every day, I used to place name and path columns side by side wherever possible.

      Reporting is unother pain point here. Unfortunately, most MS’s reports tend to overaggregate data and do not treat the report’s scope in a user friendly manner. I do believe that it will be much better to improve reporting but not to include principal name into every object’s name.

  4. Hi Oleg. Entity display name is just one property of the instance – there are several other properties that may be used to describe the instance in more detail. My argument is to not use vague display names, like “C” for a logical disk or the version of Windows, because this directly impact user experience in the console and also has an impact in other workflows, like notification subscription criteria.

    In terms of reporting, as you know (you are the reporting guru), there are ways to find path and use that as criteria and display path correctly in the rendered report or dashboard.

    Thank you for your comments – I appreciate your input. 🙂

  5. Thanks for sharing your lessions learned. One question: If we add a network device (ICMP only), we just see the IP address of that device in the attribute “Display Name”. Is there any way we can change/overwrite that string to a more user friendly name?

    Thanks,
    Oliver

    1. The network device discovery part that adds the Display Name property value would need to be updated from adding the IP Address to adding another value of your choice. This should be possible, but I would hesitate to change this since it’s a core pack. You would need to pay special consideration in where IP Address is being used in actual monitoring. If it is, changing this might break monitoring somewhere.

  6. I already played with the tought to simply change the display name value directly in SQL. If my assumption is correct, then Display Name is just a String designed to be displayed, not to be used for real IP addresses in pings. I know that would not be officially supported but do you think that could be a possible way to go?

    1. Personally, I would definitely not update the database directly for this. It may end up corrupting the database. According to the product group, directly updating the database will always end up in corruption to some degree. Once the system is in a corrupt state, it can be very difficult (sometimes not possible) to recover. The best way to do this is through normal processing of discovery data, in the management pack. If you go the management pack route, you will still be considered in an “unsupported configuration”, but at least you will have a way to easily revert the change by simply importing the original pack.

  7. Alright, thanks for sharing your thoughts. Authoring MPs is on my todo list but I won’t have time to start for another month at least. Luckily I found an alternative (supported) solution to manipulate the display name. It looks like SCOM 2012 R2 does a reverse lookup on the IP and uses the returned string as display name. That also works with local hosts file entries 🙂

Comments welcome (links require moderation)