2 Building an Event Connector

Introduction

Enterprise Manager Cloud Control 12c provides a Management Connector Framework (referred to as Connector Framework) that enables developers to build event connectors based on metadata (XMLs and XSLs). The event connector allows Enterprise Manager to send generated events to external systems.

The following metadata categories are required to build an event connector:

• Connector Descriptor XML

  Provides the definition of connector in XML form

• Request Templates XML or XSL

  Provide transformation mapping for EM event and external system attributes using predefined XML template or XSL.

• Response Template XSL

  Transform response from external system into EM data model.

Building an Event Connector

Building an event connector is a two step process that involves writing a deployment descriptor and preparing the appropriate templates to manage the data. The connector descriptor contains information on the following:

• Basic configuration parameters required by enterprise manager.

• Specification for Service methods

  Service methods are used to bind the method name with Web service endpoints that define how the connector framework communicates with external systems.

• Specification for template registration

  A template is registered based on the information provided in the element. A connector deployment descriptor can have an optional list of up to 50 template registration elements.

• Specification for SOAP header authentication (optional)

Defining the Connector Descriptor File

Define a connector descriptor XML file to describe the connector metadata and the configuration properties of the connector, such as Web service end points and authentication schema.

Key points to remember while constructing the constructor descriptor:

• The connector descriptor file name must be connectorDeploy.xml

• The XML file should adhere to schema connectorDeploy.xsd

Refer to the sample connectorDeploy.xml in Appendix C, "MOM Event Connector Samples" for reference implementation. The following table provides a break-down of the sections of conenctorDeploy.xsd and explains what each section does.

<Name>Microsoft Operations Manager  Connector</Name>
  <Version>12.1.0.1.0</Version>
  <EMCompatibleVersion>12.1.0.1.0</EMCompatibleVersion>
  <Description>Microsoft Operations Manager  Integration with Enterprise Manager</Description>
  <Category>EventConnector</Category>
  <ConfigVariable required="true">
    <VariableName>SETUP_NAME</VariableName>
    <DisplayName>MOM Registered Connector Name</DisplayName>
  </ConfigVariable>
  <ConfigVariable required="true">
    <VariableName>RESOLUTION_STATE</VariableName>
    <DisplayName>Resolution State</DisplayName>
  </ConfigVariable>

<Service>
    <Method>cleanup</Method>
    <WebServiceEndpoint>
      <![CDATA[http://[server]:1271/ConnectorServiceV2.asmx]]>
    </WebServiceEndpoint>
    <SOAPAction>http://www.microsoft.com/EnterpriseManagement/Mom/Connector/V2/Cleanup</SOAPAction>
  </Service>

<TemplateRegistration>
    <FileName>setup_request.xml</FileName>
    <InternalName>setup</InternalName>
    <TemplateName>Setup</TemplateName>
    <TemplateType>OutboundXML</TemplateType>
    <Description>This is the request xml file for setup method</Description>    
  </TemplateRegistration>

<SOAPHeaderAuthentication>
    <Username required="true">
      <VariableName>USERNAME</VariableName>
      <DisplayName>Username</DisplayName>
    </Username>
    <Password>
      <VariableName>PASSWORD</VariableName>
      <DisplayName> Password</DisplayName>
    </Password>
    <AuthVariable>
      <VariableName>AUTHENTICATION</VariableName>
      <DisplayName>Authentication</DisplayName>
    </AuthVariable>
    <AuthVariable>
      <VariableName>LOCALE</VariableName>
      <DisplayName>Locale</DisplayName>
    </AuthVariable>
    <AuthVariable>
      <VariableName>TIMEZONE</VariableName>
      <DisplayName>Timezone</DisplayName>
    </AuthVariable>
 
    <SOAPHeader>
     <![CDATA[
     ]]>
    </SOAPHeader>
  </SOAPHeaderAuthentication>

Service Definition

The event connector service operations defined in the following table are supported in the current release:

The following are the key points for the above mentioned services:

• The service names in the connector descriptor should exactly match the names defined in Table 2-2, "Connector Service Operations" (case sensitive).

• Setup and initialize are called in the order when the connector is configured if they're defined.

• Uninitialize and cleanup are opposite actions to initialize and setup.

  Uninitialize can be defined if initialize is defined. Cleanup can be defined if setup is defined. If defined, the services are called in the order of uninitialize and cleanup when the connector is deleted.

• createEvent and updateEvent are called to forward an event from Enterprise Manager to an external system generated through event rules.

The following is an example for setup service:

<Service>
          <Method>setup</Method>
              <WebServiceEndpoint>....</WebServiceEndpoint>
              <SOAPAction>.......</SOAPAction>
   </Service>

Template Definition

Templates contains data that gets transformed while sending a request and receiving a response. A template can be defined as an XML or XSL file for a particular service operation in Enterprise Manager.

The following are the guidelines for defining any template:

• The internal name should be the same as the method name (case sensitive)

• The template type should be:

  InboundXSL for response xsl, 
   OutboundXSL for request xsl, and 
   OutboundXML for request xml
  

• The template filename is no longer important, but we recommend using the following:

  <methodName>_request.xml, 
  <methodName>_request.xsl, and 
  <methodName>_response.xsl.
  

  For example:

  <TemplateRegistration>
      <FileName>setup_request.xml</FileName>
      <InternalName>setup</InternalName>
      <TemplateName>Setup</TemplateName>
      <TemplateType>OutboundXML</TemplateType>
      <Description>This is the request xml file for setup method</Description>    
   </TemplateRegistration>
  

Template Registration

Coding template registration XML or XSL is driven by the following:

• Defined set of schema definition (XSD).

• Target external system attributes.

Table illustrate the list of schema definition for Enterprise Manager Event Connector.

The following are the key points for defining the request templates:

• The setup, initialize, uninitialize, and cleanup services require request XML template files to be defined.

  The template request XML is used if the information to be passed is already defined as a connector variable element. The connector variable can be defined using:

  • Connector Deployment Descriptor at the time of registration

  • Response message of any of these services.

• The createEvent and updateEvent services require only XSL files to be defined.

  The template request XSL is used to generate a request with event attributes generated within Enterprise Manager. These requests require mapping within Enterprise Manager event object and target external system attributes.

• Defining template request XSLs is optional if you have defined request XML. Ideally there won't be any need for this scenario.

• You can use the EMEvent.xsd schema to decide which Enterprise Manager fields you want to make available for mapping when sending events to external systems.

The following are the key points for defining the response templates:

• You can define the response template (XSL) based on the XSD defined in Table 2-3, "Event Connector Template XSD".

• Template response XSL are optional.

  If no response transformation (XSL) is defined, then any data returned by an external system within the response XML will not be persisted. This is an ideal implementation for an operation not concerned with external system response data.

• For createEvent and updateEvent services, you can use the EMEventResponse.xsd schema to decide how to transform the response from external systems to a response understandable by Enterprise Manager.

After the transformation, Enterprise Manager expects a <SuccessFlag> and one of the following elements depending on the value:

• True

  Enterprise Manager expects an <externalEventID>, which is the ID of the event in the external system. This is used to update the event in the future.

• False

  Enterprise Manager expects an <ErrorMessage>. Enterprise Manager annotates the event with the externalEventID or ErrorMessage.

Refer to following sample template files in Table 2-4, "Sample Template List" for reference MOM event connector implementation:

Packaging and Deploying the Connector

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 XSL template files as a .jar file

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

2. Prepare the manifest file

   The following table lists the Key attributes of self update manifest files:

   Table 2-5 Self Update Manifest File Attributes

   Name	Description
   EntityType	Value is core_connector
   EntityTypeVersion	Current release version. Value=12.1.0.1.0
   Attribute @Name=connector_type	Connector type name
   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 following example shows the code for the connector_manifest.xml file:

   <EntityInstanceList xmlns="http://www.oracle.com/EnterpriseGridControl/SelfUpdateManifest">
    <EntityInstance xmlns="http://www.oracle.com/EnterpriseGridControl/SelfUpdateManifest" EntityTypeVersion="11.2.0.1.0" EntityType="core_connector" Maturity="PRODUCTION" Vendor="Oracle" PluginID="oracle.sysman.core">
    <Description>
    <![CDATA[ BMC Remedy Service Desk Connector - 12.1.0.2.0
     ]]>
     </Description>
    <AttributeList>
     <Version>12.1.0.2.0</Version>
     <Attribute Name="connector_type" Value="Sample SCOM Connector" Label="Sample SCOM Connector" />
     <Attribute Name="connector_category" Value="EventConnector" Label="Event Connector" />
     </AttributeList>
    <Readme>
    <![CDATA[   Oracle Management Connector for SCOM integrates Oracle Enterprise Manager Cloud Control's proactive alert detect
   ion and resolution features with BMC's Remedy 7.0 Service Desk capabilities to provide a seamless workflow for incident mana
   gement and resolution.
     Change Logs:
     12.1.0.2.0
      - Miscellaneous bug fixes
      - Performance enhancements
     ]]>
     </Readme>
     <DependsOn />
    <ArchiveList>
     <Archive Filename="scomconnector.jar" IsMDS="false" />
     <Archive Filename="SCOM_webservices_adapter.jar" IsMDS="false" />
     </ArchiveList>
    <CustomData>
    <![CDATA[
     ]]>
     </CustomData>
    </EntityInstance>
    </EntityInstanceList>
   

   Refer to the self update schema definition from following location for a complete list of attributes:

   $ORACLE_HOME/sysman/emSDK/core/selfupdate/model/SelfUpdateManifest.xsd
   

3. Configure the emedk tool

   The emedk tool can be configured by following instructions from the Enterprise Manager user interface. The path is Setup > Extensibility > 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-6 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=\ hostname\
   [-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-7 describes the connector archive command options.

   Table 2-7 Connector Archive Command Options

   Options	Description
   -file	The complete pathname 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. Go to Self-Update Home page

   The connector will be shown as downloaded.

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