Templating basics

Owned by Andreas Schmidt
Last updated: Apr 14, 2021 by Tobias Viehweger
4 min read

On this page you will learn what the template in the admin section of our Jira app does and how it can help you improve your workflow. If you already know the basics and want to tweak even more, consider reading about advanced template functions.

Why template values?

Default values set for fields in Jira will automatically be picked up by our add-in for most fields. But Jira does not know anything of the email you want to create an issue from. The template defines which data of the email will be filled into the fields of your issue. If a field would have had both a default value and a template value, the template value will override the default value, because we assume the specific information of the email to be more accurate than any generic default value set in Jira.

Default template

We condensed what we think all of our users will want into a default template. By default, this template only fills the most standard fields.

  • description: <BODY>
    The body of the email will be filled into the description of the issue or the description-equivalent of the request.

  • summary: <SUBJECT>
    The subject of the email will be the summary of the issue.

  • reporter: <SENDER>
    This one is a little tricky. See in the dedicated section for Template basics | mapping-<SENDER> below.

  • customfield_*****: <ORGANIZATIONS> (the actual custom field number depends on your instance and is determined accordingly)
    If the reporter is found to be an existing customer, the organizations the customer is part of will be pre-filled.

Mappings

You can decide how the fields of your issue will be pre-filled by adding a mapping for this specific field. If a mapping is not valid for a field it will in most cases be ignored and should not cause an error.

User specific mappings

<SENDER>

This definitely is the most complicated mapping.

Our Add-In tries to find a matching Jira user or customer by searching for the email address of the email’s sender. If we are able to find an existing Jira user or customer, it will be pre-filled.

Otherwise, if the mapping is associated with the “reporter” field and all of the following are applicable, our Add-In is capable of directly creating a new customer, see also: Jira Service Management - On Behalf Of

  • Have a Jira Service Management project selected

  • You have “Request type” enabled. Creating an issue via “Issue type” can never create a customer

You will see a “(new)” appear after the email address in the “On behalf of” field.

If the tab “Service Portal” is not visible for you, check the following setting in the app settings.

If you are neither in a Service Management project nor have selected a “Request Type” nor have an existing user or customer for this email address, your own Jira user will be pre-filled into the “reporter” field.

<USER>

For User-Picker or Multi-User-Picker only.

Your own user will be pre-filled.

<RECIPIENTS>

For User-Picker or Multi-User-Picker only.

If we are able to find existing Jira users or customers for the email addresses in “To:” and “Cc:” those will be pre-filled.

<ORGANIZATIONS>

For organizations field only. (the actual custom field number depends on your instance and is determined accordingly)

If the reporter is found to be an existing customer, the organizations the customer is part of will be pre-filled.

Email content mappings

<SUBJECT>

For text field or multi-line text field only.

The subject of the email will be pre-filled.

<BODY>

Currently only working for the description field. Planned to be working for custom WYSIWYG editor fields in the future.

The whole body of the email will be pre-filled.

If you disabled the WYSIWYG-Editor in our Outlook Add-In, it will be pre-filled as markup.

<BODY_PLAIN>

For text field or multi-line text field only.

The whole body of the email as plain text will be pre-filled.

Date mappings

<SENTAT>

For Date Picker, DateTime Picker, text field or multi-line text field.

The date the email was sent at will be pre-filled, ISO string for text and multi-line text fields, always including time.

<TODAY>

For Date Picker, DateTime Picker, text field or multi-line text field.

The current date will be pre-filled, ISO string for text and multi-line text fields, always including time.

<TODAY> + x

For Date Picker, DateTime Picker, text field or multi-line text field.

Offsets the current date by x days to the future.

The offset date will be pre-filled, ISO string for text and multi-line text fields, always including time.

Concatenations of mappings

Mappings can be combined by simply entering multiple to the same field.

The most popular example would be

Mappings that are valid for Text fields can also be included in text.

Additional resources