Oracle® Enterprise Manager Connectors Integration Guide 11g Release 1 (11.1.0.0) Part Number E17065-02 |
|
|
PDF · Mobi · ePub |
This chapter provides information you need to build a help desk connector and integrate it with Enterprise Manager. This chapter has following sections:
Testing the Help Desk Configuration
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. |
Before building a help desk connector, ensure that your ticketing system meets the following pre-requisites:
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.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 |
---|---|
<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.
|
<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
|
<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.
|
<?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>
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 |
|
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, |
TargetName |
Name of the target that the alert is associated with. For example, |
MetricColumn |
Name of the metric that triggered the alert. For example, CPU Utilization(%). |
MetricName |
Category of the metric. For example, |
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: |
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 |
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"/>). |
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>
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>
A response XSL file is needed for the action Get Ticket
. The file must be named as shown:
getTicket_response.xsl
See Also:
Testing the Help Desk Configuration for details on the Get Ticket operation.The response XSL file transforms the output from ticketing systems into the format that Enterprise Manager expects, specifically the TicketID.
Example 1–3 shows an example "response transform" for Remedy. It maps the Remedy CaseID ticket attribute to Enterprise Manager's TicketID attribute:
Example 1-3 Example Response Transform for Remedy
<?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_Submit_Service" xmlns="http://xmlns.oracle.com/sysman/connector/tt" targetNamespace="http://xmlns.oracle.com/sysman/connector/tt" elementFormDefault="qualified"> <xsl:template match="urn:Create_Helpdesk_CaseResponse"> <CreateTicketResponse> <TicketId><xsl:value-of select="urn:Case_ID"/></TicketId> </CreateTicketResponse> </xsl:template></xsl:transform>
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 ParametersThe 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.
See Also:
"Configuring the Help Desk Connector"The full emctl command usage for the register_template command is
emctl register_template connector [-t <template.xsl>] [-repos_pwd <repos password>] [-ctname <connectorTypeName>] [-cname <connectorName>] [-iname <internalName>] [-tname <templateName>] [-ttype <templateType>] [-d <description>] -t Template(full path) -repos_pwd Enterprise Manager Root (SYSMAN) Password -ctname Connector Type Name -cname Connector Name -iname Template Internal Name -tname Template Name Displayed -ttype Template Type <templateType> 1 - inbound transformation <templateType> 2 - outbound transformation <templateType> 3 - XML outbound transformation -d Description
Table 1–4 provides descriptions for the emctl
parameters.
Parameter | Description |
---|---|
|
The connector deployment descriptor. |
|
Fully qualified name of the ticket template file. The file resides in the Connector home directory:
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 If the file is in a different directory, provide the complete path for the file. |
|
Host name of the Enterprise Manager repository. |
|
Listener port of the repository. |
|
Repository database instance ID or service name if you are using a RAC database as the repository. |
|
Specify |
|
Password for |
|
Connector type name you define in |
|
Connector name. This should be the same as the connector type name. For example, |
|
An intuitive name for the ticket template that will be displayed in Enterprise Manager. |
|
A short description for the ticket template. This description is also displayed in Enterprise Manager. |
|
Jar file, full jar file path |
|
Connector name |
|
Connector type name |
|
Connector descriptor file, full path |
|
Enterprise Manager root (SYSMAN) password |
|
Template file, full path |
|
Internal name (For details about this parameter, you can refer to the existing Connector documentation.) |
|
Template name |
|
Template type |
|
Template description |
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).
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).
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.
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.
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>
The generic getTicke
t 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.
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.
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.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.
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:
Connect to https://server_name:7022/console/, login: [username]/[password]
Navigate to Environment->Servers->EMGC_DOMAIN->Keystore tab
If two-way SSL is required for external web service, go to SSL->Advanced->Use Server Certs and be sure it is checked
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
See Also:
For information on creating an Oracle Wallet, see "Creating and Viewing Oracle Wallets with orapki" in the Oracle Database Advanced Security Administrator's Guide, 10g Release 2 (10.2).