Email This Issue
📈 Marketplace❓ Support❤️ Feedback🏠 META-INF Apps
Email This Issue - for Jira Cloud
Email This Issue - for Jira Cloud
  • ⬇️Overview
  • Email This Issue - for Jira Cloud
  • Features
  • How Email This Issue Works
  • Secure the email channel with Email This Issue
  • Comparing Email This Issue and Jira Cloud
  • 📤Outgoing Emails
    • Outgoing emails overview
    • Manual emails
      • Configuring manual emails
      • Sending manual emails
    • Email notification schemes and email notifications
    • Workflow post functions
    • Advanced email configuration
    • Customizing email templates
    • Canned Responses (default messages)
    • Scope evaluation
  • 📥Incoming Emails (Mail Handlers)
    • Incoming emails overview
  • Mail handlers - adding / editing
    • General handler settings
    • Filtering
    • Finding issues
    • Setting up rules and actions in the actions editor
      • Adding/editing actions
      • Adding recipients to Request Participants
      • Creating an issue
      • Updating an issue
      • Setting field values
      • Adding comments
      • Sending auto-reply emails
      • Executing workflow transitions
      • Creating a customer
      • Using split regexp
      • Conditions
      • Approve request
      • Decline request
    • Maintaining email chains
    • Mail Handler New UI
  • Global Sender Address Filters
  • Attachment Filters
    • Regular Attachment Handling Deprecation
  • 🤓Administration
    • Outgoing Mail Connections
    • Alerting via Webhooks
      • Webhooks
        • Configuring Slack to receive alerts via webhooks
        • Configuring OpsGenie to Receive alerts via webhooks
        • Configuring Microsoft Teams to receive alerts via webhooks
      • Webhook execution logs
    • Mail Queue
    • Email Audit Log
    • Permissions
    • Recipient Restrictions
    • Incoming Mail Connections
    • Email Security
    • Incoming Mail Queue
    • Incoming Mail Log
    • OAuth2 Credentials
      • Enabling OAuth2 Authorization in your Google Account
      • Enabling OAuth2 Authorization in your Microsoft 365 Account
      • Troubleshooting guides for Microsoft OAuth2 Connections
        • How to fix "BAD User is authenticated but not connected" error​
        • How to fix "401 Unauthorized" error
        • How to fix "key expires_in " error
        • How to fix "Need admin approval" error
  • ☁️Server to Cloud Migration
    • 🛫Server to Cloud - Automatic Migration tool
      • Preparing for the migration
      • Doing the migration
      • Finalizing the migration in Cloud
      • Migration with unsupported Jira versions causes errors
    • Server to Cloud - Manual migration guide for Email This Issue
  • ❓FAQ
    • No recipients error in outgoing emails
    • How-to add custom macro to email Template?
    • Why cannot I select custom event types in notification?
    • How to configure the Email This Issue addon user in Jira Cloud?
    • I get an error: Could not create request on behalf of the sender
    • Why is the Incoming Mail Queue size limited?
    • Outgoing mail not sent - Read timeout error
    • Access restriction icon is not appearing when adding internal attachments via Email this Issue
  • 🌪️General
    • Release Notes
    • API
      • API for Velocity Context Objects - 1.7
      • API for Velocity Context Objects
    • Addon Pages
      • Integrity Check
      • Feedback and Support
    • Security Advisories
      • Email This Issue Security Advisory September 28, 2020
    • Appendix
      • Supported Time Zones
    • Integration of Glass Documentation
Powered by GitBook
On this page
  • Issue key-based lookup
  • Header-based issue lookup
  • JQL lookup
  • Limitations

Was this helpful?

  1. Mail handlers - adding / editing

Finding issues

PreviousFilteringNextSetting up rules and actions in the actions editor

Last updated 4 months ago

Was this helpful?

The purpose of issue lookups is to find the matching issue based on a particular attribute (or part of its value) of an incoming email message that has not been filtered out by the global sender address filters or any of the active mail handler filters.

Only one matching issue is accepted for any incoming email.

If there are multiple hits, the first one returned by Jira API will be taken as the match. You can use IF/ELSE conditions in the Rules and Actions tab to ensure that the issue found in the lookup is the one you would expect.

The issue lookups can be configured on the Find issue tab:

There are three different kinds of lookup methods, executed in the same order they appear in the UI (cannot be changed):

Note: Please keep in mind that if multiple issue lookups are enabled at the same time, the lookup process is stopped after the first unambiguous match is found.

Issue key-based lookup

Find issue by issue key extracted from the message Subject. This is always active.

  1. It extracts parts from the mail Subject that look like an issue key.

  2. It checks if there is an issue with the extracted issue key.

  3. If such an issue does not exist, then it continues with the next extracted part from the Subject that looks like an issue key.

Header-based issue lookup

Find issues by message reference present in message headers.

  • Find issue by the Message-ID extracted from the In-Reply-To header: it looks for an issue, where any of the Message-IDs stored in the com.metainf.emailthisissue.entityproperty.messageids issue entity property equals to the message-ID in the In-Reply-To header of the incoming message.

  • Find issue by the Message-ID extracted from the References header: it looks for an issue, where any of the Message-IDs stored in the com.metainf.emailthisissue.entityproperty.messageids issue entity property is present in the References header of the incoming message.

Note: The In-Reply-To or the References headers may also contain internal (Jira-specific) Message-IDs, in this case an issue ID is extracted from the Message-ID itself in order to identify the corresponding issue.

JQL lookup

Find issues by using a JQL filter based on a regular expression that matches a part of the incoming email to a value of a JQL expression.

The JQL-based lookup is a bit more complex than the others. JQL filters have the following options:

  • Defining a static JQL condition: the Email Field and the Regular expression fields shall be kept empty, only the JQL condition is used for the lookup. This can be useful if you want to associate multiple incoming messages to a single Jira issue which can be found by a constant JQL query.

  • Constructing a dynamic JQL condition by referencing the extracted value via capture group(s), e.g. $!group0, where the decimal refers to the index of the capture group. It is possible to compile a JQL query as a mix of dynamic and constant conditions.

It is allowed to parse an email attribute that contains multiple values. If more from these would result in potential matches (e.g. if multiple recipient addresses would satisfy the JQL condition), the first applicable term (extracted from the attribute with the help of the regex) that results in an unambiguous match with a Jira issue is used.

If a JQL query can return multiple results, be sure to use the ORDER BY clause to ensure that the first returned result is the one needed. For example, to get the issue with the lowest issue ID (practically the oldest one), apply this clause: "ORDER BY key ASC"

When entering a JQL lookup, Check now option can be used to validate the JQL.

Important: If you make use of the issue key in your JQL condition (e.g. issuekey = “$!group1“), the JQL validator will return an error and may not discover other actual problems with the expression provided.

Please check the JQL validity using an actual issue key for validation, then replace it with the group values before saving.

Example:

Note: If you send issue keys in your custom X-Issue-Key email header, it can be extracted by a regular expression and the matching issue can be found. The header may contain multiple values. In the latter case, the first value matching the regex will be replaced into the JQL condition.

Eg. the X-Issue-Key: TPA-123 GLAS-42.mod header line results in the following JQL condition: issuekey = "GLAS-42".

Limitations

  • If you need to combine various needs that cannot be expressed in a single lookup (or with the linear combination of the subsequent lookups), you need to create different Mail Handlers to cover those (mutually exclusive) logical rules.

  • The issue lookup is not confined to any specific project; it will always search your entire Jira instance for matches, so be sure to add conditions in Rules and Actions to restrict the issues found, if necessary.

This lookup action can be used to maintain email chains (i.e., email threads) without having to include the issue key in the email subject. Read more about it .

here
Issue key-based lookup
Header-based lookup
JQL-based lookup
Find issue tab