Jira Epics Integration - Integration Recommendations and Best Practices

Set Plan Type for Jira Epic

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 Epics, 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 check if your plan was brought in, go to Home > Plans > All Plans. Type in the name of the plan, if the plan is there, look at the Plan Type column. If it is blank, then you need to manually change this to a valid plan type via the Reorganize button on the left side of the plan name.

Add Jira Issue Types into the OnePlan "Item Type" Work Field

Within Jira, the available out of the box (OOTB) issue types are: 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.  

Numeric Fields

A numeric field in Jira that has no value will be synchronized to OnePlan with the value of zero. 

Setting Parent Plans Using Custom Fields

By default, the integration establishes parent/child relationships based on the hierarchy of issues in Jira. However, there are scenarios where the desired parent plan is not represented within Jira itself. For example, you may have an "Application" plan type managed in OnePlan that should serve as the parent for certain Jira issues related to that application.

To support these use cases, you can configure a custom field mapping that automatically assigns a parent plan in OnePlan based on a custom field value in Jira.

Setup Instructions

1. Create a custom field in Jira

• Add a single-line text field in Jira that will represent the desired parent plan name as it exists in OnePlan.

2. Configure the field mapping in OneConnect

• In OneConnect, map the OnePlan field named "Parent Plan Name" to your custom Jira field. This must be configured as a plan-level field mapping.

How It Works

Populate the custom field in Jira with a valid, exact plan name from OnePlan.
When the OnePlanUpdate strategy runs, it will reference this field:

• If the value matches a unique plan name in OnePlan, that plan will be set as the parent.
• If the field is empty or the name does not match an existing plan, no changes will be made.

Rules and Behavior

• Duplicate Plan Names: If multiple plans in OnePlan share the same name, the integration will use the first match found.
• Mismatched Plan Types: If the identified parent plan’s type does not align with the expected hierarchy, the parent will not be set. A warning will be logged.
• Updating Parent Plans: Changing the parent plan name in Jira will update the parent in OnePlan during the next sync.
• Removing Parent Plan Name: Clearing the custom field in Jira will not remove the parent in OnePlan. The existing parent will remain unchanged.
• Non-Existent Plan Names: If the value entered does not match any plan in OnePlan, no changes will occur.
• Exact Match Required: The plan name must exactly match an existing plan name in OnePlan case-sensitive and whitespace included.

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.