Using FireHydrant with Jira Custom Fields

Note: This article is about mapping FireHydrant values and fields to Jira Custom Fields. For information about FireHydrant Custom Fields (custom fields on incidents), see this article instead.

Overview

FireHydrant's Jira custom field integration feature supports two broad categories of Jira custom fields:

• The most common Jira epic ticket type
• Jira custom fields that are mappable to FireHydrant incident fields

Using Jira epic ticket types

The most common Jira epic ticket type is supported as part of the existing Jira multi-project configuration workflow. An example is the epic ticket type created with the Jira Scrum Template.

When configuring a project as part of the Jira multi-project workflow, for some epic ticket types you may need to map the custom field Epic Name before being able to select Epic as the default ticket type for incident or action item tickets. For more information on Jira configuration or multi-project migration see:

• Integrating with Jira Cloud
• Integrating with Jira Server (On-Premise)
• Configuring Jira Projects

Other Jira custom fields

Custom field mappings can be configured once a Jira project has been configured in FireHydrant using the multi-project configuration workflow.

Mappable FireHydrant incident fields

The following FireHydrant incident fields can be mapped to Jira custom fields:

• Severity
• Priority
• Current milestone
• Ticket name
• Summary
• Incident name
• Milestone transition times

Note: Not all attributes will be able to be mapped to any Jira field, as some Jira fields may have a data structure or type restrictions that are not appropriate for the desired field. For example, one field type we do not support at this time is array fields, which Jira uses for the Components field. Also, at this time the integration is one-way only, meaning that changes to mapped fields for linked Jira tickets will not propagate back to FireHydrant.

Custom field mapping concepts

Field mappings can either be direct (basic) or based on a condition (advanced).

Basic Mapping

The basic mapping directly maps FireHydrant incident metadata (e.g. Incident Name, Current Priority) to the value of a Jira custom field.

As an example, the basic mapping would be used to: Populate the Jira custom field Incident Status with the FireHydrant attribute Current Milestone.

Advanced Mapping

Advanced mapping allows conditional logic to determine the value of a custom field based on FireHydrant attributes. This is best used when advanced logic is required to populate a specific field, for example: If the incident Severity is Sev1 or Sev 2 then populate the custom Jira Field of "Response SLA" with "Urgent" else populate the custom Jira Field of "Response SLA" with "Normal"

Custom field mapping instructions

Note: To configure FireHydrant's Jira custom field mapping requires a user with a FireHydrant owner role.

Prerequisites

• A FireHydrant owner role is required to access the Jira integration configuration settings.
• To access custom field mapping, you must first have the Jira project configured in FireHydrant using the multi-project process.

Creating custom field mappings

1. In the web UI select Integrations from the left-hand navigation bar.

2. From the Jira Cloud or Jira Server integration tile, click to Edit the configuration.

3. Under the Projects section, click the project to create the mapping in.

4. Click Field Mapping. ![Screen_Shot_2022-04-18_at_4.35.58_PM.png]

   

5. To add a new Field Mapping click the Add a Field Mapping button, and use the wizard to create your new field mapping.

For literal values, the value entered must be valid for the target field.

• For things like datetimes, this means that the value must be a valid json datetime
• For strings, it's a string.
• For options, the string value must match exactly a valid option.
• For arrays of strings they can specify comma separated values.
• Jira component type fields can be handled by passing in an array as a literal value. For example:

  

  Liquid templating is supported as long as the dynamically generated text data type matches the Jira destination field. See this supplemental docfor detailed instructions.

Modifying custom field mappings

1. You can modify the mapping by selecting Edit under the menu next to the field mapping you want to change.
2. From the Edit a Field Mapping screen, modify the existing mapping or add additional ones. When you are finished, click Update field mapping.

Deleting custom field mappings

1. You can delete the mapping by selecting Delete under the menu next to the field mapping you want to remove.

Using Liquid templating with Jira custom fields

Liquid templating variables can be used to populate supported FireHydrant fields with dynamically generated data from the FireHydrant API.

Considerations

Data type alignment

Jira requires that the data type from the literal field match the data type of the Jira destination field.

For example, a literal free-form text value to a Jira free-form text field or a literal configured array to a Jira array field.

Array handling for Jira labels

If you are planning to pass data into the Jira Labels field any spaces in an array item string will be turned into a separate Jira label (e.g. Login Portal will become 2 separate labels, Login and Portal).

To prevent this a placeholder character must be added, such as a hyphen.

Example Usage

In this example, we’ll pass the following dynamic variables to the Jira Labels field:

• Impacted functionalities
• Incident severity
• Incident number

1. Configure the field mapping

From the Integrations tiles, choose to edit the Jira configuration.  For a Jira project of interest, add a literal value field mapping with the destination as the Jira Labels External field.

2. Impacted functionalities liquid syntax

The impacted functionalities array contains both the name and ID, but we only want the name.

In this example, we’ve replaced any spaces in functionality names with a “-”. This is the Liquid code to pass in an array of impacted functionality names where each impacted functionality will get its own Jira label:

{{ incident.functionalities | map: "name" | join: "," | replace: " ", "-" }}

3. Incident severity liquid syntax

Now we'll add a label for current incident severity, which looks like this:

{{ incident.severity }}

4. Incident number liquid syntax

Lastly, we'll add a label for incident number, which looks like this:

{{ incident.number }}

5. Putting it all together

Here is the liquid code all together:

{{ incident.functionalities | map: "name" | join: "," | replace: " ", "-" }}, {{ incident.severity }}, {{ incident.number }}

Copy this into the Value field. Click Update field mapping to save the configuration.

6. Use the mapping in a Jira incident ticket

Create a runbook step pointing to the Jira project with your new Label mapping.

When an incident ticket is created with the mapped project fields, the impacted functionalities, incident number, and severity are passed to the Jira Labels field.

Once the field mapping is configured, the mappings will also be applied for any other tickets, incident or follow-up, created in the same Project.

Additional references

• Using Template Variables (also covers Liquid syntax and other supported variables)
• FireHydrant's Liquid Playground