Using FireHydrant with Jira Custom Fields

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

Optionally, other 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 (logic). The available field mapping parameters are tied to the strategy selected.

Basic strategy

The basic strategy supports direct mapping between literal values or defined FireHydrant attributes (e.g. Incident Name, Current Priority) and Jira custom fields.

An example use case is: Populate the Jira custom field Incident Status with the FireHydrant attribute Current Milestone.

Logic strategy

The logic strategy supports conditions based on FireHydrant attributes. When a condition is met, the fields are mapped similarly to the direct mapping approach used for the basic strategy.

An example use case is: If the FireHydrant incident current severity is Sev 1, then populate the custom Jira field Severity with the literal value “Urgent”.

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, identify the project of interest.
4. Click Create field mapping.
5. Create each custom field mapping using the Strategy ( basic or logic ) and Type ( attribute or literal ) of interest.

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.

6. When you are finished adding mappings, click Create field mapping. In the following example, the configuration will map the custom Jira field, Epic Name, with the FireHydrant attribute, Incident Name.

Modifying custom field mappings

1. You can modify the mapping or add additional ones by selecting Update field mapping next to the project of interest.
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. Access the Edit a Field Mapping Screen by clicking on Update field mapping next to the project of interest.
2. If you wish to delete an individual field mapping, click Remove mapping below the mapping you wish to remove. To remove all field mappings for a project, under the Delete field mapping section select Delete permanently.

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