Use Regexp Field Processor
- Mike Harrison
- Ryan Clifton
- Andy Brook [Plugin People]
Scenario
The information provided in this how-to article will cover setting up a profile, and also the configuration and testing of the Regexp Field Processor in JEMHCloud.
A Regular Expression (commonly abbreviated to Regex or Regexp) is used for pattern matching of sequences of characters. JEMHC can use this as a method for extracting information (dates, numbers, statuses etc.) from emails that have consistent but not strictly structured content. If combined with Directive Aliases, it can also be used to translate incoming information from an external system (such as Bugzilla) and translate that information into something that can be used by JIRA. For example, an Urgency status in one system can be converted to a Priority status in JIRA.
Some basic understanding of how a Regular Expression is used is advisable, but not needed as it can be picked up quickly. For more information including references on Regular Expressions, please see "Related Articles" at the end of this page.
The JEMHC Regexp Field Processor uses regular expressions to locate information from an emails subject or body text content. For this how-to guide, lets say that your incoming emails always specify one or more "team colours" (red/blue/green/yellow) and a 4 digit "team ID number" (e.g. 1234). The Regexp Field processor can be set up to find this information and populate fields within JIRA.
Initial Set-up of JEMHCloud profile
Go to the Profiles tab on your JEMHC instance. Click the Create button found at the top right hand side. This will take you to the New Profile screen. Enter a name and description for your profile, and choose a readiness state. Next, we are going to enter a Catch Email Address. This is the inbound mailbox address that emails must be addressed to in order for them to be processed by JEMHC. In order to prevent mail loops, emails will not be sent to addresses entered here. Please note the information given on this screen in regards to being specific with addresses. Whilst the regexp ".*@domainname\.com" can be used, this will prevent all emails sent to that domain name from being processed. For the purposes of this example, we have configured the screen as follows:
After clicking Submit, the profile will be added to your profile list. The small arrow next to the profile name can be used to expand/contract a view of the profiles top level settings. Click Configure (cog icon) on the right of your profile to go into the profile configuration. Choose Edit on the right, and change the Rule Evaluation Strategy to "Rule Priority". This will be explained later in the guide.
Also, please choose an Non-Delivery Email Action setting as this is a required setting. This is the action taken when an email bounces for some reason. Press Submit at the bottom of the page to save our changes.
Next, we are going to click on Project Mappings on the left hand side. Select Configure (cog icon) on the right of our default project mapping.
Adding Fields for use by the Regexp Field Processor
While the field(s) that you want to populate may already exist, for the purposes of this example, we will be setting up two new ones: Team Colours and Team ID Number. Go to Administration>Issues (by using the cog at the top right of the webpage). Choose Custom Fields from the left hand side. Click Add Custom Field . For our Team Colours field, we are going to choose the "Text Field (single line)" field type.
Select the field type and press Next. Add a field name (Team Colours in our case) and description if wanted. Click Create to create the custom label.
Next, we choose what screens that the field will appear on. It must be associated with a screen before it will be displayed. Normally, you would want to choose the appropriate screen for your particular project. For simplicity, we are selecting all available screens.
Click update, and the new field will be added to the full list of fields (list is sorted alphabetically). Repeat this process for the second field, Team ID Number. The steps are identical, except that the Number Field field type is chosen instead.
Configuration/Testing of the Regexp Field Processor
Go back to your profile. Edit the default project mapping and click the Field Processors section on the left hand side. Here is the page where you can enable or disabled different field processors for JEMHC to attempt to process an email with. Click Edit to choose which are enabled. In this example, we are setting Apply Field Processors to "On Create/Comment". We are also enabling both the At(@) Prefix, and crucially the Regexp Field Processor itself.
Regexp Set-Up View
At this point, the Field Mappings and Test Case Mail sections are now visible. This section is where we configure and test each of our Regexps individually. These sections are initially populated with example regexp field mappings and a test case email to test them with. Time for a quick overview of each column shown here.
Scope: The area of the email where this regexp is trying to match content. You can choose Body, Subject, or both.
Regex: The regular expression used to match and extract information from the email. Make sure the regexp is specific enough to only get the information you want.
Field: The field that is populated with information when the regexp match occurs.
Retrieve Strategy: "First Matching Value" means that only the first match the regexp makes are stored. "All Matching Values (CSV)" means that all matches made are stored using CSV (comma-separated values).
Expected Value: This is where the user (you) enters the expected result of the regexp when the test case mail below it is processed.
Test Case Value: This is where the actual value that the regexp retrieves is shown.
Match Status: If the expected value and the actual test case value match, a green "OK" status
is shown. If the match fails, a red "MISMATCH" status
is shown.
Example Test Case Set-up
Just before we add the regexp lines, lets set up the test case mail below it. This test case email here must be a text/plain type email if you are copy/pasting from a JEMH test case. Please follow the steps mentioned on the page if you need to convert your test email into a post-processed plain text format for use in the regexp test case window.
For this example we are using the following test case mail:
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: [#12345678] This is a starting email template, update as required
From: andy@faraway.com
To: notest@localhost
Content-Type: text/plain; charset=UTF-8
This is a test formatted email. This is the body of the text.
situationlevel=bad
teamid=5812
colours=blue
colours=red
This is also part of the email body.Example Regexp Set-up
Now to set the regexps. On the first regexp line, enter "colours=(red|blue|green|yellow)" as the regexp. Select the Team Colours field from the field drop-down list. If your custom field does not show in the list, ensure that you have followed the previous field creation steps correctly. You may need to refresh the current page (F5) in order for the new fields to be present. For Retrieve Strategy, we are choosing All Matching Values as in our example we expect multiple items of team colour information. Under Expected Value we type "blue,red". The Match Status should now go green to indicate a successful match.
On the second line, we have entered "teamid=([0-9]{4})" for the regexp. This will match "teamid=" followed by any four numbers. Select Team ID Number for field. Choose "First Matching Value" for strategy, and Expected Value as 5812. Once again, the match status should show a correct match.
This third regexp will be used alongside a Directive Alias (see below). It is a useful function to understand, but if you want to skip it proceed to the final email test at the end of this guide.
Lastly, for the third line we are going to set up a regexp for use with a Directive Alias. These can be used to shorten directives (e.g. turn priority=highest into #pr1). In our example we are using it in a more advanced way in order to translate information from an external system into JIRA-compatible information. We will set up the alias itself immediately after this. For the regexp, enter "situationlevel=(bad)". Set the field to be Priority and strategy to First Matching. Our expected value is "bad". Check the match status as always.
Directive Alias Set-up
On to the last part of this particular regexp setup, the Directive Alias itself. Select "Value" as the Alias Type. Enter "bad" as the Alias. Enter "blocker" as the Value.
Now is a good time to make sure all settings are saved, so press Submit.
Final Testing of Regexp Field Processor Configuration
Press Edit and scroll down to the bottom of the page and expand the Field Processors Email Tester section. Here we are going to do a final test to see if all of our Regexp processor configurations work as intended.
Here, you can either load a pre-made test case, or you can paste a test case. For our example, we are going to copy and paste the test case we used earlier up the page. Select what type of email event operation to test (Create or Comment). Paste your test case, then press Test.
If you have successfully set all the above up, then you will notice that all custom fields chosen are populated. Also, the priority directive has been used to set priority to "blocker" status.
Press Submit once more to ensure your settings are saved. You have now correctly set up the JEMHC Regexp Field Processor for use.
Related articles
External Links: