Skip to main content
Planview Customer Success Center

Atlassian Jira Align

Atlassian Logo

 


 

Overview

Jira Align is an Enterprise Agile Planning platform, increasingly popular in large enterprises. Ideas that start in Jira Align are executed in work management tools like Jira, Azure DevOps, and Rally; tested in tools like Tosca, qTest, ALM and SmartBear; and supported in ITSM tools like ServiceNow, Jira Service Desk, and Remedy.

Jira Align provides the ability to drill down to team level work while providing visibility and coordination at the program, portfolio, and enterprise levels. Optimized for customer value, Jira Align can connect teams across the organization to determine scope, roadmaps, and dependencies across departments.

Key Features and Benefits

  • Reliable and seamless bi-directional synchronization, eliminating friction and delays 
  • Elegantly merge several acceptance criteria from Jira Align into a single, rich text format field in a targeted tool, like Jira or qTest
  • Route feature work to the right team in the right tool based on its program or any other feature fields, and use filters to determine what’s eligible to flow   
  • Automate artifact creation in Jira Align (Themes, Capabilities, Epics, etc.) based on activities in other tools like Salesforce, SharePoint, and ServiceNow
  • Embed back-references (links) to twinned Jira Align artifacts to automate traceability and facilitate communication with colleagues  
  • Easily resolve synchronization errors with robust monitoring, troubleshooting and retry mechanisms

Demo Videos

 


 

Connector Setup Details

This section describes the basic steps needed to prepare your Jira Align instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.

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 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 to learn how to create a custom user in Jira Align.

List of minimal user permissions:

  • The Super Admin role is required to retrieve artifacts from the repository. 
  • The user used to authenticate against Jira Align must have Add and Save permissions for each of the work item types.

  • The user must have read access to products, programs, users, releases, release vehicles, teams, and iterations.

Connecting to the Jira Align Repository

API Token

Note: In Jira Align's latest release, there is now a version 1.0 and version 2.0 API token. The current (version 1.0) API token will continue to work until Jira Align's 10.83 release, at which point you will begin to see authentication failures and must update your connection to use the version 2.0 API token.

Required Fields: 

  • Location/Connection URL 
  • API Token
    • To find the API Token for a user, log in to Jira Align as the Hub user. Under User Menu > Edit Profile, click API Token.

Optional Fields: 

  • Disable Capability: Determines whether the artifact 'Capability' is available for use. 
    • If checked, the artifact 'Capability' will not be available and Feature artifacts will use Epics as parent artifacts.
  • Disable listing options for sprint field: Determines whether the connector will list options for the Sprint field.
    • If checked, the connector will not list options for the Sprint field. Options for the model field will be used directly when reading and writing the field value.
  • 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.

Screenshot 2023-09-11 at 10.43.52 AM.png

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

 


 

Other Configuration Settings

Person Reconciliation

For person reconciliation, the following fields are available:

Fields Used for Hub’s Default Person Reconciliation Algorithm

Field Names for Person Reconciliation Extensions

(Note that these are case sensitive)

Label in Jira Align

ID

uid

UID

Email

email

Email

N/A

fullName

Name

N/A

firstName

First Name

N/A

lastName

Last Name

Learn more about how to configure person reconciliation in Planview Hub here.

Full Scan

Due to third party API limitations, updates to the following fields/work items may not trigger change detection or cause a synchronization immediately. To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:

  • Release Vehicles on the Story work item
  • Additional Programs
  • Acceptance Criteria
  • Themes

Learn more about how to configure change detection and full scan intervals in Planview Hub here

Repository Queries

Planview Hub: 21.4 and later

If you’d like to refine your Jira Align collections, you can set a repository query that will filter your artifacts by Program ID. 

The following artifacts can be filtered by Program ID:

  • Capability
  • Defect
  • Epic
  • Feature
  • Story

There are two types of repository queries that can be set by Program ID: By Program IDs (Small Program Set Optimized) and By Program IDs (Large Program Set Optimized).

  • When running standard change detection:
    • Small Program Set Optimized will be faster if the number of programs listed is small relative to the total number in the repository. 
    • Large Program Set Optimized will be faster if the number of programs is high relative to the total number in the repository. Large Program Set Optimized will also be faster if changes are mostly made to items included in the Program ID list (i.e., programs not in the integration are programs that aren’t very active). 
  • When running a full scan:
    • Small Program Set Optimized will always be faster, but as the number of program IDs increases, the performance of Small Program Set Optimized will approach Large Program Set Optimized

You can learn more about setting repository queries here.

 


 

Supported Features

Special Features Supported

You can learn more about special features in Planview Hub here.

Feature

Applicable Hub Version

Applicable Repository Versions

Not_allowed.svg.png Time Worked (Worklogs)

Not_allowed.svg.png Impersonation

Planview Hub: All

Any supported repository version:

Not_allowed.svg.png Comments

Not_allowed.svg.png Impersonation 

Not_allowed.svg.png Public/Private 

Planview Hub: All

Any supported repository version:

Not_allowed.svg.png Attachments

Not_allowed.svg.png Impersonation

Planview Hub: All

Any supported repository version:

N/A - State Transitions

(Jira Align does not use state transitions. Status can flow into and out of Jira Align as a single-select.)

Planview Hub: All

Any supported repository version:

 


 

Supported Artifacts

Note: These artifact types may be labeled differently in different instances of Jira Align. To find the UI label of each of the following artifact types, go to Administration > Platform Terminology. The Object Name of each item corresponds to the artifact type name in the Jira Align connector. The Object Singular and Object Plural of each item correspond to the name that is displayed in the Jira Align UI.

Supported Work Items

Learn about the difference between containers and work items in Planview Hub here

Supported Work Item Type

Applicable Hub Versions

Applicable Repository Versions

Unique URL?

Theme

Planview Hub: 20.3 and later

Any supported repository version:

 

Epic

Planview Hub: 20.3 and later

Any supported repository version:

 

Capability

Planview Hub: 20.3 and later

Any supported repository version:

 

Feature

Planview Hub: 20.3 and later

Any supported repository version:

 

Story

Planview Hub: 20.3 and later

Any supported repository version:

 

Defect

Planview Hub: 20.3 and later

Any supported repository version:

 

Task

Planview Hub: 20.3 and later

Any supported repository version:

 

Supported Containers

Learn more about containment in Planview Hub here

Containers that can synchronize between repositories

Applicable Hub Versions

Applicable Repository Versions

Unique URL?

N/A

 

 

 

Containers used to define the boundary of a collection

(when clicking 'Manage Projects' on a collection)

 

 

 

N/A (entire repository serves as container)

Planview Hub: 20.3 and later

Any supported repository version:

N/A

Containers used for artifact routing

 

 

 

Programs

Planview Hub: 20.3 and later

Any supported repository version:

N/A

 

 

 

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.

Field Type

Does Hub support custom fields of this type?

How is field type referenced in the repository?

Sample Repository Fields Supported

Particular Repository Fields NOT Supported

checkicon.png String

checkicon.png

Text Input, Text Area

Title

Report Color

Acceptance Criteria

 

checkicon.png Single-select

checkicon.png

Dropdown

Priority

Release

Product

Status

Type

 

checkicon.png Multi-select

checkicon.png

Multi Dropdown

Release Vehicles

Releases

 

checkicon.png Boolean

Not_allowed.svg.png

 

MMF

MVP

Closed

Blocked

Is Active

 

checkicon.png Date

Not_allowed.svg.png

 

Portfolio Ask

Start/Initiation

Target Completion

 

checkicon.png Date Time

Not_allowed.svg.png

 

Detection Date

Modified

Created

 

Not_allowed.svg.png Duration

 

 

 

 

checkicon.png Double

Not_allowed.svg.png

 

Points

Hours

Remaining(hr)

 

checkicon.png Long

Not_allowed.svg.png

 

Effort

Value

 

checkicon.png Person

Not_allowed.svg.png

 

Modified By

Creator

Detected By

Assigned To

Fixed By

Owner

 

Not_allowed.svg.png Persons

 

 

 

 

checkicon.png Relationship(s)

Learn how to configure relationships in Planview Hub here.

Not_allowed.svg.png

 

Parent Artifact

Theme

 

checkicon.png Rich Text

Not_allowed.svg.png

 

Description

 

checkicon.png Location

Not_allowed.svg.png

 

 

Read-only artifact location only

Not_allowed.svg.png Web Links

 

 

 

 

Not_allowed.svg.png Time Entries

 

 

 

 

Not_allowed.svg.png Other

 

 

 

 

Note: Field types above which don't explicitly state the Jira Align name for the type are not referenced by name in the repository UI.

 


 

Functional Limitations

Category

Limitation

Applicable Hub Version

Applicable Repository Version

Third Party API Limitation

Custom Fields

Multi-portfolio configurations should have custom fields configured consistently.

Exemplar artifacts select the first artifact for each type (as given by the Jira Align API) and base custom field detection based on which custom fields can be retrieved from the first artifact.

Planview Hub: 23.4 and later

Any supported repository version:

Third Party API Limitation

Points Field

Due to an API limitation, Planview can only provide read-only support for the Points field with Story Point estimation systems. 

Points will be summed up across Initial Estimates and Releases, and will be available as one summed up value for synchronization.

Planview Hub: 23.4 and later

Any supported repository version:

Third Party API Limitation

Investment Type Field

The field is supported as an Integer field, but should be listed a Single Select field in the UI.

As the API is unable to provide a listing of the values it accepts, you must determine which integer values that each single select option correlates to and script the field properly to ensure that field flow is maintained.

You should query the API to determine applicable options and consult the documentation on custom extensions.

Planview Hub: 23.4 and later

Any supported repository version:

Good to Know

Points Field

If attempting to update the Points field on a Feature to an empty (i.e., null) value, the Points value will be set to 0.

Planview Hub: 22.1 and later

Any supported repository version:

Feature Not Supported

Customized OOTB Fields

Customized OOTB fields are not supported in any capacity.

Planview Hub: 20.3 and later

Any supported repository version:

Good to Know

Repository Queries

Repository queries do not typically support including more than 20-30 program IDs.

Depending on the configuration of your Jira Align server, this can be increased by increasing the max query size in Jira Align.

Note: You may still encounter an upper limit when including more than 30 program IDs.

Planview Hub: 21.4 and later

Any supported repository version:

Feature Not Supported

Repository Queries

Repository queries do not currently support the Theme and Task artifact types.

Planview Hub: 21.4 and later

Any supported repository version:

Third Party API Limitation

Developmental Step Fields

Due to a third party API limitation, the Developmental Step Field is read-only on the Theme artifact type.

Planview Hub: 21.3 and later

Any supported repository version:

Third Party Functional Limitation

Themes

The revision on themes will not update if the theme has been updated in the UI.

Planview Hub: 20.3 and later

Any supported repository version:

Third Party Functional Limitation

Capabilities

Program Increments (PI) set on Capabilities will only be set on the artifact if the PI is also set on the parent Epic.

If the Capability is created with a PI that is not set on the parent Epic, the PI will not be set on the Capability.

Planview Hub: 20.3 and later

Any supported repository version:

Third Party API Limitation

Creating Features

There is an issue where the API will sometimes return a 400 error response when creating features with the message "Cannot create feature. Value for programId is invalid."

This may occur when the program is valid but the API does not accept the values submitted. Creation may succeed on a subsequent retry.

Planview Hub: 20.3 and later

Any supported repository version:

Third Party API Limitation

Theme Fields

The API requires a valid value to be set for the 'Theme' field.

Planview Hub: 20.3 and later

Any supported repository version:

Third Party API Limitation

Programs Fields

The API requires a valid value to be set for the 'Programs' field.

Planview Hub: 20.3 and later

Any supported repository version:

Third Party API Limitation

Defects, Stories, and Features

Defects, stories, and features which are created in the UI will sometimes not be able to be updated by the connector. When created in the UI, a release vehicle with ID 0 will be set on the work item, which will cause any API update of the work item to fail. There is a support ticket with Atlassian about this defect at ALIGNSP-3924.

Planview Hub: 20.3 and later

Any supported repository version:

Third Party API Limitation

Owner Fields

The 'Owner' field on Tasks is only supported as a read-only person field.

Planview Hub: 20.3 and later

Any supported repository version:

Third Party API Limitation

Capabilities

Capabilities cannot be updated. Hub will produce an error if a Capability is updated as part of an integration.

Planview Hub: 20.3 and later

Any supported repository version:

Feature Not Supported

Release, Estimate, and Acceptance Criteria Fields

The 'Release,' 'Estimate,' and 'Acceptance Criteria' fields are not currently supported for Capabilities.

Planview Hub: 20.3 and later

Any supported repository version:

Feature Not Supported

Fields

Fields which are not on the basic details tab on an OOTB Jira Align instance are not currently supported.

Planview Hub: 20.3 and later

Any supported repository version: