How to parse issues' description using Automation?
Platform Notice: Cloud - This article applies to Atlassian products on the cloud platform.
Summary
This article provides a comprehensive guide on efficiently parsing issues' description content into issue fields when requests are expected to follow a specific format.
It covers some issue field types and demonstrates the process using Automation for Jira.
Environment
Jira Service Management Cloud
Solution
It is possible to extract data from request descriptions into issue fields.
This will be especially useful when your requests are created through Email Requests or from another system through an API integration.
For this article, please consider the following email as an example of a request from the HR team to the IT department for a new Employee's Onboarding.
It will be processed through the Email Requests feature.
Hi IT Team,
We have a new addition to our company:
Department: Marketing
Employee: John Doe
Starting Date: 01-11-2023
Contact Email: jdoe@email.com
Please setup the following for John:
Equipment: Notebook, Mobile phone, Monitor, Mouse, Keyboard
VPN Access: Yes
Thanks for your prompt attention to this matter.
Best,
HR Team
About Email Requests
Requests sent to your service project’s email address are automatically added to your queues so your team can focus on customers without worrying about missing requests or managing multiple inboxes.
Further information about this feature and how to set it up can be found here: Receive requests from an email address.
Understanding which information needs to be extracted
The first step is to map the information you receive in the email to the issue fields you want to update.
In this example, you have references to:
- The Department field (Single-select)
- Starting Date, which will be mapped to Due Date
- The Equipment field (Multi-select)
- The VPN Access field (Single-select)
- The Contact Email field (Short text)
For Single and Multi-select fields, their options' values must match the values sent through email.
For instance, the field setting will fail if a value is misspelled. The same will happen if we include "Laptop" in the equipment instead of "Notebook."
Capturing the data through regex
The aim is to pull out the important info from the description field through regular expressions (regex) for accurate data capture.
The following expression will match a line of text that starts with "Department:" and will capture the string that comes after it until the end of the line.
[\n\r].*Department:\s*([^\n\r]*)
This same expression will work for every field in this example, but it may require changes based on the format of the emails you receive.
Here are some resources you can refer to:
- Regular Expressions Clearly Explained with Examples
- REGEX TUTORIAL: LEARN WITH REGULAR EXPRESSION EXAMPLES
- A great tool to test and debug your regex is https://regex101.com/
Building the Automation rule
Create an automation rule with the following configuration
- Add an Issue created trigger
- Add an Issue fields condition condition that will check that Request Type equals Emailed request (To ensure that only Email Requests will be processed)
Add a Log Action component. This will be useful for troubleshooting while building the rule to ensure you captured the right information.
For instance, the following string will log the content to be set in the Department field.Department: {{issue.Description.match("[\n\r].*Department:\s*([^\n\r]*)")}}
- Add an Edit issue action.
Here, you have two options to set the fields:Some of the fields, such as Text, Number, or date fields, can be set through Basic field editing (Selecting the field to be set from the dropdown and pasting the Smart Value in the text box)
For instance, for Due Date, we use:{{issue.Description.match("[\n\r].*Starting Date:\s*([^\n\r]*)").toDate("dd-MM-yyyy")}}
For the Contact Email field, we use:{{issue.Description.match("[\n\r].*Contact Email:\s*\[([^\n\r]*)\|")}}
This field has a small catch.
Usually you will receive email addresses as links within your emails. This means that instead of receiving jdoe@email.com, you will receive [jdoe@email.com|mailto:jdoe@email.com].
In order to get only the first part, this regex is getting the values between the bracket [ and the pipe | characters.For Single and Multi-select fields, you must use Advanced field editing through JSON. This can also be used for every field
In this JSON, we are setting the Department, VPN Access, and Equipment fields:{ "fields": { "Department": {{issue.Description.match("[\n\r].*Department:\s*([^\n\r]*)").trim().asJsonObject("value")}}, "VPN Access": {{issue.Description.match("[\n\r].*VPN Access:\s*([^\n\r]*)").trim().asJsonObject("value")}}, "Equipment": [ {{issue.Description.match("[\n\r].*Equipment:\s*([^\n\r]*)").split(",").trim().asJsonObject("value")}} ] } }
We extract the value, remove any spaces, and convert each field into a JSON object.The Equipment field is slightly different because it's a multi-select field and expects an array of values. These values are separated by a comma in the email.
You can see details on how to do it and the format you need for each field type here: Advanced field editing using JSON.
- Here is what the rule will look like:
You can also import the following rule KB-ExtractValues.json
- Reference article on how to import the above rule to your site - Import and export Jira automation rules
The rule is disabled so that it doesn't run automatically before the necessary changes to the regex that suit your needs and the required testing is done.
Next, It's important to select the right Project Scope after importing the new rule. Also, leave the Import rule owners unchecked.
If you need to update a user-picker's field based on the Description, please take a look at this article: Populate a user-picker field from the description field.
Testing
Testing this rule with different scenarios and values is recommended to ensure everything works as expected.
Additional Resources
For further details related to this topic see the below documentation:
Contact Atlassian support if you have any questions.