Hitachi

JP1 Version 12 JP1/Integrated Management 2 - Manager Command, Definition File and API Reference

Automated action definition file (actdef.conf)

Organization of this page

Format

[#automated-action-definition-file-version]
[DESC_VERSION=version-information]
 
[#automated-action-status-monitoring-parameter]
cmn
    [sta {true|false}]
end-cmn
 
[#automated-action-definition-parameter]
act action-name
    [prm parameter-group]
    [cmt comment]
    aid action-ID
    [valid true|false]
    eid event-ID
 
    cnd
        event-conditions
    end-cnd
 
    [usr user-name]
    [hst {execution-host-name|group-name|business-group-name|monitoring-group-name}]
    [{cmd action|rul}]
    [var environment-variable-file-name]
 
    [det suppress-period]
    [ret delay-monitoring-period]
end-act

To Page Top

File

actdef.conf (automated action definition file)

actdef.conf.model (model file for the automated action definition file)

To Page Top

Storage directory

In Windows
For a physical host:

Console-path\conf\action\

For a logical host:

shared-folder\jp1cons\conf\action\

In UNIX
For a physical host:

/etc/opt/jp1cons/conf/action/

For a logical host:

shared-directory/jp1cons/conf/action/

To Page Top

Description

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

The maximum size of an automated action definition file is 22 megabytes (23,068,672 bytes).

The automated action function automatically executes a specified command on the basis of the definition specified in this file when a JP1 event satisfying specified conditions is received.

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 the 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

  • Use the space or the tab to separate the words in a parameter.

  • Any space or tab character at the beginning or at the end of a line is ignored.

  • A line beginning with hash mark (#) is regarded as a comment except when the hash mark (#) is preceded by a character string.

  • Use lowercase letters to specify the parameter names in action definitions. A specified parameter name that contains uppercase letters is treated as being invalid and results in a definition error.

Action priority

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

  • The first action specified in the automated action definition file (in GUI, the first action displayed in the Action Parameter Definitions) takes precedence over the other actions.

You can change the action priority order in the common definition. For details about the priority order of automated actions, see 6.3.2 Precedence of execution conditions in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

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 host 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 specified information

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

To Page Top

When the definitions are applied

The definition of an automated action takes effect when you click the Apply button in the Action Parameter Definitions window in JP1/IM - View when JP1/IM - Manager starts, or when you execute the jcachange command.

If you want to execute the jcachange command to re-load the definition, execute the jcamakea command first to make sure there are no errors in the definition.

To Page Top

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. Specify this definition on the first line of the automated action definition file (the first line in the file excluding null lines and comment lines). If this information is specified on a line other than the first line, a definition error results.

Table 2‒13: Automated action definition file format version information

Version information

Description

1

Automated action definition file version is 07-11 to 07-51.

2

Automated action definition file version is 08-01 to 08-50.

3

Automated action definition file version is 09-00 to 11-10.

4

Automated action definition file version is 11-50 or later.

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, 3, or 4 is specified in this parameter, an error is output to the integrated trace log and the value 3 is assumed as the version information for reading the file.

In such a case, the Action Parameter Definitions window cannot be displayed in JP1/IM - View. To change the version information, directly edit the definition file.

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.

To Page Top

Information that is specified (automated action status monitoring parameter)

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

cmn to end-cmn

These are the start and end parameters for the block that specifies a parameter that is applicable to all action definitions. The portion between cmn and end-cmn is called a common block. This block must be specified before the automated action definition parameters. Specify this parameter only once in the automated action definition file. Specification of this block is optional. If this block is omitted, false is assumed for the sta parameter. The AND condition is applied to each event condition.

sta {true|false}

Specifies whether the action status is to be monitored.

Specify either true or false. To monitor the action status, specify true. To not monitor the action status, specify false. The default is false.

To Page Top

Information that is specified (automated action definition parameters)

This subsection describes each item that is specified in the automated action definition parameters.

act action-name to end-act

Specifies the start and end parameters of an automated action definition. There is no limit to the number of actions that can be defined between act and end-act; however, at least one action must be specified. The portion between act action-name and end-act is called an action block.

After act, specify an action name, expressed using from 1 to 50 bytes of characters. The permitted characters are all characters other than the control characters (from 0x00 to 0x1F and from 0x7F to 0x9F).

Each action name must be unique among the action names specified in all the action blocks. The parameters that can be specified in the action block are as follows:

prm, cmt, eid, cnd to end-cnd, usr, hst, cmd, rul, var, det, ret, aid, valid

prm parameter-group

Specifies a number for the parameter group. If this parameter is omitted, 0 is assumed.

You can specify a single numeric digit (from 0 to 9) or the ampersand (&). If you specify a numeric digit, you cannot omit the action name. If you specify an ampersand (&), this parameter becomes part of an AND condition with the immediately preceding action block, which means that the automated action definition parameter in this action block belongs to the same parameter group as the immediately preceding action block. When an ampersand (&) is specified, the action name cannot be specified.

Following an action block for which the ampersand is not specified, you can specify a maximum of 9 action blocks as members of an AND condition (for a total of 10 action blocks including the first action block).

Within the same parameter group, the first action block specified (in the GUI, the top action block displayed in the Action Parameter Definitions window) has precedence over the other action blocks. When a JP1 event arrives at the manager, it is matched against the event conditions in the action block for each parameter group in the order of priority. When event conditions are found that match the JP1 event, the action in the action block that has the highest priority is executed for the parameter group and no more matching is performed for the action blocks that follow the executed action block. Events are matched in ascending order of parameter groups. For details about the priority order of automated actions, see 6.3.2 Precedence of execution conditions in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

cmt comment

Specifies a comment about the action block. This parameter is optional. Specify a comment using from 1 to 1,040 bytes of characters. All characters are permitted. If a comment exceeds 1,040 bytes in length, the portion in excess of 1,040 bytes is deleted.

aid action-id

Specifies the action ID. This parameter cannot be omitted. The action ID can be any number from 0 to 2,147,483,647. However, this parameter cannot be specified when you have specified & for the parameter-group.

This parameter can be specified only when the version information is 4.

valid true|false

Enables or disables (specifies true or false, respectively) the automated action definition. This parameter is optional. If this parameter is omitted, the value is assumed to be true. However, this parameter cannot be specified when you have specified & for the parameter-group. When you have specified & for the parameter-group, the status (enabled or disabled) of the automated action definition depends on the status of the previous action execution condition.

This parameter can be specified only when the version information is 4.

eid event-ID

Specifies the event ID for the action conditions. This parameter is mandatory and can be specified only once.

An event ID consists of a base part and an extension part. Express each part of an event ID as a string of from 1 to 8 hexadecimal characters, and separate the base part from the extension part with a colon (:). An event ID is not case sensitive. The extension part can be omitted. To specify any event ID, use an asterisk (*). 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).

The following shows an example:

Example: Specify event ID A as follows:

eid a

eid A

eid 0000000a

eid 0000000A

eid 0000000A:0

eid 0000000A:00000000

Example: Specify any event ID as follows:

eid *

cnd event-conditions to end-cnd

Specifies the start and end parameters of the block that specifies event conditions for executing an action. Specification of an event condition block is mandatory. Specify only one event condition block within an action block. You can specify from 0 to 256 event conditions in an event condition block. The AND condition is applied to each event condition.

event-conditions

Specifies the event conditions in the following format (Δ indicates a single-byte space):

attribute-nameΔcomparison-keywordΔoperand[Δoperand]...

Note that a line consisting of only spaces or tabs is ignored during processing.

attribute-name

Specifies the name of an attribute that you want to compare. To specify a basic attribute, place B. immediately before the name. To specify an extended attribute (common information or user-specific information), place E. immediately before the name. Attribute names are case sensitive.

comparison-keyword

Specifies one of BEGIN (begins with), IN (matches), NOTIN (does not match), SUBSTR (includes), NOTSUBSTR (does not include), or REGEX (regular expression) as the comparison keyword. The comparison keyword is case sensitive.

operand

Specifies a character string as the value that is to be compared with the attribute value by the specified comparison keyword. Operands are case sensitive.

To specify multiple operands, separate them with one or more consecutive spaces or a tab. The OR condition is applied to the specified operands. Note that when a regular expression is specified, only one operand can be specified.

To use a space, tab, end-of-line code (CR or LF), or % as part of an operand value, you must specify a value shown below:

No.

Value to be used

What to specify

1

Tab (0x09)

%09

2

Space (0x20)

%20

3

% (0x25)

%25

4

Linefeed code LF (0x0a)

%0a

5

Carriage return code CR (0x0d)

%0d

The character code specified after % is not case sensitive. When a JP1 regular expression is used, %0d cannot be specified. The following shows an example of defining ID matches 100 and 200, which selects multiple operands:

B.IDΔINΔ100Δ200

Legend: Δ indicates a single-byte space (0x20)

You can specify a maximum of 4,096 bytes of operands per event condition and per event condition block (total length in bytes of all operands that are specified in the event condition block).

Basic event information

If you specify B.BASIC as the attribute name, you can set the same conditions as for basic event information in the automated action definition file (for conversion).

When you specify B.BASIC as the attribute name, you must specify REGEX as the comparison keyword.

You can specify the operands in the same format as is used for basic event information in the automated action definition file (for conversion). Note that to use a space, tab, end-of-line code (CR or LF), or percent sign (%), specify %. Specify a forward slash (/) as /; there is no need to specify it as \/.

Detailed event information

If you specify B.DETAIL as the attribute name, you can set the same conditions as for detailed event information in the automated action definition file (for conversion).

When you specify B.DETAIL as the attribute name, you must specify REGEX as the comparison keyword.

You can specify the operands in the same format as is used for detailed event information in the automated action definition file (for conversion). Note that to use a space, tab, end-of-line code (CR or LF), or percent sign (%), specify %. Specify a forward slash (/) as /; there is no need to specify it as \/.

The following table lists and describes the attribute names, comparison keywords, and operands that can be specified in an event condition.

Table 2‒14: Attribute names, comparison keywords, and operands that can be specified in an event condition

No.

Item

Attribute name

Comparison keywords

Operand

1

Event ID

B.ID

  • Match

  • Does not match

  • Regular expression

Specifies an event ID.

  • A maximum of 100 event IDs can be specified. However, if a regular expression is used, only one event ID is allowed.

  • In the case of Match or Does not match, the event ID is not case sensitive.

  • The permitted range is from 0 to 7FFFFFFF.

  • In the case of a regular expression, the event ID of an event to be compared is treated as having the following format:

    • When the extended part of the event ID is 0:

    basic-part-of-event-ID (8-digit hexadecimal value consisting of uppercase letters and numbers)

    • When the extended part of the event ID is not 0:

    basic-part-of-event-ID (8-digit hexadecimal value consisting of uppercase letters and numbers):extended-part-of-event-ID (8-digit hexadecimal value consisting of uppercase letters and numbers)

If the basic part or extended part of an event ID is a value that consists of fewer than 8 characters, leading 0s are added to obtain a string of 8 characters.

2

Source process ID

B.PROCESSID

  • Match

  • Does not match

  • Regular expression

Specifies the process ID of the application program that issues the event.

  • A maximum of 100 source process IDs can be specified. However, if a regular expression is used, only one source process ID is allowed.

  • The permitted value range is from -2,147,483,648 to 2,147,483,647.

3

Registered time

B.TIME

Regular expression

Specifies the time the JP1 event was registered into the event database at the source host.

  • A regular expression in the format YYYYMMDDhhmmss must be used.

4

Arrived time

B.ARRIVEDTIME

Regular expression

Specifies the time the JP1 event arrived at the event database at the source host.

  • A regular expression in the format YYYYMMDDhhmmss must be used.

5

Source user ID

B.USERID

  • Match

  • Does not match

  • Regular expression

Specifies the user ID (numeric value) of the source process.

  • A maximum of 100 source user IDs can be specified. However, if a regular expression is used, only one source user ID is allowed.

  • The permitted value range is from -2,147,483,648 to 2,147,483,647.

6

Source group ID

B.GROUPID

  • Match

  • Does not match

  • Regular expression

Specifies the group ID (numeric value) of the source process.

  • A maximum of 100 source group IDs can be specified. However, if a regular expression is used, only one source user ID is allowed.

  • The permitted value range is from -2,147,483,648 to 2,147,483,647.

7

Source user name

B.USERNAME

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the user name of the source process.

  • A maximum of 100 source user names can be specified. However, if a regular expression is used, only one source user name is allowed.

8

Source group name

B.GROUPNAME

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the group name of the source process.

  • A maximum of 100 source group names can be specified. However, if a regular expression is used, only one source group name is allowed.

9

Source IP address

B.SOURCEIPADDR

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the IP address of the event-issuing server.

  • A maximum of 100 source IP addresses can be specified. However, if a regular expression is used, only one source IP address is allowed.

  • To specify an IPv6 address, use a four-digit value in hexadecimal (0 to 9 and a to f) as shown below. The alphabetic characters are case sensitive.

    Example: 0011:2233:4455:6677:8899:aabb:ccdd:eeff

  • Lowercase letters cannot be changed to uppercase alphabetic characters, and IPv4-mapped address, IPv4-compatible addresses, and abbreviated IPv6 addresses cannot be specified.

10

Event-issuing server name (source host)#

B.SOURCESERVER

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the host name of the host (event server name) where the JP1 event occurred.

  • A maximum of 100 event-issuing server names can be specified. However, if a regular expression is used, only one event-issuing server name is allowed.

11

Message

B.MESSAGE

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the message for a basic attribute of the event.

  • A maximum of 100 messages can be specified. However, if a regular expression is used, only one message is allowed.

12

Detailed event information

B.DETAIL

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies detailed information for a basic attribute of the event.

  • A maximum of 100 detailed information items can be specified. However, if a regular expression is used, only one detailed information item is allowed.

  • If binary data is set in the detailed information for the JP1 event, the detailed information is treated as being the null character "" (0 bytes) for performing comparison.

  • Available for compatibility purposes.

13

Reason for registration

B.REASON

  • Match

  • Does not match

Specifies a reason for registration.

  • A maximum of 100 reasons for registration can be specified.

14

Start time

E.START_TIME

Regular expression

Specifies the execution start or restart time.

  • This item cannot be specified more than once.

  • Specify the absolute time in seconds using a regular expression.

15

End time

E.END_TIME

Regular expression

Specifies the execution end time.

  • This item cannot be specified more than once.

  • Specify the absolute time in seconds using a regular expression.

16

Product name

E.PRODUCT_NAME

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the name of the product that issued the JP1 event.

  • A maximum of 100 product names can be specified. However, if a regular expression is used, only one product name is allowed.

17

Object type

E.OBJECT_TYPE

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the type of object.

  • A maximum of 100 object types can be specified. However, if a regular expression is used, only one object type is allowed.

18

Object name

E.OBJECT_NAME

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the object name of the JP1 event.

  • A maximum of 100 object names can be specified. However, if a regular expression is used, only one object name is allowed.

19

Root object type

E.ROOT_OBJECT_TYPE

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the root object type of the JP1 event.

  • A maximum of 100 root object types can be specified. However, if a regular expression is used, only one root object type is allowed.

20

Root object name

E.ROOT_OBJECT_NAME

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the root object name of the JP1 event.

  • A maximum of 100 root object names can be specified. However, if a regular expression is used, only one root object name is allowed.

21

Object ID

E.OBJECT_ID

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the object ID of the JP1 event.

  • A maximum of 100 object IDs can be specified. However, if a regular expression is used, only one object ID is allowed.

22

Occurrence

E.OCCURRENCE

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the occurrence of the JP1 event.

  • A maximum of 100 occurrences can be specified. However, if a regular expression is used, only one occurrence is allowed.

23

User name

E.USER_NAME

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the user name of the user who issued the JP1 event.

  • A maximum of 100 user names can be specified. However, if a regular expression is used, only one user name allowed.

24

Result code

E.RESULT_CODE

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the termination code.

  • A maximum of 100 termination codes can be specified. However, if a regular expression is used, only one termination code is allowed.

25

Severity

E.SEVERITY

  • Match

  • Regular expression

Specifies the severity of the JP1 event.

  • The following severity levels can be specified: Emergency, Alert, Critical, Error, Warning, Notice, Information, or Debug.

  • Multiple severity values can be specified. However, if a regular expression is used, only one severity value is allowed.

26

Event source host name#

E.JP1_SOURCEHOST

  • First characters

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • Regular expression

Specifies the event source host name of the JP1 event.

  • A maximum of 100 reasons for registration can be specified. However, if a regular expression is used, only one reason for registration is allowed.

27

Basic event information

B.BASIC

Regular expression

You can specify basic event information for compatibility with version 8 or earlier.

28

Program-specific extended attribute

--

  • Match

  • Does not match

  • Is contained

  • Is not contained

  • First characters

  • Regular expression

Specifies the attribute name of a program-specific extended attribute.

  • You can specify a name with a maximum length of 32 bytes that begins with an uppercase letter and consists of uppercase letters, numeric characters, and the underscore (_).

  • A maximum of 100 extended attribute names can be specified. However, if a regular expression is used, only one extended attribute name is allowed.

Legend:

--: None

#

If the integrated monitoring database and the IM Configuration Management database are enabled, and the comparison keyword is Match or Do not match, the business group name can be specified in a path format.

If the integrated monitoring database and the IM Configuration Management database are disabled, and a comparison keyword other than Match and Do not match is selected, a business group name specified in a path format is treated as a host name.

If the -ignorecasehost option of the jcoimdef command is set to ON, and a comparison keyword other than Regular expression is selected, the character string is no longer case sensitive.

usr user-name

Specifies the user name of the JP1 user who executes the action. The usr parameter is optional. 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.

The number of characters you can specify is 1 to 31 bytes for the user name. Only one-byte alphanumeric characters can be used. Alphabetic characters are not case sensitive. You can specify a variable for the user name. You specify a variable when you want to set information contained in the received JP1 event as the user name.

You can set event information for the 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. Note that this parameter cannot be specified together with the rul parameter.

hst {execution-host-name|group-name|business-group-name|monitoring-group-name}

Specifies the name of the host on which an action is executed, a host group name, a business group name, or a monitoring group name. For a host name, specify a name set as a managed host in the system configuration definition. The hst parameter is optional. If it is omitted, the local host is assumed.

Express the execution host name or host group name using from 1 to 255 bytes of characters. The execution host name or host group name cannot contain the space character. You can specify a variable for the execution host name or host group name. You specify a variable when you want to set information contained in the received JP1 event as the execution host name or host group name. For example, to execute the action on the host that issues the event, specify $EVHOST.

You can set event information for the execution host name or host group name.

For a business group name and monitoring group name, you can specify a character string with a maximum of 2,048 bytes. If the specified character string begins with a slash (/), it is treated as a business group name or a monitoring group name. Note, however, that the character string is treated as a host name or a host group name if the integrated monitoring database and the IM Configuration Management database are disabled.

Note that this parameter cannot be specified together with the rul parameter.

cmd action

Specifies the command that is to be executed as the action. For details about the specifiable commands, see Chapter 6. Command Execution by Automated Action in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

The cmd parameter is optional. If this parameter is omitted, no action is taken even when conditions for action execution are satisfied.

Note that if any of the following parameters is omitted, omitting the cmd parameter results in a definition error:

usr, var, hst, det, ret

The cmd parameter cannot be specified more than once. Specify the parameter using from 1 to 4,096 bytes of characters. Any tabs or spaces preceding the action are deleted, but spaces following the action are not deleted.

This parameter cannot be specified together with the rul parameter.

You can set event information for the action.

You can use a variable to specify information contained in the received JP1 event. For example, if the execution host is UNIX, the following specification sets the name of the host that issued the JP1 event in the HOSTNAME environment variable:

HOSTNAME="$EVHOST" action

xxx_BASIC="$EVBASE" xxx_MESSAGE="$EVMSG" action

Notes about the length of an action command

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 is displayed in the Message field in the Action Log Details window.

The length of a command that can be executed as an action also 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 12.4.1 Notes regarding the considerations for automated actions in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

Notes about codes that cannot be recognized as characters in an action

If codes (ASCII codes and characters not included in the character set of the multi-byte characters encoding specified in the environment settings) that are not recognizable as characters are included in an action, the action might not be executed, or if it is executed, might result in an error because of the shell or other specifications on the execution host. 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.

rul

Specifies that a rule startup request to JP1/IM - RL is to be set. This parameter cannot be specified together with the var, cmd, usr, or hst parameter.

var 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. This parameter is optional. If this parameter is omitted, it is assumed that there is no environment variable file. For details about the format of an environment variable file, see the JP1/Base User's Guide.

Express the environment variable file name using from 1 to 255 bytes of characters. You can set event information for the environment variable file name. You can specify a variable for the environment variable file name. You specify a variable when you want to set information contained in the received JP1 event as the environment variable file name. For example, to set the JP1 event extended attribute named ENVFILE as the environment variable file name, specify $EV"ENVFILE".

Note that this parameter cannot be specified together with the rul parameter. Spaces before and after the environment variable file name are not deleted. Only one tab or one space character following var is deleted.

det suppress-period

Specifies a period during which action execution is to be suppressed. The action for the action conditions is suppressed if it would otherwise occur during the period specified in this parameter. This parameter is optional. If this parameter is omitted, the action is not suppressed. The permitted value range for the suppression period is from 1 to 3,600 (seconds). This parameter cannot be specified when you have specified & for the parameter group. In the case of AND conditions, specify the suppression period in the first automated action definition parameter that is defined for the AND conditions.

ret 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. The permitted value range for the delay monitoring period is from 1 to 86,400 (seconds).

#comment-line

A line beginning with a hash mark (#) is treated as a comment. Note that if you set an action definition from JP1/IM - View, comment lines with the # mark are deleted.

To Page Top

Variables that can be used in the action definition

In a definition of automated action definition parameters, you can use variables in the usr, var, hst, and cmd parameters to specify information contained in the JP1 events.

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. If you want to specify $ as a character, specify the escape character \ before the $.

The following table lists and describes the available variables.

Table 2‒15: Variables that can be used in action definitions

Type of information

Variable name

Description

Information contained in the basic attributes of JP1 events

EVBASE

Entire basic event information#1

EVID

Event ID (basic-code:extended-code)

EVIDBASE

Event ID (basic code)

EVDATE

Event registration date (YYYY/MM/DD)#2

EVTIME

Event registration time (hh:mm:ss)#2

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)#2

EVARVTIME

Event arrival time (hh:mm:ss)#2

EVSRCNO

Serial number at the event source

EVMSG

Entire message text#3

EVDETAIL

Entire detailed event information#3, #4

Information contained in the extended attributes of JP1 events

EVSEV

Severities in extended event information (Emergency, Alert, Critical, Error, Warning, Notice, Information, Debug)#3

EVUSNAM

User name#3

EVOBTYP

Object type#3

EVOBNAM

Object name#3

EVROBTYP

Registration type#3

EVROBNAM

Root object name#3

EV"PRODUCT_NAME"

Product name#5

EV"OBJECT_ID"

Object ID#5

EV"OCCURRENCE"

Occurrence#5

EV"START_TIME"

Start time#5

EV"END_TIME"

End time#5

EV"RESULT_CODE"

Return code#5

EV"JP1_SOURCEHOST"

Issuing host name#5

EV"extended-attribute-name"

Any extended attribute#5

Other

EV"@JP1IM_CORRELATE"

Correlation event flag

  • Not a correlation event: 0

  • Correlation approval event: 1

  • Correlation failure event: 2

EV"@JP1IM_ORIGINAL_SEVERITY"

Extended event information original severity level

(Emergency, Alert, Critical, Error, Warning, Notice, Information, or Debug)#3

EV"@JP1IM_CHANGE_SEVERITY"

New severity level flag

  • Severity is not changed: 0

  • Severity is changed: 1

EV"@JP1IM_DISPLAY_MESSAGE"

Changed display message

EV"@JP1IM_CHANGE_MESSAGE"

Display message change flag

  • Message has not been changed: 0

  • Message was changed: 1

ACTHOST

Manager host name at the action request source#3

EVENV1 to EVENV9

Data obtained by specifying parentheses (()) in a regular expression in the specification of an action execution condition #5(applicable only when an extended regular expression is used at the manager host)

#1: The basic information of a JP1 event is converted to the following format and passed to the action (Δ indicates a single-byte space):

event-IDΔevent-source-user-nameΔevent-source-user-IDΔevent-source-group-nameΔevent-source-group-IDΔevent-source-event-server-nameΔevent-source-process-IDΔevent-registration-dateΔevent-registration-timeΔevent-source-host-IP-address

An item that is not set is replaced with the null character.

#2: Converted in the time zone for JP1/IM - Manager and passed to the action.

#3: When an action is executed, if the applicable attribute does not exist, the variable is converted to a null character and passed to the action.

#4: When detailed attribute information for a JP1 event is in binary format, the variable is converted to a null character and passed to the action.

#5: If the applicable attribute does not exist, the character string of the variable is passed to the action as is.

In addition, depending on the type of JP1 event, an action might not be executed, or if executed, might result in an error because the variable itself does not exist or codes (ASCII codes and characters that are not included in the character set of the multi-byte characters encoding specified in the environment settings) not recognizable as characters are included. See the documentation for the JP1 event source product to check the attribute information, and then set the characters that need to be replaced.

Encoding for event inheritance information

For Action of the action-related items, you can use URL encoding or Base64 encoding for the values for event inheritance information. The specification format is $variable-name$encoding-type. To specify a single-byte alphanumeric character or an underscore (_) immediately after encoding-type, use the format ${variable-name$encoding-type}. If you specify a dollar sign ($) as part of a character string, immediate before $, specify \ as an escape character.

In the following cases, $variable-name$encoding-type and ${variable-name$encoding-type} will be treated as character strings and thus will not be converted:

The following table describes the encoding types for event inheritance information and shows the specification formats.

Table 2‒16: Encoding types for event inheritance information and specification formats

No.

Encoding type

Specification format

Description

1

URL encoding

$variable-name$URLENC

URL encoding is used to encode the value of event inheritance information as a UTF-8 character string.

${variable-name$URLENC}

2

Base64 encoding

$variable-name$ENC

Base64 encoding is used to encode the value of event inheritance information.

${variable-name$ENC}

3

Both Base64 encoding and URL encoding

$variable-name$ENC$URLENC

The value of event inheritance information is encoded by using Base64 encoding and then by using URL encoding.

${variable-name$ENC$URLENC}

4

No encoding is performed

$variable-name

Neither URL encoding nor Base64 encoding is performed.

${variable-name}

Notes about specifying variables

To Page Top

Regular expressions in an action definition

This subsection describes how to use regular expressions to specify 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 Appendix G. Regular Expressions in the JP1/Integrated Management 2 - 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 specify JP1-specific regular expressions, see Automated action environment definition file (action.conf.update) in Chapter 2. Definition Files.

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).

Notes on regular expressions

To Page Top

Example definition

The examples below show example definitions for the automated action definition file. Note that the extended regular expression is specified as the regular expression type in these examples.

Example definition 1: Using a variable (1)

The following is an example definition for specifying JP1 event information received by using a variable as an argument of a command to be executed as an action:

  • Event condition

    The event ID (B.ID) is 00000001.

    The message format is message-ID#Δ:Δmessage-text.

    #: A message ID consists of one alphabetic character and three numeric characters.

  • Command to be executed as an action

    alarm.batΔargument-1Δargument-2

  • JP1 event information to be specified as a command argument

    argument-1: The message value (${EVMSG} is specified as a variable)

    argument-2: The extended attribute value AAA (${EV"AAA"} is specified as a variable)

    [Figure]

When the value for the received JP1 event message (B.MESSAGE) is A001Δ:ΔThe WEB server goes down. and the value for the AAA extended attribute is kanshi, the action alarm.batΔ"kanshi"Δ"A001Δ:ΔThe WEB server goes down." is performed.

Example definition 2: Using a variable (2)

The following is an example definition for specifying a part of the JP1 event information received by using the variables EVENV1 to EVENV9 as arguments of the command to be executed as an action:

  • Event condition

    The event ID (B.ID) is 00000001.

    The message format is message-ID#Δ:Δmessage-text.

    #: A message ID consists of one alphabetic character and three numeric characters.

  • Command to be executed as an action

    alarm.batΔargument-1Δargument-2

  • JP1 event information to be specified as command arguments

    argument-1: Message ID value (${EVENV1} is specified as a variable)

    argument-2: Message text value (${EVENV2} is specified as a variable)

    [Figure]

When the value for the received JP1 event message (B.MESSAGE) is A001Δ:ΔThe WEB server goes down., the action alarm.batΔ"A001"Δ"The WEB server goes down." is performed.

Example definition 3: Specifying an event ID in a regular expression (1)

The following is an example definition when B.ID is specified as the attribute name of an event condition and REGEX is specified as the comparison keyword:

  • Event condition

    The event ID is a value from 00000001 to 00000200 (Hexadecimal A to F not included).

    The event-issuing server name (B.SOURCESERVER) is kanshi.

  • Command to be executed as an action

    alarm.bat

    [Figure]

To specify an event ID as an event condition, specify * for eid so that the event ID specified as an event condition becomes the target.

Example definition 4: Specifying an event ID in a regular expression (2)

If B.BASIC is specified for the attribute name as an event condition, the conditions can be set in the same format used for the basic event information of the automatic action definition file (for compatibility).

The following is an example definition when B.BASIC is specified as the attribute name of an event condition and REGEX is specified as the comparison keyword:

  • Event condition

    The event ID is a value from 00000001 to 00000200 (Hexadecimal A to F not included).

    The event-issuing server name (B.SOURCESERVER) is kanshi.

  • Command to be executed as an action

    alarm.bat

    [Figure]

The method for specifying a tab, space, %, or linefeed is different from the method used for the automatic action definition file (for compatibility). For details, see Automated action definition file (actdef.conf) (for conversion) in Chapter 2. Definition Files.

Example definition 5: Using the AND condition

The following is an example definition for setting the action to be executed when event A and event B are received:

  • Event A conditions

    The event ID (B.ID) is 00000201.

    The message (B.MESSAGE) is WEB server A goes down..

  • Event B conditions

    The event ID (B.ID) is 00000202.

    The message (B.MESSAGE) is Web server B goes down..

  • Command to be executed as an action

    alarm.bat

    [Figure]

When the AND condition is applied, we recommend using an automated action by using the correlation event generation function. The correlation event generation function can specify the sequence or the number of JP1 events, a property not available to the AND condition. For details about correlation events, see 4.3 Issue of correlation events in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

To Page Top

Copyright (C) 2019, 2021, Hitachi, Ltd.

Copyright (C) 2019, 2021, Hitachi Solutions, Ltd.