JIRA Pro application
JIRA Pro application
JIRA integration for XWiki providing macros and possibility to create issues from XWiki.
| Category | Other |
| Rating | |
| Support |
XWiki SAS
|
| License | GNU Lesser General Public License 2.1 |
| Minimal XWiki version supported | XWiki 15.10 |
| Sources | Issues |
JIRA Application (Pro) provides an intuitive and user friendly way to display and create JIRA issues directly within XWiki, while keeping the knowledge and the issue tracking in only one place. It builds on the already existing JIRA extension rather than replacing it, adding the OAuth authentication method and the ability to create issues from the wiki.
Per user authentication to JIRA
The connection to JIRA is made per user, through OAuth or basic auth. Each user authenticates once against your JIRA instance, and XWiki then queries JIRA with that user's own rights, so everyone sees exactly what they would see in JIRA: an issue a user cannot open in JIRA is not shown to them in XWiki either, and an issue created from XWiki is attributed to the user who created it.
Displaying issues, counts and statistics
Once an instance is configured, its issues can be displayed anywhere in the wiki. The JIRA macro selects them either as a list of issue keys or as a JQL query, and renders them as a table, a bullet list or an enumeration, with a selectable set of fields. The same authentication covers the other JIRA macros, so a page can just as well show only the number of issues matching a query, a pie chart of how a set of issues is distributed over one field, a line chart comparing how many issues were created against how many were resolved over a period of time, or a table crossing two JIRA fields.
Creating issues from XWiki
Issues can also be created without leaving the page. The JIRA macro dialog gains an Issue Creation tab: choose the instance, the project and the issue type, fill in the fields JIRA requires, and press Create Issue. The issue is created in JIRA and its key is added to the content of the macro, so it is displayed in the page straight away and can be opened directly from XWiki.
Inserting a macro by pasting a JIRA URL
When the paste plugin of the underlying JIRA extension is enabled, a JIRA URL pasted into the WYSIWYG editor inserts the right macro for you: the link of an issue gives that issue inline, and the link of a search gives its results as a table.
Setting up a JIRA connection in XWiki
After having installed the JIRA Pro OAuth extension, you will need to configure your JIRA server entry in the administration to OAuth. For this you will firstly need to retrieve some information from JIRA.
Adding a new incoming link in JIRA
For JIRA server/datacenter, you will need to go on Administration > Applications > Application links. Then click on "create link", select "External application" and "Incoming" for the direction. Then complete the fields:
| field | expected value | example |
|---|---|---|
| Name | a name for the application link, could be anything | XWiki |
| Redirect URL | The callback URL. Must be the XWiki path followed by /oidc/authenticator/callback | https://example.com/xwiki/oidc/authenticator/callback |
| Permission | The "Write" permission, to be able to create a new ticket (in case of usage of the JIRA Issue creation extension) | Write |
Then you can click on "Save". On the next page save the "Client ID" and the "Client secret", this will be needed for the configuration in XWiki.
Configuring the JIRA Authentication in XWiki
For this go in the XWiki Administration > Other > JIRA
As soon as you have installed the "JIRA pro OAuth" extension you should have a new option named "OAuth" in the "Authentication type" columns. For the server that you would like to use with OAuth please select this option. Then you will have to define these following fields:
- Require authentication to see the content: when enabled, the user won't be able to use this JIRA server until the user has gone through the authentication process. Generally, for a private JIRA server, it's recommended to be enabled. See User authentication in JIRA for what each setting shows to the user.
- Client ID: The client ID that you get from JIRA
- Secret: The client secret value that you get from JIRA
When everything is set you can click on "Save".
User authentication in JIRA
As soon as you have configured JIRA to use OAuth, each user will need to proceed itself of the authentication in JIRA. This way XWiki will send the request with the same rights than the user, so the user will see exactly the same than in JIRA (an issue that the user can't see in JIRA, won't be seen in XWiki too) and when the user create a ticket from XWiki the creator will match.
So the first time the user will see a macro instance which depends of a JIRA server with OAuth, the user will need to proceed of the authentication in JIRA. A message like bellow will be shown.
When you click on "Click here to authenticate to JIRA" will request the user to process of the authentication in JIRA and allow XWiki to authenticate to JIRA with the user rights.
The JIRA macros
JIRA Pro does not replace the macros of the already existing JIRA extension, it extends them: the OAuth authentication described above applies to the macros below, and the issue creation form is added to the JIRA macro.
| Macro | What it displays |
|---|---|
| jira | A set of issues, given either as a list of issue keys or as a JQL query, rendered as a table, a bullet list or an enumeration. The fields shown are selectable as is the maximum number of issues. |
| jiraCount | The number of issues matching a JQL query. |
| jiraPieChart | A pie chart of how a set of JIRA issues is distributed over one field, using the statistics JIRA computes itself. The issues are selected by a JQL query or by the id of a filter saved in JIRA. |
| jiraCreatedVsResolvedChart | A line chart comparing how many JIRA issues were created and how many were resolved over a period of time, using the statistics JIRA computes itself. The issues are selected by a JQL query or by the id of a filter saved in JIRA. |
| jiraBiDimensionalGridChart | A table crossing two JIRA fields, in which each cell counts the issues having both values, using the statistics JIRA computes itself. The issues are selected by a JQL query or by the id of a filter saved in JIRA. |
For the complete list of parameters of each macro and more details, see the JIRA extension user documentation and the JIRA Macro reference.
Creating JIRA issues from XWiki
The JIRA macro also allows you to create issues: fill in the Issue Creation tab of the macro dialog, press Create Issue, and the issue is created in JIRA. Its key is then added to the content of the macro, so the new issue is displayed in the page and can be opened directly from XWiki.
Parameters
| Parameter | Description | Required |
|---|---|---|
| Instance id | The JIRA instance the issue is created on, chosen from the instances defined by your administrator. | yes |
| Project | The JIRA project the issue belongs to. Only the projects you are allowed to create issues in are proposed. | yes |
| Issue Type | The type of the issue (Bug, Task, Improvement…), among the types available for the selected project. | yes |
| Summary | The title of the issue. | yes |
| Description | The body of the issue. | yes |
Aditional Context
Besides the description field, the form displays only the fields required by JIRA for the selected project and issue type. Any additional fields can be completed directly in JIRA by accessing the URL provided by the macro after the issue is created.
Inserting an issue by pasting a JIRA link
Pasting a JIRA URL into the WYSIWYG editor inserts a JIRA Macro for you: the link of an issue gives that issue inline, the link of a search gives its results as a table.
This is provided by the open source JIRA extension and is not enabled by default. See Paste a JIRA URL to Insert a JIRA Macro.
Installation Steps
This paid extensions requires XWiki 15.10 or above. In order to install the extension, follow the next steps inside your XWiki instance (on cloud or on premise).
Navigate to the Extension Manager
In the Applications Panel click on "More Applications..." and then "Install new applications...". Alternatively navigate directly to the Administration and select the "Extensions" section.
Install the Extension
Search for the extension you wish to install and use the Install button to install it.
Get a License
Navigate to the "Licenses" section of the Administration, fill your details, look for the extension you just installed in the live table and click the buttons to get a trial license or to buy a license.
Install the License
If you have selected a trial license then you're good and there's nothing else to do. Your trial license is automatically installed.
However if you've selected to buy a license you'll be redirected to a page to perform the payment. At the end you need to come back to the "Licenses" administration section and click on the "Check for Updates" button. This will download and apply the license you bought.
Use the Extension
Start using the Extension! Refer to the extension's documentation to know how to use it.
Installing Paid Apps on Subwikis
If you want to install an application on the whole farm (main wiki + subwikis), you can do so directly from the main wiki’s Extension Manager, as seen below:
Extensions can also be installed only on a particular subwiki by global admins. Subwiki admins will not be able to install these extensions due to their limited rights.
Options
The price is per year and varies depending on the support level and the number of users.
| Support / Users | 10 | 25 | 50 | 100 | 250 |
|---|---|---|---|---|---|
| Business |
Benefits
What do you get when you purchase an XWiki extension?
1/3 years license
By purchasing an XWiki extension license, you'll benefit from it during one or three years, depending on the chosen engagement period.
Free updates
You benefit from all the extension updates during one year. You are always up to date.
Support included
If you are facing an issue, you can reach the XWiki support. Our team is always available to help.
How to Buy
To buy, install this extension from inside your XWiki instance and follow the instructions.
Release notes
Extension details
License
- GNU Lesser General Public License 2.1
Sources
Issues
Type
- xar
Developed by
Compatibility
- Requires XWiki 15.10 or above.
Dependencies
- com.xwiki.licensing:application-licensing-licensor-api 1.32.4
- com.xwiki.jirapro:jira-pro-issue-create-ui 1.0.1
- com.xwiki.jirapro:jira-pro-oauth-ui 1.0.1