Creating JIRA Issues from the JIRA Macro Edit Modal

[douakli]

Hi all,
I’m currently working on adding an Issue creation feature for the JIRA Macro.
See: JIRA-78: Add support for creating issue from the JIRA Macro Edit Modal

@vmassol, Since you are the project lead for the JIRA Integration, I should ask you some questions about the design of the feature and how we should proceed.

Some context to begin with

Attlassian’s Confluence’s JIRA Integration provides the ability to create a new issue while inserting a Jira Macro.

I’d like to integrate a similar feature to XWiki’s JIRA Integration.

The way I thought this could be implemented is by providing a custom displayer for the JIRA Macro’s content which is a JIRA Issues list.

I’m currently keeping the work in progress in the following PR on the JIRA Contrib repo

Here are a few screenshots of what it currently looks like.

JRJC API

In order to create an issue, the user needs to first pick an instance on which the issue should be created.
Only once this is done, can they search for a project for which they want to create an issue.
After picking a project, they can see the issue types configured for the given project.
And only then, can we get the list of fields the user needs to fill to create an issue from the JIRA API.

For my first attempt, I decided to write a simple velocity service as an intermediary between the UI and the JIRA API.
We need to perform the JIRA API requests on the server side because we can’t give the credentials to the user’s browser.
I thought I would use the existing JIRA script service which allows to recover a JiraRestClient and implements a client for the JIRA API.

Now this is not completely needed for the issue creation use-case, I suppose we could just proxy the API requests and parse the JIRA’s API answer directly in the UI.
Instead I thought I’d reuse the existing set-up for accessing the API from a script service.
This means that the answer from JIRA is parsed by the API client server-side, and I then need to serialize it again to send it to the UI.
In the process, I believe in the first parsing implemented by the JIRA Rest client library, we lose some of the data.
In the project list metadata, I don’t have access to the project avatar. This is not a big deal but I do think it’s not optimal.
More problematic, in the issue creation metadata (The list of fields expected to create an issue), I’m missing the id of the field that I need to reference in the issue creation request. But I do find it when calling the JIRA API directly.

I tried upgrading the REST Client to version 6.0.1, in case it was a known bug that was fixed by atlassian.
This did not fix my issues.

WDYT? Should I try to fix or workaround those limitations?

Architecture

Facing these issues, I’d like to ask for your opinion on the approach we should take.

So far the architecture I went with was in:

• jira-macro-default:
  • Add a js/jira-pickers.js providing
    • Instance suggests
    • Project suggests
    • Issue type suggests
    • Suggests for JIRA fields with a set of valid options
    • Suggests for JIRA fields with an autocomplete
    • The issue creation form
    • Event listeners to inject the issue creation form and the instance suggest in the JIRA Macro edit modal.
  • Add a JIRAIssuesList type in org.xwiki.contrib.jira.macro.
  • Set the content descriptor of the JIRAMacro to use the JIRAIssuesList as display type.
  • Add a templates/html_displayer/jiraserver to require our jira-pickers JSX and to insert the suggest instead of a textarea.
  • Optionally add a templates/html_displayer/jiraisssueslist to require our jira-pickers JSX and insert our issue creation form, although this can’t do anything until we fix XWIKI-23059: Can’t set a custom displayer for macro content in CKEditor’s macro editor.
  • Add a dependency to org.xwiki.contrib.jira:jira-api and org.xwiki.contrib.jira:jira-macro-ui in the pom.xml.
• jira-macro-common:
  • Change the Display Type of the id parameter to JIRAServer.class
• jira-macro-ui (New):
  • Add a velocity script service to:
    • Retrieve the list of configured JIRA instances
    • Retrieve the list of projects for an instance
    • Retrieve the list of issue types for an instance and a project
    • Retrieve the list of expected fields for an instance, a project and an issue type.
    • Retrieve the list of suggested values for a field given an instance, a project, an issue type and the field to suggest for.
    • Create a new issue given a list of fields with their values.

I now think that we shouldn’t use the rest client present in org.xwiki.contrib.jira:jira-api because we can’t really fix the upstream issues. Instead, we should perform the API calls ourselves.

The thing is, I only need a very small subset of the whole JIRA API for the issue creation feature.

Do you think the velocity service approach is viable?

Should I introduce JIRA REST endpoints for the UI to use?

These endpoints are not meant to be a public API, I just need suggests for the issue creation form basically.

@vmassol, As the project lead, what structure or approach would you approve of?

Thanks,
Dorian.

[vmassol]

Hi Dorian,

Before we talk about architecture and details, I think we need to discuss the use case a bit. See below.

@douakli

Attlassian’s Confluence’s JIRA Integration provides the ability to create a new issue while inserting a Jira Macro.

I don’t understand the use case. Why would you want to create a jira issue when you want to list jira issues? For me these are 2 different use cases and I would not mix them up.

EDIT: After reading the confluence doc, it seems it’s for use cases when, for example, you want to create a roadmap (storing the roadmap items in jira), and display it in XWiki, without leaving the editor. That last part doesn’t seem absolutely necessary to me, it could be done in 2 steps.

In any case, this seems to me like some quite edge case (to be able to create jira issues when inserting a jira macro) and it would make that macro a lot more complex to maintain than it should be (from a code pov and also from a usage pov), so even if there’s a use case for it, I’d try to keep the jira creation code separate as much as possible.

Another idea would be to add to the jira macro, in view mode, an option menu that appears when you hover over it.

That menu would contribute a UIXP for menu entries, and an extension could contribute a “Create jira issue” menu entry for it. In this manner, we would de-correlate the edit mode from the view mode, and still allow users to access that menu when editing inside the wysiwyg editor (since the wysiwyg editor renders the jira macro). It would also allow users to create new jira issues in view mode, which is an even more important use case to me if you want to create jira issues from XWiki. And it would allow to introduce a new module in the jira extension that is exclusively in charge of creating jira issues, cleanly separating it from the rest.

Note that I don’t know if that works technically, ie if macros can create dialogs that would work both in view mode and in edit mode inside the WYSIWYG editor.

Also, it means that this options menu should be visible even when the jira macro result is empty (ATM I think we don’t display anything when there are no results which would need to be changed).

That menu should also work for all jira displayers (like enum).

@douakli

Note that this screenshot tab says “Issue List” but that’s not correct. It depends on the source used (it can be a list, or a JQL query, or any other content supported by an extension that implements a JIRA Source).

Also, the creation of jira issues seems more related to the Instance section than the Content section to me.

Re jira issue creation, isn’t it possible in jira to say that some fiels are required when creating an issue? Asking since you seem to have a fixed list of fields in your UI.

Also the Reporter needs to be set. How do you configure the jira user to be used?

@douakli

For my first attempt, I decided to write a simple velocity service as an intermediary between the UI and the JIRA API.

Feels like some java side script service might be better for this (and easier to test and won’t require wiki pages that needs to be installed on all wikis where the feature is installed on).

Thanks

[douakli]

Hi Vincent,

Thanks for your answer!

@vmassol

Why would you want to create a jira issue when you want to list jira issues? For me these are 2 different use cases and I would not mix them up.

One would access the macro edition modal not necessarily only when inserting the macro, but also when editing a page with an existing jira macro.
The idea was to add new issues to the list while creating them.

I understand that they can be divided in two separate use cases, but together, they can constitute a workflow where you create and gather related issues within XWiki.

@vmassol

Another idea would be to add to the jira macro, in view mode, an option menu that appears when you hover over it.

That menu would contribute a UIXP for menu entries, and an extension could contribute a “Create jira issue” menu entry for it. In this manner, we would de-correlate the edit mode from the view mode, and still allow users to access that menu when editing inside the wysiwyg editor (since the wysiwyg editor renders the jira macro). It would also allow users to create new jira issues in view mode, which is an even more important use case to me if you want to create jira issues from XWiki. And it would allow to introduce a new module in the jira extension that is exclusively in charge of creating jira issues, cleanly separating it from the rest.

When the jira source is a list, the list is in the macro’s content. Can we safely add a new issue to that content from view mode? Should we provide a new JIRA Source that would allow more flexibility?
Having a UIXP and UIX is an interesting idea. Let me think more about it and come back to you.

@vmassol

Note that I don’t know if that works technically, ie if macros can create dialogs that would work both in view mode and in edit mode inside the WYSIWYG editor.

Also, it means that this options menu should be visible even when the jira macro result is empty (ATM I think we don’t display anything when there are no results which would need to be changed).

I do think that for the use case I had in mind, we need this to also work in edit mode. I’m sure that if we decide to make it work we will find a solution to get it to work both in view and WYSIWYG edit mode.

@vmassol

Note that this screenshot tab says “Issue List” but that’s not correct. It depends on the source used (it can be a list, or a JQL query, or any other content supported by an extension that implements a JIRA Source).

Indeed, thanks. Also, currently, once the issue is created, the new issue is added to the list, but we shouldn’t change the content when we are not using a list source.

@vmassol

Also, the creation of jira issues seems more related to the Instance section than the Content section to me.

I thought that an user would always want issues created from that menu to be included in the content.
I would also think that the content is always dependent on the selected instance.

@vmassol

Re jira issue creation, isn’t it possible in jira to say that some fiels are required when creating an issue? Asking since you seem to have a fixed list of fields in your UI.

Absolutely, for now I focused on getting the basics to work, but the idea is for that part of the form to be dependent on the instance, project and issue type.
We should retrieve the list of fields and display pickers accordingly, even for non mandatory fields.

@vmassol

Also the Reporter needs to be set. How do you configure the jira user to be used?

This is a crucial question.

• The ideal approach would be to use OAuth to connect the JIRA integration on a per-user basis, and do everything in their name directly, if there is a required reporter field, we should display it as is because the user has permissions to change it, maybe prefilling it with their own username.
• However, I would like to have this feature with a simple service user, before we add OAuth support to the JIRA integration, if we do.
  The only way to do this I can think of is to provide a configurable mapping from XWiki users to JIRA users. It could be a configurable piece of code in the administration.
  For instances sharing a SSO between XWiki and JIRA, we could simply map the username directly, eventually with a fallback to the service user when the corresponding JIRA user does not exist.
  If an instance has a more complex relationship between JIRA and XWiki users, the administrators could make calls to APIs or fetch objects attached to the current user in order to perform the mapping.
  This could allow an administrator to let their users link their JIRA account themselves for instance.

@vmassol

Feels like some java side script service might be better for this (and easier to test and won’t require wiki pages that needs to be installed on all wikis where the feature is installed on).

Thank you, I will transition to that approach then.

Thanks,
Dorian.