Interlink Software Provided Transformers
Interlink Software provides out-of-the-box transformers you can add directly to a message channel to accomplish specific actions.
When you create a user-defined transformer, you must identify it to the BES before the transformer can be added to a message channel, see Create a Transformer
issMUX
You use the issMUX transformer to send a single message stream to every connection established on a single port. The issMUX permits up to 100 connections on a single port.
HeartbeatTrans
You use HeartbeatTrans to monitor incoming data from the connection program on a message channel. It is used to report when events have not been received from a data source within a specified time frame, indicating a possible problem such as an integration program has lost its connection.
The transformer is placed in the first position of the message channel, directly following the connection program.
If the transformer is not placed directly after the connection program (for example, piPEM), the transformers modifying data before the HeartbeatTrans can provide misleading information regarding the status of the connection to the source of data
Accompanying the transformer is a default configuration file, HeartbeatTrans.cfg that enables you to define how to monitor incoming data to the message channel and the scenarios under which you want to report on connection issues or missing events.
The default configuration file is located in the $PPHOME/cfg directory.
All information within the configuration file is commented; that is, a hash character precedes each line of text negating any operation for all message channels.
The configuration file name and its placement in the directory structure should be as follows
$PPHOME/cfg/HeartbeatTrans_<mcname>.cfg
The variable <mcname> is the name of the message channel in which the transformer is placed
Adding the message channel name to the configuration file avoids conflicts with other configuration files for message channels that reside in the same directory.
The name of the configuration file does not have to mimic the name of the message channel.
If you are using multiple message channels to retrieve events from a single environment, such as PATROL Enterprise Manager, you can replace message channel name with the environment name so that you can apply it to all message channels retrieving the same event type information (for example, HeartbeatTrans_PEM.cfg)
Alerts produced by the HeartbeatTrans are directly forwarded to the AlertServer and bypass any transformers in the message channel that precede it.
The alerts are not normalized or enriched.
You must identify the CAF fields that are to be populated with values from the transformer.
The alerts are reported under the message channel where the transformer is installed.
Below is an example of the HeartbeatTrans.cfg file
MC
Template .'Domain'.id '|'
DefWarnInt 120
AlertMsgId WARNING - No messages received for [id] on MC [mcname] for [time]
AlertMsgMc WARNING - No messages received on MC [mcname] for [time]
SEV 1
VAR_ObjectState Unavailable
VAR_ObjectClass Heartbeat
ID STA1559PF 60
ID STX1457PF 60
VARID _OrigObject
VARTIME _ObjectValue
VARMC _Domain
The table below identifies the entries you define to monitor a source of data
| Entry | Description |
|---|---|
| MC DefWarnInt | Message channel is monitored; when events are not received on the message channel within the DefWarnInt period, an alert is sent reporting the lack of events DefWarnInt is an override value, in seconds, for the message channel that must elapse before an alert is sent if monitored events are not received |
| Template pattern | Template containing a uniREXX parse pattern that you use to extract an Id from incoming messages; pattern is the parse pattern You can use multiple templates to extract Ids; each template must reside on its own line. For example: Template .'Domain'.id Template .'HB'.id |
| DefWarnInt value | Default amount of time, in seconds, that must elapse without events being received before an alert is sent; value is the number of seconds Default value is 300 seconds which equates to five minutes |
| Dynamic | Monitor automatically for new identifiers (Ids) that are received by the transformer |
| AlertMsgId text | Text of alert produced referencing specific Ids when identified events are not received on the message channel within the DefWarnInt period; text is the text placed in the text field of the alert The variable [id] is populated by the HeartbeatTrans to specify an identifier defined in the template |
| AlertMsgMC text | Text of alert produced when events are not received on the message channel within the DefWarnInt period; text is the text placed in the text field of the alert Variables that you define in the text which the HeartbeatTrans populates for an alert are as follows
|
| VAR field value | Default CAF fields defined for alerts produced by the HeartbeatTrans
|
| SEV value | Severity category to be assigned to an alert produced by the HeartbeatTrans; value is one of the following severity categories:
|
| ID value time | ID to be monitored as extracted from the template; you can optionally specify an interval time for the Id that overrides the DefWarnInt for the message channel
|
| VARID field | Alert CAF field in which to place the Id; field is the name of the CAF field preceded by an underscore |
| VARTIME field | Alert CAF field in which to place the total elapsed time since receiving a monitored event; field is the name of the CAF field preceded by an underscore |
| VARMC field | Alert CAF field in which to place the name of the message channel that is monitored; field is the name of the CAF field preceded by an underscore |
The example HeartbeatTrans.cfg file above is monitoring the piPEM message channel, which means the following actions are performed
The message channel is being monitored as a whole so that if events are not received within two minutes (120 seconds):
- An alert is sent with a severity category of 1 with the Text field set to WARNING - No Messages received on MC piPEM for 2 minutes
- The ObjectState field set to Unavailable
- The ObjectClass field set to Heartbeat
- The OrigObject field set to piPEM
- The ObjectValue field initially set to 2 minutes
- The Domain field set to piPEM
- If events are still not received when the DefWarnInt elapses again, the value of 2 minutes in the alert text and ObjectValue fields increments by the original value for DefWarnInt which equates to 4 minutes
Two individual Ids: STAF1559PF and STX1457PF are being monitored.
The Template .'Domain'.id '|' extracts Ids from the incoming events and if STAF1559PF is not received within a 60-second period, an alert is sent with a severity category of 1 with the Text field set to WARNING - No messages received for STAF1559PF on piPEM for 1 minute
POWERrexxTrans
You use the POWERrexxTrans to modify an incoming message stream.
It relies on a configuration file containing REXX code and only allows modification to the incoming message stream. The incoming message stream can be transposed using any available REXX functions before it is passed onto the next process in the message channel.
The configuration file name and its placement in the directory structure should be as follows:
$PPHOME/cfg/POWERrexxTrans_<mcname>.cfg
The variable <mcname> is the name of the message channel in which the transformer is placed.
For instructions on modifying the configuration file and its placement in the BES directory structure, go to Modifying the Sample Transformer
XMLTrans
You use XMLTrans when the messages collected by the BES are in an xml format.
XMLTrans alters an xml message into a format that is used by the POWERpackTrans for creating an alert.
Alerts are created by defining rules; see Building Rules for Message Processing
When an xml message is collected, it appears similar to the following format
<TAGNAME1> tag data1 </TAGNAME1><TAGNAME2> tag data2</TAGNAME2>
After its alteration by XMLTrans, the message appears similar to the following format:
TAGNAME1 = tag data1 | TAGNAME2 = tag data2
If a collected xml message has nested tags, it appears similar to the following format
<TAGNAME1> tag data1 </TAGNAME1><TAGNAME2> tag data2 </TAGNAME2><CHILD><TAGNAME3> tag data3 </TAGNAME3></CHILD><TAGNAME4> tag data 4 </TAGNAME4>
After its alteration, the message appears similar to the following format
TAGNAME1 = tag data1 | TAGNAME2 = tag data2 | CHILD.TAGNAME3 = tag data3 | TAGNAME4 = tag data4