2 Getting Started With Enterprise Manager Plug-ins
This chapter provides an introduction to Enterprise Manager metadata plug-ins and the Extensibility Development Kit (EDK).
This chapter contains the following sections:
What is a Plug-in?
A plug-in is a group of files (such as target definition files, collection scripts to collect metrics from targets, and any custom UI components to customize user interfaces) that has been added to a plug-in archive using the Enterprise Manager Extensibility Development Kit (EDK). The plug-in files must be added to an archive before they become a plug-in officially. A plug-in archive file (*.opar) associates the files together as an official plug-in.
Each plug-in defines a new type or types of target that can be monitored by Enterprise Manager. A target, or more specifically, a target instance, can be defined as any entity that can be monitored within an enterprise. This entity can be an application running on a server, the server itself, the network, or any of its constituent parts.
Enterprise Manager makes managing target instances simple by enabling you to add new target instances to the management framework from the Enterprise Manager console. Then you can take advantage of Enterprise Manager's monitoring and administrative features.
A plug-in consists of several types of files that serve specific functions at different tiers within the Enterprise Manager framework. For example, the target type metadata file is an integral part of defining a new target type. The EDK requires the target type metadata file, in addition to a default collection file, to create a new plug-in within the plug-in archive.
To create a new plug-in, you must have the following (minimum requirement):
When you use plug-ins to define custom target types for monitoring by Enterprise Manager, you can centralize all of your management information in the console.
When you introduce a new target type to Cloud Control, the management features included in Enterprise Manager are automatically supported for the new targets by default. This includes core management features such as:
You can also choose to enable additional management features for your target types by using application programming interfaces (APIs) supported by the EDK. These features include:
Each of these management features requires additional metadata files, and possibly the creation of scripts, that must be packaged with the plug-in.
What's New in Enterprise Manager Plug-ins?
This section describes the new features of Enterprise Manager plug-ins:
-
Plug-in Deprecation and Obsolescence
This release provides an EDK to support the development of custom plug-ins for managing target types not supported out of the box.
About the Extensibility Development Kit (EDK)
A key component of the Enterprise Manager Cloud Control architecture is the Extensibility framework. To enable Oracle partners to extend the Enterprise Manager platform, an Extensibility Development Kit (EDK) is provided with the product.
The EDK is a collection of tools, utilities, and documentation, including:
-
Enterprise Manager Extensibility documentation: Provides general guidelines for programming Enterprise Manager plug-ins
-
Reference Implementation: Provides a reference code implementation, code snippets, and so on for various Enterprise Manager features
-
Build time tools to verify EDK conformance: A tool that you can use to validate and report any violations, with respect to Enterprise Manager Extensibility guidelines
-
Packaging Tool: A tool to package the plug-in components tool (
empdk) -
Verification Tool: A tool to validate plug-in code components and to report violations (if any).
The EDK includes a command line utility called empdk. Use this utility to package or validate a plug-in archive. For information about the empdk commands and their options, see the Oracle Enterprise Manager Extensibility Programmer's Reference.
After you download the EDK, unpackage it on your local system, and change your current directory to the location where you unpacked the EDK. The EDK contains reference documentation and guides to help you with plug-in development as well as the API reference you might need to integrate while developing plug-ins.
For information about downloading the EDK, see Installing the Extensibility Development Kit (EDK).
Contents of the EDK
The EDK archive contains the following directories:
-
\bin
Contains the
empdkutility, which you use to:-
Validate the structure of your plug-in
-
Package your plug-in
-
-
\doc
Contains the Oracle Enterprise Manager Extensibility Programmer's Guide and Programmer's Reference, as well as the EDK API Reference documentation, including documentation on Management Views. Review overview.html for links to the documentation provided.
You can also access the EDK API Reference documentation directly through its index page (sdk_api_ref.html).
-
\lib
Contains internal libraries used by the EDK.
-
\oui
Contains internal libraries used by the EDK.
-
\samples
Contains a complete reference implementation of a plug-in, packaged as demo_hostsample.zip. The sample metadata files included should be used as examples of the files referenced throughout the EDK documentation.
View the README packaged with the archive for instructions on building, deploying, and using the sample plug-in.
Other utilities referenced in this documentation, including EM CLI and EMCTL, are installed with Enterprise Manager and are typically deployed to the Oracle Management Service (OMS) host.
Installing the Extensibility Development Kit (EDK)
Note:
Before installing the EDK, you must have the following:
-
Latest version of the EDK ZIP archive from the Self Update console. (To access the Self Update console, from the Cloud Control console, select Setup, then Extensibility, and then Self Update.)
-
Java version 1.7.0_51 or later
-
Local system running Solaris, Linux, HP-UX, AIX, or Windows with New Technology File System (NTFS)
To install the EDK:
-
Download the EDK ZIP archive to your local system using one of the following options:
-
Using the Enterprise Manager Cloud Control console
-
Log in to Enterprise Manager Cloud Control.
-
From the Setup menu, select Extensibility, then select Development Kit.
The Extensibility Development Kit (EDK) page appears.
-
Under Installing the EDK, select Download the Extensibility Development Kit to your workstation.
-
Save 13.1.0.0.0_edk_partner.zip to your local system.
-
-
Using the Enterprise Manager Command Line Utility (EM CLI), open a command prompt and run the following command:
emcli get_ext_dev_kit
This command downloads the EDK ZIP archive to the same directory from where you ran the command and does not require any parameters.
Note:
For information about setting up EM CLI, see the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.
-
-
Set your JAVA_HOME environment variable and ensure that it is part of your PATH. For example:
setenv JAVA_HOME /usr/local/packages/j2sdk1.7.0_51 setenv PATH $JAVA_HOME/bin:$PATH
-
Unpackage the downloaded EDK ZIP archive to a directory on your local system. For example:
Unzip 13.1.0.0.0_edk_partner.zip
This command creates the following directories under the directory (release_edk_partner) where you unpackaged the EDK ZIP archive:
release_edk_partner | bin doc lib oui samples READMEFor more information about the directory contents, see Contents of the EDK.
Plug-in Development Lifecycle
Developing a plug-in involves:
-
Designing the set of entities to be included in the plug-in
-
Defining the metadata that describes them to Enterprise Manager
-
Packaging and delivering the plug-in so that users can deploy and use it in Enterprise Manager installations
Figure 2-1 depicts the lifecycle of a plug-in.
The plug-in lifecycle represents the transition of a plug-in through the following stages:
-
Publish: Publishes the plug-in at the Oracle Enterprise Manager Store
-
Download: Enterprise Manager downloads plug-ins from Oracle Enterprise Manager Store
-
Deploy: Deploys the plug-in to Oracle Management Service (OMS) and Management Agents
-
Upgrade: Upgrades the plug-in to a later version (download and deploy)
Designing Your Plug-in Metadata
The first step in developing your plug-in is to design the contents of your plug-in. At the highest level, this includes deciding what set of target types will be included in the plug-in (a plug-in may include management metadata for one or more target types) and defining what set of management capabilities you want to support for each target type. (The complete available list is included in Plug-in Contents and Packaging).
Before creating plug-in files, you must define which parameters of the target type are required to monitor and manage your new component accurately. This involves:
-
Identifying performance and configuration metrics that should be collected.
-
Determining how often each metric should be collected. Oracle recommends that the collection frequency for any metric should not be less than once every five minutes.
-
Based on customer-specific operational practices, specifying default warnings and/or critical thresholds. Whenever a threshold is crossed, Enterprise Manager raises an incident, informing administrators of potential problems.
These metrics and collection settings are the required components of every plug-in. Additional capabilities such as job definitions, custom User Interface, and so on, are optional. Each feature to be included in the plug-in requires additional thought and design to determine what aspects of the target should be manageable for those features.
Some of the key features to consider when designing your plug-in include the following:
-
Administrative features that are necessary to manage the target, such as administrative tasks or larger, and more complex jobs that may require automation support (for example, scheduling)
-
Configuration data to be used for managing the target including associations between the target and other targets in network
-
Reports and customized user interfaces to be provided for end-users to manage the targets
This is not a complete list and the information for integrating with each subsystem is summarized in this guide and provided in detail in the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.
Plug-in Contents and Packaging
The plug-in contents and packaging section includes the following topics:
Plug-in Metadata
Each plug-in includes the plug-in metadata, which is defined in XML files that represent all the information about a plug-in.
Plug-in metadata 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.
Metadata Services
Most of the Enterprise Manager features exposed to you through the Enterprise Manager EDK require the construction of metadata files (in XML). These metadata files define the items that are integrated for that target type for the particular subsystem. For example, a plug-in might contain a metadata XML file that defines the job types that are available for that target type. After deployment, the jobs will be available to be submitted or executed for any instance of that target type.
Target type metadata consists of the metrics you want to expose and the methods used to retrieve and compute those metrics. The target type metadata file tells the Oracle Management Agent what data to retrieve and how to obtain that data for this particular target type.
In addition to the metrics to be collected for the target type, the target type metadata includes the target properties and credentials information. The target properties are the key set of properties that help to define the target. These properties are typically static though Enterprise Manager does support the ability to define dynamic instance properties that are evaluated by the Management Agent. For information about defining dynamic instance properties, refer to the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.
The plug-in includes a default collections file, which defines the frequency at which metrics and configuration data will be collected
The Enterprise Manager Extensibility Framework provides the support for packaging these metadata files in the EDK as well as for deploying these files to the appropriate subsystem within Enterprise Manager. This may include deploying information to the Management Server, or to the Management Agent, or both in some cases. For more information about packaging metadata files in the EDK, see Plug-in Packaging Structure.
In certain instances, the metadata includes references to other components packaged with the plug-in. For example, a job type definition might include a step that executes a Perl script against one of the targets to perform an administrative task. In this case, the job type definition is declared in the metadata and included in the Management Server part of the plug-in while the script is included in the Management Agent part of the plug-in.
For a complete list of all metadata services available and the detailed documentation describing the use of each service, see the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.
Plug-in Packaging Structure
The final step in developing a plug-in is to package it into a plug-in archive. This step takes a staging directory (plugin_stage) as input where the files that comprise the plug-in are located. Example 2-1 summarizes the directory structure and the location for the files.
For information about the contents of the plug-in directory, see the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.
Example 2-1 Plug-in Directory Structure
plugin_stage/ | plugin.xml agent/ | plugin_registry.xml default_collection/ |target_type.xml metadata/ |target_type.xml scripts/ |scriptsoms/ | metadata/ | default_collection/ |target_type.xml derivedAssoc/ |derivedAssoc_rule.xml discovery/ |discovery.xml gccompliance/ |compliance_rule.xml jobTypes/ |job_type.xml mpcui/ |mpcui.xml reports/ |report.xml snapshotlive/ |target-type_ecmdef.xml targetType/ |target_type.xml discovery/ |discovery scripts
Releasing a Plug-in
After you have packaged the plug-in, you can distribute the plug-in archive (OPAR) file to the Enterprise Manager administrators that require support for the target types included in that plug-in. In this mode, Oracle does not certify the quality or safety of the plug-in for use in a production environment and appropriate evaluation in a test environment is strongly encouraged before deploying a plug-in that is not certified by Oracle.
To make the plug-in available for deployment, the Enterprise Manager administrator must import the plug-in archive into the Enterprise Manager installation. After this is complete, the plug-in will be available to be deployed in the same way as any other plug-in downloaded from Oracle. For information the plug-in import command, see the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.
Deploying a Plug-in
After a plug-in has been imported into Enterprise Manager, the Enterprise Manager administrator must explicitly deploy the plug-in to the Management server and to the appropriate Management Agents.
Plug-in deployment can be accomplished through the Enterprise Manager command line facility (EM CLI) or by selecting Extensibility from the Setup menu in the Enterprise Manager console. For information about the use of these options, see the Oracle Enterprise Manager Cloud Control Extensibility Reference Guide.
Automated Deployment During Discovery
If a plug-in includes support for automated discovery, Enterprise Manager deploys the plug-in to the appropriate Management Agent automatically as targets are discovered and marked as manageable targets (promoted) in Enterprise Manager. To enable automated discovery, you must include the appropriate discovery metadata in the plug-in.
For plug-ins that do not include support for the automated discovery of targets, the Enterprise Manager administrator must add targets to the Enterprise Manager console manually, specifying the Management Agents where the targets are located. In this case, the Enterprise Manager administrator must deploy the plug-in to those Management Agents before manually adding the target.
Plug-in Upgrade
As new versions of a plug-in are released, the Enterprise Manager administrator can import the new plug-in by using the self-update feature of Enterprise Manager to download the new version from the Oracle Store, or by importing the new plug-in archive if it is a private distribution.
At this point, the new plug-in version is available in Enterprise Manager but not deployed to any of the Management Servers or Agents. The Enterprise Manager administrator must explicitly deploy the new plug-in version using the same process for deployment described in Deploying a Plug-in.
Deprecating a Plug-in
Due to various business and technical reasons, sometimes released plug-ins must declare end-of-life and support for these plug-ins discontinues going forward.
When you deprecate a plug-in, you are announcing the end of life of the plug-in in advance and support will discontinue from the next major Enterprise Manager platform release. When support discontinues in the next major release, the plug-in becomes obsolete.
For example, if you deprecate a plug-in in Release 13.1.0.0, then the deprecated plug-in will have the same level of support in Release 13.1.0.1. It will not become obsolete until the next major release, such as Release 14.1. For information about deprecating plug-ins, see the "Deprecating a Plug-in" section in the Enterprise Manager Cloud Control Extensibility Programmer's Reference.
Note:
You cannot make a plug-in obsolete directly. You must mark it as deprecated in an earlier patchset release.