Jira Space Integration - Integration Recommendations and Best Practices

In OnePlan, the default Plan Types include: Portfolio, Program, Project, Epic, Objective, Idea, and Key Result. If the Work Item Type differs from these specified values, the plan will be imported but not accurately. Consequently, it might be perceived as 'missing' from the My Portfolio page.

To assign a Plan Type for Jira Spaces, type in the desired OnePlan Plan Type into the OnePlan Default Plan Type field located within the OnePlan connector.

My Plan is Missing from My Portfolio

To verify the import status of your plan, navigate to Home > Plans > All Plans. Search for the plan by its name. If the plan appears, check the 'Plan Type' column. If it's empty, you'll need to manually assign a valid plan type. To do this, use the Reorganize button located within the hamburger menu on the left side of the plan name.

Add Jira Issue Types into OnePlans Item Type Work Field

Within Jira, the available out of the box (OOTB) issue types are: Epic, Task, Bug, Story, Sub-task. Some of these options are not listed within the OnePlan Item Type choice field and will have to be added for the integration to become bi-directional.

1. Within OnePlan, navigate to the Configuration page by clicking on the Gear Icon toward the top right of the page.
2. On the left navigation panel, select Fields.
3. Expand Work Fields section.
4. Locate Item Type field, click on the Paper & Pencil Icon on the right of the name. This will open the Edit Field window.
5. Click on Click here to edit choices button. This will populate the existing options listed.
6. Click Bulk Add Choices.
7. Enter all relevant Jira issue types that will be brought into the OnePlan Backlog.
8. Once all values have been entered, click OK. This will add the values to the list.
9. Click Save. This will close the options list.
10. Click Save. This will save and close the Edit Field window.

Value Mapping Recommended for Choice Fields

When syncing a choice field between Jira and OnePlan, it's common for the options within these fields to differ. If these values don't align, it can lead to errors or incomplete data. To avoid such issues, we advise using value mapping to ensure the choice field options are transformed to align with the program receiving the data.

Connecting Multiple Jira Integrations to OnePlan

Each integration is linked to a single Jira environment. 

Authentication Keys & API Tokens

It is highly recommended to allocate a distinct OnePlan Authentication Key for each integration. This practice enhances security and ensures clear identification for each integration. 

Unique Naming Convention

To facilitate synchronization and differentiation among the Jira environments, assign a unique name to each integration. This name serves as a distinguisher when exporting data from OnePlan. To set the Unique Name:

• Access Additional Options within OneConnect Integration section.
• Locate and complete the Button Name field, specifying the name that signifies the Jira organization being synched to.
• Click Save.

Complete the next steps only if Jira is already connected/installed into your OnePlan group.

• Access Reinstall within OneConnect Advanced section of the integration.
• Click Start. 

1. Navigate to the OnePlan Configuration page.
2. On the left navigation panel, click Plan Details.
3. In the Plan Type dropdown, select the plan type you wish to add the Jira Project Type field to.
4. Locate the Jira Project Type field on the top left box and drag the field to the desired location.
5. Click Save.

Using the OnePlan Jira Marketplace App with Multiple Jira Integrations

If you have multiple Jira integrations configured in OneConnect, it is important to understand how the OnePlan app installed from the Atlassian Marketplace determines which integration to use.

The Jira Marketplace app can only operate against one Jira integration at a time. That selected integration determines:

• Which Jira connection is used

• Which OnePlan Group is displayed in the app iFrames

How the App Determines the Active Integration

Within each Jira integration configuration:

1. Open the Jira connector.

2. Expand Advanced Options.

3. Locate the checkbox labeled:
   Use this integration in the Jira Marketplace app

This setting controls which integration the app should prioritize.

Only one Active integration should have the checkbox enabled.

Multiple checked integrations can lead to unexpected behavior depending on which integration is evaluated first.

If the app displays the wrong OnePlan Group or data, verify:

• Which integration is checked

• Which integrations are Active

Integration Selection Logic

The app determines which integration to use based on the following logic:

1. If exactly one active integration has the checkbox selected

   • That integration will be used.

2. If no integrations have the checkbox selected

   • The app will use the first Active integration it finds.

3. If more than one integration has the checkbox selected

   • The app will use the first Active integration among those that are checked.

4. If all integrations with the checkbox selected are Inactive

   • The app will fall back to the first Active integration it finds.