Wiki source code of JIRA Scripting API
Last modified by Vincent Massol on 2026/07/27 21:23
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The ##jira## Script Service hands a script Atlassian's own [[JIRA REST Java Client>>https://javadoc.io/doc/com.atlassian.jira/jira-rest-java-client-api/latest/index.html]], already pointed at a JIRA instance and carrying that instance's authentication. Everything beyond obtaining the client, that is searching, reading and writing issues, is done through the client's own API. | ||
| 2 | |||
| 3 | The API is usable from Groovy, which can construct the objects it needs. Velocity cannot, so a Velocity script has no way to call it. | ||
| 4 | |||
| 5 | == Obtaining a Client == | ||
| 6 | |||
| 7 | |=Call|=Returns | ||
| 8 | |##$services.jira.getJiraRestClient($jiraServer)##|A client connected to the instance described by the passed ##org.xwiki.contrib.jira.config.JIRAServer##, authenticated with that instance's authenticator when it has one, and anonymous otherwise. ##null## when the instance URL is not a valid URI. | ||
| 9 | |||
| 10 | The client holds threads and **must be closed** by the caller once it is no longer needed. In Groovy, ##withCloseable## does it on every exit path. | ||
| 11 | |||
| 12 | == Designating the Instance == | ||
| 13 | |||
| 14 | A ##JIRAServer## either is built in the script, for a public instance, or is taken from the wiki configuration, which is what carries credentials. | ||
| 15 | |||
| 16 | |=Expression|=Use | ||
| 17 | |##new JIRAServer(url, id)##|An instance built on the spot from its URL. The id is free and only used to build the cache key of asynchronous Macro rendering, so it may be empty. The connection is anonymous. | ||
| 18 | |##services.component.getInstance(JIRAConfiguration.class).getJIRAServers().get(id)##|The instance an administrator configured under that id, with its authentication. This is the only way for a script to reach issues that are not public. | ||
| 19 | |||
| 20 | The ##JIRAServer(url)## and ##JIRAServer(url, username, password)## constructors are deprecated: pass an authenticator, or take the instance from the configuration. | ||
| 21 | |||
| 22 | == Reading an Issue of a Public Instance == | ||
| 23 | |||
| 24 | {{code language="groovy"}} | ||
| 25 | {{groovy}} | ||
| 26 | import org.xwiki.contrib.jira.config.JIRAServer | ||
| 27 | |||
| 28 | services.get("jira").getJiraRestClient(new JIRAServer("https://jira.xwiki.org", "")).withCloseable { client -> | ||
| 29 | def issue = client.getIssueClient().getIssue("XWIKI-1000").claim() | ||
| 30 | println "Summary: ${issue.getSummary()}" | ||
| 31 | } | ||
| 32 | {{/groovy}} | ||
| 33 | {{/code}} | ||
| 34 | |||
| 35 | == Reading an Issue of a Configured Instance == | ||
| 36 | |||
| 37 | {{code language="groovy"}} | ||
| 38 | {{groovy}} | ||
| 39 | import org.xwiki.contrib.jira.config.JIRAConfiguration | ||
| 40 | |||
| 41 | def jiraServer = services.component.getInstance(JIRAConfiguration.class).getJIRAServers().get("xwikiorg") | ||
| 42 | |||
| 43 | services.get("jira").getJiraRestClient(jiraServer).withCloseable { client -> | ||
| 44 | def issue = client.getIssueClient().getIssue("XWIKI-1000").claim() | ||
| 45 | println "Summary: ${issue.getSummary()}" | ||
| 46 | } | ||
| 47 | {{/groovy}} | ||
| 48 | {{/code}} | ||
| 49 | |||
| 50 | == Searching with a JQL Query == | ||
| 51 | |||
| 52 | {{code language="groovy"}} | ||
| 53 | {{groovy}} | ||
| 54 | import org.xwiki.contrib.jira.config.JIRAConfiguration | ||
| 55 | |||
| 56 | def jiraServer = services.component.getInstance(JIRAConfiguration.class).getJIRAServers().get("xwikiorg") | ||
| 57 | |||
| 58 | services.get("jira").getJiraRestClient(jiraServer).withCloseable { client -> | ||
| 59 | println "|=Key|=Summary" | ||
| 60 | client.getSearchClient().searchJql("project = XWIKI AND status = Closed ORDER BY priority DESC").claim().getIssues().each { issue -> | ||
| 61 | println "|${issue.getKey()}|${issue.getSummary()}" | ||
| 62 | } | ||
| 63 | } | ||
| 64 | {{/groovy}} | ||
| 65 | {{/code}} |
