This chapter 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 Section 2.2.1, "Defining the Plug-in ID".
Define the plug-in version.
For more information, see Section 2.2.2, "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 Section 2.4, "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 Section 2.5, "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 Chapter 14, "Validating, Packaging, and Deploying the Plug-in".
Validate the plug-in definition files.
For more information, see Section 2.6, "Validating the 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.
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
Plug-in Tag (4 chars). For example: xkey.
Note:
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:
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.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:
12.1.0.1.0
Note:
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.
Two new metadata files are required for all plug-ins deployed to Enterprise Manager Cloud Control 12c.
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.
Example 2-1 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="12.1.0.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 Section 2.2.1, "Defining the Plug-in ID". |
|
|
Y |
The plug-in version. For more information, see Section 2.2.2, "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 Section 2.4.2, "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 Section 3.3, "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.1.0 is not compatible with 12.1.0.4.0 (new plug-in version), then you can list 12.1.0.2.0 and 12.1.0.3.0 to indicate that only 12.1.0.2.0 and 12.1.0.3.0 plug-ins are compatible with the new 12.1.0.4 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.
| Tag | Description |
|---|---|
|
|
Specifies the plug-in component. Valid values:
|
|
|
Specifies the ARU ID for the OS or platform. Valid values:
|
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 valueExample 2-2 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.
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="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/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 Section 3.3, "Creating the Target Type Metadata File". |
|
|
N |
Contains one or more For information about this file, see Section 3.5, "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 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".
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:
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.
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>
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:
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 Section 14.2, "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