Enterprise Manager Cloud Control 12c provides a Management Connector Framework (referred to as Connector Framework) to allow developers to build event connectors that can be used to create/update events in an external application.

For the connector to exchange data with the external application, a web service must be available that the connector can invoke to create and update event information. The connector is composed of a set of XML and XSLT metadata files that define how the connector appears in the UI and how it connects to and exchanges data with the external application.

To create an event connector for your own system, you need to provide a set of metadata files. Table 2-1 lists the categories of metadata files that comprise an event connector:

In order to know how to build an event connector, you need to understand how one functions. The connectorDeploy.xml file, commonly referred to as the connector descriptor file, defines the connector in Enterprise Manager. When the connector is installed, the contents of the connector descriptor file are examined by Enterprise Manager to determine what fields are required by the connector and what templates to use when exchanging XML messages with the web service.

When the operator configures the connector, the configuration page is generated based on the information in the connector descriptor file. Typically this includes fields that contain the URL and credentials to use when connecting to the web service. After the operator specifies the required fields, they click the Ok button to complete the configuration process. When the button is clicked, the configuration values are saved and any setup or initialization service operations defined by the connector are performed.

If the configuration completed successfully, the connector is marked as completed and is ready to use. If an error occurs, the configuration changes will be saved but the connector will not be marked as completed. Someone must investigate why it failed and address the problem. Once the problem has been addressed, they can go back to the configuration page and click Ok to have perform setup/initialization again.

Once the connector is marked as completed, you can set up incident rules to create an event in the external application whenever certain events occur. For example you could set up a rule to create an event if any of your database tablespaces exceed a specified threshold. Whenever the rule is set up, you specify what target(s) the rule applies to, what criteria to use to trigger the rule, and the event connector to invoke.

Whenever the criteria are met and the rule fires, the Connector Framework invokes the event connector to generate the XML required to create an event in the remote application. The Connector Framework creates the request XML by performing an XSLT translation on the Enterprise Manager event data using the createEvent request template defined by the connector. The Connector Framework sends the generated create request to the web service URL configured for the createEvent service. The web service creates an event in the external application and sends a response with the identifier of the new event. The Connector Framework uses the createEvent response template to translate the new event identifier into the format expected by the Connector Framework. When the Connector Framework gets the response, it persists the external event identifier with the event.

Whenever something occurs that causes the event in Enterprise Manager to be updated, the Connector Framework uses the updateEvent request template to translate the Enterprise Manager event data format into an XML update request that it sends to the web service. The web service updates the event in the external application and sends a response. When the Connector Framework gets the response, it uses the updateEvent response template to translate the response into a format expected by the Connector Framework. This response is used by the Connector Framework to verify that the update was completed successfully.

When the event is eventually resolved and goes into a cleared status, the Connector Framework performs a normal updateEvent operation with the SeverityCode field set to CLEAR.

You must have a good understanding of the XML, XSD, and XSLT technologies because you will be required to generate several XML and XSLT files during the course of building a connector. It is highly recommended that you familiarize yourself with these technologies before attempting to build a connector.

To create the ticketing and event connectors, you will need access to the schema files that define the format of the different files. The schema files are located in the Extensibility Development Kit (EDK). To install the EDK, go to the Setup menu, select Extensibility, then Development Kit. This page gives instructions for downloading and installing the EDK. Review the Requirements section and verify the prerequisites have been met before attempting to install the EDK. Once the prerequisites are confirmed, install the EDK as directed in the Deployment section.

The schema files are located in the emMrsXsds.jar file in the emSDK directory. To access the files, you will need to extract them using the jar command or any other utility that understands the jar file format. Use the following command to extract the files using the jar command from the EDK installation directory:

$JAVA_HOME/bin/jar xvf emSDK/emMrsXsds.jar

Table 2-2 shows the location of the extracted schema files. This table will be referenced in the different sections where the schema files are discussed.

To deploy the connector, Enterprise Manager uses the Self Update feature. This feature, which can be accessed through the console, provides the ability to import the connector into the Enterprise Manager environment. To deploy the connector complete the following:

1. Prepare the connector jar file

   Package all XML and XSLT template files as a .jar file

   <name>_connector.jar
   		---> connectorDeploy.xml
   		--->template1.xml
   		--->template2.xsl
   		…..
   		…..
   		--->templateN.xsl
   

2. Prepare the manifest file

   Table 2-10 lists the Key attributes of self update manifest files:

   Table 2-10 Self Update Manifest File Attributes

   Name	Description
   EntityType	Value is core_connector
   EntityTypeVersion	Current release version. Value=12.1.0.1.0
   Version	Version number of the connector. Must be set to the value specified in the ManagementConnector/Version node in the connectorDeploy.xml file.
   Attribute @Name=connector_type	Connector type name. Must be set to the value specified in the ManagementConnector/Name node in the connectorDeploy.xml file
   Attribute @Name=connector_category	Category type can be TicketingConnector or EventConnector
   ArchiveList	This element contains the list of archives that are part of connector setup. Generally there will be single connector jar but for some special implementation there may be additional jars(adapter or agent). In these cases, the connector specific jar should be first one in the defined list. This is mandatory requirement.

   The SelfUpdateManifest.xsd schema file defines the format of the manifest file.

   See Table 2-2 in the Extracting Schema Files section for the location of the SelfUpdateManifest.xsd schema file.

   The following example shows the code for the connector_manifest.xml file:

3. Configure the emedk tool

   The emedk tool can be configured by following instructions from the Enterprise Manager user interface. From the Setup menu, select Extensibility, then Development Kit.

4. Prepare the self-update archive

   This requires the connector jar file and the manifest file for the connector. To prepare self-update, call the following utility to create a self update archive file:

   edkutil prepare_update
           -manifest "manifest xml"
           -archivedir "archives directory"
           -out "output file or directory"
           [-typexml "update type xml"]
   

   Table 2-11 describes the options available with the utility:

   Table 2-11 Self Update Utility Options

   Option	Description
   -manifest	Self update manifest file that describes the update.
   -archivedir	Directory containing the archive files specified in the manifest file.
   -out	Directory or filename for the self update archive. If a directory is specified, the filename is autogenerated.
   -typexml	Optional path to the update type xml

   The following example creates a self update archive in the /u01/sar directory based on the manifest file /u01/connector/connector_manifest.xml. The archives referred to in connector_manifest.xml are picked from the directory /u01/connector/archives.

     edkutil prepare_update
             -manifest /u01/connector/connector_manifest.xml
             -archivedir /u01/connector/archives
             -out  /u01/sar/sample_connector.zip
   

5. Import the connector archive to Enterprise Manager by calling any one of the following emcli commands:

   	emcli import_update        
     -file=\ file\         
     -omslocal
   

   or

   	emcli import_update  
   -file=\ file\         
   -host=\ host name\
   [-credential_set_name=\ setname\ ] | -credential_name=\ name\  -credential_owner=\ owner\
   

   These commands import a Self Update archive file into Enterprise Manager. On successful import, the update is displayed on the Self Update Home in downloaded status for further action. Table 2-12 describes the connector archive command options.

   Table 2-12 Connector Archive Command Options

   Options	Description
   -file	The complete path name of the update archive file
   -omslocal	The flag specifying that the file is accessible from the OMS
   -host	The target name for a host target where the file is available
   -credential_set_name	The set name of the preferred credential stored in the repository for the host target. Can be one of the following: HostCredsNormal Default unprivileged credential set HostCredsPriv Privileged credential set
   -credential_name	The name of a named credential stored in the repository. This option must be specified along with -credential_owner option.
   -credential_owner	The owner of a named credential stored in the repository. This option must be specified along with -credential_name option.

   The following paragraphs provide some examples of the use of the emcli command:

   Example 1

   Imports the file update1.zip. The file must be present on the OMS host. In a multiple OMS setup, the request can be processed by any OMS, so the file should be accessible from the OMS processing the request. This usually means that the file must be kept on a shared location that is accessible from all OMS.

   emcli import_update        
     -file=\ /u01/common/update1.zip\         
     -omslocal  
   

   Example 2

   Imports the file update1.zip that is present on the host1.example.com host. The host must be a managed host target in Enterprise Manager and the agent on this host must be up and running. The preferred unprivileged credentials for host host1.example.com are used to retrieve the remote file.

   emcli import_update        
     -file=\ /u01/common/update1.zip\         
     -host=\ host1.example.com\         
     -credential_set_name=\ HostCredsNormal\ 
   

   Example 3

   Imports the file update1.zip that is present on the host1.example.com host. The host must be a managed host target in Enterprise Manager and the agent on this host must be up and running. The named credentials \ host1_creds\ owned by user \ admin1\ are used to retrieve the remote file.

   emcli import_update        
     -file=\ /u01/common/update1.zip\         
     -host=\ host1.example.com\         
     -credential_name=\ host1_creds\         
     -credential_owner=\ admin1\ 
   

6. Apply the connector using one of the following methods:

   • From the Cloud Control console:

     1. Go to Self-Update Home page. The connector will be shown as downloaded.

     2. Select the connector row and click Apply to deploy the connector.

   • From the command line, run the following emcli list command to determine the identifier of the connector that was just imported:

     emcli list -resource=Updates -bind="et_name = 'core_connector'"
     

     The output of the command would look like this example:

     Status    Category          Type                Version      Id
     -------   ----------   ------------------  ----------   --------------
     Applied   Ticketing    Remedy Service      12.1.0.1.0   123456789ABCDE
               Connector    Desk Connector
     Applied   Event        HP OMU Connector    12.1.0.3.0   11223344AABBCC
               Connector
     Applied   Ticketing    Remedy Service      12.1.0.3.0   1A2B3C4D5E6F7G
               Connector    Desk 7.6 Connector
     Applied   Ticketing    CASD Connector      12.1.0.3.0   55443322CCBBAA
               Connector
     

     Note the ID for the connector that was just imported. You will need to select the ID for the connector that was just imported and supply to the emcli apply_updates command listed below:

     emcli apply_updates -id=<ID>