Grass Valley iControl V.6.02 - Manual (Page 316)

Alarms in iControl
General Guidelines for Alarm Attributes
306
General Guidelines for Alarm Attributes
Make URIs Meaningful
Typically, administrators want URIs are identifiers that administrators want to hide as much as
possible from end users, but it doesn't mean we want them to be totally opaque identifiers
like GUIDs. It is often useful to actually look at the URIs when troubleshooting, and when that
happens it's very hard to tell at first glance if an assignment is correct if all you have to look at
is a GUID or something equally cryptic. URIs don't have to be self-documenting or even
especially user-friendly, but they should be meaningful to humans. This way they can be
memorized, transcribed and understood more reliably.
Avoid redundancy
Information redundancy in URIs is bad. A bad example would be to include both a host name
and corresponding IP address in URIs "so they are readily available". Not only does it make URIs
longer, it also makes them brittle (if any one of the host name or IP address changes, it breaks
all uses) and impractical (users need to remember/store both elements of information when
they want to use the alarm). Pick one or the other and stick with it.
Likewise, avoid packing all sorts of information in a URI that does not serve to uniquely
identify it. For instance there were proposals to embed SNMP OIDs in the URIs of the derived
GSM alarms, but that requires all users to know that bit of information on top of everything
else, unless you make it optional (but that would require more complex parsing which doesn't
exist today). The approach here is to make a call to GSM (or one of its plug-ins) to obtain more
information when required, like we do for instance when we "resolve" an alarm URI to obtain
Device URI A unique identifier for the (hardware) device providing the alarm.
The device URI is used to group together alarms that pertain to the same device. Typically, one device
handles one channel or signal. This attribute allows us to see all alarms related to a given channel or signal as
well. The GSM contextual log viewer uses the Device URI to find alarms related to one another. Perhaps more
importantly, a number of metadata fields are attached to each GSM device using this field as a key. This
should influence the way device URIs are built so that for devices with multiple ports (usually sources), their
URIs should include an indication of the port number, so each source gets its own source metadata and the
alarms are grouped by source.
• Separate the various parts of the URI with a forward slash ( /)
2 . This allow us to have relative URIs.
• Device URIs and Long IDs should be the same. In the past, long IDs were sometimes allowed to contain
spaces, which is forbidden in URIs, so they need to be encoded "just in case". Some URIs are derived from
long IDs, but with only selected parts encoded.
Device class Device model name. Typically, this is product marketing name; for instance, for the Densité line this would be
something like DEC-1002. iControl doesn't use this in any particular fashion, but occasionally users will use
this field when searching the logs to identify problems across a product family. For instance, if you see a
specific problem with an XVP-3901 you might search for similar problems with other XVP-3901's, and not jsut
the one where you noticed the problem -- "do I experience audio losses on all my XVPs?".
1. Multiple paths for same alarms are not supported. The last specified path will be used. By convention,
each segment of the path uses Sentence case, as opposed to for example Title Case or even ALL CAPS.
2. Legacy Densite/Imaging URIs use the _ character, however.
Attributes of an alarm (Continued)
Attribute Description