====== PI/XI messages JAVA ======
  This monitor is dedicated to the monitoring of PI/XI messages statistics per component 
  and for monitoring individual messages status of Java stack instances.
  It will detect messages with an error status and report with alarms, metrics and metadata
===== Prerequisites =====
  * In case of the user management engine (UME) referred to a data source served by an ABAP client stack, the user account to access PI/XI information in the web portal must meet the following prerequisites: 
    * The web client connection user must be created in the client of the UME associated ABAP system (normally it is the “production” client, ask to the users administrator). 
    * Following roles must be granted to the user (exclusively, DO NOT USE A COPY)
      * SAP_XI_DISPLAY_USER_J2EE
      * SAP_XI_RWB_SERV_USER
===== Configuration hints =====
  * This monitor must be used with a Web portal connector to the target SAP system, with user credentials having access to the PI/XI messages view
  * **Statistics table:**
    * You must specify the XI components that you want to monitor, you cannot use regular expressions for this filter.
    * To discover the available XI components from your system, you can call the following servlet with your web browser: 
      * http://[host]:[port]/mdt/messageoverviewqueryservlet
    * It will return the available components in the XIComponents tag.
    * With this monitor, you will have the possibility to be notified when a given number of messages from an XI component are in a given state, within a period of time.

  * **Individual message monitoring table:**
    * You can activate the monitoring of individual PI messages by setting rules within this table
    * Only messages passing the filters will be processed and may generate alarm, or be sent as metadata or logs
    * Use the Alarm and metadata checkbox to define the behavior of the monitor.
    * The **collect messages** option must be active to enable individual PI messages monitoring
    * Only messages from the last "check time" will be collected. This monitor will not fetch old messages.

  * You can filter in or out certain types of messages by using Sender, Receiver and Interface fields.
  * You can adjust the level of alarm severity depending on the type of status or on message characteristic.
  * A disabled severity will filter out the messages matching the filters, for all subsequent lines.


===== Atomic fields =====
^Collect messages| Enable to collect individual messages from the portal |
^Collect faulty msg only| Enable to collect only messages with an error status |
^Collect log entries| Enable to collect logs of each message |
^Threads| The number of internal parallel workers used to fetch messages |
^Custom soap body| Use this field to customize the request used to collect messages |
^Alarm severity for component collection error|Level of the alarm when the probe can't collect information about a component defined in the surveiliance table |

===== Surveillance table =====
**Statistics table**
^Parameter^Description^
^Active|Use this field to activate or deactivate a line of configuration. |
^Status|Define the type message status to look for. |
^Period|Defines the period of time in which the probe will look for messages. |
^Component|Defines the xi component associated with the messages. The exact component name must be specified here.|
^Sender|A filter for the sender of the messages. |
^Receiver|A filter for the receiver of the messages. |
^Interface|A filter for the message interface.|
^Max. messages|The threshold of the alarm generated if an equal or greater number of messages pass the alarm filter. |
^Aggregates|If not set, threshold will be compared to the number of messages grouped by Sender, Receiver and Interface. If set, the threshold will be compared to the cumulated number of messages.|
^Severity|The default severity to apply when the simple threshold syntax is used.|
^Auto clear|If checked, the alarm will be cleared as soon as the alarm condition is not met anymore. |
^Alarm tag|This field allows to add custom text within the alarm message. %MSG% variable will contain the actual generated message and can be used such as: "my_prefix %MSG% my_suffix". By default, tag will be used as prefix. |
^Alarm|If checked, this line of surveillance will be used for alarm generation. |
^Metric|If checked, this line of surveillance will be used for metric generation. |
^Report|If checked, this line of surveillance will used for showing threshold and severity in the daily report|

**Messages monitoring table**
^Parameter^Description^
^Active|Use this field to activate or deactivate this filter |
^Sender|A filter for matching a particular sender. |
^Receiver|A filter for matching a particular receiver. |
^Interface|A filter for matching a particular interface.|
^Status|Filter to process only messages having the specified status.|
^Custom params| defines the the parameter to extract from message custom parameters (will be available in metadata) |
^Severity|The severity used to for generated alarms.|
^Alarm|Enable to generate an alarm for each message matching the filters |
^Metadata|Enable to send matching messages as metadata or logs |

===== Examples =====
^Active^Status^Period^Component^Sender^Receiver^Interface^Max. messages^Aggregates^Severity^Auto clear^Alarm tag^Alarm^Metric^Report^
|true|HOLDING|CURRENT_HOUR|mssql.xi.id2|*|*|*|5|true|WARNING|true| |true|false|false|

**Effect** : Sends a WARNING alarm if 5 or more messages are in HOLDING state in the current hour for the component mssql.xi.id2.
===== Examples =====
^Active^Status^Period^Component^Sender^Receiver^Interface^Max. messages^Aggregates^Severity^Auto clear^Alarm tag^Alarm^Metric^Report^
|true|SYSTEM ERROR|LAST_DAY|mssql.xi.id2|SenderX|*|*|50|true|MAJOR|true| |true|false|false|

**Effect** : Sends a MAJOR alarm if 50 or more messages are in SYSTEM ERROR state in the previous day, sent by SenderX.

===== Example for individual message =====
^Active^Sender^Receiver^Interface^Status^Custom params^Severity^Alarm^Metadata^
|true|*|*|*|error| |MAJOR|true|true|

**Effect** : Will process all PI messages having a status containing 'error', will genrate a MAJOR alarm for each and will send them as metadata.
===== Generated metrics =====
^metricId^metricUnit^metricTarget^metricDescription^
|PIXI_JAVA_MESSAGE_STATUS|Message errors|[STATUS][PERIOD][SENDER][RECEIVER][INTERFACE]|Sends TRUE if the corresponding rule generated an alarm, FALSE instead|
|PIXI_JAVA_MESSAGE_STATUS_COUNT|Status|[STATUS][PERIOD][SENDER][RECEIVER][INTERFACE]|Sends the number of messages matching the filter|