5 Using Out-of-Box Templates

This chapter provides details on the out-of-box ticket templates shipped with the HP Service Manager Connector based on the out-of-box Service Manager IncidentManagement WSDL. The ticket templates specify the mappings between Enterprise Manager incident attributes and HP Service Manager ticket attributes.

This chapter covers the following topics:

5.1 Out-of-Box HP Service Manager Templates

All out-of-box templates cause the following actions to occur when you create or update a ticket for an incident:

  • Write Enterprise Manager incident information to the ticket description.

  • Set the ticket summary based on the incident message.

  • Add an entry to the Journal Update that shows the incident details. This provides a trail of the changes that have occurred to the incident.

  • Sets the ticket severity based on the severity of the incident in Enterprise Manager.

The out-of-box templates are:

  • Service_Manager_9_Default_Incident.xsl

    This templates creates, updates, or reopens a Service Manager ticket using the default field mapping. This template does not close the ticket when the event severity value becomes Clear.

  • Service_Manager_9_Default_Incident_AutoClose.xsl

    This template creates, updates, or reopens a Service Manager ticket using the default field mapping. This template sets the ticket status to Closed when the incident severity value becomes Clear.

5.2 Reading and Mapping Ticket Templates

This section provides detailed mapping information for the default ticket templates described above. The mappings are based on the out-of-box IncidentManagement WSDL for the HP Service Manager Web Service.

Each template is capable of handling create and update requests. The incident TicketID field determines how it is mapped. If the TicketID is empty, it is mapped to the Service Manager create request format. Otherwise, it is mapped to an update request format. The following sub-sections identify the create and update mappings for each template.

5.2.1 Service_Manager_9_Default_Incident.xsl - Create

Table 5-1 lists the fields and values that this template maps for a create operation. All references to the incident refer to the Enterprise Manager incident.

Table 5-1 HP Service Manager 9 Default Incident Create Field Names and Values

Service Manager Field Name Value

Urgency

Set the severity based on the incident severity. See Section 5.2.6, "Severity Mapping" for details.

Area

Hard-coded to "failure".

Subarea

Hard-coded to "error message".

Product Type

Hard-coded to "applications".

Problem Type

Hard-coded to "incident".

Assignment Group

Hard-coded to "Service Desk".

Impact

Hard-coded to "1".

Description

Set to the formatted contents of the incident as specified in Section 5.2.5, "Formatted Enterprise Manager Incident Contents".

Title

Set to the incident Summary.

Journal Updates

Set to the formatted contents of the incident as specified in Section 5.2.5, "Formatted Enterprise Manager Incident Contents".

Oracle Connector ID

Set to the incident ConnectorGUID.

5.2.2 Service_Manager_9_Default_Incident.xsl - Update

Table 5-2 lists the fields and values that this template maps for an update operation. All references to the incident refer to the Enterprise Manager incident.

Table 5-2 HP Service Manager 9 Default Incident Update Field Names and Values

Service Manager Field Name Value

Incident ID

Set to the incident TicketID.

Description

Set to the formatted contents of the incident as specified in Section 5.2.5, "Formatted Enterprise Manager Incident Contents".

Title

Set to the incident Summary.

Status

Set to "Open" if the incident ReopenTicket field is set to "Yes."

Alert Status

Set to "reopen" if the incident ReopenTicket field is set to "Yes."

Journal Updates

Set to the formatted contents of the incident as specified in Section 5.2.5, "Formatted Enterprise Manager Incident Contents".

5.2.3 Service_Manager_9_Default_Incident_AutoClose.xsl - Create

The field mappings for this template are identical to the mappings specified in Section 5.2.1, "Service_Manager_9_Default_Incident.xsl - Create".

5.2.4 Service Manager_9_Default_Incident_AutoClose.xsl - Update

Table 5-3 lists the fields and values that this template maps for an update operation. All references to the incident refer to the Enterprise Manager incident.

Table 5-3 HP Service Manager 9 Default Incident AutoClose Update Field Names and Values

Service Manager Field Name Value

Incident ID

Set to the incident TicketID.

Description

Set to the formatted contents of the incident as specified in Section 5.2.5, "Formatted Enterprise Manager Incident Contents".

Title

Set to the incident Summary.

Status

Set to "Open" if the incident ReopenTicket field is set to "Yes."

Set to "Closed" if the incident severity is "Clear."

Alert Status

Set to "reopen" if the incident ReopenTicket field is set to "Yes."

Set to "closed" if the incident severity is "Clear."

Resolution Fix Type

Set to "permanent" if the incident severity is "Clear."

Closure Code

Set to "User Closure" if the incident severity is "Clear."

Solution

Set to "The alert was resolved in Oracle Enterprise Manager" if the incident severity is "Clear."

Journal Updates

Set to the formatted contents of the incident as specified in Section 5.2.5, "Formatted Enterprise Manager Incident Contents".

5.2.5 Formatted Enterprise Manager Incident Contents

shows the format used by the templates for the Description and JournalUpdates fields.

  • Text delimited by angle brackets (< and >) designates an Enterprise Manager Incident field name that will be replaced by the actual field contents.

  • Lines marked with double asterisks indicate they will only be present if the designated incident field contains data.

  • The Notes section after the format contains information about some of the fields.

Example 5-1 Formatted Incident Contents

EM User: <NotificationRuleOwner>
.
Incident Information:
.
    Source Name: <SourceObjInfo/ObjName>
    Source Owner: <SourceObjInfo/ObjOwner>**
    Source Type: <SourceObjInfo/SourceObjType>
    Source SubType: <SourceObjInfo/SourceObjSubType>
    Target Name: <TargetInfo/TargetName>
    Target Type: <TargetInfo/TargetType>
    Target Type Label: <TargetInfo/TargetTypeLabel>
    Target URL: <TargetInfo/TargetURL>
.
    Target Properties:**
        <TargetProperty/Name>: <TargetProperty/Value>**
.
    Severity: <Severity>
    Priority: <Priority>
    CreationDate: <CreationDate>
    LastUpdatedDate: <LastUpdatedDate>
    Owner: <Owner>
    Notification Rule: <NotificationRuleName>**
    URL: <IncidentURL>
.
    EM Incident Status: <ResolutionState>
    EM Acknowledge: <Acknowledge>
    EM Auto Close: <AutoClose>
    EM Escalation Level: <EscalationLevel>
    <AdditionalDetails/Name>: <AdditionalDetails/Value>**

Example 5-1 Notes

  • EM User is set to the incident rule set owner when the ticket is created through auto-ticketing, and is the Enterprise Manager log-in user when the ticket is created through manual-ticketing.

  • The Target Properties section is only present if the incident contains target property values. Listed below are a couple of sample target property name/value pairs:

    Line of business: Finance

    Owner: Finance-DB Team

  • CreationDate is set to the date the incident was created in Enterprise Manager.

  • Owner is set to the incident owner in Enterprise Manager.

  • URL is set to the URL of the incident details page in Enterprise Manager. The URL is set up as a link that can be clicked on to view the incident in Enterprise Manager.

5.2.6 Severity Mapping

The Service Manager ticket severity is set based on the Enterprise Manager incident severity value. Table 5-4 shows the values used when creating the ticket in Service Manager.

Table 5-4 Ticket Severity Mappings

When the incident severity is … Set the ticket severity to …

Fatal

1 (Critical)

Critical

1 (Critical)

Warning

3 (Average)

Minor Warning/Advisory

4 (Low)

Informational

4 (Low)

5.3 Customizing Ticket Templates

If the out-of-box ticket templates do not satisfy your requirements, you can create custom templates tailored to your environment. Templates are XSLT files, so you must have a good understanding of XSLT transformations to create custom templates. To do this, Oracle recommends that you use one of the existing templates as the base template.

To create a custom template:

  1. Export the default template XSLT files from Enterprise Manager to use as a baseline. Follow the instructions in Section 5.4, "Exporting the Ticketing Template Files" to obtain copies of the default template files.

  2. Review Section 5.1 and Section 5.2 to understand the default mappings. Determine which file you want to use as a baseline and what mapping changes you want to make. Copy the baseline file to a new file with a different name.

  3. Make the desired mapping changes to the new template file. See Section 5.5, "Modifying Ticket Templates"for guidance on mapping changes.

  4. Register the new template with Enterprise Manager as specified in Section 3.5.1, "Adding Ticket Templates" .

See Section 5.6, "Custom Template Examples" for examples of how to create a custom template.

5.4 Exporting the Ticketing Template Files

The connector installation .jar file is included in the Self Update archive that was installed in Section 2.1, "Installing the Connector".

To extract the installation file:

  1. Determine the command required to export the adapter installation file. To do this, perform the following steps:

    1. From the Setup menu in the Enterprise Manager console, select Extensibility, then Self Update.

    2. Click on the Management Connector link.

    3. Click on the HP Service Manager 9 connector and then select Export from the Actions list.

      A pop-up window appears with the command required to export the file. Figure 5-1 shows an example of the window.

      Figure 5-1 Export Command Example

      Surrounding text describes Figure 5-1 .

  2. Open a command window on the Management Server host system and navigate to a temporary directory where you can copy the file.

  3. Log into EM CLI using the following command. You will be asked to provide the password information for the sysman account.

    emcli login -username=sysman

  4. Run the EM CLI export_update command from your system, changing <dirname> to the full path of the temporary directory.

    This creates a .zip file. The file name is comprised of the id value specified in the export_update command with a .zip extension. In the example command in Figure 5-1, the .zip file name would be:

    E9F684312AE7A18E98340715D079E58D.zip

  5. Extract the adapter installation .jar file from the .zip file using the following command:

    unzip *.zip archives/*connector.jar

  6. Extract the templates from the connector .jar file using the following command:

    $JAVA_HOME/bin/jar xf archives/*.jar templates

    Note:

    If the system where the connector file is located does not have the JDK installed, you cannot extract the .jar file contents. You must copy the .jar file to a system that has the JDK installed and transfer the template files after they have been extracted.

5.5 Modifying Ticket Templates

A template is an XSLT file that transforms an input XML format to an output XML format. To make the mapping changes, you need to understand the input XML format being transformed, and the output XML the template generates. The input document is the XML document that contains the Enterprise Manager incident information. The output document is the request being sent to the HP Service Manager web service. The output XML document must conform to the data format specified in the Service Manager IncidentManagement WSDL.

Appendix C contains details on the format of the incident data Enterprise Manager generates. Appendix D contains details on the XML format required by the out-of-box IncidentManagement Service Manager web service. Service Manager web services may be customized, so the format used in your environment could be significantly different.

To modify the custom template file:

  1. Review Appendix D to identify the names of the fields in Service Manager that you are planning to modify. The order of the fields is important, so if you need to add new fields, make sure to note where the field goes.

  2. If you are planning on using data from the incident, review Appendix C to identify the field(s) you want to use in the mapping. Appendix E contains sample transactions that could be very helpful in identifying what data is present in the XML document from Enterprise Manager.

  3. Open the custom template file in a text editor or a utility that you can use to build XSLT files.

  4. Make the necessary changes to the custom template file and save it.

  5. Unless the change is very simple, you should test the changes that you have made using the sample data from Appendix E. This requires a utility that performs XSLT translations.

5.6 Custom Template Examples

This section provides walk-through examples of what is required to create custom templates. The first example is a simple case of changing values for fields that are already specified in the default templates. The second example is more involved, and includes populating fields that are not already in the default templates.

5.6.1 Example 1

In this example, the customer has determined that the default mappings do not function for their environment. They have created a new assignment group named "Tier 1 Support" that should handle all incidents that Enterprise Manager reports. They are running version 9 in their environment and would like to close the incidents in Service Manager after the incidents have cleared in Enterprise Manager. They have also created a temporary directory on the OMS server system at /home/oracle/custom_templates to hold the templates.

To create a custom template that handles the customer's requirements:

  1. Navigate to the Management Connector Updates page and export the HPSM 9 Connector.

  2. Copy the first EM CLI command listed in the Export Steps window for later use:

    emcli export_update -id=DD4E9161C5E7129F9641447FB4F0497B -omslocal -dir=<dirname>

  3. Open a command window on the OMS server system and change the working directory to the temporary directory:

    cd /home/oracle/custom_templates

  4. Log into EM CLI:

    emcli login -username=sysman

  5. Run the EM CLI command from step 1 to export the .zip file to the temporary directory.

    emcli export_update -id=DD4E9161C5E7129F9641447FB4F0497B -omslocal -dir=/home/oracle/connector_templates

  6. Extract the connector .jar file from the .zip file:

    unzip *.zip archives/*connector.jar

  7. Extract the template files from the .jar file:

    $JAVA_HOME/bin/jar xf archives/*.jar templates

  8. Copy the default template to a custom template file for modification:

    cd templates

cp ServiceManager_9_Default_Incident_AutoClose.xsl Tier1_Support_AutoClose.xsl

  9. Open the custom template file with a text editor and make the modifications shown below to the AssignmentGroup node.

    Before changes —

    <m:AssignmentGroup>Service Desk</m:AssignmentGroup>

    After changes —

    <m:AssignmentGroup>Tier1 Support</m:AssignmentGroup>

    Since this is a trivial change, you can skip testing.

  10. At the OMS server system, run the following command to register your new custom template:

    emctl register_template connector
-t /home/oracle/custom_templates/templates/Tier1_Support_AutoClose.xsl
-repos_pwd sysmanpass
-cname "HPSM 9"
-iname "Tier1SupportAutoClose"
-tname "Tier1 Support AutoClose"
-ttype 2
-d "Template to set assignment group to Tier1 Support"

5.6.2 Example 2

In this example, the customer would like to populate the following additional fields:

  • Affected Item — This field will be populated by the Target Host information from the Target Properties.

  • Location — This field will be populated by the Location information from the Target Properties.

  • Target URL — This a new custom field that was added to their web service to hold the Target URL from the Enterprise Manager incident.

They are running version 9 in their environment, and would like to close the incidents in Service Manager after the incidents have cleared in Enterprise Manager. They have also created a temporary directory on the OMS server system at /home/oracle/custom_templates to hold the templates.

To create a custom template that handles their requirements:

  1. Navigate to the Management Connector Updates page and export the HPSM 9 Connector.

  2. Copy the first EM CLI command listed in the Export Steps window for later use:

    emcli export_update -id=C5289206C5A5A84AF82C49821C8F2931 -omslocal -dir=<dirname>

  3. Open a command window on the OMS server system and change the working directory to the temporary directory:

    cd /home/oracle/custom_templates

  4. Log into EM CLI:

    emcli login -username=sysman

  5. Run the EM CLI command from step 1 to export the .zip file to the temporary directory.

    emcli export_update -id=C5289206C5A5A84AF82C49821C8F2931 -omslocal -dir=/home/oracle/connector_templates

  6. Extract the connector .jar file from the .zip file:

    unzip *.zip archives/*connector.jar

  7. Extract the template files from the .jar file:

    $JAVA_HOME/bin/jar xf archives/*.jar templates

  8. Copy the default template to a custom template file for modification:

    cd templates

cp ServiceManager_9_Default_Incident_AutoClose.xsl Target_Info_AutoClose.xsl

  9. Open the custom template file with a text editor and make the modifications shown below. The changes are shown in bold. Note that the new fields were added in the correct sequence as defined in the WSDL.

    Before changes —

    <m:AssignmentGroup>Service Desk</m:AssignmentGroup>
 
. . .
 
<m:Impact>1</m:Impact>
 
. . .
 
<m:OracleConnectorId><xsl:value-of select="ns0:ConnectorGUID"/></m:OracleConnectorId>

    After changes —

    <m:AssignmentGroup>Service Desk</m:PrimaryAssignmentGroup>
<xsl:for-each select="ns0:SystemAttributes/ns0:SourceInfo/ns0:TargetInfo/ns0:TargetProperty">
    <xsl:if test="./ns0:Name = 'Target_Host'">
     <m:AffectedItem><xsl:value-of select="./ns0:Value"/></m:AffectedItem>
   </xsl:if>
</xsl:for-each>
 
. . .
 
<m:Impact>1</m:Impact>
<xsl:for-each select="ns0:SystemAttributes/ns0:SourceInfo/ns0:TargetInfo/ns0:TargetProperty">
    <xsl:if test="./ns0:Name = 'Location'">
        <m:Location><xsl:value-of select="./ns0:Value"/></m:Location>
    </xsl:if>
</xsl:for-each>
 
. . .
 
<m:OracleConnectorId><xsl:value-of select="ns0:ConnectorGUID"/></m:OracleConnectorId>
<m:TargetURL><xsl:value-of 
select="ns0:SystemAttributes/ns0:SourceInfo/ns0:TargetInfo/ns0:TargetURL"/></m:TargetURL>

  10. To set up for testing, create the create.xml file and open the file in a text editor.

  11. Copy the contents of the XML document in the "Create Example" section of Appendix E into the create.xml file and save it.

  12. Test the new template using a utility that performs XSLT translations using the create.xml file as the input XML document.

  13. Examine the output XML document and verify that the results are correct.

    Note:

    You can also use an XML client to send the XML output document to the Management Server web service to verify that it is a format accepted by Service Manager.

  14. If you encounter problems with the XML document, make any necessary corrections and repeat steps 12 and 13.

  15. At the OMS server system, run the following command to register your new custom template:

    emctl register_template connector
-t /home/oracle/custom_templates/templates/Target_Info_AutoClose.xsl
-repos_pwd sysmanpass
-cname "HPSM 9"
-iname "TargetInfoAutoClose"
-tname "Target Info AutoClose"
-ttype 2
-d "Template to set target fields"