Jira Server Architectural Spec Written

[jordanh]

Adding support for Jira Server is one of our top feature ​requests. We're currently unsure what it would take to implement it. Let's remove this ambiguity.

N.B: @adaniels-parabol can grant the person who takes this issue access to our own version of Jira Server for development

AC

• Spec written in GitHub with high-level proposal on how implementation proceed, see this as an example
• After spec reviewed by Review & Maintainer, Epic created and Issues created (including design and implementation issues) and added to Epic
• Things to consider:
  • Should we create separate Jira integrations under Team→Settings→Integrations and lightweight affordances for disambiguating which integration to add when pushing to a task or the scope phase the first time? (see: Design: supporting self-hosted services #5567)
    • How might our database schema and graphql schemas need to change? (see this comment)
    • Should our initial implementation of this integration refactor the *Auth tables, or merely start by adding an IntegrationAuthProvider table to store the various oauth2 provider configurations?
  • Are all of the API calls identical between server and cloud?
  • Can we use Atlassian's new GraphQL API (see & possibly close Investigate Atlassian GraphQL API #5539)

EE

• 21 hours

[jordanh]

Related: #4915

[Dschoordsch]

Jira Server Integration Proposal

Overview

Jira Server is an onsite ticket system which Atlassian plans to fade out in favour of their Atlassian Cloud offering https://www.atlassian.com/migration/assess/journey-to-cloud There are no new features planned after January 2022.

API

REST https://developer.atlassian.com/server/jira/platform/rest-apis/
Jira Server does not offer GraphQL.

Jira Server Application

An administrator can add an OAuth 1.0a application.
https://developer.atlassian.com/server/jira/platform/oauth/#step-1--configure-jira
The administrator needs to create a private/public key pair and then enter

• Shared secret
• Request Token URL
• Access token URL
• Authorize URL
• Consumer key
• Consumer name
• Public key

in Jira to add Parabol as application. In Parabol we need

• Jira Home URL
• Private key
• Consumer name
• Consumer key

Since this is a bit more involved, we need to provide a direct link to the documentation, or in the future go further and make it a wizard type dialog on our end which generates public/private key pair automatically and presents prefilled dialog to user to only copy and paste.

Integration Provider

Following the proposal of #5594 we have two variants of adding the Jira Server integration provider: team scope or organization scope.

Team scoped

• Pro
  • more granular
• Con
  • a lot more work for the team lead
  • not every team lead will get admin rights on Jira
  • most companies will probably not have multiple Jira server instances running

Organization scoped

• Pro
  • only one time setup
  • most likely matches the one Jira instance companies are running
  • easier to organize administrator rights to set it up
• Cons
  • if there are multiple Jira instances in an organization for different teams, all of these need to be added and everyone sees all instances

This is very clear in favour of organization scope.

Users within the organization with Jira Server being set up would then have an option to connect to it similar to other integrations.

If there is more than one integration added, it would show all of them. Connecting starts the OAuth flow. The token is valid for 5 years and there is no refresh token.

[Dschoordsch]

Implementation steps

Integration provider setup

Since the setup is a bit more involved and we don't have a UI yet where the user could add integrations for the organization, I propose adding it manually for enterprise customers first with a similar process like we use for SAML, i.e. our sales folks guide them through the setup.

Feature flag

The feature will only be available when a supervisor adds the provider to the organization. There is no need for a separate feature flag.

Version 0.5 (push tasks to integration)

• Jira Server: integration provider #5809
• Jira Server: Jira Server OAuth1 flow #5817
• Make createJiraTaskIntegration/createGitHubTaskIntegration generic #5819
• Jira Server: createTaskIntegration #5810
• Jira Server: push task menu #5993
• Jira Server: show integrated task #5994

Version 1 (poker)

• Jira Server: List issues in Sprint Poker #6096
• Jira Server: adding tasks to poker scope #6158
• Jira Server: sprint poker vote to comment #5811
• Jira Server: sprint poker vote to field #5812
• Jira Server: Allow searching for issues in Sprint Poker #6097

Version 2 (polish)

• Jira Server: persist search query #5820
• Jira Server: poker read back votes #5821
• Jira Server: implement stateToJiraServerFormat #6130

[jordanh]

Since the setup is a bit more involved and we don't have a UI yet where the user could add integrations for the organization, I propose adding it manually for enterprise customers

I concur completely!

[Dschoordsch]

@BartoszJarocki could you please take a look if I forgot anything fundamental?

[Dschoordsch]

Closing this as there shouldn't be any more surprises for Version 1.