Defining the Plug-in

Introduction to Defining the Plug-in

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

Define the plug-in identifier (ID).

For more information, see Defining the Plug-in ID.
Define the plug-in version.

For more information, see Defining the Plug-in Version.
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 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 Creating the plugin_registry.xml File.
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 Validating, Packaging, and Deploying the Plug-in.
Validate the plug-in definition files.

For more information, see Validating Plug-in Definition Files

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

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

test.switch.xkey

Note:

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

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 (13.1, 13.2, and so on).
c = The developer-assigned plug-in version. This value must be incremented with each plug-in release on the same Enterprise Manager release.
d = Indicates whether the plug-in is a beta version or a production version. 0 indicates beta and 1 or later indicates production.
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 13c:

13.1.1.1.0

Note:

Oracle recommends that you update the plug-in version incrementally as you create and deploy each iteration of your plug-in. For example, 13.1.1.1.0, 13.1.2.1.0, 13.1.3.1.0, and so on.

Creating Plug-in Definition Files

The following two metadata files are required for all plug-ins deployed to Enterprise Manager.

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.
plugin-registry.xml

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

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.

This example provides a sample plugin.xml for a plug-in.

<?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="test" productId="demo" pluginTag="xkey"/>

  <PluginVersion value="13.1.1.1.0"/>

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

  <TargetTypeList>
    <TargetType name="test_demo_xkey" isIncluded="TRUE">
       <VersionSupport>
        <SupportedVersion supportLevel="Basic" minVersion="9.2.0.1"
                          maxVersion="9.8.0.0.0"/>
      </VersionSupport>
    </TargetType>
  </TargetTypeList>

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

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
`Plugin`	Y	The root element for the file.
`PluginID`	Y	The unique identifier assigned to the plug-in. For more information, see Defining the Plug-in ID.
`PluginVersion`	Y	The plug-in version. For more information, see Defining the Plug-in Version.
`PluginOMSOSAruId`	N	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 Certifying Plug-ins.
`Readme`	Y	Provides information about the plug-in that is displayed on the Plug-ins page of the Enterprise Manager 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 Note: Oracle recommends that you use a specific category value rather than Others.
`TargetTypeList`	N	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 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: `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.
`AgentSideCompatibility`	N	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 12.1.0.2.0 is not compatible with 13.1.1.1.0 (new plug-in version), then you can list 12.1.0.3.0 and 12.1.0.4.0 to indicate that only 12.1.0.3.0 and 12.1.0.4.0 plug-ins are compatible with the new 13.1.1.1.0 plug-in.

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

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)

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)

The following example 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: Certifying Generic Plug-ins

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

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.

The following example 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: Sample plugin_registry.xml File

<?xml version="1.0"?>
<PlugIn ID="test.demo.xkey" Description="Demo Sample Host Plugin" Version="13.1.1.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/test_switch_key.xml</FileLocation>  </TargetTypes>
  <TargetCollections>
       <FileLocation>default_collection/test_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>

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
`Plugin`	Y	The root element for the file. It includes the following attributes: ID: Required. The unique identifier assigned to the plug-in. For more information, see Defining the Plug-in ID. Description: Optional. A title describing the plug-in. Version: Required. The plug-in version. For more information, see Defining the Plug-in Version.
`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 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 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 the Sample plugin_registry.xml File example) 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

Validating 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 About the Extensibility Development Kit (EDK) and for more information about the empdk command and its usage, see Validating the Plug-in.

Adding Log Viewer Support to Your Plug-in

You can enable log files for your deployed plug-in to be viewable with Enterprise Manager's Log Viewer. To access this component, from the Enterprise Manager Enterprise menu, select Monitoring, then Logs.

Follow these steps to enable this feature:

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
Package this file in oms/metadata/logmgmt/ within the plug-in directory structure.

The following example provides an example of a log viewer registration file.

Example: 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>

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:

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.
Note:
- 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.
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, 12.1.0.2.0_test.demo.xkey_2000_0.opar) in this directory.

For more information about the plug-in staging directory, see Staging the Plug-in.
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

Deprecating a Plug-in

To mark your plug-in for deprecation, add the following line to your plugin.xml file:

<Deprecated />

For example:

<?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="test" productId="demo" pluginTag="xkey"/>

  <PluginVersion value="12.1.0.1.0"/>

  <Deprecated/>

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

Note:

When a plug-in is marked as deprecated, it continues to provide the same level of support until it is obsolete in the next major release.