XWiki and Jira integration

Per-user OAuth means each reader signs in to Jira with their own identity, and the Jira macros in XWiki return only the issues that identity can access in Jira. The permission decision stays in Jira, where project permissions, issue security levels and role assignments already live. XWiki does not need its own copy of those rules, which matters most for teams that already restrict sensitive projects in Jira. Before you rely on this, confirm how the macros behave for anonymous visitors and for users who have not yet authorized the connection, because the output in those cases depends on the JIRA Pro configuration.

The change for administrators is mainly where access control sits. With a single shared Jira account, every reader sees whatever that account can see, so XWiki page restrictions become the only control over Jira data. A page limited to one group could still display issues from a project that group should never see. Per-user OAuth moves the filter into Jira. You no longer maintain a service account with broad read access, and Jira's own records can show which person viewed or created an issue, within what Jira logs. The trade-off is new operational work: registering the OAuth application on the Jira side, setting the allowed redirect addresses, and handling users who leave or change roles in Jira.

Several details must be confirmed in the JIRA Pro documentation rather than assumed from the feature summary. Check how the OAuth flow starts, which application configuration Jira requires, and where XWiki stores access and refresh tokens. Ask whether tokens are encrypted at rest, how long they remain valid, and how a user revokes them. Find out whether a consent screen appears in Jira, what text it shows, and who must approve it. Also confirm what a macro displays when a token expires during a session. Record the answers in your design notes, because token storage and consent behavior affect your security review and your user onboarding instructions.

Test the model in a non-production environment before any user relies on it. Create a dedicated Jira project with issues restricted to different permission groups, then create test users in each group. Compare the results of jira and jiraCount for each user with what that user sees when searching Jira directly. Check that an issue created from the wiki records the signed-in user as reporter. Remove one test user's Jira access and confirm that the data disappears from pages on the next load. Finally, confirm that your Jira instance is Server or Data Center, since JIRA Pro does not support Jira Cloud yet, and that your XWiki version is 15.10 or above.

Choose the macro by the question the page must answer. Use the jira macro when readers need to act on individual issues, because it shows keys, summaries, statuses and assignees they can open. Use jiraCount when one number is the message, such as how many open defects a release carries. The chart macros answer questions about shape: jiraPieChart shows distribution across a field, jiraCreatedVsResolvedChart shows whether work is accumulating or draining over time, and jiraBiDimensionalGridChart cross-tabulates two fields. For status reporting, a count and one chart usually carry the headline, with a list underneath for exceptions. Backlog pages depend mostly on lists. Project home pages work best with a count and a single chart, which keeps the page short enough to scan.

The JQL behind each macro decides what the page means, so write and review it before choosing the layout. A list and a count built from different queries will disagree, and readers will conclude the page is wrong. Keep one query per question and reuse it wherever the same number appears. Check that the scope names the projects, issue types, sprints or labels the report intends, and avoid open-ended clauses that pull in issues from other teams. Backlog pages need an explicit ordering and a status filter, otherwise the list can grow as projects change. Ask your Jira administrator which statuses and fields your workflows use, because a status name that differs between projects will split one count into several. Run each query in Jira issue search first and compare the result count with what the macro displays.

Visibility is the part most likely to surprise a shared page. With per-user OAuth, each reader sees the issues their own Jira account can access, so one page can show different content to different people. A project lead may see every issue, while a stakeholder outside the project sees a shorter list and a lower count. This is the intended behavior, but it changes what the page can be trusted to say. Decide whether the page is a working view for team members or a summary for executives, and state the audience at the top. Saved filters add a second layer. A macro that relies on a saved filter inherits that filter's owner and sharing settings, so confirm who owns it and what happens if that person leaves. Ask the vendor how the version you run handles filter references and any caching of results.

Start with a pilot page for one project before any wider rollout. Pick a project with a stable workflow, a named owner and an active backlog, then build one status page with a list, a count and one chart using the agreed JQL. Test the page with at least three accounts: a project member, a project lead, and a reader with no Jira access to the project. For each account, compare what the page shows with what Jira search returns for the same account. Record every mismatch and resolve it in the query or the permission model before copying the pattern. Confirm the prerequisites as well: JIRA Pro works with Jira Server and Data Center only, Jira Cloud support is listed as under development, and the XWiki version must be 15.10 or above. Widen the rollout only after the pilot results match, and document the pattern so the next team starts from the same tested setup.

JIRA Pro works with Jira Server and Data Center only. The XWiki Store lists Jira Cloud support as under development, so the macros and issue creation described on this page do not yet have a supported path to a Jira Cloud site. If your organization runs Jira Cloud, plan on the basis that this integration is not available to you today. Because the status is a vendor statement that can change, record it in your planning file with the date you checked it and the name of the person who checked. Confirm the current status on the XWiki Store page for JIRA Pro before you schedule any build work, and repeat the check before any go-live decision.

Teams on Jira Cloud should not design around a Cloud connection until XWiki confirms one in writing. That includes choosing an authentication model, registering an OAuth application on the Jira side, defining how wiki readers are matched to Jira permissions, and drafting page layouts that assume Cloud site URLs will work. Each of those choices rests on an assumption that the vendor has not yet confirmed. If the assumption is wrong, the rework lands in the authentication layer, which is the part that decides whether readers see only the issues they are allowed to access. Keep those workstreams on hold, or limit them to items that do not depend on the connector, such as Jira project structure and issue fields.

In the meantime, a Jira Cloud team can keep the scope of the open source extension under review. Ask which macros and behaviors the open source XWiki JIRA extension provides on its own, and which ones depend on JIRA Pro. Then map each wiki use case to one of those two groups. If the main need is a reference from a wiki page to a Jira issue key, the open source scope may be enough for a first phase. If the need is counts, charts or issue creation from the wiki, those requirements depend on the commercial extension and its Cloud status. Write these needs down before any vendor conversation so your questions to XWiki SAS are specific and answerable.

Check your XWiki version as well. JIRA Pro requires XWiki 15.10 or above, so a platform on an older release needs its own upgrade decision, whatever Jira hosting model you use. Compare your current version with the XWiki release line you intend to run. Ask for JIRA Pro licensing terms in writing, including whether the license covers Server and Data Center deployments only and what the quote says if Cloud support ships after your planned go-live date. A clear written answer on these points is more useful to your steering group than a general statement that Cloud support is coming.