/
Use Regexp Field Processor

Use Regexp Field Processor

Introduction

The Regexp Field Processor uses Regular Expressions (commonly known as "regexps") to extract values from email content. Issue fields are mapped to these values. In addition, the field processor can be used to associate emails to an existing issue by finding a common regexp-extracted field value.

It is primarily designed for processing emails that have predictable content. A common source for such emails is an automated system such as Bugzilla.

It is recommended to have at least a basic understanding of how Regular Expressions work before attempting to configure this field processor. Useful references can be found from Wikipedia, and this online tutorial.

Just need issue association?

If you just want to create comments from email replies to notifications, then this field processor is not needed. By default, JEMH will use issue keys found in the Subject (the pattern used to search for issue keys can be modified via the Profile>Email>Subject IssueKey (comment) Regexps setting.

The Regexp Field Processor can provide the same behaviour with a 'custom field' of 'issueKey' and the appropriate regular expression.

Just Need Field mappings?

By default the Regex Field Processor will attempt to associate issues by matching a specific Regexp pattern within the Subject. If you do not need this then you can do the following to stop the Regex Field Processor from associating issues. These configuration options are found within Profile > Regex Configuration > Issue Association

  1. Remove the Default Regex from Value Regexp

  2. Remove the Value from Expected Match Value

Configuration

In the target JEMH profile, ensure that Directive processing is enabled by going to Profile>Directives.  Then, enable the Regexp Field Processor under Profile>Field Processors:

Once enabled, you should see the Regexp Field Processor section listed at the bottom of the main profile screen.  When the Regexp Field Processor is enabled, an example configuration is added:

Editing Configurations

Editing the processor configuration is done by clicking on the pencil icon

.  Once in edit mode, the Regexp edit screen shows more details about each Match Configuration.

From JEMH 2.2.6 (JIRA 7.4+) the configuration is displayed as 3 tabs.

Config

This tab contains a range of fields that define when the particular configuration should be used.

Field

Description

Field

Description

Projects

Restricts querying to defined projects when looking for issue association.

The first project defined is used for creation of issues.  If no projects are defined, another mechanism will be required in order to identify a project, such as Project Mappings or Directives.

Use Election

If enabled, JEMH will use its standard Field Processor selection method - the field processor that finds the most fields is used.  If this setting is disabled, then the Regexp Field Processor will always be the one used once an email has been found to match the From Address or To Address settings (see below).

Allow Project Mappings

If enabled, Project Mappings are used to supply of additional custom field defaults, and potentially workflow advancement.

About Custom Field Defaults & Rules

If NO PROJECTS are scoped in the Regexp Config, the ALL RULES are tested, and custom field defaults etc are applied when such a Rule matches. If there PROJECTS are scoped in the Regexp Config, the RULES are NOT tested, as an optimization, and only the Project Mapping custom field values would be applied.

Reporter

If a user is defined here it will be used as the reporter for issues created by this Field Processor.  This takes precedence over profiles Default Reporter and would be used when the sender is not associated with a Jira user.

To Address

If the email To address matches the address entered here, the Regexp Field Processor can ensure that is the one used over other processors (if Use Election is disabled).

From Address

If the email From address matches the address entered here, the Regexp Field Processor can ensure that is the one used over other processors (if Use Election is disabled).

Select body part type to process

Choose what part of email bodies are processed in order to find an issue association value (text or HTML).

Match Many field Values

Enabling this setting means that all matches for Field Mappings will be extracted.  If disabled, only the first found match will be extracted.

Issue Association

The Regexp Field Processor can be used to associate an email with a JIRA issue:

  • On issue creation a uniquely identifiable value is extracted from the creating email through the use of a configured regular expression/script

  • This value is set on a configured custom field.

  • The next time an email is processed by the processor it will extract a value using the same steps

  • If an existing issue is found to already have this value in the custom field, and is not in a status defined under Resolved Statuses, an issue association will be made

  • Ensure that the custom field set has the Search Template set to Free Text Searcher

Field

Description

Field

Description

Require Value Match

Enabling this setting requires a valid remote system value to be found, meaning that now, many remote systems can be matched and have regexp field extracts that are applicable to that source. The only limitation is that the remote system keys must be unique in format.

If you do not enable this, comment association by regexp will not work

Use Issue Keys in the subject if valid

If enabled, issue keys present in the email subject will be used instead of using its JQL lookup.

Search in Subject

Where to search for the matching 'value' that is to be stored in a custom field, or to be searched for, for commenting instead of creating new issues if follow-up messages occur. If not checked, the Body is inferred as being the target text to scan.

Custom Field Name

The name of the custom field that will be assigned the identifying 'id' value from the remote system.

Value Type

As of JEMH 2.2.6 there are two methods for extracting values (called Value Types).  The Value Type of Regexp, combined Value Regexp is the most simple, and enables a single value to be extracted from an email's subject or body.

In more complex cases you may wish to combine extracted information from more than one part of the email.  Using the Value Type of Script allows a compound value to be created, through the parsing of a Velocity template.

Script TypeSince 3.3.46

The scripting type used for the Value Script. Allows installed script engines and languages as well as Velocity.

Value Regexp

The regular expression that matches the field in either Subject or Body, used for issue association.  This regular expression must return the actual value as capture group 1, for example, a regexp of: Ticket

#([0-9]{6})

would return a 6 digit numeric component of matching text. This value will be initially used to search for an unresolved issue with the given Custom Field containing the value, otherwise, used to populate that field during issue creation

Value Script

A custom script that extracts values from either the Subject or Body, used for issue association. This value will be initially used to search for an unresolved issue with the given Custom Field containing the value, otherwise, used to populate that field during issue creation.

Expected Match Value

For configuration time testing purposes, test case content is required, usually from a 'Basic Field Processor' description copy/paste, as the text that ends up in JIRA as an issue description will be the same text that will be scanned. The Expected Match Value will be what the eye determines is the appropriate text value that should be found by the Value Regexp (above), a mismatch or failure of any kind will be reported at configuration time.

Resolved Statuses

Identifies the optional statuses that should not be included in the search for a matching issue. Normally this would be Resolved,Closed

If this field is left empty, JEMH will fallback to excluding issues in Resolved and Closed statuses from matching, even though no statuses have been defined. This behaviour contradicts the user interface and will be improved in a future JEMH release: https://thepluginpeople.atlassian.net/browse/JEMH-6012