1 Building a Help Desk Connector

This chapter provides information you need to build a help desk connector and integrate it with Enterprise Manager. This chapter has following sections:

Introduction
Prerequisites
Defining XML and XSL Files
Packaging and Deploying the Help Desk Connector
Configuring the Help Desk Connector
Testing the Help Desk Configuration
Enabling an SSL Connection for HTTPS

Introduction

Enterprise Manager Release 11g provides a Management Connector Framework (referred to as Connector Framework) to allow developers to build help desk connectors based on metadata (XMLs and XSLs).

Help desk connectors created through the framework inherit the following features:

Auto Ticketing — Lets you describe the connector to automatically open or update a ticket whenever an alert is triggered in Enterprise Manager. You can specify the set of alerts for which tickets must be opened and the alert severity for which this should happen. You can do this with Notification Rules, the user-defined rules that define the criteria by which notifications should be sent for alerts.
Manual Ticketing — Lets you manually open a ticket from Enterprise Manager console based on an open alert in Enterprise Manager. The connector populates the ticket with details based on the alert and the ticket template.

To utilize these ticketing features for your own help desk system, you need to provide a set of metdata files. The categories of metadata files listed in Table 1-1 are required for building a help desk connector:

Table 1-1 Metadata File Categories

Category	Type	Description
Connector Descriptor	XML	Lets you customize the integration for your ticketing system. Through XML you describe how the configuration UI pages should be generated in this file.
Ticket Templates	XSLT	Describe how a ticket is filled out in the context of an event. Ticket templates explain the mappings from Enterprise Manager alert data fields to the corresponding ticket data fields in ticket creation and update through the XSLT language.
Response Transformations	XSLT	Normalize the ticketing system Web service's response data into a format that the Ticketing Connector Framework can understand.

Prerequisites

Before building a help desk connector, ensure that your ticketing system meets the following pre-requisites:

The ticketing system exposes the following Web services:
- Create Ticket
- Get Ticket
- Update Ticket
The Web service is of Document Literal style
Web service supports Simple Object Access Protocol (SOAP) header-based authentication.

Defining XML and XSL Files

The section provides details of various XML and XSL files that you must define for building a help desk connector.

Oracle recommends you to refer to the example metadata files available at the following location:

$OMS_HOME/sysman/connector/Remedy_Connector

Note:

Do not make changes to any of the files in this location.

Connector Descriptor XML 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, authentication schema, and ticket URL pattern. This XML file defines how the configuration pages are dynamically generated for the connector.

Example 1-1 conforms to the connectorType.XSD file. You can use it as a template by replacing the highlighted elements with proper values.

Note:

This sample file is located in the following directory:

$ORACLE_HOME/sysman/connector/common/schema/connectorType.xsd

The descriptor XML file for Remedy Connector is named RemedyDeploy.xml.

Example 1-1 Sample Connector Descriptor XML File

<?xml version='1.0' encoding='UTF-8'?>
<ManagementConnector xmlns="http://xmlns.oracle.com/sysman/connector">
  <Name>specify the connector name</Name>
  <Version>specify the 5-digit version, e.g., 1.0.0.0.0</Version>
  <Description>specify a short description</Description>
  <!-- Category is fixed to TicketingConnector. -->
  <Category>TicketingConnector</Category>
  <TicketingConnector>
    <!-- authentication element is optional. If authentication is required, the SOAP header should match the Data element in this section. Other elements are displayed on the default UI to collect data to generate the Data element. -->
    <Authentication>
      <Username>
        <AttributeName>specify the username_element_name</AttributeName>
        <DisplayName>specify the label</DisplayName>
      </Username>
      <Password>
        <AttributeName>specify the password_element_name</AttributeName>
        <DisplayName>specify the display label</DisplayName>
      </Password>
      <Attribute>
        <AttributeName>specify attribute other than username and password</AttributeName>
        <DisplayName>specify display label</DisplayName>

      </Attribute>
      <!-- Attribute element can repeat. -->
      <Data>
        <![CDATA[
          specify how authentication element should appear in SOAP header
        ]]>
      </Data>
    </Authentication>
    <TicketingService>
      <Method>createTicket</Method>

      <WebServiceEndpoint>
        <![CDATA[specify URL]]>
      </WebServiceEndpoint>
      <SOAPAction>specify the SOAP action</SOAPAction>
      <Namespace>specify the namespace</Namespace>
      <NamespacePrefix>specify the namespace prefix</NamespacePrefix>
    </TicketingService>
    <TicketingService>
      <Method>updateTicket</Method>
      <WebServiceEndpoint>

        <![CDATA[specify the URL]>
      </WebServiceEndpoint>
      <SOAPAction>specify the SOAP action</SOAPAction>
      <Namespace>specify the namespace</Namespace>
      <NamespacePrefix>specify the namespace prefix</NamespacePrefix>
    </TicketingService>
  <!-- BaseURL element is for the default UI for ticketing connectors, the following value should not be changed. -->
  <BaseURL>/em/console/connector/ticket/ticketConnectorConfig</BaseURL>
    <!-- ExternalURL is used to generate the ticket URL. -->
    <ExternalURL>

      <!-- Strings in brackets ([]) are user variables, i.e., the values to be collected from UI. Strings in {} are substitution variables, i.e., the values to be collected from the web service response (they need to have the same element names as the ones from the response XML. The following is an example. -->
      <Pattern>
        <![CDATA[specify the URL as http://[Web Server]/arsys/servlet/ViewFormServlet?form=[HelpDesk Case Form Name]&server=[ARServer Name]&eid={Case_ID}]]>
      </Pattern>
      <UserVariable>specify the Web server</UserVariable>
      <UserVariable>specify the HelpDesk Case Form Name</UserVariable>
      <UserVariable>specify the ARServer Name</UserVariable>
      <SubstitutionVariable>specify the Case_ID</SubstitutionVariable>
    </ExternalURL>
  </TicketingConnector>
</ManagementConnector>

The Table 1-2 provides a break-down of the file and explains what each section does:

Table 1-2 Connector Descriptor XML File Explained

Metadata File Sections Explanation

Metadata File Sections	Explanation
<Authentication> <Username> <AttributeName>specify the username_element_name</AttributeName> <DisplayName>specify the label</DisplayName> </Username> <Password> <AttributeName>specify the password_element_name</AttributeName> <DisplayName>specify the display label</DisplayName> </Password> <Attribute> <AttributeName>specify attribute other than username and password</AttributeName> <DisplayName>specify display label</DisplayName> </Attribute> <!-- Attribute element can repeat. --> <Data> <![CDATA[ specify how authentication element should appear in SOAP header ]]> </Data> </Authentication>	(Optional) This section allows you to describe the authentication schema of ticketing system Web services. The authentication section of the Configure Management Connector page (Figure 1–2) is generated based on this section. The username, password, and additional text fields are populated based on this section. The `<AttributeName>` tag marks the name of the attribute in the Web services XML document. The `<DisplayName>` tag describes how the corresponding text-box should be labeled.
<TicketingService> <Method>createTicket</Method> <WebServiceEndpoint> <![CDATA[specify URL]]> </WebServiceEndpoint> <SOAPAction>specify the SOAP action</SOAPAction> <Namespace>specify the namespace</Namespace> <NamespacePrefix>specify the namespace prefix</NamespacePrefix> </TicketingService> <TicketingService> <Method>updateTicket</Method> <WebServiceEndpoint> <![CDATA[specify the URL]> </WebServiceEndpoint> <SOAPAction>specify the SOAP action</SOAPAction> <Namespace>specify the namespace</Namespace> <NamespacePrefix>specify the namespace prefix</NamespacePrefix> </TicketingService> <BaseURL>/em/console/connector/ticket/ticketConnectorConfig</BaseURL>	This section allows you to specify configurations specific to the Ticketing System's Web services. For your Ticketing System's `create ticket` and `update ticket` Web services, you need to describe the corresponding SOAP action and namespace prefix in order to enable the framework to properly communicate with the Ticketing System. The `<WebServiceEndpoint>` tag describes the default Web service endpoint string to be displayed in the Web service section of the Management Connector page (Figure 1–2). `<BaseURL>` tag is for the default UI for help desk connectors. You should not edit the values.
<ExternalURL> <Pattern> <![CDATA[specify the URL as http://[Web Server]/arsys/servlet/ViewFormServlet?form=[HelpDesk Case Form Name]&server=[ARServer Name]&eid={Case_ID}]]> </Pattern> <UserVariable>specify the Web server</UserVariable> <UserVariable>specify the HelpDesk Case Form Name</UserVariable> <UserVariable>specify the ARServer Name</UserVariable> <SubstitutionVariable>specify the Case_ID</SubstitutionVariable> </ExternalURL> </TicketingConnector>	This section enables you to configure the Ticket Connector Framework to generate a ticket URL to your unique Ticketing System. The value of the `<Pattern>` tag describes the URL string, and how user configured variables are inserted into it. A textbox label pair is inserted into the Webconsole section for each `<UserVariable>` tag. The values that the users provide for each user variable is inserted into the URL pattern string accordingly. If there is a user variable `"X"` then the user input value replaces `"[X]"` when the ticket URL is generated. The `<SubstitutionVariable>` tag describes which tag from the Web service create ticket response should map into the URL pattern string. For example, if the Ticketing System create ticket Web service returns a tag `<TicketID>`, it will replace the text in the ticket URL pattern `{TicketID}`.

    <Authentication>
      <Username>
        <AttributeName>specify the username_element_name</AttributeName>
        <DisplayName>specify the label</DisplayName>
      </Username>
      <Password>
        <AttributeName>specify the password_element_name</AttributeName>
        <DisplayName>specify the display label</DisplayName>
      </Password>
      <Attribute>
        <AttributeName>specify attribute other than username and password</AttributeName>
        <DisplayName>specify display label</DisplayName>
      </Attribute>
      <!-- Attribute element can repeat. -->
      <Data>
        <![CDATA[
          specify how authentication element should appear in SOAP header
        ]]>
      </Data>
    </Authentication>

(Optional) This section allows you to describe the authentication schema of ticketing system Web services.

The authentication section of the Configure Management Connector page (Figure 1–2) is generated based on this section.

The username, password, and additional text fields are populated based on this section.

The <AttributeName> tag marks the name of the attribute in the Web services XML document.
The <DisplayName> tag describes how the corresponding text-box should be labeled.

    <TicketingService>
      <Method>createTicket</Method>
      <WebServiceEndpoint>
        <![CDATA[specify URL]]>
      </WebServiceEndpoint>
      <SOAPAction>specify the SOAP action</SOAPAction>
      <Namespace>specify the namespace</Namespace>
      <NamespacePrefix>specify the namespace prefix</NamespacePrefix>
    </TicketingService>
    <TicketingService>
      <Method>updateTicket</Method>
      <WebServiceEndpoint>
        <![CDATA[specify the URL]>
      </WebServiceEndpoint>
      <SOAPAction>specify the SOAP action</SOAPAction>
      <Namespace>specify the namespace</Namespace>
      <NamespacePrefix>specify the namespace prefix</NamespacePrefix>
    </TicketingService>
  <BaseURL>/em/console/connector/ticket/ticketConnectorConfig</BaseURL>

This section allows you to specify configurations specific to the Ticketing System's Web services.

For your Ticketing System's create ticket and update ticket Web services, you need to describe the corresponding SOAP action and namespace prefix in order to enable the framework to properly communicate with the Ticketing System.

The <WebServiceEndpoint> tag describes the default Web service endpoint string to be displayed in the Web service section of the Management Connector page (Figure 1–2).
<BaseURL> tag is for the default UI for help desk connectors. You should not edit the values.

    <ExternalURL>
      <Pattern>
        <![CDATA[specify the URL as http://[Web Server]/arsys/servlet/ViewFormServlet?form=[HelpDesk Case Form Name]&server=[ARServer Name]&eid={Case_ID}]]>
      </Pattern>
      <UserVariable>specify the Web server</UserVariable>
      <UserVariable>specify the HelpDesk Case Form Name</UserVariable>
      <UserVariable>specify the ARServer Name</UserVariable>
      <SubstitutionVariable>specify the Case_ID</SubstitutionVariable>
    </ExternalURL>
  </TicketingConnector>

This section enables you to configure the Ticket Connector Framework to generate a ticket URL to your unique Ticketing System.

The value of the <Pattern> tag describes the URL string, and how user configured variables are inserted into it.
A textbox label pair is inserted into the Webconsole section for each <UserVariable> tag.

The values that the users provide for each user variable is inserted into the URL pattern string accordingly. If there is a user variable "X" then the user input value replaces "[X]" when the ticket URL is generated.
The <SubstitutionVariable> tag describes which tag from the Web service create ticket response should map into the URL pattern string. For example, if the Ticketing System create ticket Web service returns a tag <TicketID>, it will replace the text in the ticket URL pattern {TicketID}.

connectorType.XSD

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns="http://xmlns.oracle.com/sysman/connector"
            targetNamespace="http://xmlns.oracle.com/sysman/connector"
            elementFormDefault="qualified" >
 
  <xsd:element name="ManagementConnector">
    <xsd:annotation>
      <xsd:documentation>Deployment Descriptor for Management Connectors</xsd:documentation>
    </xsd:annotation>
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Name" type="xsd:string"/>
        <xsd:element name="Version" type="xsd:string"/>
        <xsd:element name="Description" type="xsd:string"/>
        <xsd:element name="Category">
          <xsd:simpleType>
            <xsd:restriction base="xsd:string">
              <xsd:enumeration value="EventConnector"/>
              <xsd:enumeration value="TicketingConnector"/>
            </xsd:restriction>
          </xsd:simpleType>
        </xsd:element>
        <xsd:choice>
          <xsd:element name="EventConnector" type="EventConnector"/>
          <xsd:element name="TicketingConnector" type="TicketingConnector"/>
        </xsd:choice>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:complexType name="EventConnector">
    <xsd:sequence>

    <xsd:element name="IsNewTargetType" type="xsd:boolean"/>
      <xsd:element name="Authentication" type="Authentication" minOccurs="0"/>
      <xsd:element name="EventService" type="EventService" minOccurs="1" maxOccurs="unbounded"/>
      <xsd:element name="TargetResponse" type="Response" minOccurs="0"/>
      <xsd:element name="BaseURL" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="TicketingConnector">
    <xsd:sequence>
      <xsd:element name="Authentication" type="Authentication" minOccurs="0"/>
      <xsd:element name="TicketingService" type="TicketingService" minOccurs="1" maxOccurs="unbounded"/>
      <xsd:element name="BaseURL" type="xsd:string"/>
      <xsd:element name="ExternalURL" type="ExternalURL"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="EventService">
    <xsd:sequence>
      <xsd:element name="Method" maxOccurs="1">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:enumeration value="getNewAlerts"/>
            <xsd:enumeration value="getUpdatedAlerts"/>
            <xsd:enumeration value="acknowledgeAlerts"/>
            <xsd:enumeration value="setup"/>
            <xsd:enumeration value="initialize"/>
            <xsd:enumeration value="uninitialize"/>
            <xsd:enumeration value="cleanup"/>
            <xsd:enumeration value="updateAlerts"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="WebServiceEndpoint" type="xsd:string"/>
      <xsd:element name="SOAPAction" type="xsd:string" minOccurs="0"/>
      <xsd:element name="Namespace" type="xsd:string"/>
      <xsd:element name="NamespacePrefix" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>

 <xsd:complexType name="TicketingService">
    <xsd:sequence>
      <xsd:element name="Method" maxOccurs="1">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:enumeration value="createTicket"/>
            <xsd:enumeration value="updateTicket"/>
            <xsd:enumeration value="getTicket"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="WebServiceEndpoint" type="xsd:string"/>
      <xsd:element name="SOAPAction" type="xsd:string" minOccurs="0"/>
      <xsd:element name="Namespace" type="xsd:string"/>
      <xsd:element name="NamespacePrefix" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Authentication">
    <xsd:sequence>
      <xsd:element name="Username" type="Username"/>
      <xsd:element name="Password" type="Password"/>
      <xsd:element name="Attribute" type="Attribute" maxOccurs="unbounded" minOccurs="0"/>
      <xsd:element name="Data" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Username">
    <xsd:sequence>
      <xsd:element name="AttributeName" type="xsd:string"/>
      <xsd:element name="DisplayName" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Password">

    <xsd:sequence>
      <xsd:element name="AttributeName" type="xsd:string"/>
      <xsd:element name="DisplayName" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Attribute">
    <xsd:sequence>
      <xsd:element name="AttributeName" type="xsd:string"/>
      <xsd:element name="DisplayName" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="Response">
    <xsd:sequence>
      <xsd:element name="ScriptName" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="ExternalURL">
    <xsd:sequence>
      <xsd:element name="Pattern" type="xsd:string"/>
      <xsd:element name="UserVariable" type="xsd:string" maxOccurs="unbounded" minOccurs="0"/>
      <xsd:element name="SubstitutionVariable" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Default Ticket Template XSL Files

Ticket templates describe how Enterprise Manager alerts should be transformed into the messages (SOAP body XML) expected by the ticketing system. To ensure that the tickets generated are compatible with your help desk, you can use ticket templates to specify how ticket fields should be pre-filled when opening or updating a ticket based on an Enterprise Manager alert.

You can add new ticket templates or modify existing ticket templates. You should provide at least one ticket template with your help desk connector. The template should include the logic on how to transform the following requests:

Create Ticket
Get Ticket
Update Ticket
Reopen Ticket
Close Ticket

You can ship as many templates as needed. For example, you might choose to ship templates based on categories such as production database, development database, and test database, or priority, or combination of both. Oracle recommends that you ship at least two sets of templates: those that auto close and those that do not.

You can modify these templates or add more templates if required. You can delete the ticket templates from the user interface or upload them using emctl.

The fields available to map to a ticket are shown in Table 1–3:

Table 1-3 Enterprise Manager Data Fields

Data Fields	Description
EMUser	For auto-ticketing, this is the notification rule owner. For manual ticketing, this is the console user that triggered the ticket creation.
HDUser	Helpdesk user registered with the Connector; this is same as the user name specified for the WS authentication.
TicketID	Identifies the ticket associated with the current alert (this is available after ticket creation).
ConnectorID	Identifies the help desk connector that processed the event and issued the ticket creation or ticket update.
TargetType	Type of target that the alert is associated with. For example, `host`.
TargetName	Name of the target that the alert is associated with. For example, `Database1` or `stadc40.us.oracle.com`.
MetricColumn	Name of the metric that triggered the alert. For example, CPU Utilization(%).
MetricName	Category of the metric. For example, `Load` for the memory utilization alert.
KeyColumn	For metrics that monitor a set of objects, the KeyColumn indicates the type of object monitored. For example, for the Tablespace Space Used (%) metric that monitors tablespace objects, the KeyColumn is 'Tablespace Name'.
KeyValues	Key values associated with a key value base alert. For metrics that monitor a set of objects, KeyValues indicates the specific object that triggered the severity. For example, for the Tablespace Space Used (%) metric that monitors tablespace objects, KeyValues is 'USERS' if the USERS tablespace triggered at warning or critical severity.
Message	Description of the alert. For example, CPU Utilization is 100%, crossed warning (80), or critical (95) threshold.
Severity	Severity of the alert: `critical, warning, clear,` or `down.`
CollectionTime	Timestamp of an alert occurrence.
EventPageURL	Enterprise Manager console URL to the alert details page of the alert.
NotificationRuleName	Name of the notification rule that generated the notification during auto-ticketing.
TargetTimezone	Time zone of the target associated with the alert.
GracePeriodCheckMade	Value `Yes` indicates that the alert is cleared since the last update or creation, but is within the configured grace period.
TargetHost	Name of the server hosting the target that generated the alert.
EventId	Enterprise Manager internal IDs for Target, Metric, and Key.
SeverityCode	Corresponding code for the Severity element. Severity Code has a one-to-one mapping relationship in the order listed. Therefore the first Severity Code entry (ex: <xsd:enumeration value="15"/>) is mapped to the first Severity Element (ex: <xsd:enumeration value="Clear"/>).

Schema

The following schema describes the model that contains the attributes in Table 1-3:

<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns="http://xmlns.oracle.com/sysman/connector/tt"
            targetNamespace="http://xmlns.oracle.com/sysman/connector/tt"
            elementFormDefault="qualified">
 
  <xsd:element name= "EventModel" type="EMEventModel"/>
 
  <xsd:complexType name="EMEventModel">
                <xsd:sequence>
      <xsd:element name="TicketId" type="xsd:string" minOccurs="0" maxOccurs="1" />
      <xsd:element name="ConnectorId" type="xsd:string" minOccurs="1" maxOccurs="1" />
      <xsd:element name="EventId" type="EventIdType" minOccurs="1" maxOccurs="1" />
        <xsd:element name="TargetType" type="xsd:string" minOccurs="1" maxOccurs="1" />
        <xsd:element name="TargetName" type="xsd:string" minOccurs="1" maxOccurs="1" />
        <xsd:element name="MetricColumn" type="xsd:string" minOccurs="1" maxOccurs="1" />
        <xsd:element name="MetricName" type="xsd:string" minOccurs="1" maxOccurs="1" />
        <xsd:element name="KeyColumn" type="xsd:string" minOccurs="0" maxOccurs="1" />
        <xsd:element name="KeyValues" type="xsd:string" minOccurs="0" maxOccurs="unbounded" />
        <xsd:element name="Message" type="xsd:string" minOccurs="1" maxOccurs="1" />
        <xsd:element name="Severity" type="SeverityType" minOccurs="1" maxOccurs="1" />
        <xsd:element name="SeverityCode" type="SeverityCodeType" minOccurs="1" maxOccurs="1" />
        <xsd:element name="CollectionTime" type="xsd:dateTime" minOccurs="1" maxOccurs="1" />
        <xsd:element name="EventPageURL" type="xsd:string" minOccurs="0" maxOccurs="1" />
      <xsd:element name="EMUser" type="xsd:string" minOccurs="1" maxOccurs="1" />
      <xsd:element name="HDUser" type="xsd:string" minOccurs="1" maxOccurs="1" />
      <xsd:element name="NotificationRuleName" type="xsd:string" minOccurs="0" maxOccurs="1" />
      <xsd:element name="TargetHost" type="xsd:string" minOccurs="1" maxOccurs="1" />
      <xsd:element name="GracePeriodCheckMade" type="xsd:string" minOccurs="0" maxOccurs="1" />
      <xsd:element name="TargetTimezone" type="xsd:string" minOccurs="1" maxOccurs="1" />
    </xsd:sequence>
        </xsd:complexType>
 
  <xsd:complexType name="EventIdType">

    <xsd:sequence>
      <xsd:element name="TargetId" type="xsd:string" minOccurs="1" maxOccurs="1"/>
      <xsd:element name="MetricId" type="xsd:string" minOccurs="1" maxOccurs="1"/>
      <xsd:element name="KeyId" type="xsd:string" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
  </xsd:complexType>
 
        <xsd:simpleType name="SeverityType">
        <xsd:restriction base="xsd:string">
        <xsd:enumeration value="Clear" />
        <xsd:enumeration value="Info" />
        <xsd:enumeration value="Warning" />
        <xsd:enumeration value="Critical" />
        <xsd:enumeration value="Agent Unreachable Clear" />
      <xsd:enumeration value="Blackout End" />
      <xsd:enumeration value="Blackout Start" />
      <xsd:enumeration value="Metric Error End" />
      <xsd:enumeration value="Metric Error Start" />
      <xsd:enumeration value="Unknown" />
        </xsd:restriction>
        </xsd:simpleType>
 
        <xsd:simpleType name="SeverityCodeType">
        <xsd:restriction base="xsd:string">
        <xsd:enumeration value="15" />
        <xsd:enumeration value="18" />
        <xsd:enumeration value="20" />
        <xsd:enumeration value="25" />
        <xsd:enumeration value="115" />
      <xsd:enumeration value="125" />
      <xsd:enumeration value="215" />
      <xsd:enumeration value="225" />
      <xsd:enumeration value="315" />
      <xsd:enumeration value="325" />
        </xsd:restriction>
        </xsd:simpleType>
</xsd:schema>

Sample Template

Example 1–2 shows a sample ticket template for the Remedy Connector. It creates Remedy tickets with the default categorization high priority, and fills the description with alert information.

Note:

This sample file is located in the following directory:

$ORACLE_HOME/sysman/connector/Remedy_Connector

On updates, the field for work log is updated with a history of the latest changes. The template closes the ticket when the alert clears.

Example 1-2 Sample Ticket Template for Remedy Connector

<?xml version='1.0' encoding='UTF-8'?>
<xsl:transform version="1.0" 
              xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
               xmlns:ns0="http://xmlns.oracle.com/sysman/connector/tt"
               targetNamespace="http://xmlns.oracle.com/sysman/connector/tt"
               elementFormDefault="qualified">
  <!-- 
  This template creates an incident type ticket with default categorization
  (Category: Default, Type:Default, Item:Default), and high priority. On update,
  the description and message fields are updated, and the ticket is closed if the
  associated alert has cleared. 
  -->
  
  <xsl:template match="ns0:EventModel">
    <xsl:choose>
      <xsl:when test="normalize-space(ns0:TicketId) = ''">
        <urn:Create_Helpdesk_Case xmlns:urn="urn:HelpDesk_Submit_Service">   
        
           <!-- EDIT THE TAG VALUES BELOW TO CHANGE HOW A TICKET IS FILLED
                DURING TICKET CREATION. REFER TO THE REMEDY HELPDESK MANUAL
                FOR DESCRIPTION OF THESE HELPDESK SUPPORT DATAFIELDS-->

                      <urn:Case_Type>Incident</urn:Case_Type>          <urn:Category>Default</urn:Category>          <urn:Department></urn:Department>          <urn:Description>              Ticket created by EM Remedy Connector.              --------------------------------------              EM User: <xsl:value-of select="ns0:EMUser"/>              Event Information:              Target Type: <xsl:value-of select="ns0:TargetType"/>              Metric Column: <xsl:value-of select="ns0:MetricColumn"/>              Metric Name: <xsl:value-of select="ns0:MetricName"/>              <xsl:choose>              <xsl:when test="normalize-space(ns0:KeyColumn) != ''">              Key Column: <xsl:value-of select="ns0:KeyColumn"/>              Key Values: <xsl:value-of select="ns0:KeyValues"/>               </xsl:when>              </xsl:choose>               Severity: <xsl:value-of select="ns0:Severity"/>              Collection Time: <xsl:value-of select="ns0:CollectionTime"/>              Target Host: <xsl:value-of select="ns0:TargetHost"/>              <xsl:choose>              <xsl:when test="normalize-space(ns0:NotificationRuleName) != ''">              Notification Rule: <xsl:value-of select="ns0:NotificationRuleName"/>               </xsl:when>

 </xsl:choose>  
              URL: <xsl:value-of select="ns0:EventPageURL"/>
          </urn:Description>
          <urn:Escalated></urn:Escalated>
          <urn:Hotlist></urn:Hotlist>
          <urn:Item>Default</urn:Item>
          <urn:Office></urn:Office>
          <urn:Orig_Submitter>
            <xsl:value-of select="ns0:HDUser"/>
          </urn:Orig_Submitter>
          <urn:Pending></urn:Pending>
          <urn:Phone_Number></urn:Phone_Number>
          <urn:Priority>High</urn:Priority>
          <urn:Region></urn:Region>
          <urn:Request_Urgency>High</urn:Request_Urgency>
          <urn:Requester_Login_Name>
            <xsl:value-of select="ns0:HDUser"/>
          </urn:Requester_Login_Name>
          <urn:Requester_Name>
            <xsl:value-of select="ns0:HDUser"/>
          </urn:Requester_Name>
          <urn:Site></urn:Site>
          <urn:Source>NMP</urn:Source>
          <urn:Status>New</urn:Status>
          <urn:Summary>
            <xsl:value-of select="ns0:Message"/>
          </urn:Summary>
          <urn:Type>Default</urn:Type>
          <urn:WorkLog>
              Severity: <xsl:value-of select="ns0:Severity"/>
              Collection Time: <xsl:value-of select="ns0:CollectionTime"/>
          </urn:WorkLog>
          <urn:Create_Time></urn:Create_Time>
        </urn:Create_Helpdesk_Case>
      </xsl:when>
      <xsl:otherwise>

        <urn:SetBy_Case_ID xmlns:urn="urn:HelpDesk_Modify_Service_w_Wlog">
 
          <!--  UNCOMMENT THE TAGS YOU WISH TO HAVE MODIFIED WHENEVER
              THE TICKET IS UPDATED, AND GIVE THEM DESIRED VALUES   -->
 
         <!-- <urn:Accounting_Code></urn:Accounting_Code>           -->
         <!--  <urn:Assignee_Login_Name></urn:Assignee_Login_Name>  -->
         <!--  <urn:Case_Type></urn:Case_Type>                      -->
         <!--  <urn:Category></urn:Category>                        -->
         <!--  <urn:Department></urn:Department>                    -->
              <urn:Description>
              Ticket updated by EM Remedy Connector.
              --------------------------------------
              EM User: <xsl:value-of select="ns0:EMUser"/>
 
              Event Information:
              Target Type: <xsl:value-of select="ns0:TargetType"/>
              Metric Column: <xsl:value-of select="ns0:MetricColumn"/>
              Metric Name: <xsl:value-of select="ns0:MetricName"/>
              <xsl:choose>
              <xsl:when test="normalize-space(ns0:KeyColumn) != ''">
              Key Column: <xsl:value-of select="ns0:KeyColumn"/>
              Key Values: <xsl:value-of select="ns0:KeyValues"/>
              </xsl:when>
              </xsl:choose>
              Severity: <xsl:value-of select="ns0:Severity"/>
              Collection Time: <xsl:value-of select="ns0:CollectionTime"/>
              Target Host: <xsl:value-of select="ns0:TargetHost"/>
              <xsl:choose>
              <xsl:when test="normalize-space(ns0:NotificationRuleName) != ''">
              Notification Rule: <xsl:value-of select="ns0:NotificationRuleName"/>
              </xsl:when>
              </xsl:choose>
              URL: <xsl:value-of select="ns0:EventPageURL"/>
          </urn:Description>
          <!-- <urn:Escalated></urn:Escalated>                      -->
          <!-- <urn:Hotlist></urn:Hotlist>                          -->
          <!-- <urn:Item></urn:Item>                                -->
          <!-- <urn:Office></urn:Office>                            -->
          <!-- <urn:Pending></urn:Pending>                          -->
          <!-- <urn:Phone_Number></urn:Phone_Number>                -->
          <!-- <urn:Priority></urn:Priority>                        -->
          <!-- <urn:Region></urn:Region>                            -->
          <!-- <urn:Request_Urgency></urn:Request_Urgency>          -->
          <!-- <urn:Requester_Login></urn:Requester_Login>          -->
          <!-- <urn:Requester_Name></urn:Requester_Name>            -->
          <!-- <urn:Site></urn:Site>                                -->
          <!-- <urn:Solution_Description></urn:Solution_Description>-->
          <!-- <urn:Solution_Summary></urn:Solution_Summary>        -->
          <!-- <urn:Source></urn:Source>                            -->
          <!-- <urn:Status></urn:Status>                            -->
          <xsl:choose>
           <xsl:when test="ns0:Severity = 'Clear'">
              <urn:Status>Closed</urn:Status>
            </xsl:when>
            <xsl:when test="ns0:Severity = 'Agent Unreachable Clear'">
              <urn:Status>Closed</urn:Status>
            </xsl:when>
            <xsl:when test="ns0:GracePeriodCheckMade = 'Yes'">
              <urn:Status>Assigned</urn:Status>
            </xsl:when>
          </xsl:choose>
          <!-- <urn:Submitted_By></urn:Submitted_By>                -->
          <!-- <urn:Summary></urn:Summary>                          -->
          <!-- <urn:Type></urn:Type>                                -->
          <urn:Case_ID>
            <xsl:value-of select="ns0:TicketId"/>
          </urn:Case_ID>
          <urn:WorkLog>
              Severity: <xsl:value-of select="ns0:Severity"/>
              Collection Time: <xsl:value-of select="ns0:CollectionTime"/>
          </urn:WorkLog>
        </urn:SetBy_Case_ID>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
</xsl:transform>

Response XSL Files

A response XSL file is needed for the action Get Ticket. The file must be named as shown:

getTicket_response.xsl

Packaging and Deploying the Help Desk Connector

To complete the integration of the connector, package all XML and XSL files (defined in the section Defining XML and XSL Files) as a .jar file and then deploy, register, and configure. To do this:

Copy the .jar file to the host that is running the Oracle Management Service (OMS). For multiple OMSs, you have to copy the .jar file for all OMSs.
Run the following command on all OMSs:

emctl extract_jar connector [-jar <jarfile>] [-cname <connectorName>]

Files are extracted from the .jar file to the following directory:

$ORACLE_HOME/sysman/connector/connector name

Note:
connector name is the name of the connector with spaces (if any) replaced by underscores ("_").

The full emctl command usage for the extract command is:
```
emctl extract_jar connector [-jar <jarfile>] [-cname <connectorName>]
      -jar          Connector Jar File(full path)
      -cname        Connector Name
```
Deploy the connector by running the following command:

emctl register_connector connector [-dd <connectorType.xml>] [-repos_pwd <repos password>]
Example 1-4 Deploying the Help Desk Connector
```
emctl register_connector connector Remedy_Connector.xml  $emHost $emPort $emSID sysman $sysmanPwd
```
After you deploy a connector, it appears in the Management Connector page (Figure 1–1). After you configure the connector, it is functional.

Note:
See also emctl Parameters

The full emctl command usage for the register_connector command is:
```
emctl register_connector connector [-dd <connectorType.xml>] [-repos_pwd <repos password>]
      -dd           Connector Deployment Descriptor File(full path)
      -repos_pwd    Enterprise Manager Root (SYSMAN) Password
```
For every ticket template shipped as part of the connector, run the following command to upload new or modified ticket templates:

emctl register_template connector [-t <template.xsl>] [-repos_pwd <repos password>] [-ctname <connectorTypeName>] [-cname <connectorName>] [-iname <internalName>] [-tname <templateName>] [-ttype <templateType>] [-d <description>]
Example 1-5 Uploading New or Modified Help Desk Ticket Templates
```
emctl register_ticket_template connector Remedy_DefaultCategory_LowPriority.xsl $emHost $dbPort $dbSID sysman $sysmanPwd "Remedy Connector" "Remedy Connector" "Low Priority Template" "This template creates a ticket with low priority and default categorization"
```

Log into Enterprise Manager Console and do the required configurations.

Parameter	Description
`connectorType.xml`	The connector deployment descriptor.
`ticketTemplate.xsl`	Fully qualified name of the ticket template file. The file resides in the Connector home directory: `$OMS_HOME/sysman/connector/Remedy_Connector` Oracle recommends that you use intuitive names since there might be notification methods created with the same names, and you have to choose one of them when you use the Auto Ticketing feature. Use `xsl` as the file extension since the format is XSLT. For example, `Remedy_DefaultCategory_LowPriority.xsl.` If the file is in a different directory, provide the complete path for the file.
`server`	Host name of the Enterprise Manager repository.
`port`	Listener port of the repository.
`database_sid/ Service Name for RAC DB`	Repository database instance ID or service name if you are using a RAC database as the repository.
`username`	Specify `SYSMAN.`
`password`	Password for `SYSMAN.`
`connectorTypeName`	Connector type name you define in `connectorType.xml`. For example, "`My Ticketing Connector".` The double quotes ("") are mandatory.
`connectorName`	Connector name. This should be the same as the connector type name. For example, `" My Ticketing Connector"`
`templateName`	An intuitive name for the ticket template that will be displayed in Enterprise Manager.
`description`	A short description for the ticket template. This description is also displayed in Enterprise Manager.
`jar`	Jar file, full jar file path
`cname`	Connector name
`ctname`	Connector type name
`dd`	Connector descriptor file, full path
`repos_pwd`	Enterprise Manager root (SYSMAN) password
`t`	Template file, full path
`iname`	Internal name (For details about this parameter, you can refer to the existing Connector documentation.)
`tname`	Template name
`ttype`	Template type
`d`	Template description

Configuring the Help Desk Connector

To configure the help desk connector:

As Super Administrator, log in to the Enterprise Manager console.
Click Setup.

The Overview of Setup page appears (Figure 1–1).

Figure 1-1 Management Connectors Page
Click Management Connectors in the left pane.

The Management Connector Setup page appears. The row for the help desk connector should appear in this page.
Click the Configure icon for the connector that you registered.

The General tab of the Configure Management Connector page appears (Figure 1–2).

Figure 1-2 Configure Management Connector Page for Remedy Connector
Configure the following:
- Connection settings
  - WS End Points
  - Related Fields
- Web Console settings
- Grace Period
Click OK. The Management Connector Setup page reappears. The help desk connector row should have a check mark in the Configured column.
In the Configure Management Connector page, go to the Ticket Templates tab and ensure that ticket templates are successfully loaded.

For more detailed configuration information, see the associated chapter for your particular help desk connector, such as Remedy or Siebel, in the Oracle Enterprise Manager Connector Installation and Configuration Guide.

Testing the Help Desk Configuration

Rather than saving your configuration without knowing whether it is correct as intended, you can use the Ticket Number field in Table 1–2 to test the connection to this system. To customize the test to suit your needs, Oracle has provided the required default Remedy files that you can modify for other help desk ticketing systems, such as Siebel. The basic process to use these files is as follows:

Modify the transformation file (XSLT) to transform the generic getTicket request into connector-compliant XML data.
Modify the transformation file (XSLT) to transform the connector-compliant getTicket response back to the generic XML data.

The following sections explain the files and code used for this process.

Transforming the Request into Connector-compliant XML Data

The generic getTicket request is defined in the getTicket_request.xsd XML schema, which is located here:

$ORACLE_HOME/sysman/connector/common/schema

The content of this file is shown below:

<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="getTicketRequest">
 <xsd:complexType>
  <xsd:sequence>
   <xsd:element name="ticketID" type="xs:string"/>
  </xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

According to this schema, a sample generic getTicket request for any help desk connector is as follows:

<getTicketRequest>
             <ticketID> … </ticketID>
</getTicketRequest>

This is generated by the Management Connector Framework, which an XSLT transformation file, getTicket_request.xsl, needs to transform into connector-compliant XML data. The transformation file for Remedy Connector is located here:

$ORACLE_HOME/sysman/connector/<Remedy_Connector>/getTicket_request.xsl

The content of this XSLT file is shown below:

<?xml version='1.0' encoding='UTF-8'?>
<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:template match="getTicketRequest">
        <urn:GetListBy_Case_ID xmlns:urn="urn:HelpDesk_Query_Service">
                <urn:Case_ID>
                        <xsl:value-of select="ticketID/text()"/>
                </urn:Case_ID>
        </urn:GetListBy_Case_ID>
    </xsl:template>
</xsl:transform>

For help desk connectors other than Remedy, you need to modify this XSLT file and place it in a similar location as shown for the Remedy Connector above. The file should transform the generic getTicket request to data acceptable to the ticketing system, as shown below for a Remedy system:

<urn:GetListBy_Case_ID xmlns:urn="urn:HelpDesk_Query_Service" >
        <urn:Case_ID>HD0000000016686</urn:Case_ID>
</urn:GetListBy_Case_ID>

Transforming the Response Back to the Generic XML Data

The generic getTicket response that the management connector framework can accept is defined by the getTicket_response.xsd XML schema, which is located here:

$ORACLE_HOME/sysman/connector/common/schema

The content of this file is shown below:

<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="getTicketResponse">
 <xsd:complexType>
  <xsd:sequence>
   <xsd:element name="ticketID" type="xs:string"/>
  </xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

According to this schema, a sample generic getTicket response for any help desk connector is as follows:

<getTicketResponse>
          <ticketID> … </ticketID>
</getTicketResponse>

To transform the connector-compliant getTicket response back to the generic XML data, you need to use a the getTicket_response.xsl transformation file. For the Remedy connector, the file is located here:

$ORACLE_HOME/sysman/connector/<Remedy_Connector>/getTicket_response.xsl

The content of this XSLT file for the Remedy Connector is shown below:

<?xml version='1.0' encoding='UTF-8'?>
<xsl:transform version="1.0"
              xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
              xmlns:urn="urn:HelpDesk_Query_Service"
              xmlns="http://xmlns.oracle.com/sysman/connector/tt"
              targetNamespace="http://xmlns.oracle.com/sysman/connector/tt"
              elementFormDefault="qualified">
  <xsl:template match="urn:getListValues">
      <getTicketResponse>
        <ticketID><xsl:value-of select="urn:Case_ID/text()"/></ticketID>
      </getTicketResponse>
  </xsl:template>
</xsl:transform>

You need to modify this getTicket_response.xsl file for help desk connectors other than Remedy and place it in a similar location as shown for the Remedy Connector above.

Enabling an SSL Connection for HTTPS

Follow the steps provided in this section if you choose HTTPS as the protocol to establish a connection between the external ticketing system and Enterprise Manager.

Generating Certificate Request File

Generate a certificate request file for the external ticketing system and send it to the Certificate authority, such as VeriSign.

Note:

The certificate request file is dependent on the Web server used by the external ticketing system.

Importing the Certificate from the Certificate Authority

After you get the certificate, import it to the Web server the external ticketing system uses. The import mechanism varies depending on the Web server the external ticketing system uses.

Adding Signed Certificates to Wallet Manager

Note:

Oracle Wallet Manager is available at $ORACLE_HOME/bin on OMS. See the Oracle Application Server Administrator's Guide for details.

Get the port number from user_projects/domains/EMGC_DOMAIN/config/config.xml:

<server>
<name>EMGC_ADMINSERVER</name>
<ssl>
<name>EMGC_ADMINSERVER</name>
<enabled>true</enabled>
<hostname-verification-ignored>true</hostname-verification-ignored>
<listen-port>7022</listen-port>
</ssl>
<listen-port-enabled>false</listen-port-enabled>
<listen-address>server_name</listen-address>
</server>

Connect to the WebLogic Admin Console:
1. Connect to https://server_name:7022/console/, login: [username]/[password]
2. Navigate to Environment->Servers->EMGC_DOMAIN->Keystore tab
3. If two-way SSL is required for external web service, go to SSL->Advanced->Use Server Certs and be sure it is checked
4. Make sure that CA signed the external system server's certificate is added to trustStore specified in the Keystore tab, for example, WebLogic's DemoTrust, or java standard cacerts