Thursday, March 13, 2008

Migrating ITM 6.1 Situation Associations

Recent ITM 6.1 enhancements provide mechanisms for exporting TEP workspaces from one TEP to another but no way to migrate situation associations without doing a full export of the TEPS database. Read on to find out how situations are associated to TEP navigator items and how to export the associations and import them into a different TEP server.

Unlike situation definitions which are stored in the TEMS EIB database, the associations to navigator items are stored in the TEPS database in the KFWTMPLSIT table. This table is composed of three columns NAME, TEMPLATE, STATE, and TYPE. As you have may have already guessed, the NAME column is the situation name. The TEMPLATE column is the navigator entry where a situation is associated. This value is an internal identifier, not the actual text a person sees in the TEP display. The STATE column is the severity (Critical, Warning, or Informational) of the association. The TYPE column is a numeric value. Associations manually configured from the TEP always seem to have a 0 for the TYPE column. Situations added by product support seem to have a TYPE of 256 and a form of pattern matching fro the NAME. An example of this is the row:
'*Critical' 'KFW_ENTERPRISE' 'Critical' 256
This seems to imply that any situation ending with '*Critical' will be associated at the Enterprise level but this is not the case as you can create a situation ending in Critical but you will not see it unless you associate it.

To do an association using SQL you simply shut down the TEPS, issue the SQL inserts and the restart the TEPS. For example this is how you would associate the MS_Offline situation with the Enterprise navigator item:

Until the mappings of the template values to navigator items is better understood it will probably be safer to create the associations in a development environment then export them as SQL and run the SQL to import them in a production TEPS.

Another table that is modified when a situation is associated in the TEP is the KFWTMPL table. This table appears to contain information about navigator items and when an association is done, the LSTDATE is changed to the ITM timestamp of the time the association was set. It does not appear to be necessary to modify rows in this table when applying associations using SQL.

Here is a simple perl script that will export associations by generating SQL insert statements that you can redirect to a file and then use the file to import the associations.

This is the usage text:
This script is provided as is with no warranty expressed or implied.
The export and import of ITM 6.1 situation associations is undocumented and
unsupported. Use at your own risk... export [-r REGEX]
Export sitiation associations to STDOUT
Only export situation with names that match REGEX import SQL_EXPORT_FILE
Import situation associations from SQL_EXPORT_FILE -h
Prints this help text.

Run on the TEPS host.
Ensure that the KfwSQLClient executable is the PATH and the environment is
setup to allow the KfwSQLClient program to execute.

On Linux source the file and add the locations of the files and to LD_LIBRARY_PATH
. $CANDLEHOME/li6243/cq/bin/

To use this script to export the MS_Offline associated situation simply call it in this manor:
On source TEPS
./ export -r MS >/tmp/test.sql

On destination TEPS, copy the test.sql file and call
./ import /tmp/test.sql

The script has been tested on Windows and Linux, but I expect it to work on AIX. I can not stress enough that this method is not supported..


adzz83 said...

Hi, I have been trying to use this script on a ITM v6.1.4 installation and keep getting the error message as shown below:

KfwSQLClient: /opt/IBM/ITM/JRE/li6263/bin/ no version information available (required by ../lib/

I have added the LD_LIBRARY_PATH details and sourced the file.

Any help would be great.


Venkat said...

Did the script work at all for you? IIRC, the error message is really a warning and it may not effect the command execution.