---
title: "Mappings"
canonical: "https://docs.getxray.app/space/XRAYCLOUD/44570571/Mappings"
format: markdown
---
<details>
<summary>Table of Contents</summary>

> Macro (toc)
</details>

# Introduction

Mappings in the **Xray Document Generator** are placeholders that you include in Templates (DOCX or XLSX formats) to dynamically populate them with data from your Jira environment. These placeholders correspond to specific fields or elements in Xray and Jira, such as Issue fields, custom fields, comments, work logs, attachments, or other related data.

## Benefits of Using Mappings

- **Dynamic data population**: mappings are replaced with real-time data when the document is generated, ensuring the report reflects the latest information from your Jira Issues and Xray Test artifacts.
- **Customization**: you can use mappings to tailor your documents according to your needs. For example, you might include mappings for:
  - Basic fields: Issue summaries, descriptions, or statuses.
  - Advanced fields: custom fields, [Test Steps](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565316), or execution results.
  - Additional data: comments, attachments, or work logs.
- **Flexible reporting - **mappings enable you to create detailed, customized reports, such as:
  - [Test Execution](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565117) summaries.
  - Requirement coverage reports.
  - Defect analysis reports.
- **Having reusable Templates**: once mappings are set up in a Template, the same document structure can be reused for multiple reports.

By leveraging mappings effectively, you can ensure your documents are accurate, detailed, and aligned with your project needs.

## Example of Mappings in Action

Imagine you want to generate a Test Execution Summary. Your Template might include mappings like:

- **${issue.summary}**: replaced with the summary of the Test Execution.
- **${issue.key}**: replaced with the Issue key (e.g., "TEST-123").
- **${testResults.passed}**: Replaced with the number of passed Tests.

When you generate the document, these mappings are substituted with actual data from Jira and Xray, producing a complete, professional report.

> ℹ️ To use a mapping, just open your Template document and type the mapping using this notation: `${<Field>}`


# JIRA Mappings

The available keywords are listed in the following table:

| **Field** | **Description** |
| --- | --- |
| ActivityEntriesCount[DeprecaTED] | Returns the number of activity entries in the Issue |
| AffectedVersions | The project versions affected by the Issue (a list with one version per line) |
| AffectedVersionsCount | Returns the number of affected versions in the Issue |
| AffectedVersionsList | The project versions affected by the Issue (separated by commas) |
| AggregateOriginalEstimate | The sum of the originally estimated time for Issue completion, in seconds |
| AggregateRemainingEstimate | The sum of the remaining estimated time for Issue completion, in seconds |
| AggregateTimeSpent | The sum of time spent working on the Issue, in seconds |
| Assignee | The Issue assignee display name |
| AssigneeGroups | The groups to which the Issue assignee belongs |
| AssigneeId | The Issue assignee ID |
| AssigneeUserDisplayName | The Issue assignee display name |
| AssigneeUserEmailAddress | The issue assignee email address |
| Attachments | The attachments of the current Issue (a list with one attachment per line).<br>You can iterate over Attachments and get some metadata from them. |
| AttachmentsCount | Returns the number of attachments in the Issue |
| AttachmentsResources | A JSON file containing all the information regarding Issue attachments |
| BaseURL | The Jira Cloud instance URL |
| BelongsToEpic | Returns "true" if the current Issue belongs to an Epic Issue; otherwise, it returns "false" |
| BulkIssueIndex | The index/position of the current Issue being mapped.<br>Usable only in bulk export.<br>0 is the index for the first Issue. |
| BulkIssuesCount | The number of Issues selected in a bulk export.<br>Usable only in bulk export. |
| CommentsCount | Returns the number of comments in the Issue |
| Components | The components to which an Issue belongs |
| ComponentsCount | Returns the number of components in the Issue |
| Created | The Issue creation date time in ISO Format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):Created}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):Created}** |
| CreatedDate | The Issue creation date time in ISO Format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):CreatedDate}. **<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):CreatedDate} ** |
| CreatedDateTime | The Issue creation date time in ISO Format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):CreatedDateTime}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):CreatedDateTime} ** |
| Current Date | The current date time in ISO Format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):Current Date}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):Current Date} ** |
| Current Date Time | The current date time in ISO Format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):Current Date Time}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):Current Date Time} ** |
| CurrentDate | The current date time in ISO Format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):CurrentDate}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):CurrentDate} ** |
| CurrentDateTime | The current date time in ISO Format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):CurrentDateTime}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):CurrentDateTime} ** |
| Description | The Issue description |
| DocumentId | Unique ID generated to identify the document |
| Due Date | The Issue due date |
| DueDate | The Issue due date |
| DueDateTime | The Issue due date |
| Environment | The Issue [environment](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565129) |
| FilterJQL | Current JQL used to search Issues |
| FilterName | Current Filter Name used to search Issues |
| FixVersions | The versions an Issue fixes |
| FixVersionsCount | Returns the number of fix versions in the Issue |
| FixVersionsList | The versions an Issue fixes, separated by commas |
| FixVersionsReleaseDate | The release date of the versions an Issue fixes |
| FixVersionsReleaseDateList | The release dates of the versions being fixed by an Issue, separated by commas |
| Folder Name | The Folder Name where the Test is located on the folder tree inside the [Test Plan](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565153) or [Test Repository Plan boards](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565285) |
| Id | The Issue ID. For example: 1. |
| Images | When used as a single field, `${Images}` renders the images list of images attached to the Issue.<br>Images are rendered in an order respecting the creation date.<br>For this field, you are allowed to define extra attributes with the max image width, max image height, and the sort order of the images.<br>Examples:<br>`$``{``Images|maxwidth=100|maxheight=100}`<br>`$``{``Images|maxwidth=100|maxheight=100|sortby=name}`<br>`$``{``Images|maxwidth=100|maxheight=100|sortby=date}`<br>**Note: **You can iterate over images and get some metadata from them. |
| ImagesCount | Returns the number of images attached to the Issue |
| <span style="color: #000000">IssuesInEpicCount</span> | Returns the number of Issues in an Issue of the Epic Type |
| Issue Type | The Issue Type name |
| Issue Type.Id | The Issue Type ID |
| Issue Type.Name | The Issue Type name |
| Issue Type.Description | The Issue Type description |
| Issue Type.Type | The type of the Issue Type (standard or sub-task) |
| Issue Type.IconURL | The icon URL of the Issue Type |
| IssueType | The Issue Type name |
| IssueTypeDescription | The Issue Type description |
| IssueTypeName | The Issue Type name |
| IssuesCount | The number of exported Issues |
| Key | The internal issue Key. For example, PROJECT-1. |
| Labels | The Issue labels |
| LabelsCount | Returns the number of labels in the Issue |
| LinksCount | Returns the number of links to the Issue. |
| OriginalEstimate | The originally estimated time for Issue completion, in seconds |
| Priority | The Issue's priority |
| PriorityDescription | The Issue's priority description |
| Project | The Issue's project name related to the Issue |
| ProjectComponents | The Issue's project components |
| <span style="color: #000000">ProjectComponentsCount</span> | Returns the number of components in a project |
| ProjectId | The Issue's project ID |
| ProjectID | The Issue's project ID |
| ProjectKey | The Issue's project key |
| ProjectLead | The Issue's project lead account ID |
| ProjectName | The Issue's project name |
| ProjectURL | The Issue's project URL |
| ProjectCategory | The Issue's project category |
| Project.Components | The Issue's project components an Issue belongs |
| Project.Id | The Issue's project ID |
| Project.ID | The Issue's project ID |
| Project.Key | The Issue's project key |
| Project.Lead | The Issue's project leader |
| Project.Name | The Issue's project name |
| Project.URL | The Issue's project URL |
| Project.Category | The Issue's project category |
| Project.Description | The Issue's project description |
| ProjectVersionsCount | Returns the number of project versions |
| RemainingEstimate | The remaining estimated time for issue completion, in seconds. |
| Reporter | The Issue's reporter display name |
| ReporterId | The Issue's reporter ID |
| ReporterID | The Issue's reporter ID |
| ReporterGroups | The groups to which the Issue's reporter belongs |
| ReporterUserDisplayName | The Issue assignee Jira display name |
| ReporterUserEmailAddress | The Issue's assignee Jira email address |
| Resolution | The Issue resolution |
| ResolutionDescription | The Issue's resolution description |
| Resolved | The issue resolution date in ISO format.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):Resolved}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):Resolved}** |
| SecurityLevel | The Issue's security level |
| SecurityLevelDescription | The Issue's security level description |
| SecurityLevelId | The Issue's security level ID |
| SprintsCount | Returns the number of sprints |
| Sprint | The Issue's sprint name |
| Status | The Issue's status |
| StatusDescription | The Issue's status description |
| StatusTransitionsCount | Returns the number of status transitions of the Issue |
| SubTasks | List of Issue subtasks |
| SubtasksCount | Returns the number of subtasks of the Issue |
| Summary | The Issue's summary |
| Time Spent | The time spent working on the Issue |
| TimeSpent | The time spent working on the Issue |
| Updated | The Issue's update timestamp.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):Updated}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):Updated}** |
| UpdatedDate | The Issue's update timestamp.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):UpdatedDate}**<br>If you want to print the date and time, you must use **${dateformat("dd-MM-yyyy  HH:mm:ss"):UpdatedDate}** |
| UpdatedDateTime | The Issue's update timestamp.<br>If you want to print only the date, you must use **${dateformat("yyyy-MM-dd"):UpdatedDateTime}**<br>If you want to print the date and time, you should use **${dateformat("dd-MM-yyyy  HH:mm:ss"):UpdatedDateTime}** |
| URL | Returns the URL of the Issue's detail screen |
| UserAccountId | The user account ID who is exporting |
| UserDisplayName | Displays the name of the user who is requesting the export |
| UserEmailAddress | Email address of the user who is requesting the export |
| Votes | The number of times an Issue was voted |
| Watchers | Returns a list of users that are watching the Issue. Functions **fullname** and **emailaddress** can be used in this field |
| Watches | The number of watches in the Issue |
| WorklogsCount | Returns the number of worklogs in the Issue |

# Custom Field Mappings

To use your own defined custom fields, use the same notation: `${<Custom field name>}`

The *<Custom field name>* must match exactly the name on which you created the custom field. Example: `${My Special One And Only Custom Field}`

If you have Custom Fields with the same name, it is possible to explicitly indicate the custom field that you want to export using its internal Jira identifier. You can find the identifier of a custom field by going to the Jira administration, section fields, and edit the custom field. The ID will appear in the URL (e.g.:  [http](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[:](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[//](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[jiraserver](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[/secure/admin/EditCustomField](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[!](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[default](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[.](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[jspa](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[?](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)[id=](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)**[10070](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070)**[ ](http://jiraserver/secure/admin/EditCustomField!default.jspa?id=10070) ). 

The notation to be used is: `${<Custom field name>[<Custom field id>]}`

<details>
<summary>Expand to see the example on sample code</summary>

```
${My Custom Field[10070]}
```
</details>

The officially supported custom fields are:

- Number Field.
- Text Field (read-only).
- Text Field (multi-line).
- Group Picker (single group).
- Group Picker (multiple groups).
- User Picker (single user).
- User Picker (multiple users).
- Date Picker.
- Date Time Picker.
- Select List (single choice).
- Select List (multiple choices).
- URL Field.

 The plugin may work with other custom fields (even provided by other plugins). This depends on the way other custom field Types implement the rendering of the field values.

> ℹ️ Custom Fields can also be referenced using their translated name. For example, if a custom field named *Reason* is translated in Jira to French as *Raison*, you can refer to the field in The template with `${Reason} `or `${Raison}`

# Parent and Epic Link Mappings

[Document Generator](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565169) allows rendering all the fields from the Epic Link and Parent for an Issue.

<details>
<summary>Expand to see the examples on sample code</summary>

```
// Epic Link
${Epic Link.Key}
${Epic Link.Summary}
${Epic Link.LinkType}

// Parent
${Parent.Key}
${Parent.Summary}
${Parent.Description}
```
</details>


<details>
<summary>Support/Troubleshooting</summary>

If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44577312).
</details>