10X: Jira Integration Setup

Ensure you have completed all steps in 10X: Jira Integration Prerequisites and 10X: 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.

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 the buffer date range set under Administration > Connectors > Jira Settings > Jira Setup > Sprint Buffer Days (generally 3-5 days). All future sprints on the Jira board are then matched in board order to the next in line Jira Align Sync Sprint.

Generation of Sync Sprints when the PI is created is required unless the Create Sprints in Jira Align 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 go to Administration > Connectors > Jira Management > Jira Sprints to remap the true sprint to the next Sync Sprint.

Recommended practices for Jira teams

  • Do not create or use “bucket” sprints for backlog grooming. Instead, use the Project backlog for grooming 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 10X: Jira Integration Data Collection.

 Once these steps have been completed, you can configure settings in the Administration > Jira Settings and Jira Management sections.

Establish connection

  1. Select Administration from the left menu bar, and then click Jira Settings under Connectors.
  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.   Click Jira Connectors (top-right of the page), and then select the necessary Jira connector from the corresponding dropdown menu.
    b.   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 user is selected in this field, only they will be able to manage them.
    c.    In the corresponding boxes, type the URL to connect to Jira and URL that the connector uses to make API calls to Jira.
    d.     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).
    e.     Click Add to add more Jira instances, as needed.
    f.      Close the dialog box.
    g.     Select the necessary Jira connector from the Connector dropdown menu (top-right of the page).

Map projects to programs

  1. To add Jira projects, click Add Project on the Manage Projects tab, and then complete the fields in the table. Use the information you collected in 10X: Jira Integration Data Collection.
    • Project Key. Type the Jira Project Key.
    • Project Name. Type the Jira Project Name. Note, if the Jira Project name changes, the name displayed in Jira Align will automatically change.
    • Program. Select to which Program in Jira Align your Jira project will map.
  2. Click 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. Click 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 10X: Jira Integration Data Collection:

  1. Click 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. Click Add and type the board ID and team name in the corresponding boxes.
  4. From the dropdown menu, select the program.
  5. The Project 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 Project 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 enable  "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 the toggle for "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. Click Save.

Configure timers, issues, and fields

  1. Click 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. Click Save.
  3. Open the Jira Integration tab, and then click 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, click Add and map Issue Types 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 Administration > Platform > Dropdowns section.
  5. Click Save.
  6. Next-gen projects contain issue types that are project-specific. To set up fields for next-gen projects, see the Set up next-gen projects section.

Pull Jira user data

Open the Pull Jira User Data tab, and then select whether you want to update the Jira Align user’s name, email, and external ID based on the changes to the Jira user’s data:

  • None. Select to not make any changes to the Jira Align user’s name, email, and external ID.
  • Username. Select to find a matching Jira user for the existing Jira Align user and update the Jira Align user's name, email, and external ID if there are changes. Click the User data pull button to run the synchronization. Jira Align user’s external ID is set to the Jira user’s user name. In case you create a user in Jira Align ahead of the Jira integration or before a user has work in Jira, the connector uses email to determine if a user from Jira already exists in Jira Align.

Map statuses to states

  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.     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 Software 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 Software.
    There is also a delete item state in the Jira connector. When this state is configured, it hard deletes the item in Jira Align.
  2. Set up state or process step mappings from Jira Align to Jira on the Manage Projects tab:
    a.     Click the State Mapping option next to a Jira project.
    b.     Select if you’d like to map Jira Align States or Process Steps using the options at the top of the modal.
    c.     Use the dropdown menu to select a work item type (epic, feature, story, task or defect).
    d.     Map each Jira Align state or process step to a Jira status.
    e.     Click Update.
    f.      Repeat this process for each classic project. You can also push state mappings to all classic projects using this option.
    Note: Next-gen projects contain unique statuses which must be mapped to states individually (see the Set up next-gen projects section).
  3. Click Save.

Set up next-gen projects

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

  1. Open the Manage Projects tab.
  2. In the Project Key column, click the project key of the next-gen project to view its details.
  3. In the slide-out that displays, open the Next-gen settings tab.
    Note: This tab only displays on the slide-out when a project is a next-gen project.
  4. Fill in the text fields on the tab:
    • Story Points. The key for the Jira field used for storing the Story Points. Use the following format: customfield_10001.
    • Parent Feature Name. The key for the Jira field used for a parent epic or capability assignment on Jira Align features. Use the following format: customfield_10001. It is synced only one way from Jira Align to Jira.
    • Program Increment (Read-only text field). The key for the Jira text field used for a Program Increment. Use the following format: customfield_10001. It is synced only one way from Jira Align to Jira for features.
    • Acceptance Criteria (Text Field [multi-line]). the Jira custom field ID that is used for acceptance criteria. Use the following format: customfield_10001. After the acceptance criteria are synchronized with a Jira custom field, no more acceptance criteria fields can be added in Jira Align. You can add all acceptance criteria in one field in Jira Align.
  5. 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. Then, map each status to a Jira Align step or process step in the State Mapping table.
  6. Click Save & Close to save your changes.

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 10X: 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.     Click 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, click View Logs.
    b.    View the issues, correct, and resynchronize if needed.
  2. Check the following areas to confirm that the integration worked as expected:
    • Under Portfolio > Track, view the Work In Process and Program Increment Progress reports.
    • View several sprints in the Team Room.

Authentication types

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

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 click 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.

API token authentication

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 click 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

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. Click Save.
  4. Click Generate OAuth Public Key.
  5. Sign in to Jira as an administrator, and then go to Administration > Applications > Integrations > Application links.
  6. Type the URL to the Jira Align application, and then click Create new link.
    1_Configure_Application_Link.png
  7. Select the Use this URL check box, and then click 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 click Continue. The link is created, and now you need to configure it.
    3_Link_applications.png
  9. Click the pencil icon next to the link you created, and then click 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. Click Save.
  14. Go back to Jira Align, and then click Authorize Jira OAuth access. Wait for the Jira connector to run. It runs even if deactivated.
  15. Click Request Jira for access.
    Note: If you need to restart the process of authorizing a new token (to reset something), click Restart Jira OAuth access.
  16. Click Allow, and then close the page that appears.
    Note: When you need to authorize a new token (if a token expires), click Re-Authorize Jira OAuth access.
  17. Click 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.

Jira setup fields

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

Timer on Jira Boards

  • Timer on Jira Boards. Type the number in minutes for how often the Jira boards synchronize with Jira Align. The default value is 60 minutes.
  • Sprint 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.

Timer on Jira Issues

  • Timer on Jira Issues. Type the number in minutes for how often the Jira issues synchronize with Jira Align. 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.

Timer on continuous push to Jira

  • Timer on continuous 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. 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.
  • Email address list to use for alerts. 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 10X: Jira Integration Data Collection.

  • Issue Type Epic. The numeric ID and name for the issue type that is used as an Epic in Jira classic projects.
    Note: Next-gen projects contain unique issue type IDs that must be mapped individually (see the Set up next-gen projects section).
  • Issue Type Story. The numeric ID and name for the issue type that is used as a Story in Jira classic projects.
    Note: Next-gen projects contain unique issue type IDs that must be mapped individually (see the Set up next-gen projects section).
  • Issue Type Sub-Task. The numeric ID and name for the issue type that is used as a Sub-Task (or Task) in Jira classic projects.
  • Issue Type Defect. The numeric ID and name for the issue type that is used as a Bug in Jira classic 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.
    • Next-gen projects contain unique issue type IDs that must be mapped individually (see the Set up next-gen projects section)

Custom Fields

Some fields you have already identified in the Jira custom field IDs and type names section under 10X: Jira Integration Data Collection.

  • Epic Name. The key for the Jira field used for storing the Epic Name. Use the following format: customfield_10001.
  • Story to Epic Link. The key for the Jira field used for storing the Epic Link or
    Epic ID Link when you assign a story to an epic. Use the following format: customfield_10001.
  • Story Points. The key for the Jira field used for storing the Story Points. Use the following format: customfield_10001.
  • Sprint. The key for the Jira field used for storing the Sprint ID. Use the following format: customfield_10001.
  • Accepted Date. The field name of the value/flag set when you accept/resolve the issue. This one is usually called ResolutionDate in Jira.
  • Organization. Optional: The key for the Jira field used for a Team. Use the following format: customfield_123.
  • Rank. Numeric ID value from Jira for a Rank in the backlog.
  • 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.
  • MMF. Optional: The key for the Jira field used for an MMF. Use the following format: customfield_123. You also need to set it up in Jira Align under Manage Custom Fields > Sync Jira MMF.
  • Issue Priority Default. When you create a story in Jira Align, it will create a story issue type in Jira. This is a default priority that the connector will set the issue type in Jira to.
  • Feature Product. Optional: The key for the Jira field used for Product. It shows what product the feature maps to. Use the following format: customfield_123. You also need to set it up in Jira Align under Manage Custom Fields > Sync Jira ProductsNOTE: 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 in Manage Custom Fields > Sync Jira Products.
  • History Resolution Label. The label name in the change log in Jira used when you set an issue to Resolved.
  • Why? Details. Data from Jira Align's Why panel that shows progress of related items and context within overall strategy. Use the following format: customfield_123. Read-only in Jira Software. One-way sync from Jira Align. 
  • Default User. If, for some reason, the connector cannot find the matching user, it will use this user as a default one.
  • Parent Name. The key for the Jira field used for a parent item assignment on Jira Align features. Use the following format: customfield_123. It is synced only one way from Jira Align to Jira.
  • PI. The key for the Jira field used for a Program Increment. Use the following format: customfield_123. It is synced only one way from Jira Align to Jira for Features.
  • T-Shirt. The key for the Jira field used for the feature’s T-shirt sizing. Use the following format: customfield_123.
  • Business Owner. Optional: The key for the Jira field used for the Business Owner team role. Use the following format: customfield_123.
  • Work Code (Features only). The key for the Jira field used for a Work Code which applies to features only.

Settings

  • Permission to Edit Epic Name. Select Yes to allow changing the epic name in Jira when syncing from Jira Align.
  • Enable Rank Sync. Select Yes 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.
  • Enable Feature Sync. Select Yes to allow syncing from Jira Align to Jira for all features.
  • Enable Story Sync. Select Yes to allow syncing from Jira Align to Jira for all stories.
  • Enable Defect Sync. Select Yes to allow syncing from Jira Align to Jira for all defects.
  • Enable Task Sync. Select Yes to allow syncing from Jira Align to Jira for all Jira Align Tasks to Jira Sub-Tasks.
  • Enable Story State Sync. Select Yes to allow syncing the state of Jira Align story to the issue in Jira.
  • Enable Feature State Sync. Select Yes to allow syncing the state of Jira Align features to the corresponding epics in Jira.
  • Enable Defect State Sync. Select Yes 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.
  • Story Creation Requires Team. 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.
  • Epic Creation Requires Team. 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.
  • Issue Creation Allows Reporter & Assignee. 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.  
  • Team Uses Both Parent & Child. Select Yes if the Custom Team field in Jira is of Type Cascading and No if the Custom Team Field in Jira is of type Single or Multi-Select.  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.
  • Team Multiple Drop-Down Menu. 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 Data. 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.
  • Enable Feature Point Sync. Select Yes to allow syncing the feature points from Jira Align to epics in Jira.
  • 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.
  • Allow Features to have multiple Jira projects. Select Yes to allow selecting multiple Jira projects for the same program when you create or edit the feature in Jira Align.
  • Allow Jira to add users to team if they belong to an issue. 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.
  • Create Sprints in Jira Align 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.
  • Synchronize 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].
  • Allow bidirectional syncing of points for Features. Select Yes to allow points estimation for features to be updated both from Jira and Jira Align.
  • Allow Feature, Story, and Defect Program Increments to be automatically updated by Jira 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. Note, when set to No, the program increment will be automatically updated by Jira Fix Version Dates when the item is created in Jira Align. After the item is created, the Jira Fix Version Dates will not update the program increment.
  • Allow Release Vehicles to sync with Jira Fix Versions. Select Yes 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.
  • Allow Jira Align to create Jira issue web links. Select Yes to create Jira issue web links that link back to the Jira Align features, stories, tasks, and defects.
  • Initial Data Load Start Date. 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 10X: Jira Integration Data Collection.  
  • Rich Text Format. Select HTML to maintain rich text content in Jira and Jira Align for the description and acceptance criteria of stories and features. If you use the Atlassian built-in wiki syntax editing, select Jira rendered field to pull the rich description from Jira into Jira Align. This is a one-way pull only. To view the pulled details, click the eye icon next to the story or feature description. The data is read-only. If set to None, the text is synchronized as plain text.
  • 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 – 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/No – The Fix Version will only drive/impact the PI as expected.
  • Yes/Yes – The Fix Version will drive both the PI and the Release Vehicle.

Viewing logs

On the Manage Projects tab, click 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 filter the Jira log report by the following items:

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

You can also filter the Configuration data by date.

Manage custom fields

On the Manage Projects tab, click 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 value stream.
  2. Map the Jira states on the left to the corresponding Jira Align process steps on the right.
  3. Click 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, click 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 following 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. Click Update Teams.
  8. To add more teams, click 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, click 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. Click Update Teams.
  5. To add more teams, click 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 classic projects, for example, customfield_12345. After the acceptance criteria are synchronized with Jira custom field, no more acceptance criteria fields can be added in Jira Align. You can add all acceptance criteria in one field in Jira Align.

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, click 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 Story Predecessor action type.
  5. Click 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 click 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, under Program > Dependencies > More Actions > Story Link Report.

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?
0 out of 0 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.