Field Mappings
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.
Field Mappings: basics
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.
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.
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.
<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.
This is probably the most popular example.
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.
This is probably the most popular example.
Mappings that are valid for Text fields can also be included in text.
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.
This is probably the most popular example.
Mappings that are valid for Text fields can also be included in text.
Field Mappings: advanced
On this page you will learn how to configure the templates in the admin section of our Jira app and use their power to its fullest. Make sure to have read the #field-mapping-basics to fully understand the topic.
Why make it even more complex?
If you oversee a bigger Jira instance it can happen that creating issues does not have the same requirements everywhere in your company when using our Outlook add-in. Different issue types might have their fields to be filled differently and the same issue type might have to be treated differently in another project. Keep in mind that none of this is required to use our Outlook add-in as many use-cases are already represented by using only the default template.
Enable multiple templates
You can enable multiple templates in the top-right of the Templates tab of our Jira app’s admin section (“Enable Context”).
You can then create your first additional template.
Scope of the template
You can choose in which context the template should be applied. The selected scopes can be combined to further sharpen the scope of the single template.
Jira User group
Especially useful for testing out new templates only for “jira-administrators” without fearing to impact users in production but other use cases are conceivable.
Project
Defines the project this template should be applied to. Probably most used to fulfill specific needs for users of this project.
Issue Type
Defines the issue type this template should be applied to. Probably most used to fulfill specific needs for users using this issue type. When selecting this option it is strongly advised to also select a specific project to get better suggestions for the selectable fields and their possible values.
Template priority
When creating an issue with our Outlook add-in the creating user’s user groups, the chosen project and issue type determine which templates are applicable.
The first found template for this exact scope (user group, project, issue type) is directly applied.
The default template will only be applied if no other template matches the scope.
As user groups can overlap: If you specified user groups for your templates, you can define the priority of those templates relative to each other to define which template should be applied if a user was in both user groups.