REQUEST A DEMO

User-Defined List (Hgbst) utility

 

A common source of bad or corrupt data in an Amdocs/Clarify system is in the area of User-Defined lists.

 

It’s not uncommon to find issues such as:

  • orphaned elements
  • duplicate elements
  • a level referencing a non-existing element
  • a level referencing a non-existing parent level
  • lists that don’t have a root level
  • elements linked to multiple levels or multiple lists
  • lists with a loop in the element/show hierarchy
  • etc.

 

Many of these issues can be identified using the Data Verifier utility that is included as part of the Dovetail SDK. However, when the data is really bad, other tools may be useful.

How does data get this way?

 

The most common way that I’ve seen data end up in this state is by developers incorrectly trying to add/update user-defined list data programmatically. The data model for this data is confusing. Very confusing. Programmatically trying to write data against these tables is difficult. And the end result is typically a whole bunch of bad data.

 

I’ve also seen corrupt baseline lists before, such as the “Assessment Response” list, which had a loop to itself. And because of the loop, the list can’t be deleted using the UI. Doh!

HGBSTs

 

User-defined lists are also commonly referred to as HGBST lists. HGBST is an acronym for Hierarchical GloBal STring list. User-defined lists are stored in the HGST tables:

  • hgbst_elm
  • hgbst_show
  • hgbst_lst
  • mtm_hgbst_elm0_hgbst_show1

Data Model

 

Here’s what the model looks like:

hgbst

 

Told you it was confusing – especially when you get into the multiple hgbst_show to hgbst_show relations. The MTM can also be confusing. A show (level) having many elements makes sense, but an element belonging to many levels? odd.

Another tool in the toolbox

 

As we’ve helped customers clean up their data over the years, we’ve developed tools that can help. I mentioned the Dovetail SDK Data Verifier earlier. Another such tool is the HGBST Utility.

The HGBST Utility

 

The HGBST Utility is a tool for visualizing user-defined lists (HGBST data). It’s a Windows command line application that connects to a Clarify database and allows for simple visualization of HGBST data. This is especially helpful when troubleshooting bad data.

 

It does not require the Dovetail SDK, nor is there any fee or license to use it.

 

It can:

  • Output a tree-view display of all HGBST LISTS or a specific LIST or set of LIST
  • Output the LIST tree for a given Element
  • Output the LIST tree for a given Show (level)
  • Output the LIST tree for a given LIST

 

Each operation will output a tree-view display to the console. This shows how the list/show/element hierarchy looks for the particular LIST or set of LISTS specified.

 

If there is corruption in the LIST structure, this will be noted in the output with a special flag: *** ERROR ***

 

If a particular list contains a loop condition, processing will stop after the 2nd time a particular SHOW is seen in the same LIST hierarchy.

 

Lets take a look at running it and seeing how it works.

Output a single list

 

Here’s an example of running the utility, and having it output the multi-level list “FAMILY” list:

 

DOS> hgbstutils.exe /db_name dovetail /db_server localhost /db_type MSSQL /db_user sa /db_pass myPassword  /tree “FAMILY“

 

LIST[1]: FAMILY (268435460)
| |_Show: lev1 (268435476)
| | |_Element: All (268435504)
| | | |_Show: lev2 (268435462)
| | | | |_Element: All (268435505)
| | |_Element: Hardware (268435506)
| | | |_Show: Hardware Line (268435460)
| | | | |_Element: PC Hardware (268435507)
| | | | |_Element: Server Hardware (268435508)
| | | | |_Element: All (268435509)
| | |_Element: Software (268435510)
| | | |_Show: Software Line (268435461)
| | | | |_Element: All (268435511)
| | | | |_Element: Operating Systems (268435512)
| | | | |_Element: Application SW (268435513)

 

Notice that it outputs the list, each show (level), and each element. It includes the title of each list, show (level), and element; along with the objid of each.

Output the LIST for a given Element

 

Here we’ll give it the objid of an element, and the utility will output the list to which this element belongs:

 

DOS> hgbstutils.exe /db_name dovetail /db_server localhost /db_type MSSQL /db_user sa /db_pass myPassword  /elm268435505
LIST[1]: FAMILY (268435460)
| |_Show: lev1 (268435476)
| | |_Element: All (268435504)
| | | |_Show: lev2 (268435462)
| | | | |_Element: All (268435505)
| | |_Element: Hardware (268435506)
| | | |_Show: Hardware Line (268435460)
| | | | |_Element: PC Hardware (268435507)
| | | | |_Element: Server Hardware (268435508)
| | | | |_Element: All (268435509)
| | |_Element: Software (268435510)
| | | |_Show: Software Line (268435461)
| | | | |_Element: All (268435511)
| | | | |_Element: Operating Systems (268435512)
| | | | |_Element: Application SW (268435513)

Output the LIST for a given Show (level)

 

Here we’ll give it the objid of a show (level), and the utility will output the list to which this level belongs:

 

DOS> hgbstutils.exe /db_name dovetail /db_server localhost /db_type MSSQL /db_user sa /db_pass myPassword  /show 268436044

 

LIST[1]: Solution Status (268435598)
| |_Show: Level 1 (268436044)
| | |_Element: Draft (268438870)
| | |_Element: Pending Approval (268438871)
| | |_Element: Approved (268438872)
| | |_Element: Retired (268438873)
| | |_Element: Rejected (268438874)

Output all lists:

 

Here we can output all of the lists. Rather than streaming this to your DOS console, I recommend redirecting the output to a file:

 

DOS> hgbstutils.exe /db_name dovetail /db_server localhost /db_type MSSQL /db_user sa /db_pass myPassword   /tree> hgbst.out

 

No surprise, the output will be thousands of lines long. Here’s an example: http://dovetail.pastebin.com/raw.php?i=NjwckjwL

Get It

 

The HGBST Utility is freely available on github at https://github.com/DovetailSoftware/hgbst-utils

 

If you just want to simply run the executable, download and unzip the hgbst-util.zip out of the output directory.

Another tool in the toolbox

 

Hopefully you can use the user interfaces available for maintaining your user-defined lists. But should you find a need to get your hands dirty with the raw data – hopefully you’ll find this tool useful.

 

Rock on.