Jira Field Mapping

FireHydrant's incidents have numerous out-of-box fields as well as custom fields. Subsequently, organizations may need to map these FireHydrant fields to Jira fields when creating tickets. FireHydrant allows for this via the Field Mapping tab.

This step is required if your organization's Jira project(s) have custom required fields, in which case these mappings must be configured, or API calls will fail.

Prerequisites

• You will need Owner permissions on FireHydrant to configure integrations.
• You must have already created at least one Jira project.
  • If not, see the guides for Jira Cloud or Jira Server (On-Premise).

Default mappings

When you create Jira incident tickets or follow-up tickets from FireHydrant, these are the following default behaviors. You must set up custom field mappings if you'd like anything more or to override/customize the behaviors below when creating Jira tickets.

Incident tickets

Follow-Up tickets

When do I need to configure custom mappings for fields?

There are multiple scenarios where you must configure field mappings for FireHydrant to be able to create tickets in your project(s):

• When you want more than the default mappings/behavior - See the previous section
• When you have custom, required fields - If a specific project has any required fields that are not set automatically above, especially if they are custom issue fields, then you'll need to configure them in FireHydrant so we know what to set for those fields
• (Sometimes) When using the Epic issue type - Some organizations have configurations in place such that when creating a ticket of type Epic, both Summary and Epic Name fields are required. In this instance, you must create a mapping for Epic Name (you can set it to a dynamic value, like {{ incident.name }}, see below)

How to configure field mapping

Assuming you're in a situation where you must map fields, follow the instructions below.

1. Navigate to the Jira settings page and click on the project you'd like to configure, then the Field Mapping tab.
2. Click '+ Add mapping' to create a new mapping.
3. A drawer will come out on the right where you can select between two choices:
   1. Basic mapping allows you to always set fields in Jira to the same values.
   2. Advanced mapping allows conditional logic to map different fields to different values in Jira based on various parameters within FireHydrant.

3. You can select a Jira field once you've selected between basic vs. advanced mapping.
   1. If Basic, you can set the field's value, and this will apply each time you create the ticket and whenever any detail on the incident is updated.
   2. If Advanced, you can select conditions and values that should apply when those conditions are met, along with an Else default value if no conditions are met.

📘

Note:

Field mappings for a project and its tickets are evaluated and applied upon every incident update. For example, if you have a condition to "set Jira ticket Severity field to SEV1 whenever the incident is is SEV1, otherwise default to SEV3," this will evaluate each time you make updates on the incident so that if the severity is escalated/de-escalated, the field in Jira will change accordingly.

4. For values, you will see multiple possibilities depending on the field's configuration in Jira:
   1. For single-select fields: You will see a dropdown to choose an existing value from Jira
   2. For all other fields: You can choose between preset FireHydrant parameters and "Use a custom value." If you select Custom Value, you can input any value you'd like, and the field will also support Template Variables. Note that what you can insert as a custom value will depend on the field's settings in Jira. For in-depth examples, visit the section below.
5. Once this field's mapping has been configured to your liking, click Save to persist. Rinse and repeat these steps for all fields you'd like to map.

📘

Note:

Currently, the integration is one-way only. Changes to mapped fields for linked Jira tickets will not propagate back to FireHydrant.

Advanced Mapping Conditions

The following conditions are available for configuring advanced if/else if/else rules in Jira Field mapping:

• Current severity - Current incident's severity
• Current milestone - Current incident's milestone
• Incident name
• Incident number
• Ticket priority - Priority of the Follow-up created on FireHydrant (not Incident)
• Ticket tags - Tags of the Follow-up created on FireHydrant (not Incident)
• Incident impacted infrastructure - Which Service Catalog components are impacted on an incident
• [Custom Fields] - Any Incident Custom Fields configured by users
• Entered [milestone] at - If timestamp for the specified milestone exists and has been filled in

Custom field mapping values

Custom values allow you to input what you'd like us to send to Jira. Remember to check the type of the Jira field you are attempting to map, as some formats and inputs may not be accepted.

• The value entered must be valid for the target field for literal values.
• For things like datetimes, the value must be a valid JSON datetime.
• For options, the string value must match a valid option exactly.
• For arrays of strings, you 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 if the dynamically generated text data type matches the Jira destination field.

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 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 the current incident severity, which looks like this:

{{ incident.severity }}

4. Incident number liquid syntax

Lastly, we'll add a label for the 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 be applied to other tickets - incident or follow-up - created in the same project.

Next Steps/Resources

• Learn more about FireHydrant's Template Variables
• Look at FireHydrant's Liquid Playground
• Browse the rest of our integrations