How-to Guide: OS Command Adapter

This guide explains how you can react to MAI Alerts in SAP Focused Run (FRUN) by sending an OS Command

E2E Monitoring and Alerting Infrastructure (E2E MAI):

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

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 OS Command Adapter is available standard with Focused Run (FRUN) FP01.
  • 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 Focused Run (FRUN) 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:

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 FRUN FP01, 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 FP01

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 connector at one or more of the following levels:

  • Global
  • Template
  • Alert

Enabling the Outbound Connector at Global Level

  • Run transaction FRUN
  • In the Advanced Event and Alert Management tab, Select the tile Alert Management - Manage Consumer Configuration.
  • In the dialog box that appears, choose the Outbound Connector tab.
  • From the Outbound Connector dropdown list, select Use Variant.
  • In the Outbound Connector Variant, 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 Connector at Template Level

  • Run transaction FRUN
  • Under Advanced System Management tab, 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 connector tab.
  • In the Outbound Connector dropdown list, choose Use Variant.
  • In the Outbound Connector 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 Connector at Alert Level

  • Run transaction FRUN
  • Under Advanced System Management tab, 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 connector tab.
  • In the Outbound Connector dropdown, select “Use Variant”.
  • In the Outbound Connector 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 Manually.
  • In the configuration wizard that opens, select Next to go to Step 2 [Execute Configuration].
  • For step 2 [Execute Configuration], Select Configure System Monitoring and choose Next to go to step 3 [Complete configuration].
  • For step 3 [Complete Configuration], choose Activate System.

Variant Configuration for Outbound Connector

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

3.   In the dialog box, create a New Variant.

4.   Provide the Name and Description, and set the outbound connector to Active status.

5.    Choose Add, select the appropriate outbound connector in the pop-up, and choose OK.

6.    Choose Save to save the 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: