Configuring Data Points for Email

Data Point Configuration: https://veristorinfo.wistia.com/medias/jkqd1w68ro

Data points extract information from an incoming email that matches an email handler. You configure data points differently depending on the format of the incoming email message—as key-value pairs or as regular expressions. After you define data points, you can use them as variables in handler actions.

Prerequisites

Configuring Key-Value Pairs

If email messages that match this handler will contain data structured as key-value pairs—such as data from a web form—you must identify the keys to extract the matching values as data points.

  1. In JIRA, click the gear icon, and then click Applications.
  2. Under Integrations, click SmartHandler, and then click the handler in the list.
  3. Click the Data Points tab, and then do one of the following:
    • To create a new data point, click New Data Point.
    • To edit an existing data point, click the row in the list.
  4. Configure the settings for the value you want to extract.

    FieldDescription
    Key

    Enter the key name as it will appear in the email message. For example, if the email will contain a key-value pair such as date_needed: 09-12-2017, enter date_needed as the key. In this example, the extracted value will be 09-12-2017.

    DescriptionEnter a brief description of the extracted value.
    Is this a Date or Time?Select the check box if the value is a date or time, and then indicate the expected format. See Defining the Date or Time Format.
  5. Click Save.
  6. Repeat steps 2 – 6 for each value that you want to extract from incoming email messages.

Configuring Regular Expressions

If email messages that match this handler will contain free-form text, you must define regular expressions to extract keywords and phrases as data points.

  1. In JIRA, click the gear icon, and then click Applications.
  2. Under Integrations, click SmartHandler, and then click the handler in the list.
  3. Click the Data Points tab, and then do one of the following:

    • To create a new data point, click New Data Point.
    • To edit an existing data point, click the row in the list.
  4. In the Define a Data Point section, configure the following settings.

    FieldDescription
    NameEnter a name for the information you want to extract.
    DescriptionEnter a brief description of the extracted value.
    How many results will this Data Point return?If the regular expression will match more than one value in the email, select true, and then indicate the number of expected matches. The add-on will store each matching value as an item in an array. For example, if the email will contain the start time and end time for a maintenance window, you can enter 2, and then define a regular expression that looks for the time pattern.
    Is this a Date or Time?Select the check box if the value is a date or time, and then indicate the expected format. See Defining the Date or Time Format.
  5. In the Create Regex Expression section, define patterns to find the value you want to extract.

    1. (Optional) In the Template column, select the template that most closely matches the pattern you are looking for in the email message.
      The regex for the selected template is automatically populated as the initial regex.
    2. In the Initial Regex column, enter the regex for the entire pattern you are looking for.

      The add-on supports the standard JavaScript syntax for regular expressions. To test your regexes, you can use online tools such as regexr.com and regex101.com.

    3. OPTIONAL In the Nested Regex column, enter the regex for subset of the initial regex that you want to extract as the value.
      For example, if your initial regex matches a pattern such as Invoice #123456, you can use a nested regex to extract only the number itself as the value of the data point. In this example, the initial regex would be ^Invoice\W#\d{6}$, and the nested regex would be ^\d{6}$. If you don’t enter a nested regex, the entire initial regex is used as the value.
    4. OPTIONAL To add another regular expression, click the plus sign, and then repeat steps a – d.
      The handler evaluates the regexes in order. If it does not find a match for the first regex, it will evaluate the next regex for a match. The handler stops evaluating subsequent regexes as soon as it finds a match in the email message.

      Use cases for multiple regexes

      This feature allows you to handle differences in formats for the same type of information. For example, an invoice number may be formatted as Invoice #123456 or Invoice #:123456, depending on the sender of the email. Likewise, you may have multiple number formats for invoices from different vendors.

  1. Click Save.
  2. Repeat steps 2 – 7 for each value that you want to extract from incoming email messages.

Defining the Date or Time Format

If the value you are extracting is a date or time, you must specify how the value will be formatted in the email message.

  1. In the Define a Data Point section, select the Is this a Date or Time? checkbox.
    A menu appears that lists templates for common date and time formats.
  2. Select the template that most closely matches the expected format of the value in the email.
    The pattern for the selected template is automatically populated in the field below the menu.
  3. Edit the pattern to reflect how the value will be formatted in the email message.
    The add-on supports the Java date and time pattern syntax. For example, MM/dd/yyyy for dates formatted such as 10/21/2006. For a complete list of supported formats, see Java Documentation - Customizing Formats.

Next Steps