1 Building a Help Desk Connector

Introduction

Enterprise Manager Cloud Control 12c 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 Incident is triggered in Enterprise Manager. You can specify incident rules for tickets to be created or updated.

• Manual Ticketing — Lets you manually create a ticket from Enterprise Manager console based on an open incident in Enterprise Manager. The connector populates the ticket with details based on the incident and the ticket template.

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

Building a Ticketing Connector

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

• Basic configuration parameters required by enterprise manager.

• Specification for web services that define how the connector framework communicates with external systems

• Specification for Service Methods

  Service Methods are used to bind Method name with web service endpoints. CreateTicket, updateTicket and getTicket are the supported method names for ticketing connector.

• Specification for Template Registration

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

• Specification for SOAP header authentication

Defining 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.

The key points to remember when constructing a descriptor are

• 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 A, "Ticketing Connector Samples" for reference implementation.

The following table provides a breakdown of the sections of conenctorDeploy.xsd and explains what each section does:

<SOAPHeaderAuthentication>
<Username required="true">
<VariableName>USERNAME</VariableName>
<DisplayName>Remedy Username</DisplayName>
</Username>
<Password>
<VariableName>PASSWORD</VariableName>
<DisplayName>Remedy 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[
<urn:AuthenticationInfo xmlns:urn="urn:HelpDesk_Submit_Service">
<urn:userName>$USERNAME$</urn:userName>
<urn:password>$PASSWORD$</urn:password>
<urn:authentication>$AUTHENTICATION$</urn:authentication>
<urn:locale>$LOCALE$</urn:locale>
<urn:timeZone>$TIMEZONE$</urn:timeZone>
</urn:AuthenticationInfo>
]]>
</SOAPHeader>
</SOAPHeaderAuthentication>

<Name>Remedy Service Desk Connector</Name>
<Version>12.1.0.1.0</Version>
<EMCompatibleVersion>12.1.0.1.0</EMCompatibleVersion>
<Description>Remedy Integration with Enterprise Manager</Description>
<Category>TicketingConnector</Category>

<ConnectivityTestVariable>
<VariableName>TICKET_ID</VariableName>
<DisplayName>Ticket ID</DisplayName>
</ConnectivityTestVariable>

<ExternalURL>
<Pattern>
<![CDATA[http://$WEB_SERVER$/arsys/forms/$ARSERVER_NAME$/$FORM_NAME$/?qual=%27Incident%20Number*%27=%22@Incident_Number@%22]]>
</Pattern>
<ConfigVariable required="true">
<VariableName>WEB_SERVER</VariableName>
<DisplayName>Web Server</DisplayName>
</ConfigVariable>
<ConfigVariable required="true">
<VariableName>FORM_NAME</VariableName>
<DisplayName>HelpDesk Case Form Name</DisplayName>
</ConfigVariable>
<ConfigVariable required="true">
<VariableName>ARSERVER_NAME</VariableName>
<DisplayName>ARServer Name</DisplayName>
</ConfigVariable>
</ExternalURL>

<Service>
<Method>createTicket</Method>
<WebServiceEndpoint>
<![CDATA[http://[midtier_server]/arsys/services/ARService?server=[servername]&webService=HPD_IncidentInterface_Create_WS]]>
</WebServiceEndpoint>
</Service>
<Service>
<Method>updateTicket</Method>
<WebServiceEndpoint>
<![CDATA[http://[midtier_server]/arsys/services/ARService?server=[servername]&webService=HPD_IncidentInterface_WS]]>
</WebServiceEndpoint>
</Service>
<Service>
<Method>getTicket</Method>
<WebServiceEndpoint>
<![CDATA[http://[midtier_server]/arsys/services/ARService?server=[servername]&webService=HPD_IncidentInterface_get_WS]]>
</WebServiceEndpoint>
</Service>

<TemplateRegistration>
<FileName>getTicket_request.xml</FileName>
<InternalName>getTicket</InternalName>
<TemplateName>Get Ticket</TemplateName>
<TemplateType>OutboundXML</TemplateType>
<Description>This is the request xml file for getTicket method</Description>
</TemplateRegistration>
<TemplateRegistration>
<FileName>getTicket_response.xsl</FileName>
<InternalName>getTicket</InternalName>
<TemplateName>Get Ticket</TemplateName>
<TemplateType>InboundXSL</TemplateType>
<Description>This is the response xsl file for getTicket method</Description>
</TemplateRegistration>
<TemplateRegistration>
<FileName>createTicket_response.xsl</FileName>
<InternalName>createTicket</InternalName>
<TemplateName>Create Ticket Reponse</TemplateName>
<TemplateType>InboundXSL</TemplateType>
<Description>This is the create ticket response template. </Description>
</TemplateRegistration>
<TemplateRegistration>
<FileName>templates/Remedy_DefaultCategory.xsl</FileName>
<InternalName>Remedy_DefaultCategory.xsl</InternalName>
<TemplateName>Remedy Default Category </TemplateName>
<TemplateType>OutboundXSL</TemplateType>
<Description>This is the Remdy default category template. </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

Following event connector service operations are supported:

• createTicket

  Create ticket on the external system.

• updateTicket

  Forward event updates to the external system.

• getTicket

  Service method to validate the ticket connector connectivity with Enterprise Manager.

Note that the service names in the connector descriptor should exactly match the names defined above and are case sensitive.

The following is an example of service setup:

<Service>
<Method>createTicket</Method>
<WebServiceEndpoint>
<![CDATA[http://[midtier_server]/arsys/services/ARService?server=[servername]&webService=HPD_IncidentInterface_Create_WS]]></WebServiceEndpoint>
</Service>

Template Definition

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

A template implementation for ticketing connector can be further classified as:

<TemplateRegistration>
<FileName>getTicket_request.xml</FileName>
<InternalName>getTicket</InternalName>
<TemplateName>Get Ticket</TemplateName>
<TemplateType>OutboundXML</TemplateType>
<Description>This is the request xml file for getTicket method</Description>
</TemplateRegistration>
<TemplateRegistration>

<TemplateRegistration>
<FileName>templates/Remedy_DefaultCategory.xsl</FileName>
<InternalName>Remedy_DefaultCategory.xsl</InternalName>
<TemplateName>Remedy Default Category </TemplateName>
<TemplateType>OutboundXSL</TemplateType>
<Description>This is the Remdy default category template. </Description>
</TemplateRegistration>

The following are the guidelines for defining any template:

• Method specific templates should have internal name same as the method name (case sensitive)

• Default templates can have any internal names.

• 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 Oracle recommends that you use the following:

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

Template Registration

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

• Defined set of schema definition (XSD)

• Target external system attributes

The following table lists the schema definitions for Enterprise Manager Event Connector:

Key points for defining the request templates are

• The getTicket service only requires the request XML template file to be defined.

  Template request XML is used if the information to be passed is already defined as connector test variable element. The connector test variable can be defined via Connector Deployment Descriptor XML at the time of registration.

• The createTicket and updateTicket services use default XSL template files defined via connector deployment descriptor XML.

  Template request XSL is used to generate a request with event and incident attributes generated within Enterprise Manager. These request require mapping within Enterprise Manager event and incident objects and ticketing system attributes.

• Defining the template Request XSL is optional if the user has already defined Request XML.

  Ideally there won't be any need for this scenario.

• You can use the EMIncident.xsd and EMEvent.xsd schema to decide which Enterprise Manager fields you want to make available for mapping when creating a ticketing request.

Key points for defining the response templates are

• You can define the response template(XSL) based on the XSD defined in the Ticketing Connector Template XSD table.

• Template response XSL are optional.

  If no response transformation(XSL) is defined, then any data returned by external systems within response XML will not be persisted. This is the ideal implementation for operations that does not care about external system response data.

• For createTicket and updateTicket services, you can use the createTicket_response.xsd schema to decide how to transform the response from external systems to the response understandable by Enterprise Manager.

After the transformation, Enterprise Manager expects a <TicketId> and updates the proper status depending on the value:

• Not Null

  Enterprise manager will persist the ticketId with the associated Incident and annotate the proper status messages in the EM Incident Manager grid.

• Null

  Enterprise manager will annotate a error message with the associated Incident in the EM Incident Manager grid.

Refer to following sample template files for Remedy 7 Ticketing 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

   Key attributes of the self update manifest files are

   • 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 the connector setup. Generally there will be a single connector jar, but for some special implementations there may be additional jars (adapter or agent). In these cases, the connector specific jar should be the first one in the defined list. This is a 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 the complete list of attributes:

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

3. Configure emedk tool

   The emedk tool can be configured by following instructions from EM UI. 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:

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

   Table 1-6 describes the options available with the utility

   Table 1-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/connector1_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:

   edktool import_update 
   -file=\ file\ 
   -omslocal  
   

   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 1-7 describes the options available with this command:

   Table 1-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 sample_connector.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/sar/sample_connector.zip         
     -omslocal  
   

   Example 2

   Imports the file sample_connector.zip.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/sar/sample_connector.zip                
     -host=\ host1.example.com\         
     -credential_set_name=\ HostCredsNormal\ 
   

   Example 3

   Imports the file sample_connector.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/sar/sample_connector.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.