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)
<Property TypeID="System!System.Entity" PropertyID="DisplayName"/>
Set entity display name property in a registry discovery (suggesting PrincipalName)
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:
<Name>I'm a display name!</Name>
<Description>I'm a description of this thing!</Description>
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.