How to parse issues' description using Automation?

Summary

This article provides a comprehensive guide on efficiently parsing work item description content into work item fields when requests are expected to follow a specific format.

It covers some work item field types and demonstrates the process using Automation for Jira.

Solution

It is possible to extract data from request descriptions into work item 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.

Understanding which information needs to be extracted

The first step is to map the information you receive in the email to the work item 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-select and Multi-select fields, the values in the request description must match the field option values exactly. A misspelled value, or a value that differs from the configured option, will fail to set the field.

For example, use Notebook when that is the configured Equipment option; Laptop is a different value.

Capturing the data through regex

The aim is to extract the important info from the description field using regular expressions (regex) to ensure 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.

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 Flow

Create an automation flow with the following configuration

• Add an work item created trigger

• Add an work item 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 flow to ensure you capture 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]*)").trim().asJsonObject("value")}},

• Add an Edit work item 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].

    To get only the first part, this regex matches the values between the bracket [ and the pipe | characters. Note: For fields containing strings with control characters (e.g., 'Description'), use smart values like {{issue.Description.asJsonString}} to escape special characters and ensure correct parsing.

  • 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]*)")}} || VPN Access: {{issue.Description.match("[\n\r].*VPN Access:\s*([^\n\r]*)")}} || Due date: {{issue.Description.match("[\n\r].*Starting Date:\s*([^\n\r]*)").toDate("dd-MM-yyyy")}} || Equipment: {{issue.Description.match("[\n\r].*Equipment:\s*([^\n\r]*)")}} } }

    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. Note: Add custom fields not available by default under 'extra properties' in the JSON payload for correct processing, as shown in the sample payload in our official documentation 'Create alert - JSM Ops API’.

• You can also use the following code block to create the JSON file to import

  KB-ExtractValues.json

  { "cloud": true, "rules": [ { "id": 15460902, "clientKey": "879629d9-c172-3e16-a203-d050c07481be", "name": "KB-ExtractValues", "state": "DISABLED", "description": "", "authorAccountId": "", "actor": { "type": "ACCOUNT_ID", "value": "557058:f58131cb-b67d-43c7-b30d-6b58d40bd077" }, "created": 1697542244320, "updated": 1698674065728, "trigger": { "id": "345704403", "component": "TRIGGER", "parentId": null, "conditionParentId": null, "schemaVersion": 1, "type": "jira.issue.event.trigger:created", "value": { "eventKey": "jira:issue_created", "issueEvent": "issue_created" }, "children": [], "conditions": [], "connectionId": null }, "components": [ { "id": "345704404", "component": "CONDITION", "parentId": null, "conditionParentId": null, "schemaVersion": 3, "type": "jira.issue.condition", "value": { "selectedField": { "type": "NAME", "value": "Request Type" }, "selectedFieldType": "com.atlassian.servicedesk:vp-origin", "comparison": "EQUALS", "compareValue": { "type": "NAME", "modifier": null, "value": "Emailed request", "multiValue": false, "source": null } }, "children": [], "conditions": [], "connectionId": null }, { "id": "345704405", "component": "ACTION", "parentId": null, "conditionParentId": null, "schemaVersion": 1, "type": "codebarrel.action.log", "value": "Department: {{issue.Description.match(\"[\\n\\r].*Department:\\s*([^\\n\\r]*)\")}} || VPN Access: {{issue.Description.match(\"[\\n\\r].*Department:\\s*([^\\n\\r]*)\")}} || Due date: {{issue.Description.match(\"[\\n\\r].*Starting Date:\\s*([^\\n\\r]*)\").toDate(\"dd-MM-yyyy\")}} || Equipment: {{issue.Description.match(\"[\\n\\r].*Equipment:\\s*([^\\n\\r]*)\")}}", "children": [], "conditions": [], "connectionId": null }, { "id": "345704406", "component": "ACTION", "parentId": null, "conditionParentId": null, "schemaVersion": 10, "type": "jira.issue.edit", "value": { "operations": [ { "field": { "type": "ID", "value": "duedate" }, "fieldType": "duedate", "type": "SET", "value": "{{issue.Description.match(\"[\\n\\r].*Starting Date:\\s*([^\\n\\r]*)\").toDate(\"dd-MM-yyyy\")}}" }, { "field": { "type": "NAME", "value": "Contact Email" }, "fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:textfield", "type": "SET", "value": "{{issue.Description.match(\"[\\n\\r].*Contact Email:\\s*\\[([^\\n\\r]*)\\|\")}}" } ], "advancedFields": "{\n \"fields\": {\n \"Department\": {{issue.Description.match(\"[\\n\\r].*Department:\\s*([^\\n\\r]*)\").split(\",\").trim().asJsonObject(\"value\")}},\n \"VPN Access\": {{issue.Description.match(\"[\\n\\r].*VPN Access:\\s*([^\\n\\r]*)\").trim().asJsonObject(\"value\")}},\n \"Equipment\": [\n \t \t{{issue.Description.match(\"[\\n\\r].*Equipment:\\s*([^\\n\\r]*)\").split(\",\").trim().asJsonObject(\"value\")}}\n ]\n }\n}", "sendNotifications": true }, "children": [], "conditions": [], "connectionId": null } ], "canOtherRuleTrigger": false, "notifyOnError": "FIRSTERROR", "projects": [], "labels": [], "tags": [ { "id": 48091427, "tagType": "IS_RULE_UPDATED", "tagValue": "true" } ], "ruleScope": { "resources": [ "ari:cloud:jira:f35b2a78-2342-4e89-99a4-bb8cb1f8aecf:project/10003" ] }, "ruleHome": { "ruleLifecycleHome": { "locationARI": "ari:cloud:jira:f35b2a78-2342-4e89-99a4-bb8cb1f8aecf:project/10003" }, "ruleBillingHome": { "locationARI": "ari:cloud:jira-servicedesk::site/f35b2a78-2342-4e89-99a4-bb8cb1f8aecf" } }, "writeAccessType": "UNRESTRICTED", "collaborators": [], "billingType": "NORMAL" } ] }

• Reference article on how to import the above flow to your site - Import and export Jira automation

  ℹ️ The flow 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 Space Scope after importing the new flow. Also, leave the Import flow owners unchecked.

Testing

Test the disabled flow after adapting the regex expressions to the format of your requests. Use request descriptions containing the following exact keywords:

• Department:

• Employee:

• Starting Date:

• Contact Email:

• Equipment:

• VPN Access:

Check the Log Action output to confirm that the expected values were captured, then check the issue fields updated by the Edit issue action:

• Confirm the Request Type is Emailed request

• Test that single- and multi-select values exactly match the configured field-option values

• Department, VPN Access, and Equipment should receive values matching the request description.

• Starting Date should be converted to Due Date using the existing dd-MM-yyyy format.

• Contact Email should extract the value before the pipe character when the email is received as a link.

• Equipment should be tested with comma-separated values because the existing JSON example splits that value into an array.

  • For example, use Notebook rather than Laptop when that is the configured option

Additional Resources

For further details related to this topic, see the documentation below:

• Components in Jira automation

• Debug an automation

• Smart values in Jira automation

If you have any questions, please contact Atlassian Support.