Atlassian Jira

Jira Core

Jira Core is the default application of the Jira platform, and will always be present in a Jira instance. It includes Jira core functionality, such as users, business projects, and workflows, and its main work item types are tasks and sub-tasks.

Jira Software

Jira Software includes users, software projects, and workflows, and its main work item types are tasks, sub-tasks, stories, bugs, and epics.

Jira Service Management 

Jira Service Management (formerly Jira Service Desk) includes users, service projects, and its main work item types are change, access, purchase, IT help, fault, new feature, improvement, incident, problem, and service request.

Service Desk Type Mappings

The Service Desk Type Mappings field enables you to create a Service request for artifacts synchronized into a Service project by specifying the Jira and Service Management artifact type pairs for each project.

When specifying artifact type pairs, please use the following format:

• Project A: Artifact Type in Service Management = Artifact Type in Jira, Artifact Type in Service Management = Artifact Type in Jira; Project B: Artifact Type in Service Management = Artifact Type in Jira

Example:

• Project A: Get IT help = Service Request, Report a system problem = Incident; Project B: Upgrade or change a managed system = Change, Report a system problem = Incident

Good to Know:

• If the following characters are included in the project or artifact type names (: ; , =), they must be escaped with a preceding backslash (\).
• If an invalid value is provided (e.g., misspelled projects, missing projects or artifact type names), a detailed error message will appear and the debug output will diagnose the error. 
• If a project name is incorrect, it can still be mapped. However, as it is possible to create two Service Management types with the same name and different case, the type name must match the case or Hub will be unable to map it. 
• If you create a Service request type with extra spaces before and after the name, an error will appear and will need to be diagnosed by the error message and debug output.

Please see details below regarding Jira Service Management limitations. 

Jira Data Center

Please see configuration details below if using Jira Data Center.

Zephyr Squad Plugin 

Zephyr Squad augments Jira's capabilities with test management. Hub’s Atlassian Jira Connector provides support for Zephyr ‘Test’, 'Test Cycle' and ‘Test Execution’ artifacts. Test Artifact (without the "special" test model pieces) is supported as a regular issue type as well.

Requirements:

• The Zephyr for Jira Add-On is installed and licensed for ‘Test Execution’ support.
• The ZAPI Add-On is installed and licensed.
• Hub repository settings are set with a user with permissions to use the Zephyr API (ZAPI).
• For Zephyr Cloud, the Zephyr Access Key and Zephyr Shared Secret Key must be provided in the Hub repository settings. These can be created in the Jira Administration settings under Add-Ons, ZAPI.

Note: In Zephyr for Jira Cloud versions 7.1.1 and later, the ZAPI add-on is no longer supported and will not be required for the Zephyr Squad plugin.

The 'Test Cycle' and ‘Test Execution’ artifact types are only visible if the above requirements are met and the associated project has the ‘Test’ type enabled. Similarly, you will only be able to execute Test Cycle and Test Execution queries if the above requirements are met.

Beginning in Hub version 24.4, Test Cycle, Text Execution, and Test Artifacts are fully supported.

Test Steps:

• The following default fields are currently supported:

  • Test Step

  • Test Data

  • Test Result

  • Order Id(Read only)

Cross-artifact linking between Zephyr artifact types are supported, including:

• Test Execution Links to:

  • Cycle

  • Issue (Zephyr Test linked to Test Execution)

  • Defects

• Zephyr Test Links to:

  • Test Executions (Read Only)

  • All Jira standard relationships

Zephyr Cloud:
Synchronization of dates in Zephyr Cloud Test Cycles is supported starting Hub 24.4 and later releases.

Change Detection

We recommend to disable change detection in Zephyr Test Cycle and Test Execution artifacts because of a known limitation in the Zephyr API. With Change Detection switched on, it results in creating a high volume of network traffic and become non-performant.

Note : If change detection is not disabled, then, Hub may not be able to process any other event until change detection is completed.

To configure change detection for your integration(s), please see the following instructions:

1. In Planview Hub, navigate to the integration page and select the integration that you want to set a change detection configuration to.

2. It is recommended that the integration is set to a one-way creation into the Zephyr connector.

3. Under the Overview section, select “Change Detection”.

4. Navigate to the Zephyr section and select “Override”.

5. Under Change Detection, set Repeat Method to “Advanced Scheduling”.

6. Set Cron to a setting that will not trigger the change detection. Example: '0 0 12 ? * * 2000.'

7. Click Save and Done.

8. Repeat these steps for the required Zephyr Integrations.

Jira Agile Plugin

Jira Agile is one of the most common plugins in the marketplace and has become an out-of-the-box piece of Jira Software installation since the 6.3.1 version. This means that if you are on a version later than 6.3.1, you likely did not even have to install the Agile plug-in, as it was automatically installed along with Jira Software. This plugin enables features for easy day to day work management with scrum/agile/Kanban processes. The plugin also creates various custom fields.

Some of the following Jira Agile fields are created by the plugin:

• Jira Agile Sprint Field
  • Note: This field is read-only in Planview Hub versions 18.3 and earlier / Tasktop Sync versions 4.15 and earlier. You can learn more in the FAQ below.
• Epic Status
• Epic Name
• Epic Link

Jira nFeed Plugin

The Jira connector supports nfeed fields. Note that nFeed user fields are read-only.

Dynamic Forms for Jira

Planview Hub supports synchronizing dynamic custom fields via the Dynamic Forms for Jira Plug-in. 

• Dynamic Forms fields Select, Cascading Select, Radio Buttons, and Checkbox fields are writable.
  • Please see details below regarding cascading select fields.
• Bundled fields are read-only.

Jira Crowd

Atlassian Crowd enabled SSO is supported in the Hub versions listed above. When setting up the Crowd server in the customer environment, the instructions outlined in this guide must be followed.

The Hub user created through Crowd should have the same Jira permissions as recommended for the regular Hub user. 

Users should review the Atlassian SSO troubleshooting guide to troubleshoot any network issues relating to SSO. If the Hub user is unable to authenticate, the first step should be to try to log in via the Jira UI. If the user is unable to authenticate through the UI, it implies that there are issues with the way Crowd SSO is set up in the customer environment.

iRise Plug-in for Jira

The iRise Plug-in for Jira allows you to render up-to-date iRise screen thumbnails directly on the corresponding artifact in Jira cloud. To use the plug-in with your Jira-iRise integration, follow the instructions below:

1. Install the iRise Plug-in for Jira to your Jira cloud instance.
2. Create a string field in your Hub model called 'iRise Prototype.'
3. On the iRise side, map that model field to the 'Chapter Simulation URL' location field.
4. On the Jira side, create a custom string field called 'iRisePrototypeURL,' and map it to the 'iRise Prototype' model field in Hub.
5. On the Field Flow screen for your iRise-Jira integration, update the field update frequency on the Jira side to 'always update.'
   
6. Run your integration.
7. On the Jira artifact, copy the link from the 'iRisePrototypeURL' field and paste it into the iRise plug-in field. Then click 'Attach screen.'
8. You will see the screen thumbnail for the iRise artifact rendered directly within Jira.

Jira Project Specific Select Field Plug-in

Planview Hub supports synchronizing the following custom fields via the Project Specific Select Field Plug-in: Single, Multi, and Simple.

Requirements Management for Jira Plug-in (R4J)

Planview Hub supports synchronizing the relationship fields Child Requirements and Parent Requirements for the R4J plug-in.

Hub also supports R4J Folders as container type artifacts.

Note: This artifact and any related fields will only be visible if the R4J plug-in has been enabled on the server and for the projects in the collection.

• A regular Jira issue in R4J can have multiple parent folders (if the parent folders are not in the same project), but a folder can only have one other folder as its parent.
• The 'Parent Folder' field exists as a container link field on folder type artifacts, and a 'Parent Folders' field has been added as a multi-container link field on regular Jira artifacts.

Note: The supported relationship fields do not support change detection, therefore, a full scan is required to pick up changes for these fields.

See Functional Limitations table below for limitations regarding this plug-in.

Jira Tempo Plug-in

Planview Hub supports synchronizing the Team and Account fields for the Jira Tempo plug-in.

• For a team to appear as an option for the Team field for a project, the Hub user must be added to each team as a member or as part of a group, and the project must be linked to it.

• For the Account field, the account must be linked with the project.

• For Hub to write to a Tempo field, the field must be added to the Jira edit screens for each project and type used in integrations.

The Tempo Cloud API Token field allows you to retrieve the actual Jira author on worklogs when retrieving worklogs created with the Tempo plugin on Jira Cloud. 

Note: If the provided Tempo token is not valid, an error will be thrown when retrieving Tempo worklogs. If no Tempo token is provided, worklogs will be retrieved without using the Tempo API and any Tempo created worklogs will have 'Tempo Timesheets' set as the author.

To create a Tempo API token for your user, open the Jira Tempo App and navigate to Tempo > Settings. Then, scroll down to Data Access and select API integration.

 Note: The only access required for the token is View Worklogs access.

Advanced Roadmaps for Jira Data Center Plug-in (on-prem)

Planview Hub supports the Team and Parent Link fields for the Advanced Roadmaps (formerly Jira Portfolio) plug-in.

Note: The Hub user created through Advanced Roadmaps must be granted Advanced Roadmaps shared team management permissions. To list non-shared projects/teams, you must also have Advanced Roadmaps user permissions.

Label Manager for Jira Plug-in

Planview Hub supports synchronizing the Label Manager fields for the Label Manager for Jira plug-in.

Note: Hub does not support label colors or the “Label Manager Progress” custom field type.

See Functional Limitations table below for limitations regarding this plug-in.

For more information, refer to Jira documentation here.

Xray Test Management for Jira Plug-in

Jira Plug-ins (other)

Fields created by other plug-ins may be exposed in Hub as read-only fields. These are typically fields that are added to the normal Jira artifact UI by the plug-in (i.e., a field that is displayed within the typical Jira defect UI). Fields created by unsupported plug-ins that are included in totally new UI sections in Jira, on the other hand, will likely not be exposed in Hub.

Minimal User Permissions & Hub User

We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization. 

In general, your Hub user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.

Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'

See instructions on how to create a new Hub user in Atlassian Jira.

List of minimal user permissions:

Note: The minimal user must be a member of the group and have the following permissions at the project level.

Note: We recommend setting the Hub user in Jira's language to English to prevent errors upon synchronization.

Please see additional details below on the following:

• Enabling fields to be synchronized in Jira
• Updating closed Jira issues
• Cascading Select Fields

Connecting to the Jira Repository

Standard Authentication

Required Fields:

• Location/Connection URL

  • Example Format: https://jiraserver.com:8080

• Username

• Password

Standard Authentication (Via AWS Secrets Manager)

This authentication method connects to AWS Secrets Manager to retrieve the username and password and then authenticates with the Jira repository via Standard Authentication.

Note: This authentication method is only available to Jira Data Center instances as Jira Cloud does not support standard authentication.

Prerequisites: 

• IAM Role Permissions: The machine hosting the application must have IAM Role permissions to access the necessary AWS Secrets Manager secret. 
• KMS: Customer managed keys created in AWS Key Management Service (KMS), used for encrypting secrets, should be created in the same AWS account and region of the secret.

Required Fields: 

• Location/Connection URL
  • Example Format: https://server.atlassian.net 
• AWS Secret ARN
  • The Amazon Resource Name (ARN) is automatically generated in AWS when a new secret is created.
  • The ARN can be copied from the AWS Secrets Manager Secret details page in the AWS console.
    • 
  • Note: The Secret ARN will also support cross-account cases where the Secret is stored on a different account. In this scenario, the Policy configuration to access external AWS account Secret must be done and tested. 
  • The username and password must be created in that secret with keys “username” and “password” respectively. 
    •  

Optional Fields:

• Zephyr Access Key (see details above)

• Zephyr Shared Secret (see details above)

• Xray Cloud Client ID (see details above)

• Xray Cloud Client Secret (see details above)

• Tempo Cloud API Token (see details above)

• Service Desk Type Mappings (see details above)

• Attachment URL: This field is used to fetch attachments from an alternate URL.

  • Note: The Attachment URL should only contain the base URL.

• Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.

  • Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment. 

• Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Note: Atlassian will be deprecating basic authentication with passwords and cookie-based authentication for Jira Cloud by December 1, 2018. Users must configure a Hub repository authentication method other than Standard Authentication, such as Email Address and API Token Authentication (Jira Cloud only) by that time for Jira Cloud instances. See Atlassian notice here.

Learn more about how to set up your repository in Planview Hub here. 

Authentication Chain: Basic Authentication with Two Way SSL

Required Fields:

• Location/Connection URL

  • Example Format: https://server.atlassian.net

• Certificate (.p12)

• Certificate Password

• Username (for Jira)

• Password (for Jira)

Optional Fields:

• Zephyr Access Key (see details above)

• Zephyr Shared Secret (see details above)

• Xray Cloud Client ID (see details above)

• Xray Cloud Client Secret (see details above)

• Tempo Cloud API Token (see details above)

• Service Desk Type Mappings (see details above)

• Attachment URL: This field is used to fetch attachments from an alternate URL.

  • Note: The Attachment URL should only contain the base URL.

• Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.

  • Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment. 

• Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Email Address and API Token Authentication (Jira Cloud only) 

Required Fields:

• Location/Connection URL

  • Example Format: https://server.atlassian.net

    • URL format must begin with https

• Email Address

  • The email address used to create the API token

• Jira API Token

  • You can learn how to create an API Token in Jira here

  • The token can only be accessed once via the Atlassian website during this setup phase. If you lose the contents of the token, you must revoke the token and start from the beginning.

  • If the token is revoked on the Atlassian website, you must create a new token and update the Hub settings.

Optional Fields:

• Zephyr Access Key (see details above)

• Zephyr Shared Secret (see details above)

• Xray Cloud Client ID (see details above)

• Xray Cloud Client Secret (see details above)

• Tempo Cloud API Token (see details above)

• Service Desk Type Mappings (see details above)

• Attachment URL: This field is used to fetch attachments from an alternate URL.

  • Note: The Attachment URL should only contain the base URL.

• Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.

  • Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment. 

• Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

OAuth 1.0a Authentication

Required Fields:

• Location/Connection URL

  • Example Format: https://jira-8-0-oauth1.server.com

• Consumer Key

  • The consumer key set up using the instructions below.

• Authorization User ID

  • A valid user ID with rights to the issues you'd like to flow (see Minimal User Permissions & Hub User section above).

• Authorization Password

  • The password for the Authorization User ID.

• Private Key

  • The jira_privatekey.pcks8 you created in the steps outlined below. As an example, if the private key looks like the following: 

-----BEGIN PRIVATE KEY-----
12345
abcde
-----END PRIVATE KEY-----

Note: You only have to copy/paste the 12345abcde text. Hub will handle with the line wrap characters for you.

Optional Fields:

• Zephyr Access Key (see details above)

• Zephyr Shared Secret (see details above)

• Xray Cloud Client ID (see details above)

• Xray Cloud Client Secret (see details above)

• Tempo Cloud API Token (see details above)

• Service Desk Type Mappings (see details above)

• Attachment URL: This field is used to fetch attachments from an alternate URL.

  • Note: The Attachment URL should only contain the base URL.

• Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.

  • Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment. 

• Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

See additional instructions below.

openssl genrsa -out jira_privatekey.pem 1024
openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365
openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8
openssl x509 -pubkey -noout -in jira_publickey.cer  > jira_publickey.pem

Load Balancing

When a web application such as Jira requires horizontal scalability, a load-balancing solution is often used to aggregate the network traffic from a pool of web application servers. The solution may be referred to by one of the following labels:

• Load-balancer
• Reverse-proxy
• Application delivery controller (ADC)

Services configured on these solutions usually consist of three common components:

• A listener or virtual server
• A pool or cluster of web servers or nodes
• A health check

The listener is the part of the solution that receives incoming browser requests. It may optionally be configured to perform SSL/TLS termination or offload. The pool component handles connections to the individual web application servers. The health check (if in use) will perform active tests of each of the individual application servers to determine whether or not they should be sent traffic. The health state of each web server combined with the load-balancing algorithm determine which web server receives an individual browser request.

Most load-balancing solutions offer a choice of different algorithms to use. Determining which algorithm to use may require some trial-and-error tuning and is not the subject of this documentation; what is most important when configuring a load-balancing solution for a stateful application like Jira is that all requests originating from a browser or test framework terminate at the same web server for the duration of the application session. The reason for this is that the web server (Jira in this case) creates a new session for each request that does not already belong to a valid session. Session management in the case of Jira is handled by Java's web application framework, and relies on the use of the JSESSIONID HTTP cookie to track all of a user's activities including authentication. The scope of each session is limited to the web server that created the session; Jira application servers do not see the sessions created by other Jira application servers.

To ensure that an application server is always sent the requests belonging to sessions that it creates, the load-balancer must support sticky sessions or session persistence. Apache, HAProxy and NGINX (the community/free version) can each be used to distribute traffic to a Jira Data Center, but they each perform session persistence in different ways:

• Apache::mod_proxy
  • The jvmRoute parameter is passed to each Jira cluster member. This causes the JVM for each cluster member to append the value of jvmRoute to the JSESSIONID cookie (delimited with a ".").
  • Each Jira cluster member is added to a group as a BalancerMember. The route parameter of each BalancerMember is set to the same value of jvmRoute that was passed to each corresponding Jira instance.
  • mod_proxy checks the JSESSIONID cookie for each request for a route and sends each matching request to the corresponding BalancerMember.
• HAProxy
  • Does not require jvmRoute to be set on each Jira instance.
  • Adds a server identity prefix to a Set-Cookie response header, for a named cookie (the cookie does not need to be JSESSIONID).
  • Checks the named Cookie header from the request for a server identity and sends matching requests to the corresponding JIRA instance.
• NGINX
  • Does not support cookie-based persistence without a commercial subscription.
  • ip_hash load-balancing ensures session persistence, but may result in uneven distribution of traffic.

Jira and JVM

According to the official documentation, the JVM / Tomcat environments for each cluster member will, in addition to having a jvmRoute (Apache only), require some configuration in order to work behind a reverse-proxy server. The following tasks will need to be performed:

• Set the Base URL for Jira to match the URL of the load-balancer (done via the user interface).
• Set the proxyName for the Connector in the server.xml file to match the Base URL (and load-balancer).
• Set the proxyPort for the Connector in the server.xml file to match the port number in the BaseURL.

In the following example server.xml file, we are interpolating the values for proxyName and proxyPost from the CATALINA_OPTS environment variable string eg. -Dconnector.proxyPort=8080 -Dconnector.proxyName=jira.localdomain. In this example, jira.localdomain should resolve to the external-facing side of the load balancer. If the load-balancer is a name-based virtual server, the ServerName parameter for the virtual server should match.

<?xml version="1.0" encoding="utf-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<Server port="8005" shutdown="SHUTDOWN">
    <Listener className="org.apache.catalina.startup.VersionLoggerListener"/>
    <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on"/>
    <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"/>
    <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"/>
    <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener"/>

    <Service name="Catalina">
        <!--
         ==============================================================================================================
         HTTP - Proxying Jira via Apache or Nginx over HTTP

         If you're proxying traffic to Jira over HTTP, uncomment the below connector and comment out the others.
         Ensure the proxyName and proxyPort are updated with the appropriate information if necessary as per the docs.

         See the following for more information:

            Apache - https://confluence.atlassian.com/x/4xQLM
            nginx  - https://confluence.atlassian.com/x/DAFmGQ
         ==============================================================================================================
        -->
        <Connector port="8080" relaxedPathChars="[]|" relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;"
                   maxThreads="150" minSpareThreads="25" connectionTimeout="20000" enableLookups="false"
                   maxHttpHeaderSize="8192" protocol="HTTP/1.1" useBodyEncodingForURI="true" redirectPort="8080"
                   acceptCount="100" disableUploadTimeout="true" bindOnInit="false" scheme="http"
                   proxyName="${connector.proxyName}" proxyPort="${connector.proxyPort}"/>


        <Engine name="Catalina" defaultHost="localhost">
            <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">

                <Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false" useHttpOnly="true">
                    <Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"
                              factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
                    <Manager pathname=""/>
                    <JarScanner scanManifest="false"/>
                    <Valve className="org.apache.catalina.valves.StuckThreadDetectionValve" threshold="120" />
                </Context>

            </Host>
            <Valve className="org.apache.catalina.valves.AccessLogValve"
                   pattern="%a %{jira.request.id}r %{jira.request.username}r %t &quot;%m %U%q %H&quot; %s %b %D &quot;%{Referer}i&quot; &quot;%{User-Agent}i&quot; &quot;%{jira.request.assession.id}r&quot;"/>
        </Engine>
    </Service>
</Server>

Apache

Configuring cookie-based persistence with Apache requires the extra step of setting the jvmRoute on each of the Jira servers.

For example, at Hub, we use Jira Data Center installed on Docker Containers in our test environment. We pass the jvmRoute parameter to the JVM for each container using the CATALINA_OPTS environment variable eg. -DjvmRoute=jira-a. Alternatively, jvmRoute can be added to the Engine context of the conf/server.xml. Assuming there are two Jira instances named jira-aand jira-b, our Apache configuration should contain the following:

ServerName jira.locadomain
<Proxy "balancer://jira">
  BalancerMember "http://jira-a:8080" route=jira-a
  BalancerMember "http://jira-b:8080" route=jira-b
  ProxySet stickysession=JSESSIONID
</Proxy>
ProxyPreserveHost On
ProxyPass         "/" "balancer://jira/"
ProxyPassReverse  "/" "balancer://jira/"

HAProxy

Since HAProxy does not (is not able to) read server names from the tail-end of the HTTP cookie set by Jira's jvmRoute, jvmRoute does not need to be passed to the Jira servers. There are several different ways that HAProxy can be configured to perform session persistence eg. using different cookie names. The following example instructs HAProxy to add a prefix to the JSESSIONID cookie value eg. s1 or s2, depending on which server was initially selected by the load-balancing algorithm.

defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend ft_web
  bind 0.0.0.0:80
  default_backend bk_web

backend bk_web
  balance roundrobin
  cookie JSESSIONID prefix nocache
  server s1 jira-datacentre-node-a:8080 check cookie s1
  server s2 jira-datacentre-node-b:8080 check cookie s2

NGINX

There is only one way to ensure session persistence with the free version of NGINX: Change the load-balancing algorithm from round-robin to ip-hash. The documentation states that the sticky directive is only available with a commercial license.

upstream jira-cluster-lb {
    ip_hash;
    server jira-a:8080;
    server jira-b:8080;
}

server {
    listen 80;

    location / {
       proxy_buffer_size 8k;
       proxy_set_header Host $http_host;
       proxy_set_header X-Forwarded-Host $http_host;
       proxy_set_header X-Forwarded-Server $http_host;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_pass http://jira-cluster-lb/;
       client_max_body_size 10M;
    }

}

Troubleshooting

User login attempt fails with no error

Lack of functional session persistence manifests as an inability to log in. The sequence diagram below illustrates a simplified version of what happens at the HTTP level.

Redirects and links are broken

If either the Site URL (in Jira) or the proxyName and proxyPort parameters are not set to match the DNS name of the Jira service, URLs inside the application may be incorrect, and the site may try to redirect you to individual JIRA instances instead of the load-balancer.

References

For additional details, please see the Official Atlassian guide for Jira Data Center load-balancing.

Other Configuration Settings

Frequently Asked Questions

See Jira connector FAQs here.

Supported Features

Supported Artifacts

Supported Field Types

Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.

Functional Limitations