Enterprise Manager 12c includes a new metadata plug-in framework that is significantly enhanced from the framework used in previous releases. Existing metadata plug-ins, that is, plug-ins released for any version earlier than Cloud Control 12c are not compatible with the new framework.
This chapter provides instructions on converting existing plug-ins to the format required by the new framework.
Note:
This conversion requirement applies to plug-ins from Enterprise Manager 11g or earlier only. If you are building a new plug-in for Enterprise Manager Cloud Control 12c, the issues discussed in this chapter will not affect you.This chapter contains the following sections:
As a plug-in developer, you are responsible for the following steps within the conversion process:
Familiarize yourself with the changes to the new plug-in framework.
For more information, see Section 18.2, "Impact of the New Plug-in Framework on Existing Plug-ins".
Convert the plug-in metadata to the new format by running the convert_mp utility.
For more information, see Section 18.3, "Using the convert_mp Utility to Convert Plug-in Metadata".
Manually modify the generated plug-in configuration files.
For more information, see Section 18.4, "Post-Conversion Steps".
Use the Extensibility Development Kit (EDK) to package the plug-in as a deployable archive.
For more information, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".
Validate, deploy, and test your plug-in against the Enterprise Manager Cloud Control 12 installation.
For more information, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".
Plug-in developers must be aware of the following changes to the new plug-in framework and impact to the Enterprise Manager Cloud Control 12c upgrade process.
The plug-in metadata format used by Enterprise Manager Cloud Control 12c is incompatible with the format used in earlier releases. As a result, the metadata for all existing plug-ins must be converted to the new format per the instructions in this document.
The Extensibility Development Kit (EDK) includes a convert_mp utility that converts existing plug-in metadata files to the new format, and generates additional metadata files required by the new framework.
Plug-ins must be packaged (or re-packaged) as Oracle Plug-in Archive (OPAR) files for deployment into Cloud Control 12c. The Metadata Plug-in Archive (MPA) files used to package previous plug-ins cannot be deployed into Cloud Control 12c.
An ”in-place” upgrade of existing plug-ins is not supported as part of the Enterprise Manager Cloud Control 12c upgrade process. That is, there is no automated conversion or migration of plug-in artifacts already deployed to the existing installation to the upgraded installation.
Before beginning the upgrade process, all plug-ins included in the installation being upgraded must be converted to the new plug-in format as noted above.
Once converted to the new format, plug-ins must be registered with the Cloud Control upgrade console prior to initiating the Enterprise Manager Cloud Control 12c upgrade process.
If the appropriate plug-in is not available and is not registered with the upgrade console, targets associated with the target type(s) specified in the plug-in metadata cannot be migrated from the existing installation to the upgraded installation.
Existing plug-in metadata can be transformed to the new format using the convert_mp command-line utility, which is included with the Plug-in Developer Kit. The tool also generates two new metadata files required by the new format.
The tool can be run in two modes:
Against a 10.2.x or 11.1 Management Repository containing the metadata for deployed plug-ins. See 0, "Converting Plug-In Metadata Stored In A Management Repository" for instructions.
On an existing metadata plug-in archive (MPA) file. See 0, "Converting a Metadata Plug-in Archive (MPA)" for instructions.
The tool outputs new metadata files to the directory structure required to create a Plug-in Archive (OPAR) file, which can then be deployed into Enterprise Manager Cloud Control 12c. Note that the tool does not create the archive; this must be done as a separate step.
The tool converts the following existing metadata to the new format:
Target type definitions
Performance metrics and metric collection definitions
Collection scripts and binaries
Job type definitions
Job scripts and binaries
Report definitions
Homepage chart customizations
Related links to the homepage
The utility also creates the following new files, which contain metadata required by the new framework:
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
This file declares those components included in the plug-in that are to be deployed to the Management Agent.
Note:
The plugin.xml and plugin_registry.xml files must be manually updated after the conversion process is complete.For more information, see Section 18.4.1, "Modifying the plugin.xml and plugin_registry.xml Files".
The convert_mp command can be run against an Enterprise Manager release 10.2.x or 11.1 Management Repository containing metadata for deployed plug-ins. Note that only one plug-in can be converted on each invocation of the command.
Note:
If the plug-in includes report definition metadata, it must be converted using this process. Report definitions cannot be converted by running the conversion utility against a metadata plug-in archive (MPA) file.If there are no report definitions, then you can use either mode to convert plug-in metadata.
Before running the utility, you must import the plug-in to an existing Enterprise Manager Enterprise Manager 10.2.x or 11.1 installation and deploy the plug-in to a Management Agent. This causes the plug-in metadata to be written to the Management Repository. It is not necessary to create any target instances before running the tool.
The tool connects to the Management Repository using the specified connection string as the specified Cloud Control 10.2.x or 11.1 user. It then writes the converted files to a subdirectory named /opar within the specified output directory.
To use the convert_mp utility, navigate to the /bin directory within the EDK.
The basic usage syntax for the convert_mp utility is as follows:
convert_mp -conn_desc repository_connection_string -repos_user username [-repos_password repos_password] [-mp_name plugin_name] [-mp_version plugin_version] -out_dir output_directory [-plugin_id converted_plug_id] [-force]
The following is a basic conversion example:
C:\edk\bin>convert_mp -conn_desc myhost.us.example.com:25055:$ORACLE_SID -repos_user sysman -mp_name sample_plugin_01 -out_dir /tmp/plugins
Table 18-1 provides the options that can be used to convert metadata stored in a Management Repository.
Table 18-1 Options to Convert Metadata Stored in a Management Repository
| Option | Required Y/N | Description |
|---|---|---|
|
|
Y |
The connection string used to connect to the Management Repository. Specify the string in the form of |
|
|
Y |
The user to connect to the 10.2.x or 11.1 Management Repository. Oracle recommends that you connect as Note: You must not supply a Cloud Control 12.0 user name. The tool prompts you for the password if not supplied with |
|
|
N |
The 10.2.x or 11.1 Management Repository password. You will be prompted for the password if not specified. Note: Providing a password on the command line is insecure and should be avoided in a production environment. |
|
|
Y |
Required if multiple plug-ins exist in the Management Repository. Because only one plug-in can be converted at a time, the name of the plug-in to convert must be supplied. |
|
|
Y |
Required if multiple plug-ins with the same name exist in the Management Repository. |
|
|
Y |
The directory to output the converted XML files to. A new subdirectory named /opar will be created in this directory |
|
|
N |
An identifier that will be written to the plugin.xml and plugin_registry.xml files generated as part of the conversion process. If not included on the command line, the identifier must be specified in the plugin.xml and plugin-registry.xml files before packaging the plug-in. |
|
|
N |
If set, an existing output directory for the plug-in will be deleted, and a new directory will be created. If not set, an error will occur if an output directory already exists. |
The convert_mp utility can also convert the metadata files for one or more plug-ins packaged in a metadata plug-in archive (MPA). You can specify a single plug-in to convert, or convert all plug-ins within the archive simultaneously.
Note:
If the plug-in includes report definition metadata, it must be converted using the Management Repository option. Report definitions cannot be converted by running the conversion utility against a metadata plug-in archive (MPA) file.For more information about the Management Repository option, see Section 18.3.1, "Converting Plug-In Metadata Stored In A Management Repository".
Note that unlike the Management Repository option, the plug-in does not need to be deployed to Enterprise Manager Cloud Control before conversion.
The syntax is as follows:
convert_mp -mpa mpa_file_location [-mp_name plugin_name] [-mp_version plugin_version] -out_dir output_directory [-plugin_id converted_plug_id] {-force]
The following is a basic conversion example. The tool will convert all plug-ins within my_gc11_plugins.mpa and output the converted files for each to a unique /opar directory within /tmp/plugins/.
convert_mp -mpa /tmp/my_gc11_plugin.mpa -out_dir /tmp/plugins
Table 18-2 describes the options that can be used to convert an MPA file.
Table 18-2 Options to Convert an MPA File
| Option | Required Y/N | Description |
|---|---|---|
|
|
Y |
The path to the MPA file, relative to the EDK installation. |
|
|
N |
The name of a plug-in within the archive to convert. If not supplied, all plug-ins in the archive will be converted. |
|
|
N |
If multiple plug-ins have the same name, the plug-in version to convert. If not supplied, all versions of the specified |
|
|
Y |
The directory to output the converted XML files to. A new subdirectory named /opar will be created in this directory. If multiple plug-ins are converted, a unique /opar directory will be created for each. |
|
|
N |
An identifier that will be written to the plugin.xml and plugin_registry.xml generated as part of the conversion process. If not included on the command line, the identifier must be specified in the plugin.xml and plugin-registry.xml files before packaging the plug-in. |
|
|
N |
If set, an existing output directory for the plug-in will be deleted, and a new directory will be created. If not set, an error will occur if an output directory already exists. |
After the transformation process is complete, several additional manual changes that should be considered before packaging the plug-in.
The plugin.xml file is generated during the conversion process. It is used during the plug-in deployment process.
The file 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 using other metadata included in the plug-in.
If the -plugin_id option is not included on the command line when running the convert_mp command, a <PluginID> element must be specified in the plugin.xml and plugin_registry.xml files before packaging the plug-in.
For more information about the contents of the plugin.xml file and plugin_registry.xml file, see Section 2.4, "Creating the plugin.xml File" and Section 2.5, "Creating the plugin_registry.xml File".
Example 18-1 Modifying the plugin.xml File
<?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/">
<!-- If the -plugin_id option is not included on the command line when running
the convert_mp command, the PluginID element must be manually specified. -->
<PluginId vendorId="oracle" productId="sysman" pluginTag="db2"/>
<PluginVersion value="11.2.0.1.0"/>
<TargetTypeList>
<TargetType name="ibm_db2_database" isIncluded="TRUE">
</TargetType>
</TargetTypeList>
<EMPlatforms>
<CertifiedPlatform version="11.2.0.1.0"/>
</EMPlatforms>
<AgentSideCompatibility>
<Version>11.2.0.1.0</Version>
</AgentSideCompatibility>
<PluginJ2EEArtifacts/>
</Plugin>
Report definitions created using PL/SQL that include SQL statement references through the ”oracle.sysman.eml.ip.render.elem.sqlStatement” type cannot be converted directly to the new report metadata format supported in Enterprise Manager Cloud Control 12c.
If the report definition includes SQL statements that retrieve the report data, the SQL must be extracted and registered as ”namedSQL”.
An existing report definition might contain a SQL statement such as:
l_param_values(N) := MGMT_IP_PARAM_VALUE_ RECORD('oracle.sysman.eml.ip.render.elem.sqlStatement', 'select target_name, target_type from mgmt$target');
It might also include the following:
l_element_guid := mgmt_ip.add_element_to_report_def (
p_report_guid => l_report_guid,
p_element_name_nlsid => 'IPMSG_TABLE_FROM_SQL',
p_element_type_nlsid => 'IPMSG_ANY_TARGET_TYPE',
p_header_nlslid => null,
p_element_order => 2,
p_element_row => 2,
p_parameters => l_param_values,
p_targets => null
);
Before you begin to convert your report to XML format, check Section 18.4.2.1, "Named SQL Statements".
If you have a Named SQL statement registered for your report, you must convert it to XML.
For example, if your PL/SQL report definition includes a line similar to the following:
mgmt_ip.register_sql_statement ( p_name =>'oracle.sysman.db.storage.reports.TablespaceUsage', p_sql_statement => 'select * from dual');
Convert to an XML file as follows:
<?xml version = '1.0' encoding = 'UTF-8'?> <NamedSQLStatements xmlns= "http://www.oracle.com/DataCenter/NamedSQL/"> <NamedSQL sqlName="oracle.sysman.db.storage.reports.TablespaceUsage" sqlValue="select * from dual"/> </NamedSQLStatements>
The steps for converting report definitions are as follows.
Run the report definition PL/SQL to register the report against your Enterprise Manager 10.2.x or 11.1 installation.
Log in to Enterprise Manager as SYSMAN and from the Reports page, use Create Like to make a copy of your out-of-the-box report.
Note:
You must change the name of your report temporarily using the Edit Report Definition page.Export the report definition to an XML file using the emcli export_report command as shown below. Note that you must specify the report ID as the value for -title:
emcli export_report -title='MY_REPORT_ID' -output_file='./tmp/report.xml'
MY_REPORT_ID is the name of the copied file that you created in step 2.
Include the generated file in the /oms/metadata/report directory within the plug-in staging area. The file will be imported when the plug-in is deployed
Create an XML file that includes the named SQL statements referenced in the report, as shown below. Multiple statements can be included in the file. Ensure that the same statement identifier is used:
<?xml version = '1.0' encoding = 'UTF-8'?>
<NamedSQLStatements xmlns="http://www.oracle.com/DataCenter/NamedSQL/">
<NamedSQL sqlName="MY_UNIQUE_SQL_STATEMENT_ID”
sqlValue="'select target_name, target_type from mgmt$target"/>
</NamedSQLStatements>
Note:
Oracle supports one XML file per report definition. Named SQL statements can be grouped into one file at your discretion.These steps must be repeated for all report definitions that include SQL statements.
Include the file in the /oms/metadata/namedsql directory within the plug-in staging area. The file will be imported when the plug-in is deployed.
Job type definitions created in an existing plug-in will be converted by the convert_mp utility. However, the XSD that describes the job type metadata is more strictly validated in Cloud Control 12c. As a result, validation errors may occur during plug-in deployment if any existing job type definitions include XML that is not valid according to the new XSD.
The best way to proactively find such issues is to run the empdk validate_plugin command against the plug-in. Each time you encounter an error, fix it, then run the command again. Continue running the command until it no longer reports any validation errors.
See Section 14.3, "Validating the Plug-in" for details on using the empdk validate_plugin command.
Refer to the job type XSD to determine how to restructure incorrectly formatted job type definitions.
Once you have completely converted your plug-in to the new format, you will be ready to package the plug-in for deployment into Enterprise Manager Cloud Control 12c. See Section 14.4, "Creating the Plug-in Archive" for details.