Rule Definition Action Clause

RULE <rule-name> {PRIMARY|SECONDARY} [DISABLED]

	[<initialization>]
	<record-clause>

	[ACTION
		[WHERE 	<action-where-clause>]
		[LOG   	{
				PROBLEM_SUMMARY | 
		  		PROBLEM | 
		  		EMS |
				AVAILABILITY <msg-number> 
					ENTITY_NAME <entity-name> 
					ENTITY_TYPE <entity-type>
					[SUBID1]
					[SUBID2]
					[PRIORITY n]
					[TIMEOUT <seconds>]
					[EVENT_TYPE { UP_EVENT | DOWN_EVENT }] 
					[REVERSE_COND_TYPE { PAIR | OFF_EVENT_NUM }]
					[CONDITION_PAIR <pair-name>]
					[DESTINATION <node>] |
			  	FILE <file-name> |
		  		PROCESS <proc-name> | 
		  		SNMPTRAP <msg_number> 
					[VERSION {v1 | v2c | v3}] 
					[HOST <host>] 
					[PORT <port_no>] 
					[COMMUNITY <string>] 
					[AUTHPROTOCOL {MD5 | SHA}] 
					[ENCRYPTION {DES | AES128 | AES192 | AES256 | 3DES} ] |
		  		TERMINAL <term-name> |
		  		<msg_number>
				} 
				[PRIORITY { ERROR | WARNING | INFORMATION | CRITICAL}] 
				[EVENTNUMBER <n>] 
				[SUBJECT (<subject1>, <subject2>, ...)] 
				[COLLECTOR <coll-name>] 
				[EMSACTION] 
				[EMSACTIONOFF] 
				{IMMEDIATELY | WHEN_CLOSED}
		]

		[EXEC 
			[#<SERVER>] <n> 
			[NODE <node-name>] 
			[USER <password-key>]
			[ 	{	
				IMMEDIATELY | 
				WHEN_CLOSED | 
				WAIT_WHEN_OFF | 
				WAIT [ {AT | TIMEOUT | AT TIMEOUT} {<dd-mmm-yyyy hh:mm> | <mmm-dd-yyyy hh:mm>} ]
				}
			[OPER_ACK]
			[NOLOG]
			[SHELL_SHARING {ENABLED | DISABLED | DEFAULT}]

		[START RULE <rule-name>]
			[WAIT [ AT {<dd-mmm-yyyy hh:mm> | <mmm-dd-yyyy hh:mm>} ]

		[SET <identifier> := <expression>]

		[NEXT_RULE_STATE {OPEN | CLOSED} ]
	END_ACTION]

	[IF <action-where-clause>
		[LOG...]
		[EXEC...]
		[START RULE...]
		[SET...]
		[NEXT_RULE_STATE...]
	END_IF]

END_RULE

Syntax

ACTION

Indicates a set of actions to be taken when the rule triggers. There can be multiple Action blocks within a rule, and each Action block can contain a number of actions. The Action blocks are executed in the order that they appear in the rule. If you have three Action blocks (each with its own Where Clause) the first one will process, then the second, then the third.

If the second one contains a NEXT_RULE_STATE CLOSED, and if that second action takes effect, the third action will not execute. Execution of all clauses in the Action block is dependent upon its Where Clause. Only if the Where Clause is satisfied, will the actions be executed.


WHERE

An <action-where-clause> further narrows down the number of records that the contained actions will be performed on. For further details see the Where Clauses section.

Conventional field names are NOT allowed in an <action-where-clause>. Instead, only global variables, local variables, system variables, field variables and literals are accessible.

The field variables can include values inherited from higher level rules. For example, if the record associated with the current rule is JOBS and the record associated with the higher level rule is CPU, then the field variables in this Where Clause can come from both the CPU and JOBS fields.

The ability to extract values from a string field using 'matches regex' and regular expressions is permitted in the <action-where-clause>.  Up to 30 values can be extracted which are placed into system variables named ^var01 through to ^var30.  For example;

ACTION
	WHERE @event.text matches regex "(.*)Resource Name: (.*), Specific Problem: ([^,]*),(.*)"
	SET_Resource :=^var02
	SET_Problem :=^var03
END_ACTION

In this example two regular expressions are used; ([^,]*) which means 'match anything except a comma (,)' and (.*) which means match anything. See the Using Regular Expressions in a Where Clause section for further details.

When comparing timestamps in <where-clause> or <action-where-clause>, there are some special considerations. Especially when one of the timestamps has been stored in a global or local variable. For more information, see Use of Timestamps in Analyst Where Clauses.


LOG

Use this keyword to cause a message to be logged to one of a number of destinations.

PROBLEM_SUMMARY
Logs to the PrognosisAutomationProblemSummary (PROBSUM) record. This log type is normally only logged once for a given problem. This enables tracking of the problem via the Alerts Central Display.

PROBLEM
Indicates logging to the PrognosisAutomationProblem (PROBLEM) record. This is the default value. This log type is normally used for logging the output of detailed problem analysis, or recording actions that have been taken by a rule.

EMS
Indicates logging to the local event management system (or event log).

On HPE NonStop, an event will be logged to EMS with a subsystem owner=PRGNOSIS, subsystem name=PRGNOSIS (127) and subsystem-version=<prognosis-ver>.
e.g. PRGNOSIS.PRGNOSIS.803 (for version 8.3.5).

On Windows, an event will be logged to the Application event log with a source of 'Prognosis'.
On UNIX and Linux, an event will be logged to the default system log and the text will begin with 'Prognosis event'.

AVAILABILITY

This logs to the Availability Collector, which is used to show the UP/DOWN state of monitored entities. Refer to Availability Monitoring. Using complex Analyst rules, entities can be monitored and the state can be shown in the Availability Monitoring feature of Prognosis.

<msg-number> - The number entered here corresponds to the number assigned to the text in the Analyst Rules Output. This message number must be less than 32000.

ENTITY_NAME <entity-name> - The entity name is any unqiue name up to 60 characters long

ENTITY_TYPE <entity-type> -  The AvMon entity target type, this can be a threshold or AvMon type (for available entities refer to Monitoring Existing AVMON Entities)

SUBID1 and SUBID2 - The SUBID's of the entity. See Availability - Message Destinations Primary and Secondary SubID

PRIORITY <n> - The Priority is an integer value specifying the process priority to trigger the up/down event.  If two opposing events are trying to trigger an entity up/down the Priority decides which one will be applied.

TIMEOUT <seconds> - The timeout integer followed by units (defaults to seconds). Unit Types DAYS, HRS, HOURS, MINS, MINUTES, SECS, SECONDS. See Setting a Threshold Initialization State and Timeout.

EVENT_TYPE  - This specifies the new state of the entity, can be either UP_EVENT or DOWN_EVENT, defaults to DOWN_EVENT.

REVERSE_COND_TYPE - If set to 'Pair' then when this condition is stopped the pair will also stop (This is usually used if your pair is sending the down event to your up event). If 'OFF_EVENT_NUM' then when the specified event stops, a down event is sent.

CONDITION_PAIR <pair-name> - Sets which condition to use, <pair-name> can be anything as long as it is the same on the entity you wish to pair to. Only relevant if REVERSE_COND-TYPE is set to PAIR.

DESTINATION <node> - Specifies which node the entity will be triggered on.

FILE
Indicates logging to the file identified by <file-name>.

PROCESS
Indicates logging to the process identified by <proc-name> (HPE NonStop only).

SNMPTRAP
This option can be used in both Primary and Secondary rules to set the Analyst to generate an SNMP Trap message when a rule is triggered. A message number needs to be included which corresponds to a message added in the Analyst Rules Output.

VERSION - Version of SNMP to send. Valid values are v1, v2c or v3.

HOST - A host name is required which is the node name where the Traps will be delivered to and this can be entered as either a valid DNS name or IP address.

PORT - Optional port number which is used to deliver the SNMP Trap, if not included the default is 162.

COMMUNITY - (Applicable for SNMP v1 and v2c only) Optional community string, if not included the default is 'public'.

AUTHPROTOCOL - (Applicable for SNMP v3 only) SNMP authentication protocol to use. Valid values are MD5 or SHA. Note that using MD5 is not FIPS compliant.

ENCRYPTION - (Applicable for SNMP v3 only) Encryption method to use.  Valid values are DES, AES, AES128, AES192, AES256 or 3DES.

These SNMPTRAP settings can be included with the SNMPTRAP statement or they can be added as Global parameters in the Analyst Rule Configuration and Global Variables. However, if they are included in the SNMPTRAP statement any Global parameters will be overwritten.

The SUBJECT statement can be used with the SNMPTRAP statement to add Variable Bindings which will allow logging to select a set of fields to be recorded when the SNMP Trap is sent out. The TRAP severity can be set by using the PRIORITY statement.

Notes for SNMP Usage:

1)    Prior to version 11.1, Analysts could only send SNMP v1 Traps. Effective with version 11.1, Analysts can send v1, v2c or v3 Traps. However, if no SNMP options are entered, the default configuration remains as v1 sending to 127.0.0.1 (localhost) on port 162.

2)    If FORCE-FIPS-ENCRYPTION is enabled in the NETWORK Configuration, then the following SNMP restrictions will apply:

  • Only SNMP v3 can be used.

  • Authentication must use a FIPS compliant algorithm, at present only SHA is available.

  • Encryption must use a FIPS compliant algorithm, AES128, AES192, AES 256 or 3DES can be used.

3)    SNMP v3 requires the applicable username and password to be added to the PASSWORDS Configuration on the server that the Analyst runs. To do this the following entries are used:

autoan:authentication:<ip-address>:<port>
autoan:encryption:<ip-address>:<port>

Where <ip-address> is the server running SNMP v3 and <port> is the port used for SNMP access.
In the authentication entry, the username and password are the same as configured in the SNMP v3 server for authentication.
In the encryption entry the username is ignored, only enter the password as configured on the SNMP v3 server for encryption.

Where applicable, separate PASSWORD Configuration entries are required for each SNMP v3 server. That is, a hierarchy of password entries is not supported.

TERMINAL
Indicates logging to the terminal identified by <term-name> (HPE NonStop only).

<msg_number>
The number entered here corresponds to the number assigned to the text in the Analyst Rules Output. This message number must be less than 32000.

PRIORITY
Valid for PROBLEM_SUMMARY, EMS and SNMPTRAP log types. Specifies the severity of the message to be logged. For PROBLEM_SUMMARY log types, this setting controls the content of the ProblemSeverity and ProblemSeverityNumber fields in the PROBSUM record. For EMS log types, the priorities are mapped differently for the different platforms, as described in the table below:

Priority

HPE NonStop EMS Emphasis

Windows Event Log Type

Unix/Linux Log Level

Critical

Critical

Error

Critical

Error

Non-critical

Error

Error

Warning

Non-critical

Warning

Warning

Information

Non-critical

Information

Information

EVENTNUMBER <n>
Identifies event number of the message to be logged (default value is 0). This field is typically used to uniquely identify the type of event. Valid for all log types.

SUBJECT
This statement can be used in conjunction with the SNMPTRAP statement to add Variable Bindings which will allow logging to select a set of fields to be recorded when the SNMP Trap is sent.

The SUBJECT statement can also be used with the EMS log type on HPE NonStop. Specifies a list of subjects to be included in the logged message. <subject> is specified in the form [<record-name>.]<field-name> (with no leading @). For example, SUBJECT (cpu.cpuno,cpu.busy)

These subjects will be logged as separate tokens in the resultant EMS event. <subject> must refer to a field in the record requested by the local rule. Only key fields are permitted in WHEN_CLOSED messages. No subjects are permitted in NOTEXIST rules.

COLLECTOR
Valid only for the EMS log type on HPE NonStop. Specifies an alternate EMS collector, identified by <coll-name>, where the message is to be logged. The default is $0.

EMSACTION
Valid only for the EMS log type on HPE NonStop. Specifies that this message should be logged as an EMS action event. It can only be specified in one LOG message per rule.

EMSACTIONOFF
Valid only for the EMS log type on HPE NonStop. Specifies that this message should be logged as an EMS action off event, related to the event specified by the EMSACTION clause. Only valid if a LOG EMSACTION was specified for the current rule. It can only be specified in one LOG message per rule.

IMMEDIATELY|WHEN_CLOSED
'Immediately' will log the message straight away. 'When Closed' will log the message when the problem instance has been closed (either by the rule completing or from a NEXT_RULE_STATE closed command).


EXEC

Use this keyword to send a command to a Prognosis command server.

#<SERVER>
The optional #<SERVER> name entered here specifies to which process the command text, located in the MSG_TEXT section, will be sent. The default is #AUTO (Command Shell). Currently the available destinations include:

Analyst Syntax

Command Destination

More information

#AUTO

Command shell

See Commands for further details.

#DISPMAN

Dispatch Manager

See Sending Messages via Dispatch Manager for further details.

#SNMPTR

SNMP Traps In collector

See the SNMP Event Management section in the User Guide.

#WVTEC

Tivoli Enterprise Console Adapter

See Send Analyst Messages to Tivoli Enterprise Console for further details.

#ANALYST

Analyst or Threshold

See Analyst Control via Commands and Controlling Thresholds using Commands for further details.

#ATMMON

ATM Ticketing collector

See the Commands section in the ATM Manager.

The command text is referenced by the < n > parameter that identifies the command text's ID in the MSG_TEXT section.

NODE <node-name>
NODE specifies the node on which the destination #<SERVER> resides. The NODE must follow the message number, for example, EXEC 0101 NODE \DEV-JAMIE WAIT. The default is for the command to be executed on the node that data was received from in this rule.

USER <password_key>
This is an optional key for accessing a user-id/password pair as specified in the PASSWORDS Configuration. Only applicable for shell commands, it causes the command to be run as the user specified. The referenced PASSWORDS entry must be a valid user on the destination node.

IMMEDIATELY
Will be executed immediately and the Analyst will not wait for a response before continuing with the next statement in the rule.

WHEN_CLOSED
Will execute when the problem instance has been closed, either by the rule completing or from a NEXT_RULE_STATE closed command.

WAIT_WHEN_OFF
Same as WHEN_CLOSED except that each command will wait for the previous one to finish before executing.

WAIT
This tells the Analyst to wait at this statement until the server process returns a response (which is stored in the system variables ^RET_CODE (the completion code) and ^RET_TEXT (the output)). If the WAIT option is not specified, the rule will continue processing the next statement at the same time as the server is doing the requested EXEC command, as specified in the LOG section for that log number. Use AT to specify a date and time for the EXEC action to start. TIMEOUT can be used with the WAIT and/or AT option so that if the EXEC action has not been completed by the server (no ^RET_CODE returned) by the date and time specified the action is considered complete and the rule continues.

OPER_ACK
Instructs the Analyst to wait until an operator has activated the action before executing the command in the server process.

Pre-packaging documents offer the following operator options for OPER_ACK:
  • Ignore - Ignores the problem message; it will not be reported again.
  • Continue Automation - Execute the command that has been defined in the EXEC statement

NOLOG
The NOLOG option stops the EXEC text from being logged in the PROBLEM record. However, the command is still executed and if it is a shell command it will still be shown in the CMDLOG and AUTOOUT records.

SHELL_SHARING
Only valid for the #AUTO (Command Shell) destination. The SHELL_SHARING option, when set to DISABLED, ensures that Analyst rules do not share the same command shell process as other commands executed by this Analyst. Typically, this would be done when a long running command is executed in order to prevent other commands queuing up behind. When set to ENABLED, the command will execute using the Analyst’s 'default' command shell for the USER specified. The default is ENABLED.


START RULE

Calls the next level of problem solving. Specify the name of a Secondary rule that is to be invoked at this stage.

You can use the same WAIT and WAIT AT options when starting Secondary rules as you can for the EXEC keyword.


SET

Use this keyword to set the value of a local or global variable.

<identifier>
The name of the local or global variables to be set.

<expression>
For STRING variables, this contains either a string literal, string substitution, or the name of a local, global, field or system variable. String literals must be surrounded by double quotes.

For NUMERIC variables, these contain an arithmetic expression consisting of numeric literals and/or local, global, field or system variables.

SET Functions

There are 2 functions that can be used within the <expression>;

Subst

A string substitution is specified as follows;  subst("<string-with-substitutions>"). The format of <string-with-substitutions> is similar to the format used in the <text> parameter allowed in the Analyst Rules Output.

For example:

ACTION
	SET test_string := subst("CPU number @CPU.CPUNO@")
	SET test_string := subst("@test_string@ is @CPU.BUSY@% busy")

The contents of the test_string, after the second SET, would be similar to "CPU number 01 is 90% busy".

Be aware of the following limitations:

  • The function will only populate up to the maximum STRING variable length, if the subst() concatenate result exceeds this length mid-variable it will generate an error.
  • The maximum length within the subst text is 240 characters, even if the output will be shorter. To overcome this 240 limit, use the MSG section and put several variables strings together in an event number. See the examples below.
  • There is a single set of double quotes within a subst command and it is not required to encapsulate text separate from variables, put the text and variables side-by-side within the double quotes.
  • Variables and Records within a subst command are both referenced with the @var@ and @record.field@ respectively.
  • There must be some data within the double quotes or the subst command will fail.
  • Try to avoid using escape characters in the subst command or any comments, such as ‘\’, ‘/’; the results may not be as expected.
Cast

This is an implied function (i.e. no specific command).

It is possible to cast a STRING variable to a NUMERIC variable (i.e. convert a string to a number) if it needs to be used for numeric processing in later instructions.

This casting can only be done under the following conditions:

  • The String Variable must only contain numeric characters and optionally a preceding minus sign ('-')
  • The SET command must only contain one single cast operation, otherwise, it will fail (i.e. SET numericVar := stringVar)
  • The NUMERIC variable type must be initialized for the correct format of the string
    • An integer can be cast to a float
    • A float can be cast to an integer, but the fractional part of the float will be truncated before the cast

To define an Integer use Numeric MyInt[0] := 0. To define a Float use Numeric MyFloat[2] := 0.00

See the examples below.


NEXT_RULE_STATE

Indicates whether the current rule will be considered open or closed after this action is performed. When set to CLOSED, processing will drop out of this rule without executing any more statements. The default is OPEN, which has no effect.

IFThis is an alternative syntax for specifying an ACTION block. As the <action-where-clause> statement must be specified with the IF keyword, the WHERE option is not supported inside the IF/END_IF block.  All other ACTION options (e.g. LOG, EXEC, START RULE, SET and NEXT_RULE_STATE) are valid and operate exactly the same way as when specified in an ACTION/END_ACTION block. Also note that the <action-where-clause> is not optional when the IF keyword is used.

Examples

Example 1

Use the MSG to concatenate a string longer than 240 characters

SET _alrtst1 := subst("TRIG: ^srcnode Capacity Workload Alert CPU RunQ @_RunQue@ and is ABOVE the threshold value of @_P5100c_HiThr_g@.")
SET _alrtst2 := subst("CPUQueue=@NTSYSTEM.PROCQUE@, Processes=@NTSYSTEM.NUMPROC@, Threads=@NTSYSTEM.NUMTHRD@, ContSwitch=@NTSYSTEM.CONTEXSW@, rSec=@NTSYSTEM.READOPS@, rMBSec=@NTSYSTEM.READMB@, wSec=@NTSYSTEM.WRITOPS@, wMBSec=@NTSYSTEM.WRITEMB@")
SET _alrtst3 := subst("This field will be updated by output of S005_GETNTCPUDATA!")
SET _alrtst4 := subst(".")
SET _alrtst5 := subst("Triggered after 2 Occurrences in 5 minutes")
SET _alrtst6 := subst("Capacity_Alert_ON Wintel_Alert")

!THEN In the Message Section use the following to get a very long string.
MSG 9111 "@_alrtst1@ @_alrtst2@ @_alrtst3@ @_alrtst4@ @_alrtst5@ @_alrtst6@"

Example 2

Numeric cast example using RegEx

SECTION CONFIG
	! Note Variables only have 8 significant characters and
	! cannot be Greater than 23 characters.
	!Numeric Integers
	NUMERIC _g_year[0] := 0
	NUMERIC _g_mon[0] := 0
	NUMERIC _g_day[0] := 0
	NUMERIC _g_hour[0] := 0
	NUMERIC _g_min[0] := 0
END_SECTION

SECTION RULE_DEF
	RULE test PRIMARY
		STRING _MsgText
		STRING _HoldTime
		!Numeric Floats
		NUMERIC _year [4] := 0.0000
		NUMERIC _month [4] := 0.0000
		NUMERIC _day [4] := 0.0000
		NUMERIC _hour [4] := 0.0000
		NUMERIC _minute[4] := 0.0000
		RECORD PSTATUS
		WHERE PSTATUS.type = "PROMGR"
		REFRESH 10 seconds
		EVERY 10 MINUTES
	
		ACTION
			set _HoldTime := subst( "^currtime")
		END_ACTION
	
		ACTION
			WHERE HoldTime matches regex "(\d\d\d\d)(\d\d)(\d\d)(.)(\d\d)(.)(\d\d)(.)(\d\d)"
			SET _Year := ^var01
			SET _Month := ^var02
			SET _Day := ^var03
			SET _Hour := ^var05
			SET _Minute := ^var07
			SET _MsgText := subst( "@_Year@/@_Month@/@_Day@ @_Hour@:@_Minute@")
			LOG problem 00200 IMMEDIATELY
			SET _g_Year := _Year * 10000
			SET _g_mon := _Month * 10000
			SET _g_day := _Day * 10000
			SET _g_hour := _Hour * 10000
			SET _g_min := _Minute * 10000
		END_ACTION
	
		ACTION
			SET _MsgText := subst( "@_g_Year@/@_g_mon@/@_g_day@ @_g_hour@:@_g_min@")
			LOG problem summary 00200 IMMEDIATELY
		END_ACTION
	END_RULE
END_SECTION
	
SECTION MSG_TEXT
	MSG 00200 "@MsgText@"
END_SECTION
Provide feedback on this article