This section contains items that are part of the KM best practices, but for various reasons these items were not included in the KM certification criteria. In most cases, these item were not included because they were not testable, or there was not a good business case to require all KMs to meet these requirements. However, all the items covered in this appendix are very good ideas, and these items are already included in products and development processes by many KM teams.

Altering core product KMs

If it is absolutely necessary to make run-time modifications to ALL_COMPUTERS or any OS-type KM classes, the KM must create a new KM that contains the changes and manually modify the KM so it will effectively modify the in-memory copy of the original KM.

For example: PFX_ALL_COMPUTERS_MENUCOMMANDS.km

Inside this KM, you would have the following code:

... 
 
 COMPUTERS = { 
 
 {{{ NAME = "ALL_COMPUTERS",}} 
 
 SCREEN_POSITION = {12, 24}, 
 
 ... 

This means you can add menu commands and InfoBox commands to the ALL_COMPUTERS application class, but the file name of the KM that loads these ALL_COMPUTERS items will not have the name ALL_COMPUTERS.km and the file name will be prefixed by the KM prefix.

Setting out-of-the-box alarm ranges

The KM must set suitable out-of -the-box alarm ranges for active alarms.

Because alarm ranges are defined as integers, if your KM will set fractional values, make sure these values don't fall between the cracks in the alarm ranges.

Parameters that show data as True/False or 0/1 to represent on and off must use Boolean State style output. If the value of the parameter can be other than 0 or 1, another type of parameter output style must be used. This is to alleviate issues of inconsistency like these examples:

• PING status is 0 on and 1 off
• PATROL_agent status is 0 off and 1 on but the PATROL Agent thresholds are set per the ping status thresholds)
• Status is 0 on and 2 off

The KM should provide applicable out-of-the-box parameter thresholds for the top parameters, as determined by the product group. These thresholds must be suitable for at least 90% of the customer cases. If values that are applicable to 90% of the customer cases cannot be found due to wide usage variances, the KM should do their best to determine how the customer uses the managed product so that applicable thresholds can be set. This use case profile can be built by mining information from the users environment, or prompting them at configuration time.

Setting out-of-the-box border alarm conditions

When parameter data range limits are known, the KM must define out-of-range border conditions.

Defining out-of-range border conditions ensures that values outside the norm (less than or greater than the defined range limits) will make the user aware of the condition. The out-of-range alarm conditions also prevent recovery actions from triggering when the data is not in the expected range. The border range can help discover defects in an instrument providing the measurement or in software reporting metrics.

Naming application instances with unusual characters

When the KM creates application instances, it should not use unusual or special characters. The use of special characters can cause problems for programs that interface with PATROL (e.g., command-line utilities). When discovering instances which natively contain special characters it is recommended that the KM create an instance name without such characters and store the unmodified name within the instance namespace for use if needed. Characters of special concern are: ", ', \, *, &, comma and any non-printable characters.

Setting parameter attributes programmatically

The KM must not programmatically set parameter attributes because the user will not be able to override the settings using the standard methods provided by BMC. The following parameter attributes should not be manipulated programmatically by the KM:

• Parameter status
• Parameter settings

If there is a need for the KM to set parameter attributes programmatically, this must be documented as stated in the following sections:

Document if the KM adjusts parameter settings

If the KM programmatically adjusts parameter settings, the documentation must describe the conditions when the KM adjusts parameter settings. 

Parameter settings include the following:

• Changing alarm range thresholds and recovery actions
• Activating or deactivating alarm ranges
• Activating or deactivating parameters

Document if the KM sets the parameter status

If the KM programmatically sets the parameter status, the product documentation must describe the conditions when the KM sets the parameter status.

Parameter status

Setting the parameter status variable directly bypasses the ability to control the parameter state using standard methods. Setting the parameter status provides a UI presentation of an alert condition but the agent does not generate the events associated with a normal threshold exceeded condition. In this case, users are unable to attached recovery actions or set the desired status of the alert. Further, event management systems often rely on threshold exceeded events to indicate an issue condition on the management console. 

 Parameter settings

Parameter settings include the following:

• Changing alarm range thresholds and recovery actions
• Activating or deactivating alarm ranges
• Activating or deactivating parameters

If the KM programmatically adjusts parameter settings, the user will not be able to use the PATROL KM for Event Management or agent rules to configure parameter settings.

Storing list-based pconfig values

KMs storing configuration values as lists should use the comma as a list item separator. This allows the user to use the following pconfig operations to manage the list: MERGE, DELETE and APPEND. For example, if a KM maintains a configuration setting indicating the application users to be monitored, the list should be stored as follows: user1,user2,user3.

An example pconfig variable using such a list format is, /AgentSetup/preloadedKMs.

Providing recommendations and expert advice for parameters

For at least the top x parameters, as determined by the KM product group, each KM must provide expert recommendations that appear in the parameter Help topic. This help information should provide the following information:

• Description of the parameter - The description needs to describe in simple terms what the parameter represents. First of all, the value type itself needs to be described (example: if it is a Boolean value of 0/1 representing on/off). Next, from the perspective of the managed system, describe what this parameter means, why it is important, how it interacts with other parameters, how it affects the operation of the managed system and what things affect its setting.
• Default action taken by PATROL - This section describes what action, if any, that PATROL performs with this parameter by default. Many parameters have none, but some perform actions such as: when the parameter reaches the alarm range, PATROL will annotate the parameter value with a report which can show the top units of work at that time, for example.
• Default alarm and warning thresholds - This just lists the various default values shipped with the product by alarm description (Border, Alarm 1, etc.), threshold value, and state (Warn, Alarm outside of border, etc.).
• Recommendations - The recommendations are used by customer to help them determine what the various reasons that the value might go into alarm status, or not operating appropriately. This needs to be a comprehensive section which will give users general expert advice about what the possible causes are and ways to resolve the issue.

Formatting recommendations in parameter topics

The following figure shows the format used for providing expert recommendations in a parameter help topic. Only use this format when you include crucial recommendations for the customer.

 Parameter help topic for expert recommendations

Packaging KMs for each platform

The KM must have a separate package for each supported platform that has unique binary files.

Managing console screen usage for I18N

KM captions, titles, menu commands, etc. must not get truncated when they are translated.

Using pconfig() to retrieve pconfig values

The KM should use the PSL pconfig() function instead of the PSL get() function to obtain configuration values from the PATROL Agent configuration database.

Changing Application Class Instances from VOID to OK State Upon Creation

When application class instances are created, they should change from the VOID > OK state.

Otherwise, the parameter settings for all the instances of that application class, including thresholds and poll times, will not be applied. Therefore, when the configuration of such parameters is performed from PATROL Configuration Manager and PATROL KM for Event Management, the changes will only last for that session and will be lost when the PATROL Agent is restarted.

PATROL KM for Event Management traps only the VOID => OK state change events for a newly created application class instance to apply the threshold and polltime rules for its parameters. Therefore, if the instances were not created as OK but as some other state, such as OFFLINE, none of its parameters would have the PATROL KM for Event Management settings because the VOID-OFFLINE (or VOID => any other state other than OK) state change events are not captured.

If the instance must remain OFFLINE after creation, one possible solution is to create the instance as OK, which achieves the VOID => OK state change event that PATROL KM for Event Management needs, and then use change_state to set it to OFFLINE.

The exception to this is when UpdInstState VOID => OK is used for rules containing an instance name and not for _ANYINST_ rules. Values set with _ANYINST_ will be applied.

Using consistent case

You must use consistent case, such as all capital letters, all lower-case letters, or initial capital letters.

The case of the instances to be created does matter for the PATROL KM for Event Management. In certain situations, the user needs to know the exact case of the instances to be created, especially in the instance filtering feature of the PATROL Configuration Manager and the PATROL KM for Event Management.

Testing the KM Packages

You should test the KM packages to be sure they have been created correctly.

To test the KM packages

1. Install the KM resource packages on a Console Server computer.
2. Install the KM on an agent (3.9.00 or later).
3. Connect to the Console Server using PATROL Central Operator.
4. Create a new management profile and add the agent from step 2.

5. Inspect the Console Server log file at BMC_BASE/Patrol7/log/cserver/cserver- serviceId.log
   Check the log for any messages of type WARNING or ERROR that refer to the KM product code, prd_v_r_m.
   Here is an example of an error message.

    INFORM:8/19/2004 10:03:00 AM::51.5:Request to load package 'prd_2_5_00' ERROR:8/19/2004 10:03:00 AM::Error:package.mof(5) undeclared property

   
   The error message indicates a syntax error on line 5 of the package.mof file.

6. Verify that the KM Help works.
7. Verify that the KM icons appear correctly.