Using Default Templates

Template Process

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

Write incident information to Description (Jira ticket description).
Set the Jira ticket title based on the incident message.

The out-of-box templates are as follows:

jiraStoryCreateAndUpdate.xsl
This template will create Oracle Enterprise Incidents as a Story ticket in Jira.
jiraBugCreateAndUpdate.xsl
This template will create Oracle Enterprise Incidents as a Bug ticket in Jira.
jiraTaskCreateAndUpdate.xsl
This template will create Oracle Enterprise Incidents as a Task ticket in Jira.
jiraSubtaskCreateAndUpdate.xsl
This template will create Oracle Enterprise Incidents as a Subtask ticket in Jira.
jiraIncidentCreateAndUpdate.xsl
This template will create Oracle Enterprise Incidents as an Incident ticket in Jira.
jiraProblemCreateAndUpdate.xsl
This template will create Oracle Enterprise Incidents as a Problem ticket in Jira.
jiraServiceRequestCreateAndUpdate.xsl
This template will create Oracle Enterprise Incidents as a Service Request ticket in Jira.

Reading Ticket Templates

The following table illustrates the creation of a ticket using jiraStoryCreateAndUpdate.xsl. This illustration will help you to read a ticket template. In the table, * denotes a literal string and ** indicates if the attribute applies.. Additionally, the table also shows Jira ticket attributes and corresponding Enterprise Manager incident values for ticket creation mappings.

Ticket creation mappings are the same for jiraStoryCreateAndUpdate.xsl, jiraBugCreateAndUpdate.xsl, jiraTaskCreateAndUpdate.xsl, and jiraSubtaskCreateAndUpdate.xsl.

Table 4-1 Ticket Creation Mappings (for all templates)

Jira Ticket Attributes	Enterprise Manager Incident Attributes	Value
Issue type	.	10001 (this is the story type and changes between templates)
project/key	$PROJECT_ID$	Set to the value of Project Key during configuration.
labels	.	"oracle_enterprise_manager" *
description	Summary Severity Code Priority Notification Rule Name Notification Rule Owner Target Type Target Name Obj Owner Target Properties Last Updated Date Incident URL	Summary – The details about the incident that has fired Severity Code – The severity of the incident in Oracle Enterprise Manager Priority – The priority of the incident in Oracle Enterprise Manager Notification Rule Name – Name of the rule that created the ticket (Auto ticketing only) Notification Rule Owner – Name of the user that owns the rule that created the ticket (Auto ticketing only) Target Type – The type of target that the incident fired on Target Name – The name of the target that the incident fired on Obj Owner – Name of the user that owns the object the incident is fired on Target Properties – Additional names and values about the incident. Includes things like host, version, OS and platform Last Updated Date – Date the incident was created in Oracle Enterprise Manager Incident URL – A URL link that directs the user to the Oracle Enterprise Manager Incident
Title	Summary	Summary – The details about the incident that has fired New *

Use the mapping table above as a reference to read the following XSLT file (jiraStoryCreateAndUpdate.xsl).

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:emcf="http://xmlns.oracle.com/sysman/connector" version="1.0">
  <xsl:template match="emcf:EMIncident">
    <!-- Please remember to backup all files before editing -->
    <!--
        This area is where variables are set to be used in the rest of the template.
        By default, there are two variables set:
          * Action: Used to figure out if the connector is 'creating' or 'updating' the Jira Ticket.
          * Severity: Used to set the Severity of the Jira ticket (if used).
          * Priority: Used to set the Priority of the Jira ticket.

          If you want to add or change variables, do so below.
       -->
    <xsl:variable name="action">
      <xsl:choose>
        <xsl:when test="normalize-space(emcf:TicketID) = ''">CREATE</xsl:when>
        <xsl:otherwise>UPDATE</xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <xsl:variable name="severity">
      <xsl:choose>
        <xsl:when test="emcf:SystemAttributes/emcf:SeverityCode = 'FATAL'">Sev-0</xsl:when>
        <xsl:when test="emcf:SystemAttributes/emcf:SeverityCode = 'CRITICAL'">Sev-0</xsl:when>
        <xsl:when test="emcf:SystemAttributes/emcf:SeverityCode = 'WARNING'">Sev-1</xsl:when>
        <xsl:when test="emcf:SystemAttributes/emcf:SeverityCode = 'ADVISORY'">Sev-2</xsl:when>
        <xsl:otherwise>Sev-3</xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <xsl:variable name="priority">
      <xsl:choose>
        <xsl:when test="emcf:SystemAttributes/emcf:Priority = 'Urgent'">Highest</xsl:when>
        <xsl:when test="emcf:SystemAttributes/emcf:Priority = 'Very High'">Highest</xsl:when>
        <xsl:when test="emcf:SystemAttributes/emcf:Priority = 'High'">High</xsl:when>
        <xsl:when test="emcf:SystemAttributes/emcf:Priority = 'Medium'">Medium</xsl:when>
        <xsl:when test="emcf:SystemAttributes/emcf:Priority = 'Low'">Low</xsl:when>
        <xsl:otherwise>Medium</xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <Message>
      <!--
          The following areas (Method, Variables, and Headers) should not be edited.
          They are used to make communication work between Oracle Enterprise Manager and Jira.
        -->
      <Method>
        <xsl:choose>
          <xsl:when test="$action = 'CREATE'">POST</xsl:when>
          <xsl:when test="$action = 'UPDATE'">POST</xsl:when>
          <xsl:otherwise>ERROR</xsl:otherwise>
        </xsl:choose>
      </Method>
      <Variables>
        <Variable>
          <Name>TKT_KEY</Name>
          <Value>
            <xsl:value-of select="normalize-space(emcf:TicketID)" />
          </Value>
        </Variable>
      </Variables>
      <Headers>
        <Header>
          <Name>Authorization</Name>
          <Value>Basic $TOKEN$</Value>
        </Header>
        <Header>
          <Name>Accept</Name>
          <Value>*/*</Value>
        </Header>
      </Headers>
      <!--
        The body is used to send data to Jira. By default, the connector sends data either 'On Create' or 'On Update'.
        
        Fields that are sent when the ticket is created are found under the following header: <xsl:if test="$action = 'CREATE'">
          * Summary: This is the title of Jira ticket
          * Issue Type: This is the type of the Jira ticket. By default, it is set to 'Story'
          * Project: This is the project the Jira tickets will be created under. This is taken from the configuration settings.
          * Labels: This is an array of any labels you wanted added to the ticket.    
          * Description: This is the description of the Jira ticket.
          * Priority: This is the priority of the Jira ticket based on the priority of the Oracle Enterprise Manager ticket.

        Fields that are sent when the ticket is updated are found under the following header: <xsl:if test="$action = 'UPDATE'">
        Note: These items will be sent as a 'comment' in Jira
          * Body: This is the description of current values when an incident is updated in Oracle Enterprise Manager

        There are also a number of fields that are not enabled in Jira by default. They are included but commented out.
        To see if you have these fields enabled, go to your Jira project > 'Project Settings' > 'Issue Types' > 'Story'
        If your Jira instance uses these fields, feel free to uncomment them and your tickets will be created with them as well.
        Note: If you uncomment a field that your Jira project is not using, it will fail to create the ticket.
        
        Additionally, there are a number of fields that Jira has provided or that you have created called 'custom fields'.
        To find your custom fields navigate to 'Administration (gear icon)' > 'Issues' > 'Custom Fields'.
        To find the ID of your custom field, click on the '...' and select 'Edit Details' or 'View field information'.
        Once you are on this page, the ID will be in the URL.
          Examples:
            * customFieldId=10000
            * id=10004
        Once you have your ID, you can add a custom field with the name customfield_<ID>.

        Here are a few examples with some different types of custom fields:
          Let's say we wanted to add the 'requested participants' field in Jira and found it's ID was '30032'
          Requested participants is an array of users. To add it to the fields, we would add the following:
          <array name="customfield_30032">
            [
              <object>
                <string name='id'>"USER ID 1"</string>,
              </object>
              <object>
                <string name='id'>"USER ID 2"</string>
              <object>
            ]
          </array>
        
          Let's say we wanted to add the 'severity' field in Jira and found it's ID was '30043'
          Severity is an object with a value. To add it to the fields, we would add the following:
          <object name="customfield_30043">
            <string name="value">"SEV-0"</string>
          </object>

          If you don't want all your issues to be SEV-0 in Jira, use the $severity variable above to dynamically set severity:
          <object name="customfield_30043">
            <string name="value">
              <xsl:value-of select="$severity"/>
            </string>
          </object>

          Finally, let's say you wanted to add a component to Jira based on Target Type in Oracle Enterprise Manager. This would require a few steps.
          First, we need to set a component variable. This variable will be located above with the other variables (action, severity and priority).
          Here is an example of what that variable would look like:
          <xsl:variable name="component">
            <xsl:choose>
              <xsl:when test="emcf:SystemAttributes/emcf:SourceInfo/emcf:TargetInfo/emcf:TargetType = 'host'">Host</xsl:when>
              <xsl:when test="emcf:SystemAttributes/emcf:SourceInfo/emcf:TargetInfo/emcf:TargetType = 'agent'">Agent</xsl:when>
              <xsl:otherwise>Default</xsl:otherwise>
            </xsl:choose>
          </xsl:variable>

          In this example you can see that we look if the target type is a 'host' or 'agent' and returns the component name based on that ('Host' or 'Agent').
          If it does not find either target type, it returns a default value of 'Default'.
          If you would like to add more target types, simply copy one of the 'when' statements and change the target type and return value.

          Now, that the variable is set, we must verify that our return values are valid components in Jira.
          To do that, go to your Jira Project > 'Project Settings' > 'Components'
          If the component does not exist, click 'Create component' and create it. In this example, we created 'Host', 'Agent', and 'Default'.

          Finally, in the body below, we need to add component. It needs to be added under the line: <object name="fields">
          Here is a good example of what that should look like:
          <array name="components">
            [
            <object>
              <string name="name"><xsl:value-of select="$component"/></string>
            </object>
            ]
          </array>
        -->
      <Body>
        <object>
          <xsl:if test="$action = 'CREATE'">
            <object name="fields">
              <object name="issuetype">
                <string name="name">Story</string>
              </object>
              <!-- This is the title of the Jira ticket. -->
              <string name="summary">
                <xsl:value-of select="emcf:SystemAttributes/emcf:Summary" />
              </string>
              <!-- This is the Project that the ticket is created under in Jira. This is taken from the configuration settings. -->
              <object name="project">
                <string name="key">$PROJECT_ID$</string>
              </object>
              <!-- This is an array of labels applied to the ticket in Jira. By default, we added the label 'oracle_enterprise_manager' -->
              <array name="labels">
                [
                <string>oracle_enterprise_manager</string>
                ]
              </array>
              <!-- This is the main description of the ticket in Jira. -->
              <object name="description">
                <string name="type">doc</string>
                <number name="version">1</number>
                <array name="content">
                  [
                  <object>
                    <string name="type">paragraph</string>
                    <array name="content">
                      [
                      <object>
                        <string name="text">Incident created in Oracle Enterprise Manager: <xsl:value-of select="emcf:SystemAttributes/emcf:Summary" />
Original Severity: <xsl:value-of select="emcf:SystemAttributes/emcf:SeverityCode" />
Original Priority: <xsl:value-of select="emcf:SystemAttributes/emcf:Priority" />
<xsl:choose>
  <xsl:when test="normalize-space(emcf:NotificationRuleName) != ''">
Incident trigged by the following rule: <xsl:value-of select="emcf:NotificationRuleName" />
  </xsl:when>
</xsl:choose>
<xsl:choose>
  <xsl:when test="normalize-space(emcf:NotificationRuleOwner) != ''">
Rule is owned by: <xsl:value-of select="emcf:NotificationRuleOwner" />
  </xsl:when>
</xsl:choose>

Target Type: <xsl:value-of select="emcf:SystemAttributes/emcf:SourceInfo/emcf:TargetInfo/emcf:TargetType" />
Target Name: <xsl:value-of select="emcf:SystemAttributes/emcf:SourceInfo/emcf:TargetInfo/emcf:TargetName" />
Original Owner: <xsl:value-of select="emcf:SystemAttributes/emcf:SourceInfo/emcf:SourceObjInfo/emcf:ObjOwner" />

Additional Properties: <xsl:for-each select="emcf:SystemAttributes/emcf:SourceInfo/emcf:TargetInfo/emcf:TargetProperty">
  * <xsl:value-of select="./emcf:Name" />: <xsl:value-of select="./emcf:Value" />
</xsl:for-each>

This incident was created at: <xsl:value-of select="emcf:SystemAttributes/emcf:LastUpdatedDate" />
To manage the incident in Oracle Enterprise Manager, </string>
                        <string name="type">text</string>
                      </object>
                      <object>
                        <string name="text">click here.</string>
                        <string name="type">text</string>
                        <array name="marks">
                          [
                          <object>
                            <string name="type">link</string>
                            <object name="attrs">
                              <string name="href">
                                <xsl:value-of select="emcf:SystemAttributes/emcf:IncidentURL" />
                              </string>
                            </object>
                          </object>
                          ]
                        </array>
                      </object>
                      ]
                    </array>
                  </object>
                  ]
                </array>
              </object>
              <!-- Sets Priority in your Jira Issue. -->
              <object name="priority">
                <string name="name">
                  <xsl:value-of select="$priority" />
                </string>
              </object>
              <!-- This will put the Jira Issue into a component (or subsection). Replace 'COMPONENT NAME-X' with the component names you wish the Issue to be a part of. -->
              <!--
                <array name="components">
                  [
                  <object>
                    <string name="name">COMPONENT NAME-1</string>
                  </object>
                  <object>
                    <string name="name">COMPONENT NAME-2</string>
                  </object>
                  ]
                </array>
              -->
              <!-- This will set the reporter of the Jira Issue. Replace 'REPORTER ID' with the User's ID. -->
              <!--
                <object name="reporter">
                  <string name="id">REPORTER ID</string>
                </object>
              -->
              <!-- This will set the version of the release this Issue should be completed in. Replace 'FIXVERSION NAME-X' and implement the versions this should be worked on. -->
              <!--
                <array name="fixVersions">
                  [
                  <object>
                    <string name="name">FIXVERSION NAME-1</string>
                  </object>
                  <object>
                    <string name="name">FIXVERSION NAME-2</string>
                  </object>
                  ]
                </array>
              -->
              <!-- This will set the remaining time and the original estimated time for the Jira Issue. Replace '100' with the number of minutes for each estimate. -->
              <!--
                <object name="timetracking">
                  <string name="remainingEstimate">100</string>
                  <string name="originalEstimate">100</string>
                </object>
              -->
              <!-- This will set environment details in the Jira Issue. By default, it will link to the Target URL inside Oracle Enterprise Manager. To add more details, implement them under 'text'. -->
              <!--
                <object name="environment">
                  <string name="type">doc</string>
                  <number name="version">1</number>
                  <array name="content">
                    [
                    <object>
                      <string name="type">paragraph</string>
                      <array name="content">
                        [
                        <object>
                          <string name="text">To visit the target in Oracle Enterprise Manager, </string>
                          <string name="type">text</string>
                        </object>
                        <object>
                          <string name="text">click here.</string>
                          <string name="type">text</string>
                          <array name="marks">
                            [
                            <object>
                              <string name="type">link</string>
                              <object name="attrs">
                                <string name="href"><xsl:value-of select="emcf:SystemAttributes/emcf:SourceInfo/emcf:TargetInfo/emcf:TargetURL"/></string>
                              </object>
                            </object>
                            ]
                          </array>
                        </object>
                        ]
                      </array>
                    </object>
                    ]
                  </array>
                </object>
              -->
              <!-- This will set the affected version the Jira Issue was found on. Replace 'VERSION NAME-X' with the version name. -->
              <!--
                <array name="versions">
                  [
                  <object>
                    <string name="name">VERSION NAME-1</string>
                  </object>
                  <object>
                    <string name="name">VERSION NAME-2</string>
                  </object>
                  ]
                </array>
              -->
              <!-- This will set the date the Jira issue is due by. Replace YYYY-MM-DD with the Year, Month and Day. -->
              <!--
                <string name="duedate">YYYY-MM-DD</string>
              -->
              <!-- This will assign the Jira Issue to a user. Replace 'ASSIGNEE ID' with the User's ID. -->
              <!--
                <object name="assignee">
                  <string name="id">ASSIGNEE ID</string>
                </object>
              -->
            </object>
          </xsl:if>
          <xsl:if test="$action = 'UPDATE'">
            <object name="body">
              <string name="type">doc</string>
              <number name="version">1</number>
              <array name="content">
                [
                <object>
                  <string name="type">paragraph</string>
                  <array name="content">
                    [
                    <object>
                      <string name="text">The incident was updated in Oracle Enterprise Manager.
<xsl:value-of select="emcf:SystemAttributes/emcf:Summary" />

Severity is currently: <xsl:value-of select="emcf:SystemAttributes/emcf:SeverityCode" />
Priority is currently: <xsl:value-of select="emcf:SystemAttributes/emcf:Priority" />
Owner is currently: <xsl:value-of select="emcf:SystemAttributes/emcf:SourceInfo/emcf:SourceObjInfo/emcf:ObjOwner" />
This incident was updated at: <xsl:value-of select="emcf:SystemAttributes/emcf:LastUpdatedDate" />
                      </string>
                      <string name="type">text</string>
                    </object>
                    ]
                  </array>
                </object>
                ]
              </array>
            </object>
          </xsl:if>
        </object>
      </Body>
    </Message>
  </xsl:template>
</xsl:stylesheet>

Customizing Ticket Templates

If the out-of-box ticket templates do not satisfy your requirements, you can modify them. To do this, Oracle recommends that you use one of the existing templates as the base template. Copy this ticket template to a new file, modify, and register the new ticket template.

You can edit a template directly on Enterprise Manager instead of using the EM CLI command. See Editing Templates and Restoring Templates for more information. See Editing Templates and Restoring Templates for more information.

In most cases, when you modify the ticket template, you might only be changing the mappings. The following examples illustrate this concept:

Example 4-1 Add Due Date to Jira Ticket

To create a template to have a due date in Jira, find the following code in the template and remove the comment brackets () and set the date:

<!-- 
     <string name="duedate">2023-02-17</string>
-->

Example 4-2 Add a custom field into the template

Jira allows you to create your own custom fields. To add a custom field of your own, find the ID in Jira and add it into the template. To find your custom fields, from the Administration (gear icon) menu, select Issues and then Custom Fields. To find the ID of your custom field, click on the ellipses ( …) and select Edit Details or View field information. Once you are on this page, the ID will be in the URL. Once you have your ID, you can add a custom field with the name customfield_<ID>. Here is an example of a custom string field:

<string name="customfield_20000">"My custom field value"</string>

The templates are highly customizable. Oracle recommends that only users with advanced knowledge of XSLT make complex changes.

You can use incident or event rules as a filter to associate proper ticket templates with incidents. You can have as many tickets templates as desired. One incident or event rule can have only one ticket template.

Defining New Templates

The out-of-box templates are based on the default forms. If the new ticket templates you define are based on these forms, Customizing Ticket Templates applies.

However, if you use a different form, you need to define a new ticket template.

Enterprise Manager Attributes

The following table provides the Enterprise Manager fields that you can map when using Jira:

Table 4-2 Enterprise Manager Attributes

Data Fields	Description
EMUser	For auto-ticketing, this is the incident rule owner. For manual ticketing, this is the console user that triggered the ticket creation.
TicketID	Identifies the ticket associated with the current incident (available after ticket creation).
TargetType	Type of target that the incident is associated with, such as `host`.
TargetName	Name of the target that the incident is associated with. For example, `Database1` or `yourhost.example.com`.
TargetProperties	TargetProperties store environmental or usage context information specific to the target. For example, for Host Target, the name /value pair of TargetProperties are: Comment — Host running the management service and repository. Contact — John Doe Deployment Type — Production Line of Business — Development Location — Redwood Shores These are out-of-box user-defined target properties. If additional target properties are added, they are displayed with ticket information.
Summary	Description of the incident. For example: CPU Utilization is 100%, crossed warning (80) or critical (95) threshold.
Priority	Priority of the incident from `low` to `urgent`.
Severity	Severity of the incident: `critical, warning, clear,` or `down.`
CollectionTime	Timestamp of an incident occurrence.
IncidentURL	URL to the incident details page of the incident.
NotificationRuleName	Name of the incident rule that generated the notification during auto-ticketing.
TargetTimezone	Timezone of the target associated with the incident.

Format for Creating Ticket Templates

To create ticket templates for custom Jira forms, adhere to the following format:

Example 4-3 Template Format for Custom Jira Forms

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:emcf="http://xmlns.oracle.com/sysman/connector" version="1.0">
  <xsl:template match="emcf:EMIncident">
* [Insert any variables needed here]
 <Message>
            <Method>
        <xsl:choose>
          <xsl:when test="$action = 'CREATE'">POST</xsl:when>
          <xsl:when test="$action = 'UPDATE'">POST</xsl:when>
          <xsl:otherwise>ERROR</xsl:otherwise>
        </xsl:choose>
      </Method>
      <Variables>
        <Variable>
          <Name>TKT_KEY</Name>
          <Value>
            <xsl:value-of select="normalize-space(emcf:TicketID)" />
          </Value>
        </Variable>
      </Variables>
      <Headers>
        <Header>
          <Name>Authorization</Name>
          <Value>Basic $TOKEN$</Value>
        </Header>
        <Header>
          <Name>Accept</Name>
          <Value>*/*</Value>
        </Header>
      </Headers>
      <Body>
* [Insert body changes (details you are sending to Jira) here]
      </Body>
    </Message>
  </xsl:template>
</xsl:stylesheet>