John Alvord, IBM Corporation
jalvord@us.ibm.com
Draft #15 – 8 January 2021 – Level 0.80000
Inspiration
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.
At Version 0.75000 I cloned the sitinfo.pl into sitinfo_json.pl and altered sitinfo.pl to not include the json output. The new sitinfo.pl does not require CPAN packages.
At Version 0.80000 I have a good output with Persist and Description added.
Background
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.
Development notes
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.
Package Installation
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 sitinfo.0.80000. It contains
1) Perl program sitinfo.pl – standing for Situation Information
2) Perl program sitinfo_json.pl – which adds a json output.
3) A sitinfo.cmd [Windows] shell command to run the SQL statements.
3) A sitinfo.tar file which contains Linux/Unix versions of the SQL capture shell command sitinfo.sh. 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.
Linux/Unix: /opt/IBM/IBM/tmp/sql
Windows: c:\IBM\ITM\tmp\sql
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.
1) Linux/Unix
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
5) On AIX platform you may need to run this command if he tables are large and you get outputs that show Unknown Exception
export LDR_CNTRL=MAXDATA=0x80000000
2) Windows
a) c:\IBM\ITM\tmp\sql
b) If not using default install directory run specify like this:
SET CANDLE_HOME=c:\IBM\ITM
c) sitinfo.cmd
d) perl -Iinc sitinfo.pl -lst
Results
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.
If you use sitinfo_json.pl 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. The ip address of the agent is included. 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],
Screen shots
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.
Summary
The Situation Distribution tool was derived from ITM Agent Health Survey.
Sitworld: Table of Contents
Feedback Please!!
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.
sitinfo.0.80000
Correct sitinfo.cmd and sitinfo.sh
sitinfo.0.79000
Correct Description logic in -onerow output
sitinfo.0.78000
Add Situation Description to -onerow output
Show FULLNAME along with SITNAME when different
sitinfo.0.77000
Add Situation Persist to -onerow output
sitinfo.0.75000A
correct sitinfo.cmd data collection – missing TNAME table
Add knowledge of distribution for TCALENDAR, TOVERRIDE and POLICY
The Wonderful World of Situations 
2 thoughts on “Sitworld: Situation Distribution Report”