Skip Headers
Oracle® Enterprise Manager Cloud Control Extensibility Programmer's Reference
12c Release 4 (12.1.0.4)

E25161-15
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Defining the Plug-in

This chapter contains the following sections:

2.1 Introduction to Defining the Plug-in

As a plug-in developer, you are responsible for the following steps within the plug-in definition process:

  1. Define the plug-in identifier (ID).

    For more information, see Section 2.2.1, "Defining the Plug-in ID".

  2. Define the plug-in version.

    For more information, see Section 2.2.2, "Defining the Plug-in Version".

  3. Create the plug-in definition files:

    1. Create the plugin.xml file.

      The plugin.xml file provides the metadata describing the plug-in.

      For more information, see Section 2.4, "Creating the plugin.xml File".

    2. Create the plugin_registry.xml file.

      The plugin_registry.xml file provides the metadata required by the Management Agent to which the plug-in will be deployed.

      For more information, see Section 2.5, "Creating the plugin_registry.xml File".

  4. Package the plug-in definition files in the plug-in staging directory (plugin_stage):

    • plugin_stage/plugin.xml

    • plugin_stage/agent/plugin_registry.xml

    For more information, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".

  5. Validate the plug-in definition files.

    For more information, see Section 2.6, "Validating the Plug-in Definition Files"

2.2 Basic Plug-in Metadata

The most basic plug-in requires metadata for the plug-in itself, including basic information such as name and version that is used by Oracle Management Service and Management Agents; definition of a basic metric indicating whether the target being monitored is up or down; and specifying the frequency at which metric data should be collected.

2.2.1 Defining the Plug-in ID

Plug-ins are identified by a unique plug-in identifier (ID). The plug-in ID has three parts:

  • Vendor ID (8 chars). For example: acme

  • Product ID (8 chars). For example: switch

  • Plug-in Tag (4 chars). For example: xkey.

    Note:

    The Vendor ID, Product ID, and Plug-in Tag must not begin with a number or include any special characters. All these parts must contain alphanumeric characters only.

The Plug-in ID created from the previous example would be:

acme.switch.xkey

Note:

  • The plug-in ID must be unique across Enterprise Manager.
  • If you are developing a plug-in within Oracle, contact Enterprise Manager Release Management to get the plug-in ID.

2.2.2 Defining the Plug-in Version

Each plug-in must be assigned a version. The plug-in versioning syntax is as follows:

a.b.c.d.e

  • a.b = The version of the Enterprise Manager Extensibility Development Kit (EDK) used for development (12.1, 12.2, and so on).

  • c = This value is always 0

  • d = The developer-assigned plug-in version. This value must be incremented with each plug-in release on the same Enterprise Manager Cloud Control release.

  • e = for future use. The default value is 0.

Putting it all together, the first version of a plug-in created for Enterprise Manager Cloud Control is:

12.1.0.1.0

Note:

As a best practice, you should update the plug-in version incrementally as you create and deploy each iteration of your plug-in. For example: 12.1.0.1.0, 12.1.0.2.0, and so on.

2.3 Creating Plug-in Definition Files

Two new metadata files are required for all plug-ins deployed to Enterprise Manager Cloud Control 12c.

  • plugin.xml

    This file is used during plug-in deployment. It contains properties that identify the plug-in, such as name and version, and declares the set of target types that will be added to Enterprise Manager Cloud Control.

  • plugin-registry.xml

    This file declares those components included in the plug-in that are to be deployed to the Management Agent.

2.4 Creating the plugin.xml File

The plugin.xml file provides the metadata describing the plug-in.

The following sections describe the required and some of the optional tags that you can include in the plugin.xml file. The TargetTypeList element contains a TargetType element, which in turn contains a reference to the target type metadata file location in the plug-in archive.

Example 2-1 provides a sample plugin.xml for a plug-in with basic features:

Example 2-1 Sample plugin.xml

<?xml version = '1.0' encoding = 'UTF-8'?>
<Plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/plugin_
        metadata plugin_metadata.xsd"
        xmlns="http://www.oracle.com/EnterpriseGridControl/plugin_metadata/">

 <PluginId vendorId="acme" productId="demo" pluginTag="hostsample"/>

  <PluginVersion value="12.1.0.1.0"/>

  <PluginOMSOSAruId value="2000">
  </PluginOMSOSAruId>

  <ShortDescription>Test plugin for the Acme Demo Plug-in.</ShortDescription>
  <Readme><![CDATA[Acme Demo plug-in]]></Readme>
  <AgentSideCompatibility>
     <Version>12.1.0.1.0</Version>
  </AgentSideCompatibility>

  <TargetTypeList>
    <TargetType name="acme_demo_hostsample.xml" isIncluded="TRUE">
       <VersionSupport>
        <SupportedVersion supportLevel="Basic" minVersion="9.2.0.1"
                          maxVersion="9.8.0.0.0"/>
        <NonSupportedVersion minVersion="9.1.0.0"/>
      </VersionSupport>
    </TargetType>
  </TargetTypeList>

  <PluginDependencies>
   <DependentPlugin pluginDependencyType="RunTime">
    <DepPluginId vendorId="acme" productId="switch" pluginTag="type3"/>
    <BaseVersion version="11.2.0.1.0"/>
   </DependentPlugin>
   <DependentPlugin pluginDependencyType="RunTime">
    <DepPluginId vendorId="acme" productId="switch" pluginTag="type4"/>
    <BaseVersion version="11.2.0.1.0"></BaseVersion>
   </DependentPlugin>  </PluginDependencies>
  <PluginAttributes Type="MP" Category="Others"/>
</Plugin>

2.4.1 Overview of plugin.xml Elements

Table 2-1 describes the key elements included within the plugin.xml files.

Table 2-1 Key Elements Within the plugin.xml File

Element Required Y/N Description

Plugin

Y

The root element for the file.

PluginID

Y

The unique identifier assigned to the plug-in.

For more information, see Section 2.2.1, "Defining the Plug-in ID".

PluginVersion

Y

The plug-in version.

For more information, see Section 2.2.2, "Defining the Plug-in Version".

PluginOMSOSAruId

Y

The operating system (OS) ID for the Oracle Management Service to which the plug-in will be deployed. Usually, this element is set to 2000 (generic).

For more information, see Section 2.4.2, "Certifying Plug-ins".

Readme

Y

Provides the name of the plug-in that is displayed on the Plug-ins page of the Cloud Control console.

To access the Plug-ins page, from the Setup menu, select Extensibility, then Self Update, and then Plug-ins.

PluginAttributes

N

Defines plug-in attributes such as plug-in type, display name, category, and so on.

The default Plug-in Type for metadata plug-ins is ”MP”. The default Category is ”Others”.

Valid Type values:

  • MP

    Metadata plug-in with default UI

  • MPP

    Metadata plug-in with custom UI

Valid Category values:

  • Applications

  • Databases

  • Middleware

  • Cloud

  • Engineered Systems

  • Servers, Storage and Network

  • Others

TargetTypeList

N

Contains one or more TargetType elements, each specifying the path and file name for a target type metadata file packaged with the plug-in.

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

Each TargetType element can also include a VersionSupport element identifying supported or non-supported versions of the target type.

PluginDependencies

N

Describes any dependencies that exist for the plug-in. Dependencies can be described as the following:

  • CompileTime: This dependency indicates that the dependent plug-in should exist prior to deployment of current plug-in.

  • RunTime: This dependency indicates the feature dependencies and deployment of current plug-in can go ahead without the dependent plug-in. Along with dependencies one can also describe the prerequisites. Currently supported prerequisite is of type bug.

AgentSideCompatibility

N

Identifies the Management Agent version with which the plug-in can communicate.


2.4.2 Certifying Plug-ins

Note:

All metadata plug-ins must be generic on the OMS side and are implicitly certified on all platforms. However, the plug-in can specify the OS certification for the Management Agent.

Because Enterprise Manager is released on a number of OS platforms, you must consider how your plug-in will behave on different OS platforms. The plugin.xml file contains elements and attributes that support a certification mechanism.

In cases, where the plug-in is applicable to only a subset of OS platforms, you can use the tags defined in Table 2-2. If you do not specify any information in the <Certification> section, the plug-in is assumed certified on all platforms.

Table 2-2 Certification Tags

Tag Description

Component type

Specifies the plug-in component.

Valid values:

  • Agent: Management Agent component

  • Discovery: Discovery component

PortARUId value

Specifies the ARU ID for the OS or platform.

Valid values:

  • 46: Linux x86 (32-bit)

  • 212: AIX 5L and 6.1 (64-bit)

  • 226: Linux x86-64 (64-bit)

  • 23: Solaris Sparc (64-bit)

  • 267: Solaris x86-64 (64-bit)

  • 233: Microsoft Windows x86-64 (64-bit)


Example 2-2 indicates that the plug-in is designed to work on Linux 32 and Linux 64 platforms only. If you do not specify a certified port, then by default your plug-in is certified on all operating systems and platforms. But if you specify at least one PortARUId element, then that component is certified on those specified platforms only.

Note:

The Management Agent and Discovery components must have the same value

Example 2-2 Certifying Generic Plug-ins

<PluginOMSOSAruId value="2000">
</PluginOMSOSAruId>

<Certification>
  <Component type="Agent">
        <CertifiedPorts>
              <PortARUId value="46" />
              <PortARUId value="226" />
        </CertifiedPorts>
  </Component>
  <Component type="Discovery">
        <CertifiedPorts>
              <PortARUId value="46" />
              <PortARUId value="226" />
        </CertifiedPorts>
  </Component>
</Certification>
  

2.5 Creating the plugin_registry.xml File

The plugin_registry.xml file provides the metadata required by the Management Agent that the plug-in will be deployed to. It is packaged in the /agent directory within the plug-in archive and is deployed to the Management Agent that will monitor a target.

Example 2-3 provides a sample plugin_registry.xml file. The TargetTypes element contains a reference to the target type metadata file location in the plug-in archive. The location is relative to the plugin_stage directory root, that is, starting from the Management Agent subdirectory or the same location where the plugin_registry.xml file is located.

Similarly, the TargetCollections element contains a reference to the plug-in's default collection metadata file, which is also packaged with the plug-in.

Example 2-3 Sample plugin_registry.xml File

<?xml version="1.0"?>
<PlugIn ID="acme.demo.hostsample" Description="Demo Sample Host Plugin" Version="12.1.0.1.0" HotPluggable="false"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/plugin plugin.xsd">
  <TargetTypes>
        <FileLocation>metadata/acme_switch_key.xml</FileLocation>  </TargetTypes>
  <TargetCollections>
       <FileLocation>default_collection/acme_switch_key_collection.xml</FileLocation>
  </TargetCollections>
  <PlugInLibrary>
    <FileLocation>archives/em-as-fmw-fetchlet.jar</FileLocation>
    <FetchletRegistration>
      <Fetchlet ID="DMS" ExecutionClass="oracle.sysman.as.fetchlets.DMSFetchlet" Version="" Description="" Adapter=""/>
    </FetchletRegistration>
    <AdditionalClassPath>
      <FileLocation>archives/dms.jar</FileLocation>
    </AdditionalClassPath>
  </PlugInLibrary>
</PlugIn>

2.5.1 Overview of plugin_registry.xml Elements

Table 2-3 describes the key elements included within the file.

Table 2-3 Key Elements Within the plugin_registry.xml File

Element Required (Y/N) Description

Plugin

Y

The root element for the file. It includes the following attributes:

TargetTypes

N

Contains one or more FileLocation elements, each specifying the path and file name for a target type metadata file packaged with the plug-in.

For information about target type files, see Section 3.3, "Creating the Target Type Metadata File".

TargetCollections

N

Contains one or more FileLocation elements, each specifying the default collection for a target type.

For information about this file, see Section 3.5, "Creating the Default Collection File".

PlugInLibrary

N

Lists the different types of artifacts (fetchlets, receivelets, and so on) packaged in the plug-in.

The PlugInLibrary element includes the following subelements:

  • FileLocation: Mandatory. Defines the location of the JAR containing the implementations of the following listed fetchlets.

  • FetchletRegistration: Optional. Creates an entry that maps a fetchlet id (DMS in Example 2-3) to the class that contains the implementation of the fetchlet interface.

  • ReceiveletRegistration: Optional. Creates an entry that maps a receivelet id to the class that contains the implementation of the receivelet interface

  • AdditionalClassPath: Optional. Specifies additional JAR files to be loaded by the plug-in for a specific library.

AdditionalClassPath

N

Specifies additional JAR files to be loaded by the plug-in that are shared by all the plug-in libraries


2.6 Validating the Plug-in Definition Files

To verify that your plugin.xml and plugin_registry.xml files are defined correctly, enter the following command from the /bin directory of the EDK:

empdk validate_plugin -stage_dir plugin_stage

In the preceding command, plugin_stage represents the plug-in staging directory.

For information about the EDK, see Section 1.2, "About the Extensibility Development Kit (EDK)" and for more information about the empdk command and its usage, see Section 14.3, "Validating the Plug-in".

2.7 Adding Log Viewer Support to Your Plug-in

Beginning with Enterprise Manager Cloud Control Release 2 (12.1.0.3), you can enable log files for your deployed plug-in to be viewable with Cloud Control's Log Viewer. To access this component, from the Cloud Control Enterprise menu, select Monitoring, then Logs.

Follow these steps to enable this feature:

  1. Create the log viewer registration XML file for your plug-in. The DTD for this XML file is:

    oracle/sysman/emSDK/logmgmt/registration/LogMgmtTargetTypeRegistration.xsd

  2. Package this file in oms/metadata/logmgmt/ within the plug-in directory structure.

Example 2-4 provides an example of a log viewer registration file.

Example 2-4 Sample Log Viewer Registration File

<LogMgmtUITargetConfig TARGET_TYPE="%your targe type%">
  <LogViewerImpl CLASS_NAME="oracle.sysman.emas.model.logmgmt.MASLogViewer"/>
  <VersionProperties VALID_VERSIONS="11" MIN_META_VER="11.00000"VERSION_
   CATEGORY_PROP_WILDCARD_CHAR="*"/>
</LogMgmtUITargetConfig>