Variables for tools

The following variables can be used in the Parameters box in the Configure Tools dialog box, Details tab.

Management server variables
Message variables
Node variables
Node group variables
Service variables
Environment variables

Management server variables

$OPC_MGMTSV
Returns the name of the management server. $OPC_MGMTSV can also be used in automatic and operator-initiated commands.

Availability: From all actions except automatic and operator-initiated commands.

Message variables

Some variables return TRUE or FALSE, depending on the existence of a specific message attribute. For example, if an automatic action is defined, TRUE is returned. Otherwise FALSE is returned.

If an attribute is empty, an empty string is returned. If you use an attribute that does not exist, it is treated like part of a normal string, which means no evaluation happens and the string remains unchanged. The data returned from variables is exactly the same type as that shown in the Message Properties dialog box. The indexing for word extraction from strings and for access to specific annotations starts with 1, not with 0.

All message variables are replaced per message. This means that if you select two messages, you will receive two requests; each of them might have different values for the parameters.

$OPC_CUSTOM[name]
The same as $OPC_MSG.CMA[name]. Returns the value of the custom message attribute name. For example, the $OPC_CUSTOM[device] variable could return the value Lan.
$OPC_MSG.ACTIONS.AUTOMATIC
Indicates whether an automatic action is defined. Sample output: TRUE
$OPC_MSG.ACTIONS.AUTOMATIC.COMMAND
Returns the script or program, including its parameters, performed as an automatic action for the selected message. Sample output: dist_del.sh 30 warning
$OPC_MSG.ACTIONS.AUTOMATIC.NODE
Returns the node on which an automatic action has been performed for the selected message. Sample output: kernighan.c.com
$OPC_MSG.ACTIONS.AUTOMATIC.STATUS
Returns the current status of the message's automatic action. The variable can return running, failed, or successful. Sample output: successful
$OPC_MSG.ACTIONS.OPERATOR
Indicates whether an operator-initiated action is defined. Sample output: TRUE
$OPC_MSG.ACTIONS.OPERATOR.COMMAND
Returns the script or program, including its parameters, performed as an operator- initiated action for the selected message. Sample output: ps -ef
$OPC_MSG.ACTIONS.OPERATOR.NODE
Returns the node on which an operator-initiated action has been performed for the selected message. Sample output: kernighan.c.com
$OPC_MSG.ACTIONS.OPERATOR.STATUS
Returns the current status of the message's operator-initiated action. The variable can return running, failed, or successful. Sample output: successful
$OPC_MSG.ANNOTATIONS
Indicates whether annotations exist for a message. Returns TRUE if at least one annotation exists for a message. Otherwise FALSE is returned. Sample output: TRUE
$OPC_MSG.ANNOTATIONS[n]
Returns the nth annotation. Sample output:

Performed Message Correlation; Message Key Relation: Message 59d06840-ac4f-71d5-1f67-0f887e320000 with condition id fe00fa34-9e34-71d5-143e-0f887e320000 ackn'ed 0 messages.
$OPC_MSG.APPLICATION
Returns the name of the application related to the selected message. Sample output: /usr/bin/su(1) Switch User
$OPC_MSG.CMA[name]
Same as $OPC_CUSTOM[name].
$OPC_MSG.CREATED
Returns the date and time the message was created on the managed node. Sample output: 09/18/01 18:08:08
$OPC_MSG.DUPLICATES
Returns the number of duplicate messages that have been suppressed. Sample output: 17
$OPC_MSG.GROUP
Returns the message group to which the selected message belongs. Sample output: Security
$OPC_MSG.INSTRUCTIONS
Returns the text of the instruction. Sample output: Available space on the device holding the (root) filesystem is less than the configured threshold. This may lead to ...
$OPC_MSG.LAST_RECEIVED
Returns the date and time when the last duplicate message was received on the management server. Sample output: 09/16/01 03:17:23
$OPC_MSG.MSG_KEY
Returns the message key that is associated with a message. Sample output: my_appl_down:kernighan.c.com
$OPC_MSG.MSG_ID
Returns the unique identification number for the selected message. Sample output: 217362f4-ac4f-71d5-13f3-0f887e320000
$OPC_MSG_IDS
Returns the message IDs (UUIDs) of all the messages currently selected. IDs are separated by space. Sample output: 85432efa-ab4a-71d0-14d4-0f887a7c0000 a9c730b8-ab4b-71d0-1148-0f887a7c0000
$OPC_MSG.NO_OF_ANNOTATIONS
Returns the number of annotations of a message. Sample output: 3
$OPC_MSG.NODE
Returns the managed node from which the selected message was issued. Sample output: kernighan.c.com
$OPC_MSG_NODES
Returns the names of all nodes on which the events that generated currently selected messages took place. The names are separated by spaces. Duplicate nodes are ignored. Sample output: kernighan.c.com richie.c.com
$OPC_MSG.OBJECT
Returns the object which was affected by, detected, or caused the event. Sample output: CPU
OPC_MSG.ORIG_TEXT
Returns the original text of the selected message. Sample output: SU 09/18 18:07 + 6 root-spooladm
$OPC_MSG.ORIG_TEXT[n]
Returns the nth word in the original text of the message. Sample output: the
$OPC_MSG.OWNER
Returns the owner of the selected message. Sample output: opc_op
$OPC_MSG.RECEIVED
Returns the date and time the message was received on the management server. Sample output: 09/18/01 18:08:10
$OPC_MSG.SERVICE
Returns the service name that is associated with the message. Sample output: VP_SM:Agent:ServicesProcesses@@kernighan.c.com
$OPC_MSG.SEVERITY
Returns the severity of the message. This can be Unknown, Normal, Warning, Minor, Major, or Critical. Sample output: Normal
$OPC_MSG.SOURCE
Returns the name of the application or component that generated the message. Sample output: Message:opcmsg(1|3)
$OPC_MSG.TEXT
Returns the complete text of the selected message. Sample output: The following configuration information was successfully distributed: Templates (OpC30-814)
$OPC_MSG.TEXT[n]
Returns the nth word in the text of the message text. Sample output: following
$OPC_MSG.TIME_OWNED
Returns the date and time when the message was acknowledged. Sample output: 09/18/01 18:11:10
$OPC_MSG.TYPE
Returns the message type of the message. Sample output: ECS

View Details

Examples of message variables

You can use the following examples of messages variables and parameters to perform daily tasks.

Accessing message attributes

You can access all message attributes with the following variable:

$OPC_MSG.ATTRIBUTES

You will need to add an attribute name. For example, to get the text of a message, use this:

$OPC_MSG.TEXT

When working with attributes that represent strings, you can access a specific word. For example, to get the fourth word in the text of a message, use this:

$OPC_MSG.TEXT[4]

Annotations are an exception to this rule. In annotations, an index specifies the annotations that are returned. For example, you would access the seventh annotation of the current selected messages this way:

$OPC_MSG.ANNOTATIONS[7]

Finding duplicate messages

If you need information about the number of message duplicates for an application, use this:

$OPC_MSG.DUPLICATES

Extracting creation time and severity

If you want to do some statistical calculations, specify the message creation time and the severity, as follows:

$OPC_MSG.CREATED
$OPC_MSG.SEVERITY

Extracting message text

If you have defined a policy rule that creates a message text with some status as the third word, and you want to extract this status easily and forward it to an application called evaluate_status, use this:

evaluate_status $OPC_MSG.TEXT[3].

Evaluating action attributes

If you want to use and evaluate action attributes, you could write shell scripts that check for automatic and operator-initiated actions. You can get more information about their status and whether they are annotated:

script_name $OPC_MSG.ACTIONS.AUTOMATIC

The first parameter would be TRUE if an automatic action was defined for the message. This script would be useful only if there are more attributes used afterwards, but not to check for every attribute if it is an empty string.

Accessing annotations

To access the second annotation of a selected message in an application, use this:

$OPC_MSG.ANNOTATIONS[2]

Node variables

$OPC_NODES
Returns the primary node name.

Availability: From all actions except automatic and operator-initiated commands.
- If the tool is launched from the Nodes folder in the console tree, this variable is replaced with the primary node name of the nodes that are selected at the time the tool runs.
- If the tool is launched from the Service folder in the console tree, this variable is replaced with the primary node name of the nodes that have been associated with the selected service and the selected action. If this list is empty, the primary node name of the node the service is hosted on is used.
- If the tool is launched from the Tools folder in the console tree, a node and service selector displays, allowing you to select the nodes and services to use to replace this variable.
$OPC_NODEID
Returns the node identifier (GUID) of a node.

Availability: From all actions except automatic and operator-initiated commands.
- If the tool is launched from the Nodes folder in the console tree, this variable is replaced with the GUIDs of the nodes that are selected at the time the tool runs.
- If the tool is launched from the Service folder in the console tree, this variable is replaced with the GUIDs of the nodes that have been associated with the selected service and the selected action. If this list is empty, the GIUID of the node the service is hosted on is used.
- If the tool is launched from the Tools folder in the console tree, a node and service selector displays, allowing you to select the nodes and services to use to replace this variable.

Node Group variables

$OPC_NODEGROUP_ID
Returns the identifier (GUID) of a node group.
$OPC_NODEGROUP_LABEL
Returns the display name of a node group.

Service variables

$OPC_SERVICE_NAME
Returns the ServiceName of a service.

Availability: Supports and fills in the name of the selected service. If a service is not selected, or an action is launched from a Node or Node Group, then these values will be NULL.
$OPC_SERVICE_LABEL
Returns the Caption of a service.

Availability: Supports and fills in the caption of the selected service name. If a service is not selected, or an action is launched from a Node or Node Group, then these values will be NULL.

Environment variables

$OPC_ENV(variable name)
Used to retrieve environment variables from the console that launched the action.

Example: $OPC_ENV(PATH): substitutes the variable with the PATH environment variable from the console machine.

Availability: From the actions launched from configured tools. Not available from the automatic or operator-initiated commands running on the console.