Important

   

This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 21.3 for BMC Helix Operations Management. Open link

Configuring PATROL KM metadata

This section provides an overview of PATROL Knowledge Module metadata and its configuration. This section contains the following topics:

KM metadata

PATROL Agent (PA) and the Knowledge Modules (KM) contained by it need to be configured by:

  • Central Monitoring Administration in BMC ProactiveNet Performance Management.
  • Infrastructure Monitoring Administration in TrueSight console.

While configuring in the Central Monitoring Administration or Infrastructure Monitoring Administration, the PATROL Agent must be running, but the KM need not be running. A static description of the configuration data (configuration input metadata), is required by the KM. This metadata is part of the KM XML file that contains the KM data and code. 

Return to top

Metadata specification for a simple KM

This section first discusses metadata for a simple, fictitious KM to highlight major parts of it, and then progressively provides more details on different aspects of the metadata specification and its expected rendering and output. it then provides complete reference to various constructs in the metadata. More formal description of metadata structure is provided in Appendix along with metadata descriptions for two real KMs. 
Furthermore, currently, the location of configuration variables, their handling and routine cleanup is entirely up to the KM, as the configuration tools are typically written for the KM. However, while configuring through Central Monitoring Administration in BMC ProactiveNet Performance Management or Infrastructure Monitoring Administration in TrueSight console, a set of conventions for handling of common configuration data are needed. The following topics discuss these conventions:

Input metadata specification

Most Kms require to be configured to monitor technologies running on remote computers. Our simple KM requires name of the host, port on which to connect to the host, and credentials to connect and execute some commands on the host. 
A metadata description for configuration data for such KM is given below. This metadata specification string is inserted in the .km file (in this case ABC.km file) with '!INPUT' prefix.

<!--
Sample metadata for ABC KM
-->
<KMConfigurationMetadata>
<KMLevelConfiguration
dataModelMajorVersion="1"
dataModelMinorVersion="0">
</KMLevelConfiguration>
<ConfigurationParameters>
<ConfigurationParameter>
<List
id="hosts_list"
label="List of Hosts"
description="List of Hosts"
isMandatory="true"
indexedBy="host_ip">
<AttributeSet
label="One Host Information">
<Attribute>
<String
id="host_ip"
label="Host IP"
isMandatory="true"
default="localhost">
<InputValidationRules>
<InputValidationRule
id="validateIpAddress" >
</InputValidationRule>
</InputValidationRules>
</String>
</Attribute>
<Attribute>
<String
id="portnum"
label="Port Number"
isMandatory="true"
default="5454">
<InputValidationRules>
<InputValidationRule
id="validateRange">
<Params>
<Param>1</Param>
<Param>10000</Param>
</Params>
</InputValidationRule>
</InputValidationRules>
</String>
</Attribute>
<Attribute>
<AccountName
id="user"
label="Command Execution User and Password"
description="Username and password"
isMandatory="true">
</AccountName>
</Attribute>
</AttributeSet>
<InputValidationRules>
<InputValidationRule
id="validateLength">
<Params>
<Param>1</Param>
<Param>5</Param>
</Params>
</InputValidationRule>
</InputValidationRules>
</List>
</ConfigurationParameter>
</ConfigurationParameters>
</KMConfigurationMetadata>


The Metadata is given in XML format. The specification is enclosed within KMConfigurationMetadata XML element. There are two major parts to the specification; KM-level, global configuration information which is inside 'KMLevelConfiguration' XML element; and information about configuration parameters in the KM, which is a list of 'ConfigurationParameter' XML elements. There are two properties in the 'KMLevelConfiguration' element; 'dataModelMajorVersion' and 'dataModelMinorVersion'. These XML attributes provide hint for syntax of the rest of teh specification. 

'ConfigurationParameter' element specifies structure of one configuration parameter. There are three different functional parts to it; for generating output, such as parameter name (value of 'id' XML attribute), for user interface rendering, such as display string (value of 'label' XML attribute), and for validation checks (values of 'InputValidationRule' XML element and its attributes). 

The only 'ConfigurationParameter' in this metadata is a 'List' of an 'AttributeSet'. For all XML elements in the metadata specification, value of the 'id' XML attribute is the name of configuration data-item in the KM, value of 'label' XML attribute is the display string for user interface, value of 'description' XML attribute is short description shown to user, 'isMandatory' XML attribute specifies if user needs to input value for this data-item, 'default' XML attribute specifies the default value for this configuration data-item. For 'List's, there is additional XML attribute, 'indexedBy', whose value is the name of one of the configuration data-items in the list which is identified as a unique key in it. In the example above, "host_ip" is guaranteed to be unique in this list, and therefore, value of 'indexedBy' XML attribute is "host_ip". 

'AttributeSet' XML element is used to group set of configuration data-items for display purposes (such as for displaying them inside a frame or box). In this example, remaining configuration data-items logically form a group and should be displayed together. Therefore, "host_ip", "portnum" and "user" are part of 'AttributeSet' with display name of "One Host Information". 

Specification of "host_ip" configuration data-item also demonstrates the validation rule specification. It is given by 'InputValidationRule' XML element. An out-of-box validation rule, "validateIpAddress" is used to validate the user input for this dataitem. Similarly, specification for "portnum" configuration data-item shows the validation rule with two arguments. In this case, the input value is checked as an integer with value between 1 and 10000. 

Specification identifies "user" configuration data-item as combination of user-name and password. User interface displays two separate input areas for 'AccountName'; one for user-name and one for password. The inputs are processed is special manner.

Output of Metadata specification for a KM

User interface driven by this specification is presented to the user to input the configuration data. On receiving the data and validating it, it is presented to the KM as a string which can be used to set pconfig variables in the PA. 

A sample string generated as a result of some data input is as below.

"/ConfigData/ABC/txn_id"= { REPLACE = "100"},
"/ConfigData/ABC/hosts_list/localhost/host_ip"= { REPLACE =
"localhost"},
"/ConfigData/ABC/hosts_list/localhost/portnum"= {REPLACE = "5454"},
"/ConfigData/ABC/hosts_list/localhost/user.defaultAccount" = {
REPLACE = "testuser/<plaintext-password>" },
"/ConfigData/ABC/hosts_list/www.bmc.com/host_ip"= {REPLACE =
"www.bmc.com"},
"/ConfigData/ABC/hosts_list/www.bmc.com/portnum"= {REPLACE="5000"},
"/ConfigData/ABC/hosts_list/www.bmc.com/user.defaultAccount" = {
REPLACE = "otheruser/<plaintext-password>" },

These strings are in pconfig format. Each variable name has the name of the KM ("ABC") embedded in it. CA generates a unique string, transaction-id, for each set of configuration data it downloads to PA. It must always be greater (in ASCII sorting order) than any previous transaction-ids generated by CA. Each batch of pconfig variable assignment statements also contains another pconfig variable assignment statement which sets the value of KM specific variable 'txn_id' to generated transaction-id. 

The remaining part of the pconfig variable name is derived from the 'id' attribute values of the configuration data-items specified in the metadata in a fairly straightforward manner. 'List' and 'AccountName' XML elements are handled in a special manner as follows. 

For every 'List' XML element, the value of its 'id' attribute is appended to the prefix string to generate list-prefix-string for the all configuration-data specified in the 'List'. Then, for each list-item, the user input value of the 'indexedBy' XML attribute is appended to list-prefix-string, followed by the value of the 'id' XML attribute for individual configuration data-item. This forms complete name of the pconfig variable for the configuration data item inside the list. The output string above shows output generated when user enters a list with two list-elements having "host_ip" values of "localhost" and www.bmc.com respectively. 

For 'AccountName' XML element, a string ".defaultAccount" is always appended to the value of the 'id' attribute instead of using the value of 'id' attribute directly as the pconfig variable name. The password is appended to the user input followed by '/'. The output string shown above for AccountName XML element is generated when user inputs "testuser" and "otheruser" as user names, and corresponding passwords.

Return to top

Metadata Structure and XML Elements

This section explains the metadata structure, the XML elements for basic and container types and the XML Attributes for data-types for XML elements.

Metadata Structure

As shown in the ABC KM's metadata specification, the metadata specification has the following structure.

<KMConfigurationMetadata>
<KMLevelConfiguration
KM attributes ...
</KMLevelConfiguration>
<ConfigurationParameters>
<ConfigurationParameter>
<Data-type
Data-type attributes and nested Data-types ...
<InputValidationRules>
<InputValidationRule
Validation rule Attributes ...
</InputValidationRule>
</InputValidationRules>
</Data-type>
</ConfigurationParameter>
</ConfigurationParameters>
</KMConfigurationMetadata>

'KMLevelConfiguration' XML element contains a set of attributes whose values define the KM-wide properties related to handling of its configuration data-items. The following is the complete list of XML attributes for 'KMLevelConfiguration'. There is no user interface generated and consequently, no output string generated for this XML element. 
The following table lists the attributes and their values.

Attributes values

Attribute name

Type ofvalue

Allowed values

Defaultvalue

Notes

DataModelMajorVersion

int

"1", but in future if metadata is enhanced, a new version number will be required.

"1"

Specifies the major version of the structure of metadata specification.

DataModelMinorVersion

int

"0", but in future if metadata is enhanced, a new version number will be required.

"0"

Specifies the minor version of the structure of metadata specification.

NeedsCustomGui

Boolean

"true" or "false".

"true"

Specifies if a custom GUI is needed for this KM .

CustomGuiArtifact

String

Typically, a JAR file name.

""

JAR file name containing classes required for Custom GUI. This is used only if 'needsCustomGui' attribute value is "true".

ParentApplication Class

String

Name of KM

""

JAR file name containing classes required for Custom GUI. This is used only if 'needsCustomGui' attribute value is "true".

RemoteSupport

Boolean

"true" or "false"

"false"

If "true", this KM supports remote monitoring

'ConfigurationParameter' XML element contains specification for configuration one type of configuration-data item in the KM. There is no direct User Interface or output generation implication for this element. 'ConfigurationParameters' XML element acts as a container for 'ConfigurationParameter' elements and also has no user interface or output implications. 

Metadata model defines the several XML elements which represent Data-types of the configuration data-items. Data-types represent a set of rendering and output formatting requirements that usually are needed for configuration data-items. The guiding principle in designing the data-types is to have a minimal set of data-types which have a special user-interface handling or special output producing needs.


Data-types can be classified as one of the basic or container type. In this section, basic and composite types are presented.

XML Elements for basic types

The following table lists the XML elements for basic types and their values.

XML element values for basic types

Element name

Allowed values

Possible GUIrepresentation

Semantics

Boolean

"true", "false"

Toggle Button

Flag which can be on/off

String

Text Field

Any string including special characters

AccountName

Frame

User name and password

Counter

Subject to values of minValue and maxValue attributes

Clicker

Integer values between minValue and maxValue

Enum

Subject to Enumerators XML element

Radio button or option menu

One of several statically known options

MultiSelect

Multiple enumerator elements

Check boxes

Multiple options from a statically known options

XML Elements for container types

The following table lists the XML elements for container types and their values.

XML element values for container types

Element name

Allowed values

Possible GUIrepresentation

Semantics

AttributeSet

At least one Attribute

Frame

Group of configuration data-items, each with a Data-type

Attribute

One configuration data-item

None

One config data-item. This is used to wrap a configurationdata-item if it is part of an AttributeSet.

List

Table for displaying all list elements and Frame for adding/modif ying a list-element

List of configuration-data items each with a data-type.

XML Attributes for data-types for XML elements

XML attributes are associated with each data-type. The following table lists the common attributes shared by all data-types.

Common attributes shared by all data types

Attibute name

Type of value

Allowed values

Default value

Used by

Notes

id

String

Alphanumeric string

""

Output Generation

pconfig variable name

label

String

Printable string

Same as that of 'id'

User Interface

Display label on user interface

Description

String

Printable string

Same as that of 'label'

User Interface

Hints about possible values to enter, etc. for user interface

i18nIdForLabel

String

Generated string

""

User Interface

Generated by KM as a key into catalog for internationalization of display strings specified in 'label' attribute value

i18nIdForDescription

String

Generated string

""

User Interface

Generated by KM as a key into catalog for internationalization of display strings specified in 'description' attribute value

IsMandatory

Boolean

"true" or "false"

"false"

User Interface

Specifies if the value for the configuration data-item is required to be entered by user

default

Output Generation, possible User Interface

Specifies value to be used for configuration data-item if isMandatory is "false" and user has not entered any value

IsStorageSecure

Boolean

"true" or "false"

"false"

Output Generation

Specifies if the configuration data-item's value needs to be stored in secure store of PA. Valid only for Basic Datatypes

defaultEditableBoolean"true" or "false""true" User Interface

Specifies whether the “String” text field is editable. The text field is editable if the value is "true" and non-editable if the value is “false”.

In addition to these, some Datatype XML elements need more attributes or XML elements. They are listed in the following table below.

Common attributes shared by all data types

XML element name

Additional XML elements

Attribute name

Type of value

Default value

Used by

Notes

Account Name

renderAsAttributrGroup

String

"true"

User Interface

If set to "false", GUI will not treat AccountName as a AttributesGroup (that is, will not draw a box around it and name it as per the label of the configuration parameter.

Counter

minValue

Numeric string

1

User Interface

Lower bound

maxValue

Numeric string

100

User Interface

Upper bound

Enum, MultiSelect

Enumerators

Container for Enumerator XML element

Enumerator

label

Alphanumeric string

User Interface

Specifies the enumerator string, used as label for option menu/radio button/check boxes

i18nIdForLabel

Generated string

""

User Interface

Generated by KM as a key into catalog for internationalization of display strings for name of option menu/radio button /check box

value

Numeric string

Output Generation

Value of enumerator, this is used in the output generated for the configuration-data item

AttributeSet

newPopupDialog

String

"false"

Output Generation

If "true", display this AttributeSet in a new dialog box, if "collapsed" display this AttributeSet in collapsed mode. Only when user clicks on the collapsed representation named by "label", full AttributeSet will be shown.

Attribute

No properties

A wrapper for each config data-item which is part of an AttributeSet

List

indexedBy

Value of 'id' attribute of a contained configuration data-item

"AUTO"

Output Generation, possibly input data validation to make sure each element in list has unique value for 'indexedBy ' configuration data-item

Input value of the configuration data-item identified by 'indexedBy' is used to generate pconfig variable name. If 'indexedBy' is set to "AUTO", then a unique numeric string is generated for each added list-element, and used to generated pconfig variable name.

renderAsTextBox

String

"false"

User Interface

If "true", User Interface may render this list as a text-box and accept the list as a text string where individual elements are separated by the string specified in elementSeparator attribute. Typically, In a XML specification only List types containing single XML element (and if its type is not any of aggregate types such as List, AttributeSet, AccountName) may have this attribute value set to "true".

elementSeparator

String

","

User Interface

If "renderAsTextBox" is set to "true", then the value of this attribute is used by User Interface as element separator in the text string input by user.

renderAsCollapsed

String

"false"

User Interface

If "true", User Interface shall render the List as a collapsed item. User will have to click on it to expand it. This will be used to save screen real estate, if the list is optional.

renderAsPopup

String

"false"

User Interface

If "true", User Interface shall render List in a new dialog box. This is for future use. The same functionality is currently available by enclosing exactly one AttributeSet with newPopupDialog=" true" inside a List.

Return to top

Output generation for basic data types

The output string generation for basic data type is straightforward. The output string is in the following format.

"<full-name-of-pconfig-variable>" = { <value-string> },

Where <full-name-of-pconfig-variable> is the <prefix-string-generatedso- far>/<name-of-configuration-data-item> 

The value of the 'id' attribute (except when configuration data-item has Data-type of AccountName and its isStorageSecure attribute is set to "false" - the value of 'id' attribute suffixed with '.defaultAccount') is used as the name of configuration data-item, and is appended to the prefix string generated as explained in earlier section, to get the full name of the pconfig variable. 

However, if  'isStorageSecure' XML attribute is set to "true", then the name of the pconfig variable is generated by prefixing "/SecureStore/" string to the <full-nameof-pconfig-variable> described above. 

The value string is generated according the Data-type of the configuration data-item as shown in the the following table below.

XML element values for container types

Data-type

User Input

Generated value-string

Notes

Boolean

true

REPLACE = "1"

false

REPLACE = "0"

AccountName

<name> and <password>

REPLACE = "<name>/<plaintext -password>

String

<val>

REPLACE = "<val>"

Counter

<val>

REPLACE = "<val>"

Enum

<label>

REPLACE = "<val>"

<val> is the numeric string associated with <label> in one of the enumerators


Example

This metadata specification snippet is taken VSM KM's metadata.

<Enum id="mo_type" label="Managed Object Type"
isStorageSecure="true">
<Enumerators>
<Enumerator label="Datacenter" value="1"></Enumerator>
<Enumerator label="ClusterComputeResource" value="1"></Enumerator>
<Enumerator label="HostSystem" value="2"> </Enumerator>
<Enumerator label="VirtualMachine" value="3"> </Enumerator>
<Enumerator label="ResourcePool" value="4"> </Enumerator>
<Enumerator label="Folder" value="5"></Enumerator>
<Enumerator label="Datastore" value="6"> </Enumerator>
<Enumerator label="Other" value="7"></Enumerator>
</Enumerators>
</Enum>

The output string for this when user chooses "ResourcePool" option is as follows.

"/SecureStore/ConfigData/VSM/mo_type" = { REPLACE = "<patrolencrypted-string("VSM/4")>" },

If 'isStorageSecure' attribute's value was not specified or was set to "false", then the output string is as follows.

"/ConfigData/VSM/mo_type" = { REPLACE = "4" },

Return to top

Output Generation for MultiSelect Data types

MultiSelect Data type can be considered as a special Data-type which can only contain Enumerators XML element. It is similar in functionality to AttributeSet of Boolean Data-types. The reason for choosing one over other is typically, the number of options to be presented to user. If there are large number of options, then MultiSelect is a better Data-type as drop-down, multi-selectable option list can be chosen as its GUI presentation.

Example

<MultiSelect id="event_types" label="Event Types"
isMandatory="true">
<Enumerators>
<Enumerator label="creation" value="0"></Enumerator>
<Enumerator label="change" value="1"></Enumerator>
<Enumerator label="deletion" value="2"></Enumerator>
</Enumerators>
</MultiSelect>

If creation and change check boxes are selected by user, then output string is as follows.

"/ConfigData/PROCPRES/event_types" = { MERGE = "0"}
"/ConfigData/PROCPRES/event_types" = { MERGE = "1"}

Return to top

Output Generation for Container Data-types

Metadata model defines two container Data-types; AttributeSet and List. Their GUI representations and semantics of their attributes are explained in the preceding section. This section explains the output string generated by these containers.

 AttributeSet

AttributeSet Data-type does not affect output string generation by itself. Therefore, those attributes whose values influence output generation (such as 'id', 'default' and 'isStorageSecure') are ignored for it. It is used to show a group of configuration dataitems in a dialog box.

 Attribute

Attribute Data-type does not affect output string generation by itself. An AttributeSet consists of one or more Attributes, each of which encloses a config-data item.

 List

List Data-type is used to present and accept a list of values of configuration-data items. There is no restriction on the Data-types of the configuration-data items that constitute an element of list. From User Interface perspective, List provides a view of the list-elements and also allows user to input values for a list-element. 

Output generation for a List has mainly to do with the generation of prefix-string for the pconfig variable name which is in turn used by Data-types of contained configuration data-items. 'indexedBy' attribute value is the key for generating the prefix-string.

Example

This metadata specification snippet is taken VSM KM's metadata.

<List id="configured_vcs" label="Virtual Centers' Configurations"
isMandatory="true" indexedBy="vc_host_name">
<AttributeSet label="Virtual Center Specification">
<Attribute>
<String id="vc_host_name" label="Host Name"
isMandatory="true">
</String>
</Attribute>
<Attribute>
<AttributeSet id="esx_information"
label="Configure Data Collection"
newPopupDialog="true">
<List id="esx_servers"
label="Virtual Centers' Configurations"
isMandatory="true"
indexedBy="esx_server_name">
<AttributeSet label="esx_server">
<Attribute>
<Enum id="data_collection"
label="Data Collection"
isMandatory="true" default="failover">
<Enumerators>
<Enumerator label="failover" value="0">
</Enumerator>
<Enumerator label="distributed"
value="1">
</Enumerator>
</Enumerators>
</Enum>
</Attribute>
<Attribute>
<String
id="esx_server_name"
label="ESX Server Name"
description="ESX Server Name"
i18nIdForLabel="2342"
i18nIdForDescription="2343"
isMandatory="true">
</String>
</Attribute>
</AttributeSet>
</List>
</AttributeSet>
</Attribute>
</AttributeSet>
</List>

When the first List XML element is encountered (with id="configured_vcs"), the prefix-string for pconfig variable name will be

"/ConfigData/VSM/configured_vcs"

List is indexed by 'vc_host_name'. Assuming that user inputs value of "localhost" for 'vc_host_name', the prefix string will be

"/ConfigData/VSM/configured_vcs/localhost"

And the full pconfig variable name for this configuration data-item will be

"/ConfigData/VSM/configured_vcs/localhost/vc_host_name"

When the next List XML element is encountered (with id="esx_servers") , the prefixstring for pconfig variable name will be

"/ConfigData/VSM/configured_vcs/localhost/esx_servers"

This list is indexed by 'esx_server_name', Assuming user inputs value of "esx_server_1" for 'esx_server_name', the prefix string will be

"/ConfigData/VSM/configured_vcs/localhost /esx_servers/esx_server_1"

And the full pconfig variable name for configuration data-item will be

"/ConfigData/VSM/configured_vcs/localhost/esx_servers/esx_server_1/e
sx_server_name"

Similarly, the full pconfig variable name for next configuration data-item will be

"/ConfigData/VSM/configured_vcs/localhost/esx_servers/esx_server_1/d
ata_collection"

Return to top

Validations

This metadata snippet is from the sample KM metadata in earlier section.

<String
id="portnum"
label="Port Number"
isMandatory="true"
default="5454">
<InputValidationRules>
<InputValidationRule
id="validateRange">
<Params>
<Param>1</Param>
<Param>10000</Param>
</Params>
</InputValidationRule>
</InputValidationRules>
</String>

The validation rule "validateRange" and its parameters direct the user input value for 'portnum' configuration data-item to be an integer between 1 and 10000. 

The following table lists all validation rules are available out-of-box for use in the metadata specification.

XML element values for container types

Rule Name

Parameters

Description

validateSize

min, max

Checks if the input string's size is between min and max

validateLength

min, max

Checks is the number of elements in the input list is between min and max

validateRange

min, max

Checks if the input string is integer and is between min and max

validateInetAddress

Checks if the input string follow a IP or DNS naming convention

validateNotEmpty

Checks if the input string is not empty

validateRegex

Checks if the input string is a valid regular expression

validatePattern

regex

Checks if the input string matches the pattern in regex

validateRequired

required-chars

Checks if the input string contains at least one character in required-chars

validateForbidden

forbidden-chars

Checks if the input string contains characters in forbidden-chars

Also, there are a few implicit validations that must be performed for the value of any configuration data-item that is specified as index of a List (i.e. specified as a value of indexedBy XML attribute for a configuration data-item of type List). These validations are identified below.

  • The value of such data-item should not contain '/' character.
  • As this data-item is an index, it should have a unique value within all elements of the list it indexes.

Note

If the input character string for the validate functions listed above contains only a space character, then, that space characters needs to be escaped with the standard convention followed by the XML standard. An example is shown below.

<Attribute>
<String id="hostName" label="Host Name" isMandatory="true"
default="">
<InputValidationRules>
<InputValidationRule id="validateForbidden">
<Params>
<Param> <![CDATA[ ]]></Param>
</Params>
</InputValidationRule>
</InputValidationRules>
</String>
</Attribute>

Return to top

Guidelines for KM developers

This section provides guidelines and a set of conventions and best practices for KM developers to follow while designing handling of KM's configuration parameters. 

The need for a consistent treatment of configuration parameters is more evident now as PATROL monitoring solutions are expected to be configured from the Central Monitoring Administration in BMC ProactiveNet Performance Management or Infrastructure Monitoring Administration in TrueSight console. Therefore, KM developers can no longer design their configuration parameter processing with the view that they can only be configured through classic console or through several pconfig manipulating utilities. This is the primary use case for standardization of configuration parameter naming and processing.

Handling configuration data - Location and naming of configuration parameters

In general, pconfig database is used to storing configuration parameter values for a KM. This database is simply a set of (pconfig-variable-name, value) pairs. A pconfigvariable-name is a sequence of name-strings separated by '/' characters much like a UNIX directory name and with a similar semantics. Each name-string creates a pconfig namespace under its parent namespace, with "/" name-string denoting the root namespace. However, except for a few special cases, such as "/AgentSetup" namespace, there are no conventions about how pconfig variables can be named. This has led to each KM using its own or no conventions for its configuration variables and lack of uniformity, so long as the classic console module for that KM (usually menu-commands) is aware of those conventions. 

In order that a KM is configurable, the following rules for naming must be followed by the KM.

  1. KM must provide its metadata for configuration parameters in the .km file.
  2. There must be a /ConfigData branch in the pconfig where configuration data coming from upstream system will be saved. Each KM must have a branch under it with its name, and KM specific configuration data will reside there. Thus for a KM in file XYZ.km, there will be a branch /ConfigData/XYZ, which is the root namespace for all configuration data provided by upstream system to Agent for XYZ.km
  3. There will be a pconfig variable named 'txn_id' under /ConfigData/<KM-name> which will hold the transaction-id generated and sent by CA corresponding to all other configuration data that resides under /ConfigData/<KM-name> branch.
  4. KM will have /Runtime/<km-name> branch in the pconfig where key data (not configuration related) will be stored. Typically, this is the runtime data that needs to be preserved across PATROL Agent process invocations.
  5. KM will maintain a namespace variable to keep track of the transaction-id that was processed and incorporated in the KM configuration, such as; "/XYZ/last_processed_txn_id" = "100";
  6. KM will periodically check if new configuration data has been sent by CA under its own config namespace (i.e. under /configData/XYZ). This could be through the discovery PSL process. Last processed transaction-id value stored in the namespace variable will be used to deduce the availability of new configuration data.
  7. If new configuration data is available, it will be used to find the difference between current and desired configuration of the KM. In case of additions, and changes to existing data, KM will use new configuration data under ConfigData/<KMname> branch. But, in case of deletions to a sub-branch of KM or removal of entire KM, KM needs to compute the changes. In all cases, the specific actions to take are KM-dependent.
  8. Once the changes are applied, KM needs to update its namespace variable for last processed transaction-id.
  9. It is recommended that the current configuration data is not stored away in another pconfig variable under KM's own private namespace. It should be maintained as properly-named (with KM name embedded in) namespace variables within PATROL Agent's memory, so that all PSL processes can access it.

Note

Some implicit validations are done to ensure overall integrity of the XML specification for the KM. At present, it is ensured that the id values for configuration parameters are unique within a KM. In future, it needs to be ensured that the id values for configuration parameters are unique within a scope (there are two scopes defined - Global and List).

If uniqueness criterion for the id values is violated, Central Monitoring Administration in BMC ProactiveNet Performance Management or Infrastructure Monitoring Administration in TrueSight console will not show the KM in the list of monitor types available for configuration, and an error will be logged. A sample of the contents of the error log (which is located at pw/pronto/logs/UAdmin.log) is given below.

ERROR 01/06 12:21:40 UAdmin [TP-Processor2] 854258 Duplicate List ID
- EventFilters found in Monitor XML for Solution: Microsoft Windows
Server, Version: 4.5.00 and MonitorType: Windows Event Log. So
blocking it to not show in GUI
ERROR 01/06 12:21:40 UAdmin [TP-Processor2] 854259 Duplicate
Attribute ID - eventlog_filtername found in Monitor XML for Solution:
Microsoft Windows Server, Version: 4.5.00 and MonitorType: Windows
Event Log. So blocking it to not show in GUI

Return to top

Was this page helpful? Yes No Submitting... Thank you

Comments