Job Management Partner 1/Integrated Management - Manager Command and Definition File Reference

[Contents][Index][Back][Next]


Automated action definition file (actdef.conf) (for conversion)

Format

[#automated-action-definition-file-version]
[DESC_VERSION=version-information]
 
[#automated-action-status-monitoring-parameter]
[Figure]0[: state_watch={true | false}]
 
[#automated-action-definition-parameter]
[Figure]0[ {+parameter-group-number|&}[Figure]1] {$event-ID|*}[Figure]1
[/message/] [,[/basic-event-information/] [,[/detailed-event-information/]
[,[/event-levels-of-extended-event-information/] ] ] ][Figure]1[attribute-name-of-extended-event-information=/attribute-value/
[,attribute-name-of-extended-event-information-2=/attribute-value/][,...] ][Figure]0
: [Figure]0[u=user-name[Figure]1] [e=environment-variable-file-name[Figure]1]
[d=execution-host-name|group-name[Figure]1] [dt=suppress-period[Figure]1]
[rt=delay-monitoring-period[Figure]1] [action]
   :
 

File

actdef.conf (automated action definition file) (for conversion)

Storage directory

In Windows
Console-path\conf\action\
shared-folder\jp1cons\conf\action\ (logical host)

In UNIX
/etc/opt/jp1cons/conf/action/
shared-directory/jp1cons/conf/action/ (logical host)

Description

This file defines (for conversion) conditions for executing actions by the automated action function of JP1/IM and the commands to be executed as the actions. Use the language encoding that is used by JP1/IM - Manager to specify this file.

When a JP1 event satisfying specified conditions is received, the automated action function executes automatically a specified command based on the definition specified in this file.

Each line of action definition information is called a parameter. There are three types of parameters in an automated action definition file:

You must specify the automated action definition file version and the automated action status monitoring parameter before the automated action definition parameters. If you specify the automated action definition file version and/or the automated action status monitoring parameter after any automated action definition parameters, the specified definition is ignored.

If you specify the automated action definition file version or the automated action status monitoring parameter more than once, the first definition specified takes effect and subsequent definitions are ignored.

Definition specification

The automated action status monitoring parameter and the automated action definition parameters specify one definition per line. A definition that will not fit on one line can be continued onto the next line.

An automated action definition parameter is specified in the format event-monitoring-condition:action-execution-definition, consisting of two components separated by a colon (:).

Priority order of event monitoring conditions

If a received JP1 event satisfies the execution conditions in multiple automated action definitions, only the automated action that has the highest priority level is executed (for each parameter group discussed below). The automated action priority order is determined by the following rules:

Parameter groups and AND conditions

Each automated action definition parameter belongs to a parameter group. A parameter group is a unit for checking the conditions for executing an automated action. Use of parameter groups enables you to specify complex conditions, such as when multiple actions are to be executed for a single JP1 event or when an action is to be executed only when multiple conditions are satisfied.

When a single JP1 event arrives at the manager of JP1/IM, the automated action definition parameters and execution conditions are compared for each parameter group in order of priority. When execution conditions that are satisfied are found, only the automated action definition parameter that has the highest priority is executed for each parameter group.

If you specify an ampersand (&) in a parameter group, an AND condition with the automated action definition parameter defined on the preceding line is created. When automated action definition parameters are specified in an AND condition, the corresponding action is executed when all the conditions are satisfied.

Checking the size of an automated action definition parameter

The following lists the items whose size is checked and the respective maximum sizes:

If a maximum size is exceeded, a message is displayed when the definition is applied and the corresponding automated action definition parameter is ignored.

Checking the specified information

Use the jcamakea command to check the information specified in the definition file.

When the definitions are applied

The definition of an automated action takes effect when the definition is applied by clicking the Apply button in the Action Parameter Definitions window in JP1/IM - View when JP1/IM - Manager is started, as well as when the jcachange command is executed to re-load the definition.

Information that is specified (automated action definition file version)

This subsection describes the information to be specified as the automated action definition file version.

DESC_VERSION=version-information
Defines the format version of the automated action definition file.

Table 2-11 Automated action definition file format version information

Version information Description
1 Not used. The value 2 is assumed for reading the file.
2 Automated action definition file version is 08-01 or later.
3 Automated action definition file version is 09-00.
Other
If this parameter is omitted or 1 is specified, the value 2 is assumed for reading the file. When the Apply button is clicked in the Action Parameter Definitions window in JP1/IM - View, the value 2 is set.
If a value other than 1, 2, or 3 is specified in this parameter, the file is read as an automated action definition file for version 09-00.
Because the format of an old automated action definition file version is compatible with the automated action definition file format for version 08-01 or later, the format for version 08-01 or later is assumed for reading the file.
If this parameter is specified on a line that is subsequent to a line containing an automated action definition parameter, the Action Parameter Definitions window can no longer be displayed in JP1/IM - View.
Use the jcamakea command to check the contents of the automated action definition file.

Information that is specified (automated action status monitoring parameter)

This subsection describes the information to be specified in the automated action status monitoring parameter.

state_watch={true | false}
Specifies whether the action status is to be monitored.
Specify either true or false. The default is false.
If true is specified, the Action Parameter Definitions window cannot be displayed in JP1/IM - View version 07-01 or earlier.
This parameter is effective only if it is specified before the automated action definition parameters.
If this parameter is specified on a line that is subsequent to a line containing an automated action definition parameter, the Action Parameter Definitions window can no longer be displayed in JP1/IM - View.
You should use the jcamakea command to check the contents of the automated action definition file.

When JP1/IM - View version 08-01 or later is connected to JP1/IM - Central Console version 08-01 or later, the automated action status monitoring parameter will always be output to the automated action definition file even when the action status is not to be monitored.

Information that is specified (automated action definition parameters)

This subsection describes each item that is specified in the automated action definition parameters. For details about the JP1 events, see 3. JP1 Events. Regular expressions and variables that can be specified in the definition are described later.

Event monitoring conditions
The items to be specified as the execution conditions in an automated action definition parameter are described below. The maximum length of a parameter that can be defined as execution conditions is 1,040 bytes.

{+parameter-group-number|&}
Specifies the parameter group number to which the automated action definition parameter on this line belongs, expressed as a single-digit number (from 0 to 9) preceded by a plus sign (+). If this information is omitted, 0 is assumed.
If you specify an ampersand (&), this parameter becomes part of an AND condition with the immediately preceding definition line, which means that the automated action definition parameter on this line belongs to the same parameter group as the parameter on the immediately preceding line.
Note that the parameter group number has nothing to do with the priority order for checking execution conditions or the sequence of executing actions.

$event-ID
Specifies the event ID preceded by the dollar sign ($). The specification format of an event ID is as follows:
 
  basic-part[:extended-part]
 
Specify the basic and extended parts each using from 1 to 8 hexadecimal numbers (from 0 to 7FFFFFFF). Alphabetic characters must be specified as lower-case letters.

*
Specifies that the target is all event IDs. When an asterisk (*) is specified, all events become subject to the action. If JP1 events occur frequently, a large number of actions will be implemented, in which case execution may be delayed. When you specify an asterisk, you should narrow down the applicable events by using other conditions (such as a message, basic event information, detailed event information, and extended event information).

message
Specifies as an execution condition a message text associated with the JP1 event. You can use a regular expression for the condition. When you use a regular expression, specify the message text without control codes.
To express / in a regular expression, specify \/.

basic-event-information
Specifies information about JP1 event basic attributes that are to be used as an execution condition. You can use a regular expression to specify this information.
To express / in a regular expression, specify \/. For details about regular expressions, see G. Regular Expressions in the Job Management Partner 1/Integrated Management - Manager Overview and System Design Guide.
The basic event information is passed as information about JP1 event basic attributes in the format shown below. Use this format to specify a condition for executing an action.
 
event-ID[Figure]event-source-user-name[Figure]event-source-user-ID[Figure]
event-source-group-name[Figure]event-source-group-ID[Figure]
event-issuing-server-name[Figure]event-source-process-ID[Figure]
event-registration-year-month-day[Figure]event-registration-time[Figure]event-source-host-IP-address
 
For details about the information included in the JP1 event basic attributes, see 3. JP1 Events.

detailed-event-information
Specifies information about detailed attributes in the JP1 event basic attributes that is to be used as an execution condition.
You can use a regular expression to specify this information.
To express / in a regular expression, specify \/. For details about regular expressions, see G. Regular Expressions in the Job Management Partner 1/Integrated Management - Manager Overview and System Design Guide.
The detailed attributes in the JP1 event basic attributes consist of additional JP1 event information. The details and format of this information depend on the JP1 event. If the detailed attribute information is specified in binary format, it is treated as no information (NULL).
  • Remarks: The detailed attributes in the JP1 event basic attributes are used principally to record detailed information provided by products that issue events that are compatible with the JP1/SES format of version 5 or earlier. Most products whose version is 6 or later use the JP1 event extended attributes to record detailed information.

event-levels-of-extended-event-information
Specifies the severity levels in the extended attributes of the JP1 events that are to be set as an execution condition. Specify the event levels (severities) by combining the applicable characters in the following format:
  -------E  Event level:Emergency
  ------A-  Event level:Alert
  -----C--  Event level:Critical
  ----E---  Event level:Error
  ---W----  Event level:Warning
  --N-----  Event level:Notice
  -I------  Event level:Information
  D-------  Event level:Debug
For example, to set as a condition all severities at the Error and higher event levels, specify /----ECAE/.

attribute-name-of-extended-event-information=/attribute-value/
Specifies a combined name and value of the JP1 event extended attribute used to form an execution condition. You can use a regular expression to specify this information.
To express / in a regular expression, specify \/.
You can specify a maximum of 100 pairs of attribute name and attribute value combinations.
For an attribute name, you can specify from 1 to 32 bytes of upper-case letters, numeric characters, and the underscore (_). The attribute name cannot contain a colon (:) or an equal sign (=). Specify an attribute name in a form such as PRODUCT_NAME or OBJECT_NAME. Unlike the settings in other functions, this attribute name is not prefixed with E..
If you specify an event level in this item (item name SEVERITY), specify the attribute value as a character string, such as Emergency or Alert.

Action execution definition
The following describes the items in an automated action definition parameter that can be used to specify an action execution definition.

u=user-name
Specifies the user name of the JP1 user who executes the action.
Express the user name using from 1 to 31 bytes of characters. A user name cannot contain a space.
If this parameter is omitted, the system assumes the JP1 user name specified as the default action execution user in the definition of the automated action execution environment. If the default action execution user is also omitted, jp1admin is assumed.
You can use a variable to specify information contained in the received JP1 event as the JP1 user name.
When the action is executed, the JP1 user specified here is mapped to the OS user at the execution host that will execute the command, according to the JP1/Base definition. In UNIX, the shell environment of the mapped OS user is used for execution.
If <RULE> is specified in action, this item cannot be specified.

e=environment-variable-file-name
Specifies the full path name of the environment variable file that specifies environment variables for the command that is to be executed as the action.
The file name can be a character string with a maximum size of 255 bytes. If the file name contains a space, enclose the entire name in double-quotation marks ("").
You can use a variable to specify information contained in the received JP1 event as the file name. For example, to set the JP1 event extended attribute named ENVFILE as the environment variable file name, specify $EV"ENVFILE".
For details about the format of the environment variable file, see Environment variable file in 2. Definition Files.
If <RULE> is specified in action, this item cannot be specified.

d=execution-host-name|group-name
Specifies the name of the host or host group that is to execute the action. For a host name, specify a name set as a managed host in the system configuration definition. A host name or host group name cannot contain a space.
If this parameter is omitted, the action is executed at the local host (the host that contains the automated action definition file).
You can use a variable to specify information contained in the received JP1 event as the host name or group name. For example, to execute the action on the host that issued the event, specify $EVHOST.
If <RULE> is specified in action, this item cannot be specified.

dt=suppress-period
Specifies a period during which action execution is to be suppressed. The action for the action conditions is suppressed if it would occur during the period specified in this parameter. If this parameter is omitted, the action is not suppressed. Express the suppression period using from 1 to 4 bytes of numeric characters. The permitted value range is from 1 to 3,600 (seconds).
When this parameter is specified, JP1/IM - View version 07-01 or earlier cannot display the Action Parameter Definitions window.
Note that this parameter cannot be specified in the following case:
  • & is specified.

rt=delay-monitoring-period
Specifies a period during which monitoring for the action execution is performed. If the amount of time specified in this parameter expires before a command control action termination message is received from the execution host after a JP1 event arrived at JP1/Base at the manager, a delay of action is reported by using a method such as JP1 event issuance or command execution. This parameter is optional. If this parameter is omitted, no monitoring for action delay is performed.
Express the delay monitoring period using a maximum of five bytes of numeric characters. The permitted value range for the delay monitoring period is from 1 to 86,400 (seconds).
When this parameter is specified, JP1/IM - View version 07-01 or earlier cannot display the Action Parameter Definitions window.

action
Specifies the command that is to be executed as the action.
For details about the specifiable commands, see 5. Command Execution by Automated Action in the Job Management Partner 1/Integrated Management - Manager Overview and System Design Guide.
If this parameter is omitted, no action is taken even when conditions for action execution are satisfied.
You can use a variable to specify information contained in the received JP1 event as the command parameter.
If the host where the automated action is defined is UNIX, you can use a variable to specify information contained in the received JP1 event as the command environment variable. For example, MESSAGE="$EVMSG" command arg1 arg2 can be specified.
Note that the colon (:) in the automated action definition parameter is followed by the action to be executed. If you simply specify u=, e=, d=, dt=, or rt=, it is treated as being part of the previous information, such as a user name. If you specify information such as u= and omit the action, an error will result.
The maximum length of a command that can be executed as an action is 4,096 bytes, including the information obtained after converting variables to be used in the action definition (such as $EVMSG). If the command length exceeds 4,096 bytes, the execution status becomes Fail, in which case the command is not executed. In such a case, the message KAVB4421-W Cannot execute action because command line is too long is displayed in the Message field in the Action Log Details window.
If an action contains a code that cannot be recognized as a character, the action might not be executed by the shell at the execution host or might result in an error when the action attempts to execute. In such a case, the action results in terminated status, not an execution failure. Even though there might be no invalid code in the definition file, an invalid code might be generated when a variable used in the action definition is replaced with the actual value. For details about the correct specification of variables in an action definition, consult the documentation for the products that issue action-related events.
To set a rule startup request to JP1/IM - Rule Operation, specify <RULE>. When <RULE> is specified, user-name, execution-host-name, and environment-variable-file-name cannot also be specified. If one of these items is specified together with <RULE>, the KAVB4550-W message is displayed and the automated action definition parameter is not output to the standard output.
Notes about the length of an action command
The maximum length of a command that can be executed as an action depends on the system where JP1/IM - Manager and JP1/Base are running.
If any of the hosts on the automated action execution route (including the source manager host and target execution host) runs JP1/IM - Manager or JP1/Base version 6 or version 7, the maximum length of a command must not exceed 1,024 bytes. For notes about the length of a command, see 11.4(2) Notes in the Job Management Partner 1/Integrated Management - Manager Overview and System Design Guide.

Variables that can be used in the action definition

In a definition of automated action definition parameters, you can use variables in the specification of the action to be executed (specification following a colon (:)) to set information contained in the JP1 event. When the action is executed, the variables are replaced with the actual information in the JP1 event.

To specify a variable in an automated action definition parameter, use a format such as $EVID.

The following table lists the describes the available variables.

Table 2-12 Variables that can be used in the action definition

Type of information Variable name Description
Information contained in the basic attributes of JP1 events EVBASE Entire basic event information
EVID Event ID (basic-code:extended-code)
EVDATE Event generation date (YYYY/MM/DD)
EVTIME Event generation time (hh:mm:ss)
EVPID Event source process ID
EVUSRID User ID of the event source process
EVGRPID Group ID of the event source process
EVUSR Event source user name
EVGRP Event source group name
EVHOST Event source host name
EVIPADDR Event source IP address
EVSEQNO Serial number
EVARVDATE Event arrival date (YYYY/MM/DD)
EVARVTIME Event arrival time (hh:mm:ss)
EVSRCNO Serial number at the event source
EVMSG Entire message text
EVDETAIL Entire detailed event information
Information contained in the extended attributes of JP1 events EVSEV Severities in extended event information (Emergency, Alert, Critical, Error, Warning, Notice, Information, Debug)
EV"extended-attribute-name" Any extended attribute
Other ACTHOST Manager host name at the action request source
EVENV1 to EVENV9 Data obtained by specifying "( )" in a regular expression in the specification of an action execution condition (applicable only when an extended regular expression is used at the manager host)

The value of the variable for an invalid item is NULL. Depending on the type of JP1 event, the action might not be executable or might result in an error if it is executed with a missing variable or with a code in the attribute information that cannot be recognized as a character. Consult the documentation for the products that issue JP1 events beforehand for correct specification of the information.

Notes about specifying variables

Regular expressions in the action definition

This subsection describes how to use regular expressions to specify the attributes of JP1 events (message text, basic attributes, and detailed information) in an event monitoring condition of an automated action definition.

The supported regular expressions depend on the OS. The regular expressions supported by Windows and UNIX are described below.

If you share the same action definitions among different OSs, specify conditions using expressions that are supported by all the OSs because interpretation of regular expressions depends on the OS. Regular expressions supported by all OSs are presented in G. Regular Expressions in the Job Management Partner 1/Integrated Management - Manager Overview and System Design Guide. Consult this information to determine the regular expressions that can be used.

Regular expressions for the Windows version

For the Windows version, you can set the supported regular expressions to either JP1-specific regular expressions or extended regular expressions. The default is extended regular expressions. For details about how to use the JP1-specific regular expressions, see Automated action environment definition file (action.conf.update) in 2. Definition Files.

In the case of automated actions in JP1/IM, you can also use the extended notations shown below, in addition to the OS's regular expressions:

\/, \\
Even in an expression enclosed in brackets, / and \ are treated as characters. This method is used to specify / and \ in regular expressions.

Regular expressions for the UNIX version

For the UNIX version, use the extended regular expressions. For details about the supported regular expressions, see the OS-provided regexp(5).

In the case of automated actions in JP1/IM, you can also use the extended notations shown below, in addition to the OS's regular expressions:

\/, \\
Even in an expression enclosed in brackets, / and \ are treated as characters. This method is used to specify / and \ in regular expressions.

Specifying the basic and detailed attributes using regular expressions

This subsection describes how to use regular expressions to specify basic attributes and detailed information about JP1 events in the event monitoring conditions.

The basic attributes of a JP1 event are expressed in the automated action definition parameters in the following format:

 
event-ID#1[Figure]event-source-user-name[Figure]event-source-user-ID[Figure]
event-source-group-name[Figure]event-source-group-ID[Figure]
event-issuing-server-name#2[Figure]event-source-process-ID[Figure]
event-registration-year-month-day#3[Figure]event-registration-time#4[Figure]event-source-host-IP-address
 

#1
The event ID is expressed in the format basic-code:extended-code. The basic code and extended code are each an 8-digit hexadecimal number (characters from A to F must be upper case). Any leading zeros in the ID are omitted. If the extended code is 00000000, the event ID is expressed as basic-code:0.

#2
In the event that the server name differs from the host name and the method for acquiring the event issuing host name is set to local, the host name is used, not the event server name.

#3
Expressed in the format YYYY/MM/DD.

#4
The event registration time is expressed in the format hh:mm:ss.
 

The detailed information about a JP1 event is expressed in the following format:

 
information-1[Figure]information-2[Figure]information-3[Figure]...[Figure]information-n[Figure]
 

Note:
Depending on the program, the detailed information might not be in this format or it might contain codes that cannot be recognized as characters, such as when only one byte of a multi-byte character is included because of fixed-length requirements. For details about the format, see the documentation for each program.

For both basic attributes and detailed information, each item in the information is separated by a space.

When there is no corresponding information, the item is treated as NULL and multiple consecutive delimiter spaces are displayed. Note that in the future more information might be added after the last item due to functionality extensions.

How to specify each item in the basic attributes and the detailed information is described below.

When you specify the first item in the basic attributes and detailed information, use a caret (^) to indicate the start of a character string. For example, the following specifies the JP1 event whose event ID is 00003A80:

^3A80

In specifying the second and subsequent items, use .* (indicating any character string or space) to skip each unneeded item. For example, to specify the event issuing host name, which is the 6th item in the basic event attributes, repeat .* five times, as follows:

^.*[Figure].*[Figure].*[Figure].*[Figure].*[Figure]host01

The following are examples of specifying event information:

Example 1: JP1 event sent from the user whose user name begins with JP1USER:
^.*[Figure]JP1USER.*$

Example 2: JP1 event issued at host01 to host05 (when an extended regular expression is used):
^.*[Figure].*[Figure].*[Figure].*[Figure].*[Figure]host0[1-5][Figure].*$

Example 3: JP1 event registered from 08:00 to 08:10 at host02 (when a extended regular expression is used):
^.*[Figure].*[Figure].*[Figure].*[Figure].*[Figure]host02[Figure].*[Figure].*[Figure]08:(10|0[0-9]).*[Figure].*$

Example 4: JP1 event whose third item begins with prn in the detailed information:
^.*[Figure].*[Figure]prn.*$
 
Note: For the format of detailed information, see the documentation of the program that issues the JP1 events.

Notes about regular expressions
  • To use extended regular expressions by extending JP1-specific regular expressions (Windows), you must re-evaluate the existing definition settings and redefine them for extended regular expressions in order to avoid any malfunction that might be caused by the extension.
  • The handling of control codes (such as linefeeds and tabs) might vary depending on the product and OS. If you use a regular expression to specify a message as a condition, specify only the message text without the control codes.
  • If you use many instances of .* in a regular expression to indicate all characters, the search processing might take a considerable amount of time. For data such as a long message, use .* only where it is needed.
    In an environment that supports extended regular expressions, you can use [^ ]* instead of .* to match any character other than the space. By using [^ ]* instead of .*, you can reduce the time required for search processing.
  • The vertical bar |, which is a special character, represents the OR condition. When you use this OR condition in regular expressions, note the following:
    Because the vertical bar | indicating an OR condition has a low priority level, you must explicitly specify the range of the OR condition. Omitting the range might result in no operation or a malfunction. To specify the range of an OR condition, enclose it in parentheses (). The example below specifies an OR condition for the event-issuing server name.
    Example: JP1 event issued at gyoumu or host:
    ^.*[Figure].*[Figure].*[Figure].*[Figure].*[Figure](gyoumu|host)[Figure].*$

Example definition

This example executes Act.exe and \test\sample.exe when the two events shown below occur (the example does not monitor the action status):

Table 2-13 Example definition in the automated action definition file

Event ID Event level Object name
555, 100 Critical, Error /ACTION
 
DESC_VERSION=2
:state_watch=false
$555 :Act.exe
& $100 /KAVB.*-E/,,,/----EC--/ OBJECT_NAME=/\/ACTION/ :\test\sample.exe

[Contents][Back][Next]


[Trademarks]

All Rights Reserved. Copyright (C) 2009, Hitachi, Ltd.