Sitworld: Situation Distribution Report
John Alvord, IBM Corporation
Draft #11 – 11 August 2017 - Level 0.73000
I am often asked how to discover what agents a situation is distributed to. I've been tinkering with this issue. I finally made a first draft.
At Version 0.68000 I added a report section listing Managed System lists that were unused in any situation distribution either directly or indirectly by situation groups.
Situations get distributed through four logical mechanisms:
1) Direct distribution to a Managed system [Agent]
2) Direct distribution by Managed System List that includes an agent.
3) Indirect distribution from Situation Group to a Managed system [Agent]
4) Indirect distribution from Situation Group to a Managed System List
There can be multiple MSLs or Situation Groups involved - maybe 10 different reasons why the situation will be distributed, It will only be distributed once.
Side Note for Extra Credit - There will NOT be a Test!!
A situation can take on multiple roles. For example it might be running on its own but also used in an Until situation or in a *SIT test or in a Workflow policy. In this case the situation only runs once on the agent but the results are multiplied at the TEMS so each usage gets the data needed. Sometimes you see situations start more then once on an agent. An Action command will show that result. It will also been if there are invisible sub-situations caused when multiple attribute groups are present. If you see a situation starting dozens of times, that is the likely issue. See the Mixed Up Situations blog post for scary details.
I had originally planned to use Perl/SOAP for this work. However some problems were encountered. The alternative was to run the needed SQL dumps using the KfwSQLClient program which is part of TEMS. This is rapid and simple to use - since it uses a preexisting connection. The output is a little rougher to parse but the benefits are huge.
The following assumes the default install directory. The work is done on the system which runs the TEPS. You can certainly do this any number of ways. For example you could capture the data at the TEPS and then copy the files somewhere else to process. If you are using a non-default install directory then then shell files will need to be modified. The choice of where to store the program objects is arbitrary - pick whatever you want.
The package is here. It contains
1) Perl program sitinfo.pl - standing for Situation Information
2) A sitinfo.cmd [Windows] shell command to run the SQL statements.
3) A sitinfo.tar file which contains Linux/Unix versions of the SQL files and a sitinfo.sh file. This avoids problems with the line endings. Just untar that into the install directory.
I suggest these all be placed in a single directory. For Windows you need to create the tmp directory and the sql subdirectory. For Linux/Unix create the sql directory.
Please note: In some environments installing CPAN packages is a major problem. Internet access may not be available or Perl may be a shared resource which you do not have the right to change. Changing such packages could negatively affect other programs.
To manage this case please see the CPAN Library for Perl Projects which has a package which can eliminate changing the installed Perl libraries.
Running the Program
The command line assumes you are running the the CPAN include library above.
a) cd /opt/IBM/IBM/tmp/sql
b) If not using default install directory run specify like this: export CANDLEHOME=/opt/IBM/ITM
c) sh sitinfo.sh
4) perl -Iinc sitinfo.pl -lst
b) If not using default install directory run specify like this: SET CANDLE_HOME=c:\IBM\ITM
d) perl -Iinc sitinfo.pl -lst
Two files are created:
A comma separated file [sitinfo.csv] which names the situation, the count of agents, the list of agents and the predicate. This can be unwieldy if there are thousands of agents.
A JSON file [sitinfo.json] which tells why the distribution occurred. JSON files are good for portable lists of highly structured data. There are many libraries to process these types of files.
The -onerow Option
If you specify the -onerow option the output puts each agent and each situation on a separate line. Also the ip address of the agent is added. This report is useful for some specialized data input applications. At 0.70000 a "why" column is added that lists the direct [agent and MSLs] and indirect via Situation Groups [Agent and MSLs],
First is a view of the CSV file from Symphony
Next is a view of the JSON file from a web online editor http://www.jsoneditoronline.org/ - actually this is a section of the screen.
When there is a Situation Group indirect distribution you will see a GA or GM, the agent name or MSL name and third the situation group name involved.
The Situation Distribution tool was derived from ITM Agent Health Survey.
I am new to this JSON world and you have any suggestions you will find a willing ear.
History and Earlier versions
If the current version of the Situation Distribution tool does not work, you can try previous published binary object zip files. At the same time please contact me to resolve the issues. If you discover an issue try intermediate levels to isolate where the problem was introduced.
Correct handling of Sitgroup distribution by agent name
Correct syntax error in sitinfo,cmd
Correct unused MSL count and add list of used MSL and counts
Add why column to onerow output
Better unused Managed System List report log, add totals like and remote System generated MSLs
Add unused Managed System List report section
Better parse_lst logic
Better parse_lst logic and easier to configure sh/cmd files
Add -onerow option and repackage linux/unix objects.
Improve -lst parsing. Not published here.
Handle -lst case with blank SITINFO column
Correct -lst parsing and also correct tsitdesc SQL SELECT statement
Photo Note: The Road to Big Sur has many strange sights