How-to Guide: OS Command Adapter

This guide explains how you can react to Monitoring and Alerting Infrastructure (MAI) Alerts in SAP Focused Run by sending an OS Command:


Within SAP Focused Run, MAI offers a unique and centralized alerting approach. It pulls metrics and simple events from different data providers as a simple diagnostics agent at the managed system. Alternatively, MAI provides this information via a (third-party product) CA Application Performance Management push mechanism.

MAI includes:

  • An event calculation engine for complex events and end user alerts out of the retrieved metrics, as well as for simple events to prevent alert flooding.
  • A centralized directory for metrics, events, and alerts. This includes SAP and customer template knowledge and context information, such as system landscape and interface information.

SAP Focused Run uses an Alert Consumer Connector (ACC), with adjustable protocols, to forward collected MAI data to end users via automatic notifications and an alert inbox. In addition, the ACC can process MAI data through a third-party connector. In that event, an OS command adapter executes external OS commands and directs MAI data to a desired third-party tool.


Prerequisites

  • The alerting is setup should have been successfully completed in the system.

OS Command Adapter

The OS Command Adapter is fully configurable to execute any external OS Command.

Overall Mechanism

  • The ACC is configured to send third-party alert Information to the BAdI Implementation.
  • All of the necessary data to be forwarded to the 3rd party is bundled in a table and passed to the OS Command Adapter.
    • Initiate the OS command adapter and pass the AlertInfo Bundle (key-value table).
    • Call: OSCommandAdapter execute_command()
    • This will trigger the steps 3 and 4.
  • Based on the OS command configuration, the Executable options and parameters are built.
  • The configured OS command is called.

OS Command Usage

In SAP Focused Run an SAP-Standard BAdI implementing class is provided: CL_ALERT_REACT_OS_COMMAND (package AI_SOLMAN_ALRT_AL_REACTION_IMP)

The provided implementation is bundling the following MAI Alert Information:

NameValueTypeLength

[MAI:ALERT:MO_NAME]

Name of the Managed Object reporting the Alert

Char

128

[MAI:ALERT:MO_TYPE]

T_SYSTEM, INSTANCE, HOST, DBMS…

Char

10

[MAI:ALERT:TYPE_ID]

Unique ID that identifies the Alert in MAI

Char

32

[MAI:ALERT:DATE]

UTC Date (YYYYMMDD)

Char

8

[MAI:ALERT:TIME]

UTC Time (hhmmss)

Char

6

[MAI:ALERT:NAME]

Human readable short name of the Alert

Char

128

[MAI:ALERT:TECHNICAL_NAME]

Technical ID of the Alert

Char

60

[MAI:ALERT:DESCRIPTION]

Alert Description (or Custom Description)

Char

128

[MAI:ALERT:CATEGORY]

AVAIL, PERFORM, EXCEPTION, CONFIGURE

Char

10

[MAI:ALERT:RATING]

0:Unknown, 1:Normal, 2:Warning, 3:Critical

Integer

1

[MAI:ALERT:SEVERITY]

0:Low … 5:Medium … 9:Critical

Integer

1

[MAI:METRIC:NAME_PATH]

Metric Name (or Metric Path for grouped metric)

Char

128

[MAI:METRIC:VALUE]

Metric Value and Unit (or Metric Text Value)

Char

128

[MAI:ALERT:MO_ID]

Unique ID that identifies the Managed Object

Char

32

[MAI:ALERT:REASON_FOR_CLOSURE]

1:Re-configuration, 2:Work mode Change, 3:Green alert…

Integer

1

[MAI:ALERT:PRIORITY]

1:Low, 2:Medium, 3:High, 4:Very high

Integer

1

[MAI:ALERT:SYSTEM_HOME]

System Home (Host Name) for the Managed Object

Char

128

[MAI:ALERT:CUSTOMER]

Customer Name

Char

64

[MAI:ALERT:NETWORK]

Customer Network

Char

64

The corresponding value ranges are as follows:


BAdI Implementation

Custom BAdI implementation overview

Alert Inbox listeners should implement the BAdI Definition BADI_ACC_REACTION_EXT from the Enhancement Spot ACC_REACTION_EXTERNAL (package AI_SOLMAN_ALRT_CONSM_MGMT):


The BAdI filter is as follow: ACC_REACTION_FILTER (Character-Type)
The Implementing class should be Standard MAI Information, or any
CL_ALERT_REACT_OS_COMMAND if you want to use the SAP-other implementing class according to your needs.

Steps to Create BAdI entities

With transaction SE19, create a new Z Enhancement Implementation based on the existing Enhancement Spot ACC_REACTION_EXTERNAL in a similar way as shown in the screenshot below:


The following detailed view results from the newly-created BAdI implementation:


Set a dedicated BAdI filter value that will be used to differentiate configurations:


Note: When the ACC triggers its next alert notification, it registers the activated implementing class and the BAdI implementation.

OS Command Configuration

In SAP Focused Run a dedicated User Interface has been implemented to configure the OS Command.

Note: Ensure that for transaction SICF that the service mai_os_command_config is active.

User Interface

Path: http://<FRUNHost>:<port>/sap/bc/webdynpro/sap/mai_os_command_config


When accessing the configuration UI for the first time, follow the steps below to create a new configuration:

  • Expand the Create a Configuration panel
  • Set Filter Value to <BAdI_FilterValue>_REACT (replace <BAdI_FilterValue> by its value configured when creating the BAdI entities)
  • Press Create
  • Set Filter Value to <BAdI_FilterValue>_REACT_CLOSE (replace <BAdI_FilterValue> by its value configured when creating the BAdI entities)
  • Choose Create


This will create 2 Configuration Entries for each type of forwarding (AlertChange & AlertClosure):

  • An entry describing the OS command options.
  • An entry describing the OS command parameters.

Note: The two created configurations must be set to react differently:

  • Reacting on Alert Change: Configuration <BAdI_FilterValue>_REACT
  • Reacting on Alert Closure: Configuration <BAdI_FilterValue>_REACT_CLOSE

OS Command Options


Two mandatory options are already pre-filled:

  • 00;COMMAND_NAME
  • 01;OP_SYSTEM

The values must reflect the SM49 External OS Command Configuration. An example SM49 command has been configured in the figure shown above.


Note: The two mandatory configurations react to an Alert Change (OS_COMMAND_REACT) and an Alert Closure (OS_COMMAND_REACT_CLOSE). You can deactivate a reaction by setting the value <SKIP> value to the COMMAND_NAME option.

Note: Be sure to prefix (separated by semi-columns) the option name with the index order to which you want the OS command to be executed:

  • 01;option1 / value1
  • 02;option2 / value2 …

Note: Option values can remain empty. Alternatively, you can add new options. 

For example:

00;COMMAND_NAME SM49_CMD
01;OP_SYSTEM ANYOS
02;-v              ‘true'
03;-d
04;-DIR /cfg/mydir/

The above options create the following OS Command call:

<SM49_CMD_ConfiguredCommand> -v -d ‘true' -DIR /cfg/mydir/

OS Command Parameters

Additionally, to Options, you can configure the OS Command Adapter to send Parameters.

By default it is configured with “-1;NO_PARAMETER” that indicates that no parameter will be build. Please do not remove this entry to avoid the Configuration Entry to be deleted automatically.


The format is the following: <FieldIndex>;<FieldName> <FieldType> (<FieldType> = s(tring) or i(nteger) ). If FieldType is s(tring), then the parameter value should be enclosed in quotes, but if it is i(nteger), then no need to do so.

If you need to add Parameters, replace the “-1;NO_PARAMETER” with the Parameters at your convenience as shown in the screenshot, for example:

01;r3frunAlertMOName s '[MAI:ALERT:MO_NAME]'
02;r3frunAlertDate s ‘[MAI:ALERT:DATE]' 
03;r3frunAlertSeverity i [MAI:ALERT:SEVERITY]
04;$$ i [MAI:ALERT:RATING]

This will create the following Parameters' line that will be concatenated to the previously build Options' line:

r3frunAlertMOName s '<MAI_AlertMOName_value>' r3frunAlertDate s '<MAI_AlertDate_value>' r3frunAlertSeverity i <MAI_AlertSeverity_value> i <MAI_AlertRating>

Note: The Parameter name ‘$$' indicates that there will be parameter name (only a parameter value).

Note: The OS Command is limiting the concatenated length of all Parameters to maximum 1024 chars.

MAI Configuration to React to Alerts

Enable the outbound integration at one or more of the following levels:

  • Global
  • Template
  • Alert

Enabling the Outbound Integration at Global Level

  • Run transaction FRUN
  • Select the tile Alert Management.
  • Click the Configuration'Icon and expand the Default Outbound Integrations and Edit.

  • Select the Appropriate Outbound Integration Variant from the dropdown list for the Monitoring Use Case and Click Save.


Enabling the Outbound Integration at Template Level

  • Run transaction FRUN
  • Select the tile System Monitoring – Template Maintenance.
  • In the dialog box that appears, choose the Expert Mode.
  • Select the appropriate template and navigate to the Outbound integration tab.
  • In the Outbound Integration dropdown list, choose Use Variant.
  • In the Outbound Integration Variant dropdown list, select the relevant variant ID for which the configuration has been done as shown in the screenshot below.
    Note: For variant configuration, please refer Section 5.


Enabling the Outbound Integration at Alert Level

  • Run transaction FRUN
  • Select the tile System Monitoring – Template Maintenance.
  • In the dialog box that appears, choose the Expert Mode.
  • Select both the appropriate template and the alert within the template, and navigate to the Outbound integration tab.
  • In the Outbound Integration dropdown, select “Use Variant”.
  • In the Outbound Integration Variant dropdown list, select the relevant variant ID for which the configuration has been done as shown in the screenshot below.
    Note: for variant configuration, please refer Section 4.5.


Runtime Activation

  • Run transaction FRUN
  • Under Infrastructure Administration tab, choose the Simple System Integration tile.
  • Select the appropriate managed object in the Extended System ID and choose Go.
  • Select the desired system and choose Configure Automatically.


Variant Configuration for Outbound Integration

  1. To configure the variant within any of the levels, select Use Variant from the Outbound Integration dropdown
  2. Choose Maintain Outbound Integration Variants to maintain the outbound integration variant as shown below:


3  In the newly opened window, Click Add.


4  Provide Name, Description and set the Status to Active.

5  Click the Outbound Integration Input field, and select one or more appropriate Outbound Integration from the suggestion list.


6  Choose ‘Save' to save the Outbound Integration Variant.

Troubleshooting

Logs are available using SLG1 transaction.

External ID has the following structure:
<ConfigurationFilterValue> _ OSCMD_<ManagedObject Name> _ <Alert Category> _ <AlertName>

For the Initialization process, and if an unexpected error occurs, you can also check the following External ID: