Jira Epic/Parent Link FAQ

What's changing?

Atlassian is standardizing how they associate parent and child issues across Jira for company-managed and team-managed projects. This results in deprecation of the Epic Link and Parent Link (String) custom fields in REST APIs and webhooks, as well as in some other related changes.

In some cases, the updated Jira connector will automatically handle this change for users, however there are some particular circumstances that may require manual intervention.  

Who is impacted by this change?

This change will only impact Jira Cloud customers. This will not affect customers on Jira Data Center or Server Products. See details here.

When will this change take place?

The planned change will begin rolling out to customers on November 30th. More details can be found here.

What do I need to do?

If you are using Planview Hub on-prem, you will need to upgrade to the latest version. Any extensions referencing the Epic Link or Parent Link (String) fields will need to be updated (see below). Any field mappings for the Parent Link (String) field will need to be updated (see below). Note that the new parent field should already exist in Jira Cloud.

What changes will be automatically updated?

All existing relationship mappings using the Epic Link field and all existing artifact unions based on the Epic Link field will automatically be updated to use the new Parent field.

How do I upgrade?

1. Download/Install the updated version of Hub.
   • Updated versions include:
     • 23.1.0.20221121-b4213
     • 22.4.7
     • 22.3.20
     • 22.2.27
     • 22.1.39
     • 21.4.42
2. Start the Planview Tasktop Hub application.
3. Check for any existing “Parent Link (String)” mapping.
   • Open each collection involving Jira Cloud.
   • Find any fields in your collection(s) that reference the Parent Link (String)
   • If the Parent Link field is present, contact customer care for assistance.
     • Note that the Parent Link field is not the same as the Parent field.

How will my extensions be impacted if using the Epic Link field?

Some extensions may be impacted if they reference the Epic Link or Parent Link fields. In those instances, extensions will need to be updated so they do not use the deprecated fields. If a reference is missed, it will not cause an error, but it will return null/undefined value, which may result in unexpected behavior.

Assuming that the ID for the Epic Link field was customfield_12345, here are some examples of the changes that will need to be made.  

Example: Changing Epic Link field to “Parent Field” on source or target artifacts

Original Code

context.sourceArtifact['customfield_12345'] 
context.targetRepositoryArtifact['customfield_12345'] 

Updated Code

context.sourceArtifact['parent'] 
context.targetRepositoryArtifact['parent'] 

Example: Changing any references to Epic Link on a retrieved artifact 
 
Original Code 

var artifact = artifacts.retrieveArtifact(relationship);
artifact['customfield_12345']

Updated Code

var artifact = artifacts.retrieveArtifact(relationship);
artifact['parent']

Additionally, any extensions that use the Epic Link field's label will need to be updated.

Example: Changing references to the Epic Link field's label to use the Parent field's label 

Original Code 

if (context.targetField.label === "Epic Link")...

Updated Code

if (context.targetField.label === "Parent")...

Will the release be enabled for anyone to download?

This release will follow the standard process and will be back ported to all supported main versions. If you already have access to a supported main version, you will have access. If you do not have access to a supported main version, you will need to request access.

Will existing integrations still work prior to the Jira Cloud upgrade?

Yes, existing integrations will work. 

What if I am mapping the Parent Link (string) field or have mappings or configurations involving the Epic Link field not covered by the above sections?

Please contact customer care for assistance.

How will my artifact union(s) be impacted if using the Epic Link field?

After upgrading, all artifact unions based on the Epic Link field will be automatically updated to use the new Parent field. However, due to an ongoing issue, you will notice the following behavior:

• Once you've upgraded, you'll notice that artifact unions based on the Epic Link field will still appear to include the Epic Link in the Planview Hub UI. Once Atlassian removes the Epic Link field, this will cause an error to appear on the Artifact Union screen. Although the Hub UI will still appear to include the Epic Link, the configuration will actually include the Parent field. Any existing integrations will continue to synchronize artifact successfully. However, if you'd like to change the configuration of your artifact union, you will need to manually update the Relationship field to use the Parent field.

What's changing?

Atlassian is standardizing how they associate parent and child issues across Jira for company-managed and team-managed projects. This results in the deprecation of the Epic Link and Parent Link (String) custom fields in REST APIs and webhooks, as well as in some other related changes.

Who is impacted by this change?

This change will only impact Jira Cloud customers. This will not affect customers on Jira Data Center or Server Products. See details here.

When will this change take place?

The planned change will begin rolling out to customers on November 30th. More details can be found here.

What do I need to do?

You will need to upgrade to the latest version. Any attribute mappings for the Epic Link or Parent Link (String) field will need to be updated (see below). Any custom scripts referencing the Epic Link or Parent Link (String) fields will need to be updated (see below). Note that the new parent field should already exist in Jira Cloud.

How do I upgrade?

1. Download/Install the updated version of Sync.
   • Updated versions include:
     • 4.32.7
     • 4.31.20
     • 4.30.27
     • 4.29.39
     • 4.28.42
2. Open Sync.
3. Update any existing Parent Link (String) references.
   • Open each Task Mapping involving Jira Cloud.
   • Find any Attribute Mappings using the Epic Link field and update them to use the Parent field.
   • If there any Attribute Mappings using the Parent Link (String) field, customer care.
     • Note that the Parent Link field is not the same as the Parent field.

How will custom scripts be impacted?

Some custom scripts may be impacted if they are referencing the affected fields. In those instances, custom scripts will need to be updated so they do not use the deprecated fields. If a reference is missed, it will not cause an error, but it will return null/undefined value, which could cause unexpected behavior.  

Assuming that the ID for the Epic Link field was customfield_12345, here are some examples of the changes that will need to be made.

Example: Changing Epic Link field to “Parent Field” on source artifact 

Original Code 

def sourceParent = sourceAttribute.parent.attributes['customfield_12345'].value;

Updated Code

def sourceParent = sourceAttribute.parent.attributes['parent'].value; 

Example: Changing Epic Link field to “Parent Field” on target artifact 

Original Code

def targetParent = targetTask.root.attributes['customfield_12345'].value;

Updated Code

def targetParent = targetTask.root.attributes['parent'].value;

Do I need to update my existing task mappings?

Yes. For all task mappings involving Jira Cloud, all attribute mappings using the Epic Link field will need to be updated to use the Parent field. All custom scripts referencing the Epic Link field will need to be updated to reference the Parent field. If you have any attribute mappings or custom scripts using the Parent Link (String) field, contact customer care.

Will existing integrations still work prior to the Jira cloud upgrade?

Yes, existing integrations will work.