Validating, Packaging, and Deploying the Plug-in

Introduction to Validating, Packaging, and Deploying the Plug-in

As a plug-in developer, you are responsible for the following steps within the validation, packaging, and deployment process:

Create the staging directory (plugin_stage):

The staging directory structure defines the location of files as they will be deployed to Oracle Management Service and Management Agents.

For more information, see Staging the Plug-in.
Validate the plug-in.

Use the empdk validate_plugin command to validate the content of the plug-in once you have designed and developed it. This command verifies that the XML metadata files are compliant.

For more information, see Validating the Plug-in.
Create the Oracle Plug-in Archive (OPAR) file.

The plug-in archive is the standard way of distributing the plug-in for importing and deploying the plug-in across different installations of the Enterprise Manager.

For more information, see Creating the Plug-in Archive.
Import the OPAR into Enterprise Manager.

Use the emcli import_update command to import the plug-in into Enterprise Manager.

For more information, see Importing and Deploying the Plug-in Archive into Enterprise Manager.
Deploy the plug-in.

You must deploy a plug-in on the Oracle Management Service before it is used for monitoring targets.

For more information, see Deploying the Plug-in on Oracle Management Service (OMS).
Add target instances for the deployed plug-in to monitor.

For more information, see Adding a Target Instance.
Use the Metadata Registration Service (MRS) to deploy updated metadata files.

The MRS allows you to upload one or more updated metadata files to the Oracle Management Service and Management Agents where your plug-in is deployed. The MRS registers the updated metadata files with Enterprise Manager, and overwrites the existing metadata with your updates.

For more information, see Updating Deployed Metadata Files Using the Metadata Registration Service (MRS).

Staging the Plug-in

After you have created the plug-in files, the next step is to stage the plug-in in preparation for validation and packaging. The staging directory structure defines the location of files as they will be deployed to Oracle Management Service and Management Agents.

The following example provides an example of the staging directory structure and Table 14-1 describes the archive directory structure. Files are placed in the archive based on whether they are deployed to Oracle Management Service, Management Agents, or both. When the plug-in is deployed to an OMS instance or a Management Agent, the requisite files are copied to their respective directory locations.

Example: 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/
                                         |
                                          ComplianceContent_name.xml
                            jobTypes/
                                     |            
                                      job_type.xml
                            mpcui/
                                  |            
                                   mpcui.xml
                            reports/
                                    |                       
                                     report.xml
                            snapshotlive/
                                         |                 
                                          target-type_ecmdef.xml
                            targetType/
                                       |                           
                                        target_type.xml
             discovery/
                       |
                        discovery scripts

Note:

Use of the specified subdirectory names within the archive are not required, but are recommended by Oracle.

Table 14-1 File Locations in Plug-in Archive Structure

File	Directory	Notes
`plugin.xml`	`plugin_stage/`	Required. This file defines generic plug-in metadata that is deployed to Oracle Management Service. Place it at the root level within the archive structure.For more information, see Creating the plugin.xml File.
`plugin_registry.xml`	`plugin_stage/agent/`	Required. This file defines metadata describing the plug-in used by the Management Agent. It must be placed at the top level of the `/agent` directory. For more information, see Creating the plugin_registry.xml File.
`target_type.xml`	`plugin_stage/oms/metadata/targetType/` `plugin_stage/agent/metadata/`	Required. This file defines metrics to be collected or computed for the target type. An identical copy of this file must be placed in both the `/oms` and `/agent` directories. For more information, see Creating the Target Type Metadata File.
`default_collections.xml`	`plugin_stage/oms/metadata/default_collection/` `plugin_stage/agent/default_collection/`	Required. This file defines metric collection parameters such as metric data collection frequency and default metric alert thresholds. An identical copy of this file must be placed in both the `/oms` and `/agent` directories. For more information, see Creating the Default Collection File. Note: Oracle recommends that you name the default collections metadata file with the same file name as the target type metadata file.
`target-type_ecmdef.xml`	`plugin_stage/oms/metadata/snapshotlive/`	Optional. Defines configuration data collection. For more information, see Defining Configuration Collection Tables.
`job_type.xml`	`plugin_stage/oms/metadata/jobTypes/`	Optional. Place all job type definition files in the `/jobTypes` directory. For more information, see Adding Job Types.
`report.xm`l	`plugin_stage/oms/metadata/reports/`	Optional. Put report definition files in the `/reports` directory.
`derivedAssoc_rule.xml`	`plugin_stage/oms/metadata/derivedAssoc/`	Optional. Place the metadata file that defines the association derivation rules (or set of rules) in this directory. For more information, see Using Derived Associations.
`ComplianceContent_name.xml`	`plugin_stage/oms/metadata/gccompliance/`	Optional. ComplianceContent_name.xml contains references to compliance standards, rules, and frameworks. This directory can contain compliance rule, compliance standard, and compliance framework XML files. For more information, see Packaging Compliance XML.
`compliance.dlf`	`plugin_stage/oms/rsc/area/gccompliance/`	Optional. Place all Data Loading Format (DLF) map entry (DLF) files associated with compliance rules or standards definitions in this directory.
`mpcui.xml`	`plugin_stage/oms/metadata/mpcui/`	Optional. Place all management user interface metadata files in this directory. For more information, see Defining a Management User Interface.
`discovery.xml`	`plugin_stage/oms/metadata/discovery/`	Optional. Place discovery metadata files in this location. For more information, see Packaging Discovery XML and Discovery Content.
discovery script file(s)	`plugin_stage/discovery/`	Optional. Place the Perl scripts and JAR files (if any) that are required to perform automatic discovery in this location. For more information, see Packaging Discovery XML and Discovery Content.
script file(s)	`plugin_stage/agent/scripts/`	Optional. Put any scripts that will be deployed to Management Agents, such as metric collection scripts invoked by fetchlets, in this location. Use of the `/scripts` directory is not required but is recommended, as it allows use of the `%scriptsDir%` token from metric query descriptors defined in the target-type.xml file and in job type command references.

Modifying File Permissions Within the Plug-in Directory

To specify customized file permissions for scripts packaged under the plug-in directory:

Create the following text file in the relevant directory (oms, agent, or discovery):

plugin_stage/oms/file_permissions.txt
plugin_stage/agent/file_permissions.txt
plugin_stage/discovery/file_permissions.txt

Specify the permissions for multiple files, each in one row. The format of the text file is similar to the following:
file_name:file_permission_number

or

file_pattern:file_permission_number

In these formats:
- file_name represents the name of the file that will have permissions changed
- file_pattern represents a pattern that the script will search for, such as a certain file type or all file names containing the pattern. Then all matched files will have permissions changed.
- file_permission_number represents the UNIX permission description of the file. This is the new permissions value of the matched files.
For example, to change the permissions of all occurrences of example1.sh to 655 within the plugin_stage/oms directory, add the following entry to the plugin_stage/oms/file_permissions.txt file:
```
example1.sh:655
```
To change the permissions of all script files (of file type *.sh) to 655 within the plugin_stage/discovery directory, add the following entry to the plugin_stage/discovery/file_permissions.txt file:
```
*.sh:655
```
To change the permissions of all files beginning with abc to 655 within the plugin_stage/agent directory, add the following entry to the plugin_stage/agent/file_permissions.txt file:
```
abc*:655
```
Save and close the file_permissions.txt file. These permissions are read and retained during plug-in creation with the OPAR and later used during the plug-in software installation. For more information about plug-in creation, see Creating the Plug-in Archive.

Validating the Plug-in

Validate the plug-in throughout the development cycle, and before packaging the plug-in. Use the empdk validate_plugin command to validate the content of the plug-in after you have designed and developed it to verify that the XML metadata files are compliant. The tool is run against the specified plug-in staging directory and generates a report of any violations found. Specify the format of the generated report using the -format option.

The following example provides the command usage.

Example: empdk validate_plugin Command Usage

 empdk validate_plugin -stage_dir staging directory
                [-tmp_dir temporary working location]
                [-out_dir output directory] 
                [-format (html|text|xml)] 
                [-conn_desc] - not used by external developers
                [-repos_user Enterprise Manager repository owner] 
                [-debug [file to output debug information to]]

The following example validates the plug-in source files in the specified staging directory, and generates the validation report as a text file in the current working directory:

edk\bin>empdk validate_plugin -stage_dir C:\plugin_staging -format text

Table 14-2 provides the options that can be used to validate the plug-in.

Table 14-2 Options for Validating the Plug-in

Option	Description
`-tmp_dir`	Specify a temporary location to extract the plug-in files into. If not specified, it defaults to the current directory.
`-out_dir`	The directory the validation report file will generated into. If not specified, the report file will be generated in the current working directory.
`-debug`	Specify a file name where you want to store the debug information. If not specified, the default log file (validateplugin.logtime) will be created in the out directory and will store warning and error message only. If specified, then it will store all the debugging information to that log file
`-format`	The format the validation report will be generated in. If not specified, the report will be generated as a text file.

Creating the Plug-in Archive

After you have created the plug-in stage directory and validated the plug-in, the next step is to create an Oracle Plug-in Archive (OPAR) file. The OPAR file plays an important role at various stages of the plug-in lifecycle. It serves the following:

The plug-in archive is the standard way of distributing the plug-in for importing and deploying the plug-in across different installations of the Enterprise Manager.
You must test the plug-in being developed on an Enterprise Manager installation.

A plug-in is created by adding the files previously discussed to an OPAR using the Enterprise Manager Extensibility Development Kit (EDK). For more information about the EDK, see the Oracle Enterprise Manager Extensibility Programmer's Guide.

To create an OPAR, at the command prompt, enter the empdk create_plugin command. For more information about the create_plugin verb, see the command line help

The empdk create_plugin command syntax is as follows:

empdk create_plugin -stage_dir staging dir -conn_desc repository_connection_string -repos_user username [-repos_password repos_password] 
           -out_dir output_directory [-debug] [-force]

For example:

edk\bin>empdk create_plugin -stage_dir C:\pluginstagdir -conn_desc myhost.us.example.com:25055:$ORACLE_SID -repos_user sysman -out_dir /tmp/plugins

Table 14-3 provides the options that can be used to create an OPAR:

Table 14-3 Options for Creating an OPAR

Option	Description
`-tmp_dir`	This option enables the command to create a temporary directory while executing. You can specify the path you want to use for this by providing a value following the option. Specify an existing directory or else you will receive an error. If not specified, then the out directory will be used for temporary location. If no out directory is specified, the current directory is the default.
`-out_dir`	The directory in which the plug-in archive (*.opar) file will be created. If not specified, the plug-in archive will be created in the current directory.
`-debug`	Specify a file name where you want to store the debug information.If not specified, the default log file (createplugin.logtime) will be created in the out directory and will store only warning and error messages. If specified, then it will store all the debugging information to that log file. This debugging information can be used to identify issues you may encounter while creating a plug-in. You can append the log created when you are filing a support request for a create plug-in related issue.
`-force`	If the out directory contains an OPAR with the same name, then you will be prompted to specify whether to overwrite the existing OPAR. If provided, it will automatically overwrite the existing OPAR. This is disabled by default.
`-conn_desc`	The connection descriptor that will connect to the Management Repository that the plug-in metadata will be written to when the plug-in is imported into Enterprise Manager. Specify the connection descriptor using the following syntax: `host:port:sid` For example: myhost.us.example.com:25055:$ORACLE_SID
`-repos_user`	The user to connect to the Management Repository.

If the command runs successfully, then a plugin_version.plugin_id.opar archive will be created in the directory where you ran this command.

If the command fails, an appropriate error message will be displayed. The parameters passed to the commands vary from user to user and across systems where the plug-in is being created.

Some common mistakes while trying to create the plug-in archive are:

If the path to the staging directory is entered incorrectly, then it raises a File not found or an Input not found exception.
The empdk command not found exception will be shown if you have not changed your current directory to the expanded EDK directory.
If the disk where you are trying to create the OPAR has inadequate memory, then an Input/Output-related exception might occur.

Importing and Deploying the Plug-in Archive into Enterprise Manager

Once you have the plug-in archive ready with your *.opar file, you must import the plug-in into Enterprise Manager. Importing ensures that the content that you have created and packaged in the plug-in is available within Enterprise Manager.

Note:

You must first import the plug-in before it can be deployed onto Enterprise Manager.

Prerequisites for Importing the Plug-in

The following prerequisites are met before importing the plug-in.

Setting Up the Software Library

Create a folder in the system where Enterprise Manger is installed. For example, /net/hostname/scratch/aime/swlib1.
From the console, select Enterprise, then Provisioning and Patching, and then Software Library.
Click Actions, then Administration.
Click Add.
In the pop up window, enter a name and location. For example, swlib1 and /net/hostname/scratch/aime/swlib1. This should be the folder that you created in step 1.
Wait for the processing to finish.

Setting Up the EM CLI Utility

You will use the Enterprise Manager Command Line Utility, or EM CLI, to import the plug-in archive for deployment to Enterprise Manager.

A page is provided in the Enterprise Manager console with instructions on setting up EM CLI. Access the page at the following URL:
```
https://em_host:em_port/em/console/emcli/download
```
For example:
```
https://emserver.test.com:7799/em/console/emcli/download
```
After setting up EM CLI, synchronize the EM CLI client with an Oracle Management Service (OMS):
```
emcli sync
```
After synchronization, all verbs and associated command line help available to this OMS become available at the EM CLI client.

Importing the Plug-in Archive

Once packaged, the plug-in must be imported into Enterprise Manager using the emcli import_update command. You have two options depending on where EM CLI is installed:

If EM CLI is on the same system as the system where you created the plug-in archive (*.opar file), then run the following command.
```
emcli import_update 
 -file="<path to *.opar file you created>"
 -omslocal
```
The -omslocal flag indicates that the plug-in archive is on the same system where you are running this command and the path exists on this system.

For example:

emcli import_update -file=/tmp/sample_plugin.opar -omslocal
If you are running EM CLI on a different system than the system where you created the plug-in archive (*.opar file), then run the following command:
```
emcli import_update 
       	 -file="path to the .opar file"  
       	 -host="host name of plug-in host" 
       	 -credential_name="credential for plug-in host" 
       	 -credential_owner="credential owner on the plug-in host"
```
where:
- -file: The absolute path to the *.opar file on the system where you created the archive.
- -host: The host name for the host target where the file is available.
- -credential_name: The name of the credentials on the remote system you are connecting to.
- -credential_owner: The owner of the credentials on the host system you are connecting to.
For example:

emcli import_update -file=/tmp/sample_plugin.opar -host="host1.test.com" -credential_name="myOracleCred" -credential_owner="password"
As an alternative to the previous step, you can also run the following command:
```
emcli import_update 
      -file="path to *.opar file you created"          
      -host="hostname" 
      -credential_set_name="setname"
```
-credential_set_name: The set name of the preferred credential stored in the Management Repository for the host target. It can be one of the following:
- HostCredsNormal: The default unprivileged credential set.
- HostCredsPriv: The privileged credential set.

Deploying the Plug-in on Oracle Management Service (OMS)

A plug-in must be deployed on Oracle Management Service (OMS) before it can be used to monitor targets. Follow the steps below to deploy the plug-in on Enterprise Manager.

Note:

Plug-ins must be deployed on Oracle Management Service before being deployed on Management Agents.

Plug-ins for specific target types are deployed automatically on Management Agents that will monitor those target types. For more information, see Adding a Target Instance.

To deploy a plug-in on the Oracle Management Server:

From the Setup menu, select Extensibility, then Plug-ins.

Enterprise Manager displays the list of plug-ins that have been downloaded and can be deployed on the Plug-ins page.
On the Plug-ins page, select the specific plug-in you want to deploy.
Click Deploy On, then select Management Servers.

Ensure that dependent plug-ins are deployed and that all existing Management Agents are compatible with the version of the specified plug-in. Enterprise Manager prompts for credentials if the Management Agent is not available.
On the Deploy Plug-in window, enter the required details. Note that you will require the Management Repository SYS user password to complete the deployment process.

From the Version list, select the Plug-in version. The Target Type information is displayed in the table. Enter the Repository sys Password, then click Continue.
Proceed through the steps in the Deploy Plug-in windows.
Click Deploy to deploy the selected plug-in on all Enterprise Manager servers.

Enterprise Manager displays a page that allows you to monitor the deployment status. Enterprise Manager deploys the selected plug-in on all Enterprise Manager Servers.

You can also monitor the deployment status by going to the Enterprise Manager console, then going to the Plug-ins page as described in step 1, selecting the plug-in and select the Recent Deployment Activities tab at the bottom of the page for the selected plug-ins. This bottom section also lets you see details of your plug-in, which includes the plug-in ID, version, vendor, and so on.

If any of the steps during plug-in deployment fails, the log file is available in $ORACLE_HOME/cfgtoollogs/pluginca/*. Append these files when logging a support request for failure while deploying the plug-in. You can also use them to debug the problem.

Important Details Regarding Plug-in Deployment

You can import multiple versions of the same plug-in. The version to deploy can be selected from a list if you are using Enterprise Manager to deploy the plug-in, or can be specified on the command line if using EM CLI.
Only one version can be deployed on the Oracle Management Service (OMS) at any given time. If a later version has been deployed previously, it cannot be downgraded to an earlier version.
Updating a plug-in to a new version does not remove the content of the older plug-in(s) that were imported.
The Management Agent can have the same or earlier version of the plug-in that is deployed on the OMS. A version later than the version on the OMS is not allowed on the Management Agent.
The plug-in on OMS and the Management Agent can be updated independently of each other as long as the version on the OMS is the latest version.
Available updates are visible on the Plug-ins page. They can be downloaded from the Enterprise Manager store or imported using EM CLI as described in Importing the Plug-in Archive.

Adding a Target Instance

When the plug-in is deployed on OMS, it is ready to monitor target instances.

Note:

In the current Enterprise Manager release, deployment of a plug-in to a Management Agent that will monitor targets is no longer required. Instead, the plug-in for a specific target type is automatically deployed with the Management Agent that will monitor targets of that type.

This is a significant change from previous releases, in which plug-ins had to be manually deployed to a Management Agent first. Then a target instance had to be added to the Management Agent manually.

You can add targets that the plug-in will monitor through Enterprise Manager by selecting Add Targets from the Setup menu. The process for adding targets - known in Enterprise Manager terminology as target promotion - varies depending on the option you choose.

You can also add a target instance using the EM CLI utility. Open a command prompt and run the following command:

emcli add_target
        -name="name"
        -type="type"
        -host="hostname"
        [-properties="pname1:pval1;pname2:pval2;..."]...
        [-separator=properties="sep_string"]
        [-subseparator=properties="subsep_string"]
        [-credentials="userpropname:username;pwdpropname:password;..."]
        [-input_file="parameter_tag:file_path"]
        [-display_name="display name"]
        [-groups="groupname1:grouptype1;groupname2:grouptype2;..."]...
        [-timezone_region="gmt offset"]
        [-monitor_mode="monitor mode"]
        [-instances="rac database instance target name1:target type1;..."
]

For example:

emcli add_target 
          -name="cluster_database"
          -type="rac_database"
          -host="myhost.us.example.com"
          -monitor_mode="1"
          -properties="ServiceName:service.us.example.com;ClusterName:newdb_cluster"
          -instances="database_inst1:oracle_database;database_inst2:oracle_database"

Use the emcli help add_target help command to see more options when adding the target instance.

If targets have been added before, they will be promoted and monitored by the plug-in after it is deployed.

Updating Deployed Metadata Files Using the Metadata Registration Service (MRS)

As part of the plug-in development process, you will package your plug-in as an archive and deploy it to an Enterprise Manager installation to test it. However, you will likely not want to re-deploy the plug-in each time you make changes to various metadata files.

Note:

You must update the metadata version each time you update a metadata file.

The Metadata Registration Service (MRS) allows you to upload one or more updated metadata files to the Oracle Management Service and Management Agents your plug-in has been deployed to. The updated metadata files will be registered with Enterprise Manager, and will overwrite the existing metadata with your updates.

Note:

For target types and default collections, some additional steps are required for using MRS, see Target Types and Default Collections.

This service is invoked through the emctl register oms metadata command. The syntax is as follows:

emctl register oms metadata -service Metadata Service Id (-file metadata file to register | -file_list file containing list of files to register)  
          [-core | -pluginId Plugin Id] [-sysman_pwd "sysman password"]

For example, the following command registers changes to target type metadata file:

emctl register oms metadata -service targetType -file /staging/demo_hostsample.xml -pluginId test.demo.xyz -sysman_pwd myempassword

Table 14-4 describes the usage of the command.

Table 14-4 emctl Command Usage

Option	Required Y/N	Description
`-service`	Y	Specify the type of metadata to register. Values are: `targetType`: Specify for target type metadata. `default_collection`: Specify for default collection metadata. `LiveSnapshotRegistration`: Specify for configuration metadata registration `CredStoreMetadata`: Specify for `jobTypes`: Specify for `report`: Specify for Report Metadata Registration `bipublisherreport`: Specify for BI Publisher report metadata. `discovery`: Specify for discovery metadata. `derivedAssocs`: Specify for associations metadata. `gccompliance`: Specify for compliance rules, compliance standards, and compliance framework metadata. `mpcui`: Specify for management user interface metadata.
`-file`	N	The path and file name for a single metadata file to upload and register. Either `-file` or `-file_list` can be included.
`-file_list`	N	The path and file name for a file containing a list of metadata file paths (one on each line).
`-core`	N	Not valid for plug-in development.
`-pluginId`	N	The unique three-part identifier given to the deployed plug-in to update. See Defining the Plug-in ID for details.
`-sysman_pwd`	Y	The Enterprise Manager user password.

Target Types and Default Collections

For target types and default collections, some additional steps are required for using MRS if there are existing targets of this target type.

If you have an existing target and you want to update the metadata files during the plug-in development process, follow these steps:

Register the new metadata files using the emctl register oms metadata command.

emctl register oms metadata -service targetType -file full path/TargetTypeMetadata.xml -pluginId Plugin Id -sysman_pwd sysman

emctl register oms metadata -service storeTargetType -file full path/TargetTypeMetadata.xml -pluginId Plugin Id -sysman_pwd sysman

emctl register oms metadata-service default_collection -file full path/TargetTypeCollection.xml -pluginId Plugin Id -sysman_pwd sysman 

emctl register oms metadata-service systemStencil -file full path/TargetTypeStencil.xml -pluginId Plugin Id -sysman_pwd sysman

Place the metadata XML files in the correct directories of the plug-in home directory (PLUGIN_AGENT_HOME) in the Management Agent as shown. The PLUGIN_AGENT_HOME directory is created when the plug-in is deployed to the Management Agent. The default location is AGENT_BASE_DIR/plugins.
```
$PLUGIN_AGENT_HOME/metadata/
$PLUGIN_AGENT_HOME/default_collection 
```
Restart the Management Agent.
```
AGENT_HOME/agent/bin/emctl stop agent
AGENT_HOME/agent/bin/emctl start agent
```
In the preceding command, AGENT_HOME represents the Management Agent home directory.