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

A basic plug-in requires metadata for the plug-in itself, including information such as the name and version that is used by Oracle Management Service and Management Agents, definition of a metric indicating whether the monitored target is up, and definition of 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: test

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

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


    • 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 Tag must begin with a lower-case x and cannot exceed 4 characters. All characters must be lower case.

    • If you are planning to define more than one plug-in, then make sure that the Plug-in Tag for each plug-in is distinct and unique.

    • If you want to maintain the previous names of existing plug-ins, then you must use the AgentSideCompatibility element. Otherwise, plug-in validation will fail. For information about plug-in validation, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in". For information about the AgentSideCompatibility element, see Table 2-1.

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



The plug-in ID must be unique across Enterprise Manager.

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 = The version of the Enterprise Manager Extensibility Development Kit (EDK) used for development (12.1.0, 12.2.0, and so on).

  • 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 following example shows the first version of a plug-in created for Enterprise Manager Cloud Control 12c:


  • Oracle recommends that you update the plug-in version incrementally as you create and deploy each iteration of your plug-in. For example,,, and so on.
  • The first 3 parts of the plug-in version (a.b.c) must match the first 3 parts of the version number of the EDK that you used to build the plug-in. For example, if you use EDK 12.1.0.x.0, then the plug-in versions must be 12.1.0.d.0.

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.

Example 2-1 provides a sample plugin.xml for a plug-in.

Example 2-1 Sample plugin.xml

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

 <PluginId vendorId="test" productId="demo" pluginTag="xkey"/>

  <PluginVersion value=""/>

  <ShortDescription>Test plugin for the Test Demo Plug-in.</ShortDescription>
  <Readme><![CDATA[Brief details about the Test Demo plug-in]]></Readme>

    <TargetType name="test_demo_xkey" isIncluded="TRUE">
        <SupportedVersion supportLevel="Basic" minVersion=""

   <DependentPlugin pluginDependencyType="RunTime">
    <DepPluginId vendorId="test" productId="switch" pluginTag="xyz1"/>
    <BaseVersion version=""/>
   <DependentPlugin pluginDependencyType="RunTime">
    <DepPluginId vendorId="test" productId="switch" pluginTag="xyz2"/>
    <BaseVersion version=""></BaseVersion>
   </DependentPlugin>  </PluginDependencies>
  <PluginAttributes Type="MP" Category="Databases"/>

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 Description



The root element for the file.



The unique identifier assigned to the plug-in.

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



The plug-in version.

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



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



Provides information about 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.



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

    Note: Oracle recommends that you use a specific category value rather than Others.



Contains one or more TargetType elements, each specifying the target type name 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.



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

  • RunTimeMandatory: This dependency indicates that the plug-in that the current plug-in is dependent on, must exist before deploying the current plug-in. For example, Plug-in A cannot be deployed if the plug-in on which it depends does not exist. Plug-in A uses a feature from plug-in B at runtime but this feature will break if plug-in B is missing.

  • RunTime: This dependency indicates that the deployment of the current plug-in with feature dependencies can go ahead without the plug-in that it is dependent on. If the plug-in that the current plug-in is dependent on comes into the environment later, then dependent features will be enabled. Along with dependencies, you can also describe the prerequisites. Currently the supported prerequisite is of type bug.

  • CompileTime: This dependency indicates that the dependent plug-in should exist before deployment of the current plug-in, that is, if the current plug-in explicitly consumes an API from a dependent plug-in and has a build-time dependency.



Identifies the previous plug-in versions with which the current plug-in is compatible.

By specifying this element, you indicate explicitly that the previous plug-in metadata on the Management Agent side is compatible with the new version of plug-in metadata on the OMS side. That is, after upgrading the previous plug-in, you can upload data to the new version on OMS without breaking any features, such as metrics, thresholds or configuration collections.

If you have a previous version of a plug-in that is not compatible with the new version of the plug-in, then you can use this element to list the compatible versions only. For example, if version is not compatible with (new plug-in version), then you can list and to indicate that only and plug-ins are compatible with the new plug-in.

2.4.2 Certifying Plug-ins


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.


The Management Agent and Discovery components must have the same value

Example 2-2 Certifying Generic Plug-ins

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

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="test.demo.xkey" Description="Demo Sample Host Plugin" Version="" HotPluggable="false"
    xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/plugin plugin.xsd">
        <FileLocation>metadata/test_switch_key.xml</FileLocation>  </TargetTypes>
      <Fetchlet ID="DMS" ExecutionClass="oracle.sysman.as.fetchlets.DMSFetchlet" Version="" Description="" Adapter=""/>

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 Description



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



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



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



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.



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 (, 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:


  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_

2.8 Defining Plug-ins for Upgrade

During plug-in development, if you are planning a subsequent version of your plug-in, you must ensure that the plug-in can be upgraded, that is, you can deploy a new version without having to remove an older version of the plug-in.

To ensure that your plug-in can be upgraded:

  1. In the new plug-in.xml file, include the AgentSideCompatibility tag explicitly specifying the compatible previous versions of the plug-in.

    For more information about the AgentSideCompatibility tag, see Table 2-1.


    • Oracle recommends that you include at least the two previous versions.
    • If the previous plug-in metadata is not compatible with the new version, then you might see metrics and collection errors after upgrading. Oracle recommends that you list the compatible versions of the plug-in under the AgentSideCompatibility element to avoid issues with upgrading your plug-in.

  2. When you specify previous plug-in versions under the AgentSideCompatibility element, you must bundle the OPARs of these plug-in versions in the plug-in staging directory.

    Under the plug-in staging directory (plugin_stage), create a released_plugins directory and place the previously released plug-in OPAR archive (for example, in this directory.

    For more information about the plug-in staging directory, see Section 14.2, "Staging the Plug-in".

  3. Perform upgrade testing from all previous versions of the plug-in to ensure that all features are working correctly such as:

    • Verify metric collections

    • Verify configuration collections

    • Check that there are no metric collection errors due to the upgrade

    • Check that updated metric thresholds and templates are picked up as expected

    • Check that updated job metadata is picked up as expected