JIRA URL Conversion Rules
Reference
When a JIRA URL is pasted into the WYSIWYG editor, the URL decides which jira Macro call is inserted. Two rules cover every case, and both produce a Macro displaying the type, key, summary and status of at most twenty issues.
| Pasted URL | Recognised by | Resulting Macro |
|---|---|---|
| A search | A jql query parameter | source="jql", style="table", the decoded query as the Macro content, inserted on a new line |
| An issue | The first [A-Z]+-[0-9]+ sequence in the URL path | source="list", style="enum", that issue key as the Macro content, inserted inline |
When a URL Is Converted
| Condition | Effect |
|---|---|
| The pasted text is a single URL, or a single link | Converted. |
| The URL origin, that is its scheme, host and port, starts with the URL of a JIRA instance configured in the wiki administration | Converted, and the Macro is given the id of that instance. The url parameter is set instead when the instance has no id. |
| The URL belongs to no configured instance | Left as pasted. |
| No JIRA instance is configured in the wiki administration | The feature is inactive and nothing is ever converted. |
| The plugin is not declared in the editor configuration | The feature is inactive and nothing is ever converted. |
| The paste is done without formatting, with "Ctrl+Shift+V" | Left as pasted. |
Pasting a Link to an Issue
Pasting the URL of an issue, for example the address of the ISSUE-1000 issue, inserts:
{{jira id="myJiraInstanceId" url="" style="enum" fields="type,key,summary,status" source="list" maxCount="20"}}
ISSUE-1000
{{/jira}}The enum style is used because it is the one that can be displayed inline, so the Macro replaces the URL inside the sentence being written.
Pasting a Link to a Search
Pasting the URL of a search, whose query string carries a jql parameter, inserts:
{{jira id="myJiraInstanceId" url="" style="table" fields="type,key,summary,status" source="jql" maxCount="20"}}
issuekey in (ISSUE-1000, ISSUE-1001)
{{/jira}}The query is URL-decoded on the way in. The table style cannot be displayed inline, so this Macro is always inserted on a new line.
FAQ
Why is url empty in the inserted Macro?
Because the instance is designated by its id instead, which is the recommended way; url is filled only for a configured instance that has no id.
Can I change what the inserted Macro displays?
Yes. The inserted call is an ordinary jira Macro, so its fields, style and maxCount parameters can all be edited afterwards.
Why is only the first issue key of the URL used?
Because an issue URL points at exactly one issue; to display several, paste a search URL instead.
