Skip Headers
Oracle® Enterprise Manager Cloud Control Extensibility Programmer's Guide
12c Release 4 (12.1.0.4)

E25159-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Getting Started With Enterprise Manager Plug-ins

This chapter contains the following sections:

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

  • Plug-in metadata

  • Target-type metadata

  • Default collection metadata

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:

  • Metric Collection and Alerts

  • Availability and Blackouts

  • Groups and Systems

  • Default System Reports

  • Other Common Console Features

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:

  • Automated Discovery

  • Target-to-Target Associations

  • Configuration Management

  • Custom Target Credentials

  • Automation (or Jobs)

  • Custom Reports

  • Compliance Rules and Standards

  • Custom User Interface for Management

Each of these management features requires additional metadata files, and possibly the creation of scripts, that must be packaged with the plug-in.

2.2 What's New in Enterprise Manager Plug-ins?

This section describes the new features of Enterprise Manager plug-ins:

  • Extensibility Development Kit (EDK)

    This release provides an EDK to support the development of custom plug-ins for managing target types not supported out of the box.

  • Plug-in and Connector Lifecycle Management

    The Self Update feature provides a user-friendly mechanism for downloading and deploying metadata plug-ins and connectors. A console for managing the lifecycle of plug-ins has also been provided, enabling standardized management of different plug-in types and simplified deployment of plug-ins to Oracle Management Server and Management Agents.

2.3 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 Section 2.4, "Installing the Extensibility Development Kit (EDK)".

2.3.1 Contents of the EDK

The EDK archive contains the following directories:

  • \bin

    Contains the empdk utility, which you use to:

    • Validate the structure of your plug-in

    • Package your plug-in

    • Convert the metadata for existing (pre-Cloud Control 12) plug-ins to the new metadata formats

  • \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.

2.4 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.6.0_24 or later

  • Local system running Solaris, Linux, HP-UX, AIX, or Windows with New Technology File System (NTFS)

To install the EDK:

  1. Download the EDK ZIP archive to your local system using one of the following options:

    • Using the Enterprise Manager Cloud Control console

      1. Log in to Enterprise Manager Cloud Control.

      2. From the Setup menu, select Extensibility, then select Development Kit.

        The Extensibility Development Kit (EDK) page appears.

      3. Under Installing the EDK, select Download the Extensibility Development Kit to your workstation.

      4. Save 12.1.0.4.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.
  2. Set your JAVA_HOME environment variable and ensure that it is part of your PATH. For example:

    setenv JAVA_HOME /usr/local/packages/j2sdk1.6.0_24
    
    setenv PATH $JAVA_HOME/bin:$PATH
    
  3. Unpackage the downloaded EDK ZIP archive to a directory on your local system. For example:

    Unzip 12.1.0.4.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
                        README
    

    For more information about the directory contents, see Section 2.3.1, "Contents of the EDK".

2.5 Plug-in Development Lifecycle

Developing a plug-in involves:

  1. Designing the set of entities to be included in the plug-in

  2. Defining the metadata that describes them to Enterprise Manager

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

Figure 2-1 Lifecycle of a Plug-in

Description of Figure 2-1 follows
Description of "Figure 2-1 Lifecycle of a Plug-in"

The plug-in lifecycle represents the transition of a plug-in through the following stages:

  • Design/Develop: Designs and develops the plug-in

  • Package: Packages (and releases) the plug-in

  • Publish: Publishes plug-in at Oracle Enterprise Manager Store

  • Download: Enterprise Manager Server 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)

  • Undeploy: Removes the plug-in completely from OMS

2.5.1 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 Section 2.6, "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 Enterprise Manager Programmer's Reference.

2.6 Plug-in Contents and Packaging

The plug-in contents and packaging section includes the following topics:

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

2.6.2 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 Enterprise Manager Programmer's Reference.

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 Section 2.6.3, "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 Enterprise Manager Programmer's Reference.

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

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/
                            |      
                             scripts
             oms/
                 |                 
                  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

For information about the contents of the plug-in directory, see the Enterprise Manager Programmer's Reference.

2.7 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 Enterprise Manager Programmer's Reference.

2.8 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 Enterprise Manager Programmer's Reference.

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

2.8.2 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 Section 2.8, "Deploying a Plug-in".

2.8.3 Undeploying Plug-ins

If a plug-in is not in use anymore, you can remove it from Enterprise Manager. Undeploying a plug-in removes all elements of the plug-in from the Management Server and from the Management Agents where the plug-in was deployed previously.