7 Collecting Target Configuration Data

This chapter provides information about defining configuration collection tables and integrating them into the Enterprise Configuration Management framework.

This chapter contains the following sections:

• Introduction to Collecting Target Configuration Data

• About the Configuration Definition Files

• Modeling Enterprise Configuration Management Tables

7.1 Introduction to Collecting Target Configuration Data

As a plug-in developer, you are responsible for the following steps with respect to incorporating configuration-related functions into Enterprise Configuration Management for each snapshot type:

1. Ensure that every bit of the configuration data that will be collected will not change from one collection to the next unless there is an explicit action by an administrator. Configuration data must only collect data that can change due to explicit administrator actions but should stay unchanged without such actions.

2. Define an Enterprise Configuration Management-specific metadata file that defines collection tables to match configuration collection metrics established as part of the target type definition.

   For more information, see Section 7.3.1, "Defining Configuration Collection Tables".

3. Name the snapshot type (the name must match the CollectionItem name specified on the Management Agent side) for a given target type.

   For more information, see Section 7.3.2, "Overview of Configuration Management Snapshot Metadata Elements".

4. Register the metadata with Enterprise Configuration Management during plug-in deployment. This creates tables for snapshot data, subject to any constraints imposed by the Enterprise Configuration Management framework. It also registers the data tables in Enterprise Configuration Management metadata tables.

   For more information, see Section 7.3.4, "Registering Metadata With the Configuration Management Framework".

5. Integrate with the standard Management Agent's collection mechanisms. Both CollectionItem and corresponding metrics must be defined at the Management Agent.

   For more information, see Section 7.3.7, "Modifications to Standard Collection Metrics and RAW Metrics".

6. Verify that the defined configuration collection data is returned to the Management Repository by the Management Agent.

   For more information, see Section 7.3.8, "Testing the Configuration Collection Data" and Section 7.3.9, "Troubleshooting".

7.1.1 Assumptions and Prerequisites

This chapter assumes you are familiar with the following:

• Enterprise Manager concepts including Management Agents, metrics, and collection items

• Plug-in development overview, including how to package a plug-in and its XML files

7.2 About the Configuration Definition Files

The metadata for configuration collection is defined in three metadata files packaged with the plug-in:

• The configuration metadata file

  This file defines the tables in the Management Repository that will store collected configuration data. In addition, the EDK includes an example of a configuration metadata file:

  \samples\plugins\HostSample\stage\oms\metadata\snapshotlive\demo_hostsample_ecmdef.xml
  

  For more information, see Section 7.3.1, "Defining Configuration Collection Tables".

• The target type metadata file

  Each configuration data item is collected as a metric that is defined with other metrics in the target type metadata file. In addition, the EDK includes an example of a target type metadata file:

  \samples\plugins\HostSample\stage\oms\metadata\targetType\demo_hostsample.xml
  

  For more information, see Section 3.3, "Creating the Target Type Metadata File".

• The default collection metadata file

  The frequency at which configuration data is collected for each metric is defined in the default collection metadata file. Metric Alert event conditions for each metric and the messages to display for such alerts are also defined in this file. In addition, the EDK includes an example of a default collection metadata file:

  \samples\plugins\HostSample\stage\oms\metadata\default_collection\demo_hostsample.xml
  

  For more information, see Section 3.5, "Creating the Default Collection File".

7.3 Modeling Enterprise Configuration Management Tables

This section describes how to create configuration snapshot tables. Assume that an Oracle home target type definition is added to the Enterprise Manager framework.

You can define metadata and tables to store your configuration data and define metrics to collect the data at the Management Agent.

Each Enterprise Configuration Management metric defined in the target type metadata file corresponds to a table defined by the configuration metadata XML file. For information about target type metadata files, see Chapter 3, "Creating Target Metadata Files".

Tables can have parent-child relationships similar to foreign key constraints in the database. For every parent table row, there are n numbers of child table rows, and every child table row has exactly one parent table row. In effect, Enterprise Configuration Management allows trees of tables, where each table has at most one parent table. A configuration can consist of a set of these trees where no table is repeated.

From a database perspective, a table must include all key columns of its ancestor tables. (Internally, each Enterprise Configuration Management table includes an ECM_SNAPSHOT_ID column of type RAW(16) to identify the snapshot to which a given row belongs.)

Metadata for the collection tables must specify at a minimum:

• Table names, column names, column types, and hierarchical relationships between tables (if any).

• Key columns, that is columns that uniquely identify a row in a table. You must specify keys correctly. Enterprise Manager UI, comparison, and history use key columns extensively.

• UI display names that will in the Enterprise Manager generic UI.

Figure 7-1 shows the Oracle Home Entity Relationship Diagram (ERD) of the configuration tables.

Figure 7-1 Oracle Home ERD with Tie-ins to the Framework

7.3.1 Defining Configuration Collection Tables

The configuration metadata XML file begins with the METADATA tag. The METADATA tag establishes the relationship between the target type and the snapshot type, and defines the UI display name.

<METADATAS>
  <METADATA SNAP_TYPE="oracle_home_config" TARGET_TYPE="oracle_home" VER="1">

       <METADATA_UI_NAME>Oracle Home Configuration</METADATA_UI_NAME>

       CONFIGURATION COLLECTION TABLE DEFINITIONS
  </METADATA>
<METADATAS>

The configuration collection table definitions are encapsulated within the METADATA tag.

For more information about the elements of the configuration metadata XML, see Section 7.3.2, "Overview of Configuration Management Snapshot Metadata Elements". For information about the XML Schema Definitions (XSD) that governs the configuration XML files, see the Extensibility Development Kit (EDK) specifications.

7.3.1.1 EM_ECM_OH_HOME_INFO Table

The EM_ECM_OH_HOME_INFO table stores properties related to an Oracle software installation. The metadata for this table is as follows:

<TABLE NAME="EM_ECM_OH_HOME_INFO" SINGLE_ROW="Y">
  <UI_NAME>Home Info</UI_NAME>
  <COLUMN NAME="HOME_LOCATION"  TYPE="STRING" TYPE_FORMAT="1024">Install Location</COLUMN>
  <COLUMN NAME="OUI_HOME_NAME"  TYPE="STRING" TYPE_FORMAT="256" >OUI Home Name</COLUMN>
  <COLUMN NAME="OUI_HOME_GUID"  TYPE="STRING" TYPE_FORMAT="32"  >OUI Home GUID</COLUMN>
  <COLUMN NAME="HOME_TYPE"      TYPE="STRING" TYPE_FORMAT="1"   >Home Type</COLUMN>
  <COLUMN NAME="HOME_POINTER"   TYPE="STRING" TYPE_FORMAT="1024">Home Pointer</COLUMN>
  <COLUMN NAME="IS_CLONABLE"    TYPE="NUMBER" TYPE_FORMAT="1"   >Is Clonable</COLUMN>
  <COLUMN NAME="IS_CRS"         TYPE="NUMBER" TYPE_FORMAT="1"   >Is CRS</COLUMN>
  <COLUMN NAME="ARU_ID"         TYPE="NUMBER" TYPE_FORMAT="10"  >ARU ID of the Oracle Home</COLUMN>
  <COLUMN NAME="HOME_SIZE"      TYPE="NUMBER" TYPE_FORMAT="10"  >Size of Oracle Home (KB)</COLUMN>
</TABLE>

The corresponding database table is as follows:

COLUMN_NAME	DATA_TYPE	COLUMN_WIDTH	KEY
ECM_SNAPSHOT_ID	RAW	16	PK
HOME_LOCATION	VARCHAR2	1024
OUI_HOME_NAME	VARCHAR2	256
OUI_HOME_GUID	VARCHAR2	32
HOME_TYPE	VARCHAR2	1
HOME_POINTER	VARCHAR2	1024
IS_CLONABLE	NUMBER	1
IS_CRS	NUMBER	1
ARU_ID	NUMBER	10
HOME_SIZE (in KB)	NUMBER	10

For this table, the Primary Key consists of ECM_SNAPSHOT_ID. The SINGLE_ROW=”Y” attribute from the metadata example indicates that each snapshot will have at most a single row in this table and therefore you do not have to mark any other columns in the table as key. This implies that the ECM_SNAPSHOT_ID column, which identifies the snapshot, will be the only key column in the table.

7.3.1.2 EM_ECM_OH_DEP_HOMES Table

The EM_ECM_OH_DEP_HOMES table stores the locations of the Oracle home directories that a given Oracle home depends on. This data is used to form dependency associations between Oracle homes. The metadata for this table is as follows:

<TABLE NAME="EM_ECM_OH_DEP_HOMES">
  <UI_NAME>Dependee Oracle Homes</UI_NAME>
  <COLUMN NAME="DEP_HOME_LOCATION"  TYPE="STRING" TYPE_FORMAT="1024" IS_KEY="Y">Dependee Home Location</COLUMN>
</TABLE>

The corresponding database table is as follows:

COLUMN_NAME	DATA_TYPE	COLUMN_WIDTH	KEY
ECM_SNAPSHOT_ID	RAW	16	PK
DEP_HOME_LOCATION	VARCHAR2	1024	PK

The primary key for this table consists of ECM_SNAPSHOT_ID and DEP_HOME_LOCATION.

Note:

Key columns (in addition to ECM_SNAPSHOT_ID, which is always part of the key) are marked with IS_KEY="Y" in the metadata file.

7.3.1.3 EM_ECM_OH_COMPONENT Table

The EM_ECM_OH_COMPONENT table stores information about Oracle software components in the Oracle home directory. The metadata for this table is as follows:

<TABLE NAME="EM_ECM_OH_COMPONENT">
  <UI_NAME>Components installed in Oracle Home</UI_NAME>
  <COLUMN NAME="COMPONENT_NAME"           TYPE="STRING" TYPE_FORMAT="128" IS_KEY="Y">Component Name</COLUMN>
  <COLUMN NAME="COMPONENT_VERSION"        TYPE="STRING" TYPE_FORMAT="64"  IS_KEY="Y">Base Version of Component</COLUMN>
  <COLUMN NAME="CURRENT_VERSION"          TYPE="STRING" TYPE_FORMAT="64"            >Current Version of the Component</COLUMN>
  <COLUMN NAME="INSTALL_TIME"             TYPE="TIMESTAMP"                          >Install Time</COLUMN>
  <COLUMN NAME="IS_TOP_LEVEL"             TYPE="NUMBER" TYPE_FORMAT="1"             >Is it a top level Component</COLUMN>
  <COLUMN NAME="EXTERNAL_NAME"            TYPE="STRING" TYPE_FORMAT="128"           >External name</COLUMN>
  <COLUMN NAME="DESCRIPTION"              TYPE="STRING" TYPE_FORMAT="1024"          >Description</COLUMN>
  <COLUMN NAME="LANGUAGES"                TYPE="STRING" TYPE_FORMAT="1024"          >Languages</COLUMN>
  <COLUMN NAME="INSTALLED_LOCATION"       TYPE="STRING" TYPE_FORMAT="1024"          >Installed Location</COLUMN>
  <COLUMN NAME="INSTALLER_VERSION"        TYPE="STRING" TYPE_FORMAT="64"            >Installer Version</COLUMN>
  <COLUMN NAME="MIN_DEINSTALLER_VERSION"  TYPE="STRING" TYPE_FORMAT="64"            >Minimum Deinstaller Version</COLUMN>

Note:

This metadata has no closing TABLE tag (yet) because it is a parent table to the next table (EM_ECM_OH_COMP_INST_TYPE Table), which is included as part of this TABLE tag.

The corresponding database table is as follows:

COLUMN_NAME	DATA_TYPE	COLUMN_WIDTH	KEY
ECM_SNAPSHOT_ID	RAW	16	PK
COMPONENT_NAME	VARCHAR2	128	PK
COMPONENT_VERSION	VARCHAR2	64	PK
CURRENT_VERSION	VARCHAR2	64
INSTALL_TIME	DATE	-
IS_TOP_LEVEL	NUMBER	1
EXTERNAL_NAME	VARCHAR2	128
DESCRIPTION	VARCHAR2	1024
LANGUAGES	VARCHAR2	1024
INSTALLED_LOCATION	VARCHAR2	1024
INSTALLER_VERSION	VARCHAR2	64
MIN_DEINSTALLER_VERSION	VARCHAR2	64

The primary key for this table consists of ECM_SNAPSHOT_ID, COMPONENT_NAME, and COMPONENT_VERSION.

7.3.1.4 EM_ECM_OH_COMP_INST_TYPE Table

The EM_ECM_OH_COMP_INST_TYPE table stores the installation type of Oracle software components (Oracle Universal Installer (OUI) only). This a child table of EM_ECM_OH_COMPONENT Table. The metadata for this table is as follows:

<TABLE NAME="EM_ECM_OH_COMP_INST_TYPE">
   <UI_NAME>Install Types of Components</UI_NAME>
   <COLUMN NAME="NAME_ID"                  TYPE="STRING" TYPE_FORMAT="128" IS_KEY="Y">Install Type Name ID</COLUMN>
   <COLUMN NAME="INSTALL_TYPE_NAME"        TYPE="STRING" TYPE_FORMAT="128"           >Install Type Name</COLUMN>
   <COLUMN NAME="DESC_ID"                  TYPE="STRING" TYPE_FORMAT="128"           >Install Type Description ID</COLUMN>
</TABLE>
</TABLE>

Note:

The extra closing </TABLE> tag is for the EM_ECM_OH_COMPONENT parent table.

The corresponding database table is as follows:

COLUMN_NAME	DATA_TYPE	COLUMN_WIDTH	KEY
ECM_SNAPSHOT_ID	RAW	16	PK
COMPONENT_NAME	VARCHAR2	128	PK
COMPONENT_VERSION	VARCHAR2	64	PK
NAME_ID	VARCHAR2	128	PK
INSTALL_TYPE_NAME	VARCHAR2	128
DESC_ID	VARCHAR2	128

For this table, the primary key consists of ECM_SNAPSHOT_ID, COMPONENT_NAME, COMPONENT_VERSION, and NAME_ID.

Note:

COMPONENT_NAME and COMPONENT_VERSION are not listed here but are inherited from the key columns of the parent table, and the values in these columns must match a row in EM_ECM_OH_COMPONENT with the same values for ECM_SNAPSHOT_ID, COMPONENT_NAME, and COMPONENT_VERSION.

7.3.1.5 Additional Information About the Configuration Metadata

Note the following when you are creating the configuration metadata XML file:

• Each table definition must specify its name and at least one column specification:

  Example 7-1 Table Definition

  <TABLE NAME="..." ...>
          Optional UI name
          Column definitions
  Optional Indexes definitions: starting 12c PS1 platform release
          Optional Child Table definitions
  </TABLE>
  

  Table 7-1 provides the attributes of the TABLE element.

• Table names must be specific to a given snapshot type and cannot be shared by multiple snapshot types. While internal Enterprise Manager names can start with EM_, for plug-ins and addons, Oracle recommends that you start table names with the plug-in tag (third part of a plugin ID) in upper case, followed by underscore. For example, plugin ”oracle.sysman.xyz” should define tables starting with XYZ_, such as XYZ_CONFIG.

• Each column definition must specify its name and type at least:

  Example 7-2 Column Definition

  <COLUMN NAME="..." TYPE="..." ...>...</COLUMN>
  

  Table 7-1 provides the attributes of the COLUMN element.

• Columns can be of type STRING, NUMBER, TIMESTAMP, or RAW. TYPE_FORMAT is optional; its meaning derives from the value of type. For a string, it is the maximum string length. For a number, it is precision and scale, as for an Oracle database (for example, TYPE_FORMAT=”4, 9”).

• Specify parent child relationships between tables by nesting the TABLE tags.

• Table and view names cannot exceed 25 characters.

• Table and column order is significant. The UI display replicates the order. Import and export operations preserve the order. Delete operations (on table data) occur in inverse order. Child rows are removed before parent rows.

• COLUMN tags contain the UI display name of the column.

• Tables require key columns that uniquely identify rows in the table. Oracle recommends that the total size of the key columns is not too large (4,000 should be the maximum but much smaller sizes are acceptable).

  The key columns of all ancestor tables are automatically assumed to be inherited by the child tables and are not repeated in the child table specification.

  However, a table does not require a key if it has at most one row per parent row, or per snapshot in the case of a top-level table. Tables that do not have a key must specify the SINGLE_ROW="Y" attribute, which is set to "N" by default.

For information about the key elements of the configuration metadata, see Section 7.3.2, "Overview of Configuration Management Snapshot Metadata Elements".

7.3.2 Overview of Configuration Management Snapshot Metadata Elements

Table 7-1 describes the key elements that define configuration management.

Table 7-1 Key Elements of a Configuration Metadata XML File

Element	Description
METADATAS	The configuration metadata XML file starts with the METADATAS tag. <METADATAS> One or more snapshot specifications </METADATAS> The snapshot specification corresponds to a METADATA tag.
METADATA	The snapshot specification corresponds to a METADATA tag and includes at least one table specification. It also defines the snapshot UI display name. It includes the following attributes: VER: Specifies the plug-in developer-defined metadata version and must be an integer (beginning with 1). Typically, each release increments the version (if there are changes). Only the latest ECM metadata version must be registered within a release (although Management Agents can upload older compatible versions) SNAP_TYPE: Names the type of snapshot. Snapshot types are defined in the context of target types. The name should begin with company name followed by an underscore. For example, oracle_. TARGET_TYPE: Target type for which the snapshot type metadata is defined. UI_IGNORE: Optional. Determines whether data is displayed as part of the configuration browser. Values are N (default), which uses UI functionality or Y, which ignores UI functionality. COMPARE_IGNORE: Optional. Determines whether to perform comparisons on the data. Values are N (default), which uses Compare functionality or Y, which ignores Compare functionality. COMPARE_UI_IGNORE: Optional. Determines whether to display data in the comparison UI. Values are N (default), which uses Compare UI functionality or Y, which ignores Compare UI functionality. HISTORY_IGNORE: Optional. Determines whether to track history on the data. Values are N (default), which uses History functionality or Y, which ignores History functionality. HISTORY_UI_IGNORE: Optional. Determines whether to display data in the history UI. Values are N (default), which uses History UI functionality or Y, which ignores History UI functionality. Note: If you specify a value for a name_IGNORE attribute, then it is specified for all tables unless overridden at a lower (TABLE or COLUMN) level. Inheritance flows from metadata to tables, parent tables to child tables, and from all tables to their columns.
TABLE	Specifies the table name and at least one column. It includes the following attributes: NAME: Required. Identifies the table uniquely SINGLE_ROW: Values are N (default) or Y, which indicates tables that have at most one row per parent row or at most one row per snapshot in case of top-level tables. In this latter case, no key is required. All key columns (if any) are inherited from a parent table. UI_IGNORE: Optional. Determines whether data is displayed as part of the configuration browser. Values are N (default), which uses UI functionality or Y, which ignores UI functionality. COMPARE_IGNORE: Optional. Determines whether to perform comparisons on the data. Values are N (default), which uses Compare functionality or Y, which ignores Compare functionality. COMPARE_UI_IGNORE: Optional. Determines whether to display data in the comparison UI. Values are N (default), which uses Compare UI functionality or Y, which ignores Compare UI functionality. HISTORY_IGNORE: Optional. Determines whether to track history on the data. Values are N (default), which uses History functionality or Y, which ignores History functionality. HISTORY_UI_IGNORE: Optional. Determines whether to display data in the history UI. Values are N (default), which uses History UI functionality or Y, which ignores History UI functionality. Note: If you specify a value for a name_IGNORE attribute, then it is specified for all columns and a child table unless overridden at a lower (TABLE or COLUMN) level.
COLUMN	Each column definition must a NAME and TYPE attributes. It includes the following attributes: NAME: Required. Identifies the table column uniquely. TYPE: Required. Values are STRING, NUMBER, TIMESTAMP, CLOB, or RAW TYPE_FORMAT: Optional. Value depends on the value in the TYPE attribute IS_KEY: Required. Specifies whether it is part of a key that uniquely identifies a row in the table. The key columns of all ancestor tables are automatically assumed to be inherited by the child tables. Note: A table does not require a key (unless that of ancestor table keys, if any) if it has only one row per parent row, or per snapshot in the case of a top-level table. You must specify the SINGLE_ROW=”Y” attribute (which is set to ”N” by default) for tables that do not have a key. UI_IGNORE: Optional. Determines whether data is displayed as part of the configuration browser. Values are N (default), which uses UI functionality or Y, which ignores UI functionality. COMPARE_IGNORE: Optional. Determines whether to perform comparisons on the data. Values are N (default), which uses Compare functionality or Y, which ignores Compare functionality. COMPARE_UI_IGNORE: Optional. Determines whether to display data in the comparison UI. Values are N (default), which uses Compare UI functionality or Y, which ignores Compare UI functionality. HISTORY_IGNORE: Optional. Determines whether to track history on the data. Values are N (default), which uses History functionality or Y, which ignores History functionality. HISTORY_UI_IGNORE: Optional. Determines whether to display data in the history UI. Values are N (default), which uses History UI functionality or Y, which ignores History UI functionality.
INDEXES	Optional indexes are useful when a table is used in derived associations, compliance rules, reports, or other queries where performance is important in accessing table rows based on columns other than ECM_SNAPSHOT_ID. An optional index definitions element <INDEXES> should specify at least one <INDEX> element, and each <INDEX> element should specify name and columns: <INDEXES> <INDEX NAME="..." COLUMNS="..." /> <INDEX NAME="..." COLUMNS="..." /> … </INDEXES> NAME: Required. Identifies the table column uniquely and should be unique among all index names. Oracle recommends that the name should be the same as table name followed by _IDX1, _IDX2, and so on. COLUMN: Required. Value should be a comma-separated list of column names.

Note:

A predefined ECM_METADATA_ID column is always added as the last column for each index.

Example 7-3 provides an example of a configuration metadata XML file for an oracle_home _config snapshot. All *_IGNORE attributes keep their default values (N) because they are not specified in the file.

Example 7-3 Example of a Configuration Metadata XML File

<METADATAS>
  <METADATA SNAP_TYPE="oracle_home_config" TARGET_TYPE="oracle_home" VER="1"

  <METADATA_UI_NAME>Oracle Home Configuration</METADATA_UI_NAME>

  <TABLE NAME="EM_ECM_OH_HOME_INFO" SINGLE_ROW="Y">
    <UI_NAME>Home Info</UI_NAME>
    <COLUMN NAME="HOME_LOCATION" TYPE="STRING" TYPE_FORMAT="1024">Install Location</COLUMN>
    <COLUMN NAME="OUI_HOME_NAME" TYPE="STRING" TYPE_FORMAT="256">OUI Home Name</COLUMN>
    <COLUMN NAME="OUI_HOME_GUID" TYPE="STRING" TYPE_FORMAT="32">OUI Home GUID</COLUMN>
    <COLUMN NAME="HOME_TYPE" TYPE="STRING" TYPE_FORMAT="1">Home Type</COLUMN>
    <COLUMN NAME="HOME_POINTER" TYPE="STRING" TYPE_FORMAT="1024">Home Pointer</COLUMN>
    <COLUMN NAME="IS_CLONABLE" TYPE="NUMBER" TYPE_FORMAT="1">Is Clonable</COLUMN>
    <COLUMN NAME="IS_CRS" TYPE="NUMBER" TYPE_FORMAT="1">Is CRS</COLUMN>
    <COLUMN NAME="ARU_ID" TYPE="NUMBER" TYPE_FORMAT="10">ARU ID of the Oracle Home</COLUMN>
    <COLUMN NAME="HOME_SIZE" TYPE="NUMBER" TYPE_FORMAT="10">Size of Oracle Home (KB)</COLUMN>
  </TABLE>

  <TABLE NAME="EM_ECM_OH_DEP_HOMES">
    <UI_NAME>Dependee Oracle Homes</UI_NAME>
    <COLUMN NAME="DEP_HOME_LOCATION" TYPE="STRING" TYPE_FORMAT="1024" IS_KEY="Y">Dependee Home Location</COLUMN>
  </TABLE>

  <TABLE NAME="EM_ECM_OH_COMPONENT">
    <UI_NAME>Components installed in Oracle Home</UI_NAME>
    <COLUMN NAME="COMPONENT_NAME" TYPE="STRING" TYPE_FORMAT="128" IS_KEY="Y">Component Name</COLUMN>
    <COLUMN NAME="COMPONENT_VERSION" TYPE="STRING" TYPE_FORMAT="64" IS_KEY="Y">Base Version of Component</COLUMN>
    <COLUMN NAME="CURRENT_VERSION" TYPE="STRING" TYPE_FORMAT="64">Current Version of the Component</COLUMN>
    <COLUMN NAME="INSTALL_TIME" TYPE="TIMESTAMP" >Install Time</COLUMN>
    <COLUMN NAME="IS_TOP_LEVEL" TYPE="NUMBER" TYPE_FORMAT="1">Is a top level Component</COLUMN>
    <COLUMN NAME="EXTERNAL_NAME" TYPE="STRING" TYPE_FORMAT="128">External name</COLUMN>
    <COLUMN NAME="DESCRIPTION" TYPE="STRING" TYPE_FORMAT="1024">Description</COLUMN>
    <COLUMN NAME="LANGUAGES" TYPE="STRING" TYPE_FORMAT="1024" >Languages</COLUMN>
    <COLUMN NAME="INSTALLED_LOCATION" TYPE="STRING" TYPE_FORMAT="1024">Installed Location</COLUMN>
    <COLUMN NAME="INSTALLER_VERSION" TYPE="STRING" TYPE_FORMAT="64">Installer Version</COLUMN>
    <COLUMN NAME="MIN_DEINSTALLER_VERSION" TYPE="STRING" TYPE_FORMAT="64">Minimum Deinstaller Version</COLUMN>

      <TABLE NAME="EM_ECM_OH_COMP_INST_TYPE">
        <UI_NAME>Install Types of Components</UI_NAME>
        <COLUMN NAME="NAME_ID" TYPE="STRING" TYPE_FORMAT="128" IS_KEY="Y">Install Type Name ID</COLUMN>
        <COLUMN NAME="INSTALL_TYPE_NAME" TYPE="STRING" TYPE_FORMAT="128" >Install Type Name</COLUMN>
        <COLUMN NAME="DESC_ID" TYPE="STRING" TYPE_FORMAT="128">Install Type Description</COLUMN>
      </TABLE>

  </TABLE>

  </METADATA>
</METADATAS>

Note:

Use the information in this file to define a metric in the target type metadata file. For more information, see Section 7.3.7, "Modifications to Standard Collection Metrics and RAW Metrics" and Example 7-6.

7.3.3 Packaging Configuration Metadata

When you have completed your configuration metadata XML file, save the file in the following directory in your plug-in staging directory:

oms/metadata/snapshotlive

After you save the configuration metadata file in the plug-in staging directory, it is available for automatic registration during plug-in deployment.

For information about the plug-in staging directory or plug-in deployment, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".

7.3.4 Registering Metadata With the Configuration Management Framework

After you complete the configuration metadata XML file, you must register it with the Configuration Management framework. Place the configuration metadata XML file in the oms/metadata/snapshotlive directory in your plug-in staging directory. Registration takes place automatically during the installation or upgrade of the plug-in and the necessary schema objects will be created and the configuration metadata registered with the Configuration Management framework. For more information about the plug-in staging directory and registration, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".

To manually run the registration service during development of XML-only plug-ins, enter the following:

emctl register oms metadata 
-sysman_pwd sysman password 
-pluginId plugin ID
-service LiveSnapshotRegistration 
-file snapshot metadata XML file

Note: Import the plug-in into the Management Repository before the command is run.

plugin ID is the ID of the plug-in to which the snapshot metadata target types belong. The LiveSnapshotRegistration is the metadata service that creates and updates configuration management schema objects and registers configuration metadata.

This command registers the snapshot configuration file (snapshot metadata XML file) using SYSMAN credentials in your development environment.

Configuration Management provides the following utility that can be run optionally to generate some additional files:

EDK_DIR/bin/empdk generate_metadata_resource -stage_dirplugin_stage 
         -service LiveSnapshotRegistration
         -input_dir input directory
         [-out_dir output directory]
         [-file_extension list of file extensions/suffixes]
         [-debug debug file name]

where:

• EDK_DIR: Directory where EDK package is unzipped. (For more information, see Section 1.3, "Installing the Extensibility Development Kit (EDK)").

• plugin_stage: Plug-in staging directory. (For more information, see Section 14.2, "Staging the Plug-in").

• input directory: Directory containing the configuration metadata XML files.

• output directory:Directory to contain the generated resource files. If not specified, then the resource files are generated in the current directory.

• list of file extensions/suffixes: Comma separated list of file extensions or suffixes for the resource files. If not specified, then all supported resource files will be generated in the output directory.

• debug file name: File that contains debug information. If not specified, then the default log file (createplugin.logtime) is created in the output directory and stored warning and error messages only.

For each configuration metadata XML file in the input directory, the specified resource files are generated in the output directory with the file name ecm_metadata_xml_file_name as the prefix and the following supported suffixes:

• .dlf

  file_name.dlf is a file for translations of snapshot type name, table name, and column name. A generated DLF file and its translated versions should be placed in the plugin_stage/oms/rsc/ecm directory of the plug-in.

• _metrix.xml, _collection.xml

  file_name_metric.xml and file_name_collection.xml can be used as starting templates for Management Agent-side integration. For more information, see Section 7.3.7, "Modifications to Standard Collection Metrics and RAW Metrics".

7.3.5 Supporting Translation

Data Loading Format (DLF) translation files are used to support internationalization for the display strings in plug-in metadata files so that the UI can display them in the language of the end user. Usually, you provide an original (such as English) DLF file to translators who then create similar files for other locales. All such files are loaded into the Management Repository by Enterprise Manager during the installation of a plug-in.

Note:

Generating DLF files is optional and is required only if you require translation.

To generate DLF files for translation of the snapshot type name, table, and column names, run the following command:

$ORACLE_HOME/emcore/pdk/partner/bin/empdk generate_metadata_resource
-stage_dir staging directory
-service LiveSnapshotRegistration
-input_dir input directory containing snapshot metadata XML file
-file_extension extension to use for generated DLF files
-out_dir output directory to which to generate the DLF files
[-debug debug output file]

You must place the generated DLF files and their corresponding translated versions in the following directory of the plug-in:

plugin_stage/oms/rsc/ecm

The following manual additions are required in each DLF file:

<table name="MGMT_MESSAGES">
<lookup-key>
  <column name="MESSAGE_ID"/>
  <column name="SUBSYSTEM"/>
  <column name="LANGUAGE_CODE"/>
  <column name="COUNTRY_CODE"/>
</lookup-key>
<columns>
  <column name="MESSAGE_ID" type="string" maxsize="256"/>
  <column name="SUBSYSTEM" type="string" maxsize="64"/>
  <column name="LANGUAGE_CODE" type="string" language="%l"/>
  <column name="COUNTRY_CODE" type="string" language="%Cs"/>
  <column name="MESSAGE" type="string" maxsize="1000" translate="yes"/>
</columns>
<dataset>
GENERATED FILE CONTENT
</dataset>
</table>

7.3.6 Upgrading Configuration Data

Note:

You must increment your integer metadata version (VER attribute) whenever you release a new version of metadata to your customers. The version should be incremented in the ECM XML metadata file (VER attribute in the METADATA element) as well as the corresponding Agent collection file.

For more information about the VER attribute, see Table 7-1, "Key Elements of a Configuration Metadata XML File".

When you are upgrading existing snapshot metadata, the following changes are supported:

• New tables

• New non-key columns (these should appear after previously existing columns)

• New list of indexes (replaces any prior indexes)

• Increasing length of STRING type columns

• Values of UI_IGNORE, COMPARE_IGNORE, COMPARE_UI_IGNORE, HISTORY_IGNORE, HISTORY_UI_IGNORE and UI_NAME attributes

Note:

• No key columns can be added or removed

• No columns formats except STRING can be altered

• The length of the STRING columns only can be increased

• New table cannot be added as a parent for an existing table

• Tables or columns cannot be removed from the existing snapshot metadata

Take the following metadata example:

Example 7-4 Original Metadata Definition

<METADATAS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <METADATA VER=”1”
    SNAP_TYPE="sn_dbconfig"
    TARGET_TYPE="sn_oracle_database"
    UI_IGNORE="Y"
    HISTORY_IGNORE="N"
    COMPARE_IGNORE="Y"
    COLLECTION_GROUP="COL_GRP_0">
  <METADATA_UI_NAME>Database Configuration</METADATA_UI_NAME>
  <TABLE NAME="TABLESPACES" DATA_SOURCE="R">
    <UI_NAME>Tablespaces</UI_NAME>
    <COLUMN NAME="TABLESPACE_NAME" TYPE="STRING" TYPE_FORMAT="30"
      IS_KEY="Y">Tablespace Name</COLUMN>
    <COLUMN NAME="SIZE" TYPE="NUMBER">Size</COLUMN>
    <COLUMN NAME="STATUS" TYPE="STRING" TYPE_FORMAT="10">Status</COLUMN>
    <TABLE NAME="DATAFILES">
      <UI_NAME>Datafiles</UI_NAME>
      <COLUMN NAME="FILE_NAME" TYPE="STRING" TYPE_FORMAT="1024" 
        IS_KEY="Y">File Name</COLUMN>
      <COLUMN NAME="FILE_SIZE" TYPE="NUMBER" HISTORY_IGNORE="Y">Size</COLUMN>
      <COLUMN NAME="STATUS" TYPE="STRING" TYPE_FORMAT="9">Status</COLUMN>
    </TABLE>
  </TABLE>
 </METADATA>
</METADATAS>

Example 7-5 provides an example of an upgrade to the metadata definition described in Example 7-4. The changes are highlighted in bold text.

Example 7-5 Upgraded Metadata Definition

<METADATAS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <METADATA VER=”2”
    SNAP_TYPE="sn_dbconfig"
    TARGET_TYPE="sn_oracle_database"
    UI_IGNORE="Y"
    HISTORY_IGNORE="N"
    COMPARE_IGNORE="Y"
    COLLECTION_GROUP="COL_GRP_0">
  <METADATA_UI_NAME>Database Configuration</METADATA_UI_NAME>
  <TABLE NAME="TABLESPACES"  DATA_SOURCE="R">
    <UI_NAME>Tablespaces</UI_NAME>
    <COLUMN NAME="TABLESPACE_NAME" TYPE="STRING" TYPE_FORMAT="30"
      IS_KEY="Y">Tablespace Name</COLUMN>
    <COLUMN NAME="SIZE" TYPE="NUMBER">Size</COLUMN>
    <COLUMN NAME="STATUS" TYPE="STRING" TYPE_FORMAT="10">Status</COLUMN>
    <TABLE NAME="DATAFILES">
      <UI_NAME>Datafiles</UI_NAME>
      <COLUMN NAME="FILE_NAME" TYPE="STRING" TYPE_FORMAT="1024" 
        IS_KEY="Y">File Name</COLUMN>
      <COLUMN NAME="FILE_SIZE" TYPE="NUMBER" HISTORY_IGNORE="Y">Size</COLUMN>
      <COLUMN NAME="STATUS" TYPE="STRING" TYPE_FORMAT="10">Status</COLUMN>
      <COLUMN NAME="DESC" TYPE="STRING" TYPE_FORMAT="128">Status</COLUMN>
    </TABLE>
  </TABLE>
  <TABLE NAME="TABLESPACES_1"  DATA_SOURCE="R" >
    <UI_NAME>Tablespaces_1</UI_NAME>
    <COLUMN NAME="TABLESPACE_NAME" TYPE="STRING" TYPE_FORMAT="30"
      IS_KEY="Y">Tablespace Name</COLUMN>
    <COLUMN NAME="SIZE" TYPE="NUMBER">Size</COLUMN>
    <COLUMN NAME="STATUS" TYPE="STRING" TYPE_FORMAT="10">Status</COLUMN>
    <COLUMN NAME="NOTES" TYPE="STRING" TYPE_FORMAT="128">Status</COLUMN>
    <TABLE NAME="DATAFILES_1">
      <UI_NAME>Datafiles_1</UI_NAME>
      <COLUMN NAME="FILE_NAME" TYPE="STRING" TYPE_FORMAT="1024"
        IS_KEY="Y">File Name</COLUMN>
      <COLUMN NAME="FILE_SIZE" TYPE="NUMBER" HISTORY_IGNORE="Y">Size</COLUMN>
      <COLUMN NAME="STATUS" TYPE="STRING" TYPE_FORMAT="10">Status</COLUMN>
    </TABLE>
  </TABLE>
 </METADATA>
</METADATAS>

Older Enterprise Manager releases allowed for the "DROP_EXISTING_DATA" attribute in the METADATA element, but this should be removed as it is no longer supported.

Note that if you must have non-backward compatible changes in your ECM metadata, you must create a new snapshot type (that will not be comparable with old snapshot type). ECM only supports backward compatible changes.

7.3.7 Modifications to Standard Collection Metrics and RAW Metrics

Enterprise Configuration Management data is collected by regular metrics, collections and Management Agent mechanisms. This data is collected though regular RAW metrics with the following modifications:

• Add a CONFIG=”TRUE” attribute to all Metric and CollectionItem tags that collect configuration snapshot information.

• Ensure that the CollectionItem NAME attribute is the same as the snapshot type name (for example, oracle_home_config).

• The schedule for data collections must not specify an interval that is more frequent than once per day.

Note:

Do not include ECM_SNAPSHOT_ID as a column in any RAW metric table descriptor

When ancestor key columns are included in child tables, you can populate a hierarchical set of tables one at a time, without having to express the hierarchical relationships during the collection. You should list parent tables before corresponding child tables in the Collection Item.

Example 7-6 provides a metric definition from the target type metadata XML file for the EM_ECM_OH_HOME_INFO table defined in Example 7-3. The information highlighted in bold font is provided by the configuration metadata XML file (Example 7-3).

Note:

Example 7-6 is just an example and additional nonconfiguration-specific Management Agent attributes may be required for your situation.

For more information about the target type metadata XML file, see Section 3.3, "Creating the Target Type Metadata File".

Example 7-6 Defining a Metric

    <Metric NAME="EM_ECM_OH_HOME_INFO" TYPE="RAW" CONFIG="TRUE">
        <Display>
            <Label NLSID="…">Home Info</Label>
        </Display>
        <TableDescriptor TABLE_NAME="EM_ECM_OH_HOME_INFO">
            <ColumnDescriptor NAME="HomeLocation" COLUMN_NAME="HOME_LOCATION" TYPE="S">
                <Display>
                    <Label NLSID="…">Install Location</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="OuiHomeName" COLUMN_NAME="OUI_HOME_NAME" TYPE="S">
                <Display>
                    <Label NLSID="…">OUI Home Name</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="OuiHomeGuid" COLUMN_NAME="OUI_HOME_GUID" TYPE="S">
                <Display>
                    <Label NLSID="…">OUI Home GUID</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="HomeType" COLUMN_NAME="HOME_TYPE" TYPE="S">
                <Display>
                    <Label NLSID="…">Home Type</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="HomePointer" COLUMN_NAME="HOME_POINTER" TYPE="S">
                <Display>
                    <Label NLSID="…">Home Pointer</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="IsClonable" COLUMN_NAME="IS_CLONABLE" TYPE="N">
                <Display>
                    <Label NLSID="…">Is Clonable</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="IsCrs" COLUMN_NAME="IS_CRS" TYPE="N">
                <Display>
                    <Label NLSID="…">Is CRS</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="AruId" COLUMN_NAME="ARU_ID" TYPE="N">
                <Display>
                    <Label NLSID="…">ARU ID of the Oracle Home</Label>
                </Display>
            </ColumnDescriptor>
            <ColumnDescriptor NAME="HomeSize" COLUMN_NAME="HOME_SIZE" TYPE="N">
                <Display>
                    <Label NLSID="…">Size of Oracle Home (KB)</Label>
                </Display>
            </ColumnDescriptor>
        </TableDescriptor>
        <!-- TODO : EDIT: Edit the QueryDescriptor Element Template as required -->
        <QueryDescriptor FETCHLET_ID="" AGENT_MODE="">
            <Property NAME="" SCOPE=""></Property>
        </QueryDescriptor>
    </Metric>

Example 7-7 provides a definition of the metric collection from the default collection metadata file for the metric defined in Example 7-6. The information highlighted in bold font is provided by the configuration metadata XML file (Example 7-3).

For more information about the default collection metadata file, see Section 3.5, "Creating the Default Collection File".

Example 7-7 Defining Metric Collection

<CollectionItem NAME="oracle_home_config_test" CONFIG="TRUE">
        <Schedule OFFSET_TYPE="INCREMENTAL">
          <!-- Configuration Collection is done at most once every 24 Hours -->
            <IntervalSchedule INTERVAL="24" TIME_UNIT="Hr" />
        </Schedule>
        <MetricColl NAME="EM_ECM_OH_HOME_INFO" />
        <MetricColl NAME="EM_ECM_OH_DEP_HOMES" />
        <MetricColl NAME="EM_ECM_OH_CRS_NODES" />
        <MetricColl NAME="EM_ECM_OH_CLONE_PROPS" />
        <MetricColl NAME="EM_ECM_OH_COMPONENT" />
        <MetricColl NAME="EM_ECM_OH_COMP_INST_TYPE" />
        <MetricColl NAME="EM_ECM_OH_COMP_DEP_RULE" />
    </CollectionItem>

For a plug-in, do not forget to include the metadata and default_collection XML files at both oms and agent directories within the opar file.

7.3.8 Testing the Configuration Collection Data

After integrating the configuration collection tables into the configuration management framework, you can test the configuration collection by completing the following steps:

1. Restart the Management Agent.

   AGENT_HOME/agent/bin/emctl stop agent
   AGENT_HOME/agent/bin/emctl start agent
   

   In the preceding command, AGENT_HOME represents the Management Agent home directory.

2. From Enterprise Manager Cloud Control, select Targets, then select the required target.

3. Right-click the target and select Configuration, then select Last Collected to view the most recent data collection.

4. Check that the required collected data is visible.

7.3.9 Troubleshooting

If you are having problems with your configuration collections, do the following:

1. Check that your snapshot type is registered in the MGMT_ECM_SNAPSHOT_METADATA table:

   select * from mgmt_ecm_snapshot_metadata
    where target_type   = your_target_type
      and snapshot_type = your_snapshot_type;
   

   You should see two rows. If not, check if there are any errors during registration in the regular log files for MRS in the following directory.

   $ORACLE_HOME/cfgtoollogs/pluginca
   

2. Define the corresponding metrics to verify that collections begin and data accumulates. If you are looking at the latest collection in the UI, make sure first that the UI_IGNORE flags in the metadata are not Y for the data you are checking. If the collections are not happening, then check the following:

   • Make sure that your collection item name is the same as snapshot type and CONFIG="TRUE" is specified for both the collection item and all its metrics.

     For more information, see Section 7.3.7, "Modifications to Standard Collection Metrics and RAW Metrics".

   • Make sure your metrics are defined as RAW metrics and table descriptor corresponds to your ECM tables.

   • Check if the collection arrives to the Management Repository but is not updated as "current".

     In the MGMT_ECM_GEN_SNAPSHOT table, check the is_current status for your target and snapshot type. If there are no rows, then the collection did not progress. The IS_CURRENT flag should be set to Y to indicate the latest snapshot of data. Rows with other IS_CURRENT values are possible for internal purposes. For example, if there are no rows with the Y value, then IS_CURRENT values of T and D would indicate a snapshot started loading but did not finish.

   • Check the value of META_VER in agent target type metadata and default_collection XML files.

     During development, when any new metric or collection item is added, META_VER may need to be bumped up in these files for registration of these new entries to succeed. Check the latest instructions for Enterprise Management development regarding the META_VER value.

     For example, while during your development you may need to increase the version in order to register your changes, only one increase of the version per release is required, and therefore, while merging the code, META_VER may need to be the same as before if it were already incremented for the current release.

     From a collection perspective, you have to make sure that both new target type metadata and default_collection XML files are successfully registered and that the agent is restarted with latest files. The following commands can be used to register target type metadata and default_collection XML files:

     emctl register oms metadata -service targetType -file target type XML filename [-core | -pluginId Plugin Id] [ sysman_pwd "sysman password"]
     

     emctl register oms metadata -service default_collection -file default collection XML filename [-core | -pluginId Plugin Id] [ sysman_pwd "sysman password"]
     

     Finally, for a given target instance you are testing, make sure that its META_VER matches the META_VER of the loaded snapshot type in order to see the latest collected data that is based on your latest META_VER.

   • Check the Valid-Ifs defined for the target type, snapshot type, and the metric to see if the category properties of the target instance match the Valid-Ifs. If not, the target would not show corresponding data since the configuration would not be applicable to such target.

   • On the OMS Repository, check the mgmt_system_error_log table and emoms_pbs.trc/log for the snapshot type.

     You can also examine the mgmt_metric_errors table using the following command:

     select * from mgmt_metric_errors 
     where target_guid = '<your target guid>'
       and coll_name = '<your snapshot type>'
     

     At the agent, check gcagent.log and other files in agent log directory for the same string.

   • If that does not help, turn on agent backup file feature (add backupUploadedFiles=true to emd.properties and restart the agent).

     Search for your snapshot type in the following location to ensure the agent is sending data to OMS and to see what it is sending:

     agentStateDir/sysman/emd/upload/upload/succbkup/
     

   • One potential problem you may run into relates to configuration diffing feature.

     If for some reason the configuration did not load, but the agent thinks that it has, and if the configuration does not change from that point on, the agent will keep sending short "nothing-changed" files types and the loader will keep disregarding them. To clear this issue (or just eliminate it as a potential issue while debugging), clear the agent log of config by running the following comand (no spaces around comma):

     emctl clearstate agent -incrementalconfig targetName,targetType
     

     Then, to initiate the collection, run the following command:

     emctl control agent runCollection targetName:targetType snapshot type
     

     For example:

     emctl clearstate agent -incrementalconfig myOracleHomeTargetName,oracle_home
     emctl control agent runCollection myOracleHomeTargetName:oracle_home oracle_home_config
     

3. At Oracle Management Service and the Management Repository, check the MGMT_SYSTEM_ERROR_LOG table and the emoms_pbs.trc file for the snapshot type. Also check the MGMT_METRIC_ERRORS table as follows:

   At the Management Agent, check the gcagent.log file and other files in agent log directory for the same string.

4. If you still have problems, turn on the Management Agent backup file feature:

   1. Open the emd.properties file.

   2. Add the following line to the file:

      backupUploadedFiles=true
      

   3. Restart the Management Agent.

      AGENT_HOME/agent/bin/emctl stop agent
      AGENT_HOME/agent/bin/emctl start agent
      

      In the preceding command, AGENT_HOME represents the Management Agent home directory.

   4. Search for your snapshot type in the following directory to ensure that the Management Agent is sending data to the OMS:

      agentStateDir/sysman/emd/upload/upload/succbkup/
      

5. A potential issue can arise relating to the configuration difference feature. If the configuration did not load but the Management Agent interprets that the configuration did load, (and if the configuration does not change), then the Management Agent sends short files indicating that nothing changed and the loader will continue to disregard the files.

   To clear or eliminate this potential issue, clear the Management Agent log as follows:

   emctl clearstate agent -incrementalconfig targetName,targetType
   

   For example:

   emctl clearstate agent -incrementalconfig myOracleHomeTargetName,oracle_home
   

   Then, to initiate the collection, run the following command:

   emctl control agent runCollection targetName:targetType snapshot_type
   

   For example:

   emctl control agent runCollection myOracleHomeTargetName:oracle_home oracle_home_config
   

6. From the Cloud Control console, test the history and comparison features to see how the results look or if any flags should be tweaked.

   1. From Enterprise Manager Cloud Control, select Targets, then select the required target.

   2. Right-click the target and select Configuration, then select History to view the configuration history or select Compare to test the comparison feature.

      Note:

      For more information about these pages, see the Cloud Control online help.