It contains the following sections:
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:
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.
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
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.
Vendor ID (8 chars). For example: test
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.
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 Cloud Control 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 Cloud Control 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.
The following two metadata files are required for all plug-ins deployed to Enterprise Manager Cloud Control 13c.
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.
This file declares those components included in the plug-in that are to be deployed to the Management Agent.
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>
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 |
|---|---|---|
|
|
Y |
The root element for the file. |
|
|
Y |
The unique identifier assigned to the plug-in. For more information, see Defining the Plug-in ID. |
|
|
Y |
The plug-in version. For more information, see Defining the Plug-in Version. |
|
|
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. |
|
|
Y |
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. |
|
|
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:
Valid Category values:
|
|
|
N |
Contains one or more For information about the target type metadata file, see Creating the Target Type Metadata File. Each |
|
|
N |
Describes any dependencies that exist for the plug-in. Dependencies can be described as the following:
|
|
|
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. |
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 |
|---|---|
|
|
Specifies the plug-in component. Valid values:
|
|
|
Specifies the ARU ID for the OS or platform. Valid values:
|
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>
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>
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 |
|---|---|---|
|
|
Y |
The root element for the file. It includes the following attributes:
|
|
|
N |
Contains one or more For information about target type files, see Creating the Target Type Metadata File. |
|
|
N |
Contains one or more For information about this file, see Creating the Default Collection File. |
|
|
N |
Lists the different types of artifacts (fetchlets, receivelets, and so on) packaged in the plug-in. The
|
|
|
N |
Specifies additional JAR files to be loaded by the plug-in that are shared by all the plug-in libraries |
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.
Beginning with Enterprise Manager Cloud Control Release 12c (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:
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>
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:
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.