New field mapping features for JQL query runner

user-guide/queries/querying_jira_jql.md

@@ -36,3 +36,45 @@ Count number of issues with `priority=medium`:
     "jql": "priority=medium"
 }
 ```
+
+You can also use the field mapping to rename a field for the result - this is useful when working with custom fields:
+
+```
+{
+    "fields": "summary,priority,customfield_10672",
+    "jql": "priority=medium",
+    "fieldMapping": {
+        "customfield_10672": "my_custom_field_name"
+    }
+}
+```
+
+Some fields returned by JIRA are JSON objects with multiple properties. You can define a field mapping to pick a specific member property you want to return (in this example 'id' member of the 'priority' field):
+
+```
+{
+    "fields": "summary,priority",
+    "jql": "priority=medium",
+    "fieldMapping": {
+        "priority.id": "priority"
+    }
+}
+```
+
+More complex example combining the different filter options:
+
+```
+{
+    "fields": "summary,priority,customfield_10672,resolutiondate,fixVersions,watches,labels",
+    "jql": "project = MYPROJ AND resolution = unresolved ORDER BY priority DESC, key ASC",
+    "maxResults": 30,
+    "fieldMapping": {
+        "customfield_10672": "my_custom_field_name",
+        "priority.id": "priority",
+        "fixVersions.name": "my_fix_version",
+        "fixVersions.id": "my_fix_version_id"
+    }
+}
+```
+
+If a field contains a list of values all are returned concatenated with ",".