Enhance with OS Level Scripts

This document describes how to enhance the data collection of the Advanced Configuration Monitoring by using custom scripts on OS level and how to extend existing config stores in CCDB for such custom tailored content.

For loading custom-specific data from OS level scripts into CCDB, the operation system command interface DAGT_HA_EXE of the host agent can be used. Scripts provide the data in text format. FRUN CF allows to store the output in Configuration and Change Database (CCDB) directly as text or convert the output into a table format.

The following steps must be performed:

1.     Create script and create a new conf-file for the SAP Host Agent

2.     Identify suitable CCDB table (ABAP Dictionary)

3.     Create a custom config store definition (CSA Administration – CSA Template Management)

4.     Adapt the script

5.     Perform SSI Setup

The sections below describe the above-mentioned steps in detail. For further questions please check the FAQ section at the end of this page.

Script and Conf File

Step 1: Create script and create a new conf-file for the SAP Host Agent

The operation system script has to be created and tested in a customer specific directory in the SAPHostAgent, e.g.:



OS Level folder structure for the SAP Host Agent

Figure: Path to an executable OS script (example)

In this example the script has the name “SRSM_CCDB_HdbSAPgenpse.sh”.

Now you create “<name>.conf” file in directory operations.d

Location of the SAP Host Agent's Conf-file on OS-level

Figure: Path of the Conf-file in the SAP Host Agent's directory structure

This “<name>.conf” contains the script specifications, for example: 

Command: /usr/sap/hostctrl/exe/operations.d/custom_operations/CCDB/cf_sapgenpse.sh $[HDB_PATH:#required]
Platform: Unix
ResultConverter: flat

Remark: Command: /usr/sap...    must be defined in one line.
                 ResultConverter “flat” is mandatory for CCDB scripts.

CCDB Table

Step 2. Identify a suitable CCDB Table in ABAP Dictionary

The Collector Framework (FRUN CSA CF) can store the script output as text or convert it into a table format.

For storing the script output as text use table CCDB_DATA_010. All the output is stored in in a single field of the specified length. 

Figure: Column structure of a CCDB Text Store (SE11)

To store script output as table you can choose either from the generic TableStores (recommended) or re-use a CCDB table with suitable table structure from the SAP standard. For details, please refer to document How to enhance CCDB with database content from custom SQL.

 

We usually recommend converting script output into a table format. This typically simplifies creation of check rules in the XML policies for validation later-on.

Custom Config Store

Step 3: Create a custom config store definition 

On the Focused Run system, a configuration item template must be created. Here, the name of the script and optional parameters required by the OS script are set. You can create a new SCI template and then copy and change from an existing templates as starting point.

It is possible to restrict the collector on systems having a restriction on property EC_OB_PROP:

  • The collector should only run for a system having the Extended SID (<ExtendedSid>): EC_OB_PROP="ESID=<ExtendedSid>"
  • Patterns or placeholders are not supported. All conditions separated by ";" are logically evaluated by an AND operation
    Thus, it is only possible to restrict on one Extended SID
  • If a collector should only run for productive systems use EC_OB_PROP="ITADMINISTRATIONROLE=PROD"
    Possible values for ITADMINISTRATIONROLE are: "PROD, QA, DEV, TEST, SANDBOX"
  • In general, it allows to pin a collector to any of the parameters that are reported by the report Report COF_CIM_TREE_TS (***) and that belong to TECHNICAL_SYSTEM and are flagged with BELONGS_TO_RT = X
  • The LMDB custom attributes are available as landscape parameters with the following naming convention "_LA_<Custom attribute name>"
  • There is also a not parameter "!" available. Example: EC_OB_PROP="DB_TENANT=!TRUE"

*** Report COF_CIM_TREE_TS 
Input fields of Report COF_CIM_TREE_TS can be taken from the LMDB Object Maintenance:
The report outputs the landscape hierarchy which is used by the Advanced Configuration Monitoring use case.
NSPA = Namespace (corresponds to the technical id of the namespace as displayed in the header line when displaying the object in LMDB.
ESID = Extended SIDTYPE = Managed system type, e.g. ABAP  

 

The screenshot below is an example of an SCI template for a script extractor.

Screenshot from CSA Template Maintenance

Figure: SCI template for a script extractor (example)

The following attributes must be maintained: In the header section specify the SCI Description SCI_DESC and the MODIFIED date

Take care of the following attributes:

  • Specify a meaningful SCI Description (SCI_DESC)
  • Change attribute EX_OB_DEST_ID to DAGT_HA_EXE
  • Specify the DDIC_TABLENAME and the STORE_NAME
  • Specify the STORE_TYPE as “TEXT” or “TABLE”

Below the store definition, specify the parameters:

  • “name” (mandatory): Specify the name of the OS script without the path.
  • Specify additional parameters (optional).
    The common syntax is: “$[ExecuteOperation-Parameter-Name]”
    The SAPHostAgent command ‘ExecuteOperation' does support variables which can be filled here. You can use CSA Collector Framework parameter as in the example above. They are specified by the format ${Parameter name}. You can also use constants.
    The CSA CF parameter can be displayed in the FRUN using report COF_CIM_TREE_TS  (for Technical Systems) and COF_CIM_TREE_HOST (for Hosts).

Adapt Script

Step 4: Adapt Script

If store_type “TEXT” is used, then no activity to adapt the script is required. All output will be written to the text field of table CCDB_DATA_010.

If store_type “TABLE” is used, the script must deliver its data as a table stored in a json string. The json string contains of two parts, the field list and the table data. In addition, an exit code should be returned by the script.

JSON Example:

example coding for output in json format

Figure: Example of a JSON string for transferring data into a generic Table Store

The script itself should return an exitcode “0”, “1” or “2”:

0 = Correct

1 = Warning

2 = Error

Testing

Step 5: Testing the script

For testing the script can be executed manually on OS level with the command:

example OS Command

Figure: Example command for executing a script

Perform SSI

Step 6: Perform Simple System Integration (SSI)

CCDB store template changes are triggered automatically down to the SDA's after changes have been done. The trigger should be completed for all systems within 1 hour. 

You can also trigger the SSI manually for each system in the CSA Administration by running the Setup. For triggering an immediate update on the SDA, you have to select and setup systems one by one.

Note that scripts need to be distributed with non-SAP tools, since FRUN is currently unable to perform this step.

FAQ

At this point no questions have been raised. Please be the first one or wait for other customer's questions.