Jira integration setup

Standard
Enterprise

Ensure you have completed all steps in Jira integration prerequisites and Jira integration data collection before proceeding.

Set up program increments and sprints

1. Determine program increment cadence and mapping to programs (quarterly is typical). Try to get as many programs as possible to use the same program increment to facilitate organizational alignment.

Program Increment Name

Start Date

End Date

Program

 

 

 

 

       

 

2. Determine the sync date cadence for the program increments.

  • If all teams participating in a program increment have similar sprint start and end dates, use those dates as the sync dates. You can adjust the setting for matching to sprints if needed. The default value is three days prior or post the sync date end.

Program Increment Name

Sprint Length

Start of First Sprint

 

 

 

     


Sprint syncing

When the first active Jira sprint is brought into Jira Align, the end date is recorded in Jira Align. It is matched to a sync sprint within a set buffer date range. All future sprints on the Jira board are then matched in board order to the next in line Jira Align sync sprint.

To set a buffer date range:

  1. Select the Settings gear Gear in the top navigation bar.
  2. On the left side of the page, select Jira Settings in the Connectors section.
  3. Select the Jira Setup tab.
  4. In the Sprint Buffer Days field, type the number of buffer days you’d like to use.

We recommend setting the Sprint Buffer Days value between 1 and 3 days to allow room for error in case a team forgets to complete a Jira sprint on time. However, this setting shouldn't be used to allow teams additional time to complete their work.

Generation of sync sprints when the PI is created is required unless the Sync Sprints from Jira option is set to Yes. If using this setting, the program-level teams (RTE/Architect/Product Manager) and the team-level teams (Product Owner and Scrum Master) are unable to plan and load stories into future sprints as this setting will only create the Jira Align sprint when the Jira sprint is added to the board.

“Bucket” sprints

If teams are not following Atlassian recommended practices for backlog management but are instead creating a “bucket” sprint, administrators will need to use the sprint override function to adjust those sprints regularly.

For example, a team has one active sprint on a team board, the “bucket” sprint is viewed as an intended future sprint and will be mapped to the next sync sprint. When the team then creates their next sprint and drags it above the “bucket” sprint, the integration picks it up as sprint 3 from the Jira board. The team then drags that sprint above the “bucket” sprint.

Jira Align administrators will need to remap the true sprint to the next sync sprint:

  1. Select the Settings gear Gear in the top navigation bar.
  2. On the left side of the page, select Jira Management in the Connectors section.
  3. Select the Jira Sprints tab.
  4. Use the table to remap sprints as needed.

Recommended practices for Jira teams

  • Do not create or use “bucket” sprints for backlog refinement. Instead, use Jira's project backlog for refinement as recommended by Atlassian.
  • Create sprints on board for each sprint in the PI at the start of each PI. As stories are ready and prioritized, the team can load the future sprints in Jira, either in conjunction with, in advance of, or instead of big room planning.

Recommended practices for Jira Align/BU Admins

  • Check for mismatched and out of alignment sprints routinely based on your team sprint schedules within the PI.
  • Generate all sync sprints when the PI is created.

Preparing for connector setup in Jira Align

You should configure Jira settings in Jira Align for the correct data synchronization. You can customize a number of settings according to your needs.

To configure and turn on integration:

  1. In Jira Align, set up portfolios and programs.
  2. Create program increments and sync dates you identified in Jira integration data collection.

 Once these steps have been completed, you can configure settings on the Jira Settings and Jira Management pages.

Establish connection

  1. Select the Settings gear Gear in the top navigation bar.On the left side of the page, select Jira Settings in the Connectors section.

  2. If you have multiple Jira instances and want to link them to Jira Align, do the following:
    Important: Jira Align installation team has to set up a separate service for each Jira connector to enable this functionality.

    a.   Select Jira Connectors (top-right of the page), and then select the necessary Jira connector from the corresponding dropdown menu.
    b.   In the Jira Link field, type the URL to connect to Jira, for example, https://jiraalign.atlassian.com/browse/{external}.
    c.   In the Admins field, you can allow certain users to be able to see and manage the connector settings. If this field is left blank, any users with access to the Jira Settings page will be able to manage the connector settings. However, if one or more users are selected in this field, only they will be able to manage them.
    d.    In the Jira API URL field, type the URL that the connector uses to make API calls to Jira, for example, https://jiraalign.atlassian.com/.
    e.     Select the authentication type for the connector. The authentication type descriptions are available here. The Service option indicates if the Windows Service is running (green) or has stopped (red). The Active option indicates if the connector is activated (green) or deactivated (red).
    f.     Select Add to add more Jira instances, as needed.
    g.      Close the dialog box.
    h.     Select the necessary Jira connector from the Connector dropdown menu (top-right of the page).

Map projects to programs

  1. To add Jira projects, select Add Project on the Manage Projects tab, and then complete the fields in the table. Use the information you collected in Jira integration data collection.
    • Project Key: Type the Jira project key.
    • Project Name: Type the Jira project name. Note that if the Jira project name changes, the name displayed in Jira Align will automatically change.
    • Program: Select the Jira Align program your Jira project will map to.
  2. Select Save.

Note: The table can be filtered by one or more values in the Project Key, Project Name, and/or Program fields. To filter the table:

  1. Select the column name.
    Screen_Shot_2020-01-17_at_4.23.24_PM.png
  2. In the list of items, select the checkbox next to one or more options to narrow the filter. You can also search for a specific item by typing its name in the text field.
  3. The filter criteria appear above the list of items, and the table filters to display items that meet the filter criteria.

To remove a filter:

  1. Select the column that contains the filter you want to remove.
  2. At the top of the list of items, select the option or options to remove from the filter criteria.
  3. Select Clear Selected Items to remove the filter criteria. 

Map boards to teams

Perform team mapping and use the information you collected in Jira integration data collection:

  1. Select Jira Management on the left, and then open the Jira Boards tab.
  2. From the Connector dropdown menu, select the Jira connector for this Jira board.
  3. Select Add Board and type the board ID and team name in the corresponding boxes.
  4. From the dropdown menu, select the program.
  5. The Jira Board column fills automatically from the board ID, team, and program you selected. Use this field to ensure that your mapping is correct. If no project is found, a yellow warning Screen_Shot_2020-01-17_at_3.41.54_PM.pngicon will appear next to the Project Key and the Jira Board column will not fill. Point to the icon to see the issue and actions needed to resolve it. This error often occurs for one or more of the following reasons:
    • The connector service account does not have permission to view the board in Jira or the board was deleted.
    • The board has a filter share without the parent project.
    • The board has a filter share with multiple projects.
    • The board does not have a project location in Jira's cloud version or does not have at least one shared project in the filter.

      This error will result in stories assigned to the Jira Backlog not properly receiving a team assignment when they are synced with Jira Align.
  6. It is recommended to sync Only sprints created on board for all integrated boards and ensuring that teams in Jira create sprints only on the actual board that will be integrated with Jira Align to ensure sprints are in alignment. If Only sprints created on board is selected, the connector will only map Jira sprints to Jira Align when the originBoardId from Jira matches the ID of the board integrated with Jira Align. Sprints that are not pulled in will be logged in the logs of each integrated board.
    Additional information on origin sprints can be found here:
    https://community.atlassian.com/t5/Jira-Align-articles/Jira-Align-and-Jira-Integration-Jira-Management-Shared-Sprints/ba-p/1265111
  7. Select Save.

Configure timers, issues, and fields

  1. Select Jira Settings on the left, open the Jira Setup tab, and then complete the fields in this section. The field descriptions are available in the Jira setup fields section below.
  2. Select Save.
  3. Open the Jira Integration tab, and then select Run to start the initial setup synchronization. This will create teams, sprints, and populate states.
  4. Open the Custom Issue Types tab, and then complete the fields in this section:
    a.     Jira custom issue types are converted to stories in Jira Align and can be assigned a different type. In this section, select Add and map Issue Type IDs in Jira to the corresponding Story Types in Jira Align. Select the necessary Jira connector for each issue type.
    Note: You can set up story types in the Settings > Platform > Dropdowns section.
  5. Select Save.
  6. Team-managed projects contain issue types that are project-specific. To set up fields for team-managed projects, see the Set up team-managed projects section.

Configure field management settings

Select the Field management tab to configure your field mappings. Here, you’ll set up Jira Align’s built-in fields, as well as custom fields you’ve added to your Jira Align instance. This tab consists of mapping tables of Jira Align fields and their corresponding Jira field IDs, organized by Jira Align work item.

Field management tab.png

Fields mapped on this tab (select to expand)

Feature fields:

  • Blocked
  • Business driver
  • Capitalized
  • Category
  • Feature points
  • MMF
  • Portfolio ask date
  • Priority
  • Start/initiation date
  • Target completion date
  • Text input custom fields
  • Type
  • Why? details
  • Work code
  • Single-select dropdown custom fields


To add a field mapping:

  1. Select Add field in the upper-right. A slide-out displays.
  2. In the Jira Align field dropdown, select the Jira Align built-in or custom field you’d like to map.
  3. Optionally, in the Sync direction field, select the direction you'd like the field to sync.
  4. In the Jira Field ID field, select the corresponding Jira custom field ID. The list of selectable fields is limited to fields with similar (syncable) Jira field types.
  5. Several fields require you to map field values in the Map field values section before they can sync between Jira and Jira Align.

    Fields that require value mappings (select to expand)

    Feature fields:

    • Blocked
    • Business driver
    • Capitalized
    • Category
    • Priority
    • Type
    • MMF
    • Single-select dropdown custom fields

     

    To map field values, select a Jira Align value in the Jira Align column, and enter its corresponding value in the Jira Software column. You may map multiple values from one app to a single value in the other; however, many-to-many mappings aren’t allowed.
    Note: The starred value is the value your work items will receive when no value is set in an app. For example, if you create a feature in Jira Align and assign it a priority, but no priority is set in Jira, the connector will assign the starred Jira value on the Jira epic during the initial sync.

  6. Add additional mappings as needed by selecting Add field value mapping in the lower-left.
  7. When you’re done mapping field values, select Save to save your changes.
    FieldMappingforCustomFields.png
  8. The field mapping is added to the table on the field management tab.
  9. If needed, you can return to the slide-out by pointing to a mapping row, then selecting the More actions (three dots) menu to the right of the row and selecting Edit mapping.
  10. If needed, mappings can be deleted by pointing to a mapping row, then selecting the More actions (three dots) menu to the right of the row and selecting Delete.
    Note: You can undo a mapping deletion immediately after deleting it by selecting Undo in the lower-left.
  11. For the Feature points field, you may optionally use the arrow(s) indicator in the Sync column to change the sync direction.
    Note: Other field sync directions are set by the Allow feature sync from Jira Align to Jira setting on the Jira Setup tab.

Pull Jira user data

Open the Pull Jira User Data tab, and then use the External ID Jira User field sync dropdown to select how you want to update Jira Align users' name, email, and external ID fields based on Jira user data.

Note: If you log into Jira Align with the Atlassian Guard authentication option and the connector syncs with a Jira Data Center instance, set the External ID Jira User field sync dropdown to None. This will prevent user external IDs from being overwritten, which could cause account lockouts. 

  • None: Select to update Jira Align users' First Name, Last Name, and Email fields from Jira. 
  • Username: Select to update Jira Align users' First Name, Last Name, Email, and External ID fields. The External ID field will update differently depending on the type of connected Jira instance:
    • If the connector syncs with a Jira Cloud instance, the External ID field of Jira Align users will be overwritten with Jira users' Atlassian Account IDs (AAIDs).
    • If the connector syncs with a Jira Data Center instance, the External ID field of Jira Align users will be overwritten with Jira users' usernames.

Select the User data pull button to run the synchronization. If you create a user in Jira Align before using the Jira integration or before a user has work in Jira, the connector uses email addresses to match users for sync.

Set up team-managed projects

Your Jira instance may consist of a combination of company-managed and team-managed projects. Team-managed projects contain unique states, custom field IDs, and issue type IDs, so they must be set up individually. To set up a team-managed project with the connector:

  1. Open the Manage Projects tab.
  2. In the Project Key column, select the project key of the team-managed project to view its details.
  3. In the slide-out that displays, open the Team-managed project settings tab.
    Note: This tab only displays on the slide-out when a project is a team-managed project.
  4. Fill in the text fields on the tab:
    • Story and feature points custom field. The key for the Jira field used for storing the story points. Use the format: customfield_10001.
    • Parent work item custom field on features. The key for the Jira read-only text field used for a parent epic or capability assignment on Jira Align features. Use the format: customfield_10001. It is synced only one way from Jira Align to Jira.
    • Capability parent custom field. The key for the Jira read-only text field used to display a feature’s associated epic (the parent of the feature’s parent capability) in portfolios where capabilities are enabled. Use the format: customfield_10001. It is synced only one way from Jira Align to Jira for features.
    • Program increment custom field. The key for the Jira text field used for a program increment. Use the format: customfield_10001. It is synced only one way from Jira Align to Jira for features.
    • Acceptance criteria custom field. The Jira custom field ID for the multi-line text field that is used for acceptance criteria. Use the format: customfield_10001.
      Important: If you sync acceptance criteria between Jira and Jira Align, you'll lose Jira Align's functionality to manage multiple, individual acceptance criteria on all synced Jira Align features and stories. Acceptance criteria will be limited to one field per work item in Jira Align. If you decide not to sync acceptance criteria, you'll be able to use the individual acceptance criteria functionality on Jira Align work items, but information will not sync between the two platforms.
    • Feature 'portfolio ask' date custom field. The key for the Jira date picker field that is used for the portfolio ask date on Jira Align features. Use the format: customfield_10001.
    • Feature 'start / initiation' date custom field. The key for the Jira date picker field that is used for the start/initiation date on Jira Align features. Use the format: customfield_10001.
    • Feature 'target completion' date custom field. The key for the Jira date picker field that is used for the target completion date on Jira Align features. Use the format: customfield_10001.

Please note, for the three Feature dates above, when you set up these mappings, the information in the application where the first update is made will sync to the other. For example, if Jira is your current source of truth and the Jira Align item is updated before the Jira item, the dates in Jira Align will sync to Jira. In this case, if Jira is the source of truth, we recommend setting up the mappings during off-hours and then running a JQL to pull the information to Jira Align.

  1. In the Feature, Story, Task, and Defect sections, enter the Jira Issue Type Name and Jira Issue Type ID for each respective work item in the corresponding fields.
  2. Select Save & Close to save your changes.

Map statuses to states

Map Jira statuses to Jira Align states or process steps on the State Mapping tab. Keep in mind that team-managed projects contain unique statuses that must be mapped to states individually.

  1. Open the State Mapping tab, and then set up mappings from Jira to Jira Align in this section:
    a.     From the Type dropdown menu, select the work item type (epic, feature, story, task, or defect).
    b.     Select the Jira states you'd like to map to Jira Align states in the corresponding field to add the Jira states to the mapping table.
    c.     Map each Jira State Description to the corresponding Jira Align State.
    Features, stories, and defects that are assigned to a canceled state or workflow state in Jira are automatically moved to the canceled recycle bin in Jira Align. They can also be cancelled in Jira Align, and the state will be set to the cancelled state in Jira.
    There is also a delete item state in the Jira connector. When this state is configured, it hard deletes the item in Jira Align.
    Note: Deleting a work item in Jira Align does not delete the corresponding issue in Jira.
  2. Set up state or process step mappings from Jira Align to Jira on the State Mapping tab:
    a.     Select the State Mapping option next to a Jira project.
    Note: If a project hasn't synced with Jira yet, the State Mapping option will be unavailable and a Not synced message will display instead. The initial sync will run according to your Timer for Jira boards, sprints, and fix versions setting. If you'd like to run the initial sync sooner, we recommend running a custom JQL query to instantly sync between Jira and Jira Align.
    b.     Select if you’d like to map Jira Align states or process steps using the toggle at the top of the modal.
    c.     Use the Work item type dropdown menu to select a work item type (epic, feature, story, task or defect).
    d.     Map each Jira Align state or process step on the left to a Jira status on the right.
    e.     Select Update.
    f.      Repeat this process for each project to ensure that all statuses are mapped to a state or process step. You can also push the mappings to all company-managed projects using the Update other Jira projects option.
  3. Select Save.

Sync existing issues

  1. Open the Jira Integration tab, and then run the Jira JQL query to immediately synchronize issue types, steps, and sprints for a certain period. Run the data synchronization back through the start date you identified in Jira integration data collection:
    a.     In the Projects field, select the Jira projects to include in the query. Leaving this field blank will include all projects in the query.
    b.     In the Jira Search Query field, type your JQL query, for example, (created >= '2014/1/1' or updated >= '2014/1/1') and Project = ZAM.
    c.     In the Order by box, type order by Rank ASC.
    d.     Select Run.

Notes:

  • The current integration will continue to run.
  • The Run Board, Sprint, and Fix Version sync along with the search query dropdown menu gives you an option not to run the board sync process. Use this when you want to run a Jira integration JQL query so that the JQL can run in less time when the board sync process is not needed to run for the query.

Check connector activity

  1. Check the Jira audit logs for any issues:
    a.     On the Manage Projects tab, select View Logs.
    b.    View the issues, correct, and resynchronize if needed.
  2. Check the following areas to confirm that the integration worked as expected:

When a Jira Align work item is connected with a Jira issue, the work item’s details panel will include a View in Jira button, which will open the linked Jira issue in your Jira instance.

If a work item has synced with Jira previously, but the connector encounters mapping issues that prevent the sync of information, the Jira Align details panel will display these issues at the top.

Work item details panel with Unlink from Jira.png

Connector issues listed on the details panel (select to expand)

Error messages display at the top of the details panel when:

  • A work item’s Jira project mapping has been deleted in Jira Settings > Manage Projects or deleted in Jira
  • A work item’s associated Jira project is no longer mapped to the assigned Jira Align primary program
  • On features associated with multiple Jira projects, one or more Jira projects aren’t found or aren't selected in the Jira Project(s) dropdown
    • The error message will include the linked issues where the project validation failed.

You may wish to contact your Jira Align administrator, and/or select the Unlink from Jira button to remove the work item/issue association(s) causing the error. If unlinking a story, this will also remove the links for any child sub-tasks. After unlinking from Jira, resyncing the Jira issue will create a new work item in Jira Align.

Authentication types

The connector uses the following methods for authentication against the Jira REST API.

API token authentication (Cloud)

Note: API token authentication is the replacement for the deprecated cookie-based authentication and the deprecated user name and password basic authentication.

To configure API token authentication:

  1. From the Authentication Type dropdown menu (see Step 3 (b) of the Configure and activate Jira integration procedure above), select Basic with API Token Authentication.
  2. Type the user name and token of the user whose credentials you plan to use for the connection, and then select Save. To create a token, refer to the following documentation: https://confluence.atlassian.com/cloud/api-tokens-938839638.html

Note: The existing values are not shown on the UI for the security purposes. If you enter and save new values, they will overwrite the existing values. All communication is sent over encrypted HTTPS connections.

OAuth authentication (Cloud and Server/Data Center)

Jira uses Application Links to allow and manage OAuth.

To configure OAuth authentication:

  1. From the Authentication Type dropdown menu, select OAuth 1.0 Authentication.
  2. In the Jira OAuth Consumer Key box, type a consumer key of your preference, for example, JiraAlignOAuth.
    Note: Do not use spaces.
  3. Select Save.
  4. Select Generate OAuth Public Key.
  5. Sign in to Jira as a service administrator, and then go to Administration > Applications > Integrations > Application links.
  6. Type the URL to the Jira Align application, and then select Create new link.
    1_Configure_Application_Link.png
  7. Select the Use this URL check box, and then select Continue.
    2_Configure_Application_URL.png
  8. In the Link applications dialog box, type an application name of your preference, make sure Generic Application is selected for the Application Type, and then select Continue. No other fields need to be completed. The link is created, and now you need to configure it.
    3_Link_applications.png
  9. Select the pencil icon next to the link you created, and then select Incoming Authentication.
  10. In the Consumer Key box, type the consumer key you created in Jira Align in Step 2.
  11. Type a consumer name of your preference.
    4_Configure_Incoming_Authentication.png
  12. Scroll down and, in the Public Key box, insert the public key you generated in Jira Align in Step 4.
    5_Configure_Incoming_Authentication_Part_2.png
  13. Select Save.
  14. Go back to Jira Align, and then select Authorize Jira OAuth access. Wait for the Jira connector to run. It runs even if deactivated.
  15. Make sure you're logged into Jira as the service administrator, then select Request Jira for access in Jira Align.
    Note: If you need to restart the process of authorizing a new token (to reset something), select Restart Jira OAuth access.
  16. Select Allow, and then close the page that appears.
    Note: When you need to authorize a new token (if a token expires), select Re-Authorize Jira OAuth access.
  17. Select Save.

Note: If you change the consumer key or generate a new public key, you will need to reconfigure the Jira application link for OAuth again.

Personal access token (PAT) authentication (Server/Data Center)

You can use a personal access token (PAT) to authenticate into the Jira API. To configure PAT authentication:

  1. From the Authentication Type dropdown menu (see Step 3 (b) of the Configure and activate Jira integration procedure above), select PAT Authentication.
  2. Type the PAT of the user whose credentials you plan to use for the connection, and then select Save.

Note: When creating the PAT in Jira, make sure to uncheck the Automatic expiry checkbox.

Days_until_expiry.png

Cookie-based authentication (deprecated)

Note: Cookie-based authentication is deprecated and will be removed in the future in accordance with the Atlassian REST API policy.

To configure cookie-based authentication:

  1. From the Authentication Type dropdown menu (see Step 3 (b) of the Configure and activate Jira integration procedure above), select Cookie-based Authentication.
  2. Type the user name and password of the user whose credentials you plan to use for the connection, and then select Save.

Note: The existing values are not shown on the UI for the security purposes. If you enter and save new values, they will overwrite the existing values. Cookie-based authentication uses session cookies to authenticate. All communication is sent over encrypted HTTPS connections.

Jira setup fields

You can configure the following options on the Jira Setup tab in Jira Align for the correct data synchronization:

Timer for Jira boards. sprints, and fix versions

  • Timer for Jira boards, sprints, and fix versions. Type the number in minutes for how often the Jira boards synchronize with Jira Align, between 60 and 1440 minutes. The default value is 60 minutes.
  • Jira sprint mapping buffer days. Jira sprints are mapped automatically to Jira Align sprints if they have similar sprint start and end date. Adjust the number of days that can deviate for a sprint. The default value is three days prior or post the Sync Date end. We recommend setting this value between 1 and 3 days to allow room for error in case a team forgets to complete a Jira sprint on time. 

Pull from Jira

  • Pull from Jira. Type the number in minutes for how often the Jira issues synchronize with Jira Align, between 3 and 120 minutes. Jira Align queries data based on the Jira project and issue type combinations it is configured for. Running an issue timer keeps track of when data was last synced.

Push to Jira

  • Push to Jira. Type the number in minutes to set the interval for the continuous push of data from Jira Align to Jira and not make any Jira API calls, between 1 and 120 minutes. The default value is 1.5 minutes.

Notification

  • Allow Jira connection alert API calls. Select Yes to allow connecting to the Jira API.
  • Alert when Jira API connection fails. Select Yes to receive emails when the connectivity to the Jira connector fails. The Allow Jira connection alert API calls option needs to be activated to send the failed API connection alerts.
  • Send alerts if Jira Align cannot connect to API. Type email addresses (separated with commas) to send the alert emails to.

Issue Types

These fields you have already identified in the Jira custom field IDs and type names section under Jira integration data collection.

  • Feature issue type. The numeric ID (required) and name (optional, informational only) for the issue type that is used as an epic in Jira company-managed projects.
    Note: Team-managed projects contain unique issue type IDs that must be mapped individually (see the Set up team-managed projects section).
  • Story issue type. The numeric ID (required) and name (optional, informational only) for the issue type that is used as a story in Jira company-managed projects.
    Note: Team-managed projects contain unique issue type IDs that must be mapped individually (see the Set up team-managed projects section).
  • Task issue type. The numeric ID (required) and name (optional, informational only) for the issue type that is used as a sub-task (or task) in Jira company-managed projects. This identifies the sub-task issue type for tasks to be created in Jira as (when tasks are created in Jira Align and then sync to Jira).
  • Defect issue type. The numeric ID (required) and name (optional, informational only) for the issue type that is used as a bug in Jira company-managed projects.
    Notes:
    • Bidirectional sync of defects only supports one Jira issue type. The entry in the ID field determines what issue type is synced to Jira from Jira Align. If the ID is not supplied, the sync will only pull defects from Jira and will not push changes from Jira Align.
    • Team-managed projects contain unique issue type IDs that must be mapped individually (see the Set up team-managed projects section).

Custom Fields

Some fields you have already identified in the Jira custom field IDs and type names section under Jira integration data collection:

  • Jira Epic name custom field (this field may alternatively be called Feature name custom field if you’re only syncing with Jira Data Center or Jira Server). Optional if you’re syncing to one or more Jira Cloud projects. The key for the Jira field used for storing the epic name. Use the format: customfield_10001.
  • Feature custom field on stories. The key for the Jira field used for storing the epic link or
    epic ID link when you assign a story to an epic. This will sync with the Feature name field on stories in Jira Align. Use the format: customfield_10001.
  • Story points custom field. The key for the Jira field used for storing the story points. Use the format: customfield_10001.
    • Sync direction. The direction(s) the story points custom field will be synced.
  • Sprint custom field. The key for the Jira field used for storing the sprint ID. Use the format: customfield_10001.
  • Resolution date custom field. The field name of the value/flag set when you accept/resolve the issue. This one is usually called ResolutionDate in Jira.
  • Default user. If, for some reason, the connector cannot find the matching user, it will use this user as a default one.
  • Team custom field. Optional: In the dropdown, select whether you’d like to sync team field information with a built-in Jira team field, or with another custom field of your choice. In the text field, enter the key for the Jira field used for a team. Use the format: customfield_123.
  • Story and feature backlog rank custom field. Numeric ID value from Jira for a rank in the backlog. Use the format: 12345.
  • Delete item status. Optional: The Status numeric ID value from Jira which will result in items being permanently deleted from Jira Align. Do not use this if you want to use the recycle bin (two-stage delete) process in Jira Align. Regulated industry customers may have processes to support requirements around who may delete items from production/ production support/development systems. Use the format: 12345.
  • Default Jira Align story and feature priority. When you create a feature or story in Jira Align, it will create a feature or story issue type in Jira. This is a default priority that the connector will set on the newly-created issue in Jira. This is a one-time sync upon creation; editing the feature or story in Jira Align will not update the priority in Jira. The priority also does not sync to Jira Align when a feature or story issue type is first created in Jira. This setting will be ignored for features if you map feature priorities on the field management tab.
  • Product custom field. Optional: The key for the Jira field used for a product. It shows what product the feature maps to. Use the format: customfield_123. You also need to map Jira products to Jira Align products under the Customize link. NOTE: The Jira custom field must be of type Select List (single choice) and contain a list of products in Jira against which Jira Align will match the mapped products.

Please note, for the three Feature dates above, when you set up these mappings, the information in the application where the first update is made will sync to the other. For example, if Jira is your current source of truth and the Jira Align item is updated before the Jira item, the dates in Jira Align will sync to Jira. In this case, if Jira is the source of truth, we recommend setting up the mappings during off-hours and then running a JQL to pull the information to Jira Align.

  • Sync Jira resolver name on stories. Select whether to sync information from Jira to Jira Align on which user accepted/resolved stories in Jira. We recommend setting this to No for faster connector performance.
  • Jira change log resolution label. The label name in the change log in Jira used when you set an issue to Resolved.
  • Parent work item custom field on features. The key for the Jira field used for a parent item assignment on Jira Align features. Use the format: customfield_123. Read-only in Jira. It is synced only one way from Jira Align to Jira.
  • Program increment custom field. The key for the Jira field used for a program increment. Use the format: customfield_123. It is synced only one way from Jira Align to Jira for features.
  • T-Shirt custom field. The key for the Jira select list (single choice) field used for the feature’s T-shirt size estimate. Use the format: customfield_123. Use the Sync direction menu to choose the direction of sync: either Bidirectional sync (default) or Jira to Jira Align sync. Select the Configure link to open a settings window where you can map t-shirt size values between Jira Align and Jira.
    Jira_Tshirt_SetupWindow.png
    Notes:
    • In the Sync direction dropdown, a third choice, Jira Align to Jira sync was available in the past. If you currently have this option selected, it will remain available. We no longer support new connector setups using this option. If you change your sync direction to either the Bidirectional or Jira to Jira Align option, the Jira Align to Jira option will no longer be available. This is because users see better results either designating Jira as the source of truth or using a bidirectional sync.
    • This field only syncs when the Jira Align portfolio is set to use t-shirt size estimates through the Settings > Platform > Portfolio > Portfolio Specific Configuration > Estimation System setting.
    • Inside the Configure link for mapping, the values for T-Shirt are collected from t-shirt sizes set up for features. Configure your t-shirt size names at Settings > Platform > Portfolio > Estimation Conversions.
      • If a t-shirt size is deleted from the Estimation Conversions menu for features, existing features that contained the size will have their t-shirt estimates set to No estimate. This change will not sync to Jira until another edit is made to the feature inside of Jira Align. Syncs from Jira to Jira Align will not complete successfully unless a valid, mapped value is set on the Jira epic.
    • Inside the Configure link for mapping, leave the Jira Value field for the No estimate row blank if you would like to map No estimate in Jira Align with an empty value in Jira. 
      • If you map a custom Jira value such as “not estimated” with the No estimate Jira Align value, blank entries in Jira will be ignored during sync, and will not affect the Jira Align t-shirt estimate.
  • Capability parent custom field. Optional: The key for the Jira field used to display a feature’s associated epic (the parent of the feature’s parent capability) in portfolios where capabilities are enabled. Use the format: customfield_123. Read-only in Jira. It is synced only one way from Jira Align to Jira.
  • Business owner custom field. Optional: The key for the Jira field used for the Business Owner team role. Use the format: customfield_123.

Settings

  • Allow feature title updates from Jira Align to Jira. Select Bidirectional sync to allow changing the epic name in Jira when syncing from Jira Align

  • Sync story and feature ranks. Select Bidirectional sync to allow syncing the rank in the backlog. Rank is manually pushed or pulled between Jira Align and Jira by selecting Pull Rank on the backlog when the PI is set to None in the Configuration bar.
  • Allow feature sync from Jira Align to Jira. Select Bidirectional sync to allow syncing from Jira Align to Jira for all features.
  • Allow story sync from Jira Align to Jira. Select Bidirectional sync to allow syncing from Jira Align to Jira for all stories.
  • Allow defect sync from Jira Align to Jira. Select Bidirectional sync to allow syncing from Jira Align to Jira for all defects.
  • Allow task sync from Jira Align to Jira. Select Bidirectional sync to allow syncing from Jira Align to Jira for all Jira Align tasks to Jira sub-tasks.
  • Allow story state sync from Jira Align to Jira. Select Bidirectional sync to allow syncing the state of Jira Align story to the issue in Jira.
  • Allow feature state sync from Jira Align to Jira. Select Bidirectional sync to allow syncing the state of Jira Align features to the corresponding epics in Jira.
  • Allow defect state sync from Jira Align to Jira. Select Bidirectional sync to allow syncing the state of Jira Align defects to the corresponding bugs in Jira. When a state in Jira is set to Done, the state in Jira Align will be set to Closed.
  • Does story creation in Jira require a team assignment? Select Yes if the Jira Story issue type screen has a required team field.  This setting will require the custom field ID of the Jira custom field utilized for team mappings to be listed on the Organization field under Jira Align Admin > Jira Settings > Jira Setup.
  • Does epic creation in Jira require a team assignment? Select Yes if the Jira Epic issue type screen has a required team field. This mapping as been deprecated for current builds of Jira Align and is scheduled to be removed from the product.  Its setting will currently have no impact on the Integration.
  • Does creating stories in Jira allow both an assignee and reporter assignment? Select Yes to allow an issue in Jira to have a Reporter and Assignee when it is created.  When enabling this setting please ensure that the Jira Issue Create and Edit Screens have both the Reporter and Assignee fields present.  You should also validate that users creating Jira Align Work Items and users assigned as Owners to Jira Align work items have the create issue, and assignable user permissions on the corresponding Jira project.  

  • Is your Jira Team field a cascading select list? Select Yes if the Custom Team field in Jira is a cascading field and No if the Custom Team field in Jira is a single or multi-select field.  The parent and child relationships are set up in Jira Align under Manage Custom Fields > Sync Jira Team Values with Jira Align Teams.  The Parent field will be populated with the left value of a Jira cascading field and the Child field will be populated with the right value of a Jira cascading field.

  • Is your Jira Team field a multiple choice select list? Select Yes if the Team setting is a dropdown menu and No if it is single select to help reading and writing the data.

  • Allow Jira to overwrite Jira Align if two simultaneous syncs conflict. It is usually set to No. Select Yes to allow the Jira data to overwrite the Jira Align data when the data is changed at the same time and there is a conflict.

  • Make selection of Jira projects mandatory when creating items. Select Yes to make the Jira Project option required when you create working items in Jira Align, for example, features.
  • Assign features to multiple Jira projects in Jira Align. Select Yes to allow selecting multiple Jira projects for the same program when you create or edit the feature in Jira Align.
  • Assign Jira users to Jira Align teams when associated with stories and defects. Select Yes to allow Jira to check which issues the users are associated with and automatically add users to the team to which these issues belong. This setting will also automatically set team member allocations. When a Jira team member is assigned to multiple team sprints associated with the same sync date (anchor sprint), their sprint allocation will automatically be updated to be equal across those sprints, so that they add up to a total of 100% allocation. For example, if a member is assigned to three sprints that use the same sync date, their allocation for each sprint will be 33% per sprint by default. When a user is assigned to a kanban team via the connector, their team allocations are also included in the calculations at the end of each Jira Align anchor sprint. Allocations can be manually updated in Jira Align to override the automatic allocation values, and any existing manually-set values will not be affected by the automatic allocations. For situations where a user is not part of a team in Jira Align, but records time in Jira against a task, Jira Align will add the user to the sprint and team associated with the task’s parent story, with 0% allocation.
  • Sync sprints from Jira. Select Yes to allow creating sprints in Jira Align based on the sprints in Jira. The sprints will only be created if they can map to a sync date.
  • Allow Jira Align to assign stories to sprints. Select Yes to allow Jira Align to assign a story to a sprint in Jira. Otherwise, sprint assignment is one way from Jira to Jira Align. If a board has more than one active sprint or is sharing a sprint with another board, the synchronization will not occur.
  • Sync sprint names from Jira. Select Yes to allow renaming sprints in Jira and reflecting these changes in Jira Align automatically. You will not be able to name sprints in Jira Align, and any manual changes to sprint name in Jira Align will be overridden by Jira. The sprint name will still include the Jira Align team name and will look like [Jira Align Team Name - Jira Sprint Name].
  • Update program increment dates based on sprint or fix version dates. Select Yes to allow the program increment for a feature, story, or defect to be updated by using the latest dates of the Jira fix version or a Jira sprint. If both are assigned, the program increment assignment will be updated using the Jira sprint dates. When set to No, the program increment assignment will be automatically updated by Jira fix version dates or sprint dates when the item is created in Jira Align. After the item is created, the Jira fix version or sprint dates will not update the program increment.
  • Sync Jira Align release vehicles with Jira fix versions. Select Bidirectional sync to allow Jira fix versions to synchronize with Jira Align. If this option is turned off, fix versions do not synchronize. 
  • Allow Jira to update the team field for stories. If set to Yes and a customer has a one-to-one ratio of projects/boards/Jira Align teams, the field will sync the Jira Project field with the Jira Align Team field. Syncing will occur only in one direction from Jira to Jira Align. Changes to the Jira Align Team field will not sync back to Jira. Note that this setting does not apply if you have custom field team mappings on.
  • Create web links on Jira issues to Jira Align work item. Select Bidirectional sync to create Jira issue web links that link back to the Jira Align features, stories, tasks, and defects.
  • Start date of sprint import. Select the start date from which you want to import sprints from Jira into Jira Align.  The connector will map sprints created after this date on all integrated boards.  Historic issues from Jira can be integrated with Jira Align by running a JQL in Jira Align or conducting a bulk update in Jira.  This is the start date you identified in Jira integration data collection.
  • Jira text formatting type. elect how information in description and acceptance criteria fields should be formatted. The connector automatically detects which tool is being connected to and the editor being used in Jira to intelligently select this setting value. This will determine the editor functions available in these fields:
    • None (plain text) synchronizes the text as-is.
      Editor for plain text formatting.png

      Note: Jira Align environments will sync wiki markup feature descriptions for features in programs synced with Jira, even if this setting is set to None.

    • HTML maintains rich text content in Jira and Jira Align. We recommend selecting this value if you’re connecting to a Jira instance using a third-party editor that saves in HTML like JEditor.Editor for HTML text formatting.png
    • Jira rendered field saves feature and story description and acceptance criteria field information as wiki markup. For feature descriptions, this is a bi-directional sync.
      Editor for Jira rendered field formatting.png
      For story descriptions, as well as feature and story acceptance criteria, the rich text sync is a one-way pull from Jira into Jira Align and data is read-only. To view story description pulled details, select the eye icon next to the story description. Task and defect description information will be synchronized as plain text. We recommend selecting this value if you’re connecting to Jira Cloud or Jira Data Center.
  • Jira users' Full Name Format. Select a Jira display name format for the Jira users to set the correct first and last name parts in Jira Align. The following options are available: First Last and Last, First. The First Last option is the default one. You need to re-sync the user data on the Pull Jira User Data tab for the changes to happen.
  • Default system role for new users. Select a system role to assign all new integrated users by default. System roles mainly control what you see: menu items, buttons, and other.
  • Default Team Role for new users. Select a team role to assign all new integrated users by default. Team roles have certain responsibilities, such as running standup meetings, accepting stories, or managing sprints.

Notes

This is in reference to the two Yes/No toggles around the following options:

  • Allow Feature and Story Program Increments to be automatically updated by Jira Fix Version Dates
  • Allow Release Vehicles to sync with Jira Fix Versions

Permutations:

  • No/No or Yes/No – Fix versions in Jira will not create or set anything in Jira Align.
  • No/Yes – Jira fix versions that have a release date that falls between the start and end date of a Jira Align PI will create a corresponding release vehicle in Jira Align.  When a Jira project is selected on Jira Align release vehicles, the release vehicle will sync to Jira as a fix version on the corresponding Jira project.
  • Yes/Yes – The fix version will drive both the PI and the release vehicle.

Viewing logs

On the Manage Projects tab, select the View Logs button to view audit logs on the Jira synchronization process. The log captures changes to the data on managing projects, Jira setup, custom issue types, Jira integration, pulling Jira user data, and state mappings. You can view the Jira log report for the following items:

  • Configuration
  • Jira API
  • Issues
  • Boards
  • Sprints
  • Release Vehicles

You can also view the log data within a selected time period, or search the logs for entries containing specific text in the entry’s details.

The logs also contain filters to further refine the items displayed. To apply a filter:

  1. Select the Apply Filters button.
  2. In the dialog box that displays, select your filtering criteria from the dropdown menu.
  3. To further refine the filter, select the plus (+) sign next to the dropdown menu to activate another field where you can add specific search strings to include in the filter.
  4. Select the Filter button to view the results in the log.

Manage custom fields

On the Manage Projects tab, select the Manage Custom Fields button, and then ensure that you select the right Jira connector at the top of the Jira Custom Setup dialog box.

Sync process steps with Jira states

You can map process steps in Jira Align to the Jira states. Depending on the state of the working item in Jira, the corresponding process step will be set in Jira Align for this item. The synchronization works only one way from Jira to Jira Align.

To sync process steps with Jira states:

  1. Under Sync Process Steps with Jira States, select a level and a process flow.
  2. Map the Jira states on the left to the corresponding Jira Align process steps on the right.
  3. Select Update Steps.

Sync Jira products and MMF

You can add custom fields in Jira and map them to the corresponding fields in Jira Align for synchronization. For example, you can create new fields for MMF and Product in Jira (under Administration Issues Custom Fields), and then map them in Jira Align. Jira Align field names should match the values in Jira.

Sync Jira team values with Jira Align teams

You can synchronize Jira teams with Jira Align teams. As there is no team field in Jira, the custom field is usually created in Jira for this purpose.

If your projects use different team custom fields for selecting teams in each project, you must map each custom field by project and associated teams.

To sync Jira team values with Jira Align teams:

  1. Under Sync Jira Team Values with Jira Align Teams, select Add New.
  2. Select the Jira project to which the Jira team that you want to synchronize belongs.
  3. Select whether the team custom field in Jira is a dropdown menu or a label.
  4. If it is a dropdown menu, type the custom field value in the corresponding box. Use the format: customfield_#####, where ##### is the team custom field ID in Jira.
  5. In the Jira Team Value box, type the name of the team in Jira that you want to synchronize. This must match exactly the board name in Jira.
  6. From the Jira Align Team dropdown menu, select the team in Jira Align with which you want to synchronize the Jira team.
  7. Select Update Teams.
  8. To add more teams, select Add New and repeat Steps 5–7.

If no projects are selected, the default values are used.

To sync Jira default team values with Jira Align teams:

  1. Under Sync Jira Team Values with Jira Align Teams, select Add New.
  2. In the Jira Team Value box, type the name of the team in Jira that you want to synchronize. This must match exactly the board name in Jira.
  3. From the Jira Align Team dropdown menu, select the team in Jira Align with which you want to synchronize the Jira team.
  4. Select Update Teams.
  5. To add more teams, select Add New and repeat Steps 2–4.

Sync acceptance criteria

For features and stories, you can synchronize a Jira custom field with acceptance criteria with Jira Align's acceptance criteria. In the box, type the Jira custom field ID that is used for acceptance criteria on company-managed projects, for example, customfield_12345.

Important: If you sync acceptance criteria between Jira and Jira Align, you'll lose Jira Align's functionality to manage multiple, individual acceptance criteria on all synced Jira Align features and stories. Acceptance criteria will be limited to one field per work item in Jira Align. If you decide not to sync acceptance criteria, you'll be able to use the individual acceptance criteria functionality on Jira Align work items, but information will not sync between the two platforms.

Set up Jira link actions

You can synchronize issue links from Jira and convert them into dependencies in Jira Align.

To set up Jira link actions:

  1. Under Set up Jira Link Actions, select Add New.
  2. Type the link ID (you can get it by taking an example from Jira and exporting it to XML; look for issuelinktype id).
  3. Type the link name (for example, Depends On; look in Jira).
  4. From the Action dropdown menu, select the action type. Story Predecessor allows dependency generation on the story link report for the default Jira issue links. Story/Task Link allows the linkage of a Jira custom issue type to a Jira Align task. We recommend this link type for custom issue links.
  5. If the link action is a story/task link, type the issue type ID used for tasks in Jira in the Issue ID text field.
  6. Select Update Link.

After the setup, the issue links from Jira appear on the story’s page in Jira Align under Story Links on the right. You can view the links from the story and to this story.

Here, you can convert the Jira issue links to Jira Align dependencies. Select the check boxes next to the stories you want to convert, and then select Mass create dependencies. The stories should belong to a feature to create a dependency.

You can also generate a report of all story links, which are not yet converted to dependencies on the story link report page.

Sync Jira Bug to Jira Align Defect Priorities

You can configure the bi-directional mapping between the Priority field on Jira bugs and Jira Align defects in this section of Manage Custom Fields.  Out-of-the-box and custom priorities from Jira will show on the left and you can setup bi-directional mapping to Jira Align by selecting a Jira Align priority on the right.  If there is a greater number of priorities in Jira than Jira Align, and there is a single Jira Align priority mapped to multiple Jira priorities, the connector will default to the priority highest on the list in the Jira Align User Interface.

 

Was this article helpful?
1 out of 2 found this helpful
Print Friendly Version of this pagePrint Get a PDF version of this webpagePDF

Join the Atlassian Community!

The Atlassian Community is a unique, highly collaborative space where customers and Atlassians come together. Ask questions and get answers, start discussions, and collaborate with thousands of other Jira Align customers. Visit the Jira Align Community Collection today.

Need to contact Jira Align Support? Please open a support request.