Use Case Description and Assumptions

These are the primary characteristics of the Research and Development use case for the Clarizen-Jira integration:

• A project is initiated in Clarizen and injected into Jira by a PMO role in the form of a Solution / Portfolio entity
• Jira epics (from multiple Delivery Projects) are linked to the Solution / Portfolio entity via Custom Links
• A detailed project plan (epics, stories, sub-tasks, etc.) and the entire project management is done by an engineering team in Jira
• The epics and stories are injected back into Clarizen (as Milestones and Tasks respectively) under the original Project
• The effort and status updates are synchronized back into Clarizen so that the PMO is provided with a clear view of the entire project

Additional assumptions:

• An issue in Jira may be moved from one epic to another epic or from one Delivery Project to another Delivery Project
• An issue type in Jira may be changed from epic to story or vice versa
• Issues in Jira may be deleted

What's New

Our integration with Jira has been enhanced with new features and improved robustness to better support the assumptions mentioned above.

Note: It's important to re-apply best practices when implementing the enhancements described below.

Jump to

• Use Custom Links to Connect Jira Issues and Associate with Parent Items in Clarizen
• Moving an Issue between Epics in Jira Automatically Moves the Work Item between Corresponding Milestones in Clarizen
• Moving an Issue between Projects in Jira Automatically Updates Jira ID in the Clarizen Work Item
• Changing the Issue Type from Epic to Story or from Story to Epic in Jira Updates Work Items in Clarizen Accordingly
• Link Multiple Related Jira Issues Using JQL
• Specify Event’s Condition Using JQL
• Identify and Act on Deleted Jira issues in Clarizen

Use Custom Links to Connect Jira Issues and Associate with Parent Items in Clarizen

Typically, issues in Jira are linked using Epic links or parent links. Sometimes Jira issues are linked using custom links, for example, a portfolio link, which can come as part of Jira plug-ins and/or customizations. With the new enhancements, it is possible to:

• Map the association field in Jira to a field in Clarizen using the corresponding Jira key
• Automatically locate a parent Work Item in Clarizen that corresponds to the association field of a Jira item, and push/create the Jira item under the Work Item in Clarizen

Example

A Jira Issue with the key KBA-1234 is associated to another JIRA issue using the “portfolio link” field. The portfolio link field in Jira for Issue KBA-1234 has the value of DBA-982.
In Clarizen, there is a Project object, which has a Jira Key field set to DBA-982. When issue KBA-1234 is pushed to Clarizen, the system queries a Project with the Jira key value of DBA-982, and associates the newly created Work Item for KBA-1234 to it.

Moving an Issue between Epics in Jira Automatically Moves the Work Item between Corresponding Milestones in Clarizen

When an Issue in Jira is moved to another Epic, iHub will capture the change in the epic link and identify the ID of the new milestone in Clarizen. Then it will utilize the “move” action to safely move the Work Item in Clarizen to the new Milestone.

Example

An Issue in Jira has a key KBA-1234, and an Epic link field UI-8772, which is an Epic in Jira.

A Milestone in Clarizen M-9887 has the JIRA key value set to UI-8772, and under this Milestone a Task T-1234 has a Jira key value of KBA-1234. Another Milestone in Clarizen M-9888 has the Jira key UI-8775.

The Jira team decides to move KBA-1234 to Epic UI-8775, and as a result the Epic link field of KBA-1234 changes to UI-8775.

The system detects this change and moves T-1234 under M-9888 in Clarizen using the “move” action. The 'move' action ensures the Work Item object is moved in its entirety. 

Moving an Issue between Projects in Jira Automatically Updates Jira ID in the Clarizen Work Item

When an Issue in Jira is moved to another project, its ID in Jira changes. Until now, the updated Jira Issue ID in Clarizen could have broken the integration. Now, the updated Jira Issue ID gets updated both in Clarizen One and in the sync registry.

Changing the Issue Type from Epic to Story or from Story to Epic in Jira Updates Work Items in Clarizen Accordingly

When an Issue in Jira changes type, the corresponding mapping between Jira and Clarizen requires updating. This is now supported using a new Conditional Mapping Change section that lets you choose how to handle changes.
It is possible to create several conditional mapping blocks by clicking Add Conditional Mapping.

Each block allows selecting a target mapping and setting a condition under which this mapping should be applied.
In addition, you can specify what to do with the currently linked item in Clarizen. The options are:

• Unlink existing item and create new item (default) – will keep the existing item in Clarizen and create a new one (with the corresponding type) to be linked to the Jira item, whose type has been changed
• Delete current item and create a new one – will delete the existing item in Clarizen and create a new one (with the corresponding type) to be linked to the Jira item, whose type has been changed
• Keep current item, but apply the new mapping – will preserve the link to the existing item and will try to apply the new mapping on it

Link Multiple Related Jira Issues Using JQL

Until now, you could only link related Jira Issues under the same Project. But in reality, Jira Issues from different projects can be grouped together (by release, Epic name, etc.) using a JQL expression. Now you can use a JQL expression to configure a group of related items for a given mapping.

Example:

issueFunction in issueFieldMatch(\'issuetype=epic and \"Clarizen ID\" is empty\', \"Portfolio Project\", \" - P-\") and \"agile team\" is not empty

This is how it works:

1. Under the Map Related Jira Objects section, click Add Relation via JQL.
   
2. Inside the new Relation Mapping via JQL block, specify a JQL expression to bind related Jira Issues.
   You can use the $CurrentObjectKey variable to reference the current Jira object.
   Note: We recommend preparing and validating a JQL expression in Jira before saving it in iHub.
3. In the Entity mapping field, specify the relevant mapping to be used for the related Jira Issues.
4. Select the Set current object as a parent option to automatically link the current object as a parent to the related Jira issues.

Specify Event’s Condition Using JQL

Until now, you could only specify an event’s condition using the existing condition builder.

Now it is possible to specify an event’s condition using a JQL expression directly in iHub, without the need to modify the webhook in Jira.
To specify the event’s condition in JQL:
1. Enable the Use Custom JQL option in the condition’s definition section:

2. The JQL expression will be automatically populated with the corresponding expression, which represents the current condition in the condition builder.

3. Update/change the JQL expression according to your needs and click update to save it.
Notes:

• You can reference the current object in your JQL expression by using the $CurrentObjectKey variable
• We recommend preparing and validating a JQL expression in Jira before saving it in iHub

Detecting a Mismatch in Conditions between iHub and Jira
Although Clarizen does not recommend modifying webhooks created by iHub in Jira, there can be a situation, when a webhook’s definitions in Jira (JQL expression, event state, triggering state) may not match the event’s definitions in iHub.
In such a case, iHub will display an alert to inform you about any mismatches upon opening an event for editing:

If no action is taken to resolve the mismatches, clicking Update will override the webhook’s settings in Jira to match the ones defined in iHub.

Identify and Act on Deleted Jira issues in Clarizen

Until now, deleted Issues in Jira could not be reflected in, or handled by Clarizen.

Now, deleted Issues can be detected and displayed in Clarizen with a DELETED Sync Status.

To enable reflecting Jira issues' deletions in Clarizen, go to the corresponding event’s definition in iHub and scroll to the Select Triggering Object section and select the Delete Webhook Enabled checkbox:

This new detection and status provide more robustness, as you can add logic to workflows that first of all don't break the workflows, and allow adding handling options for deleted items.