16.4 JIRA Integration V2

This page describes the JIRA integration and includes the following sections:

OVERVIEW

JIRA is a flexible software development tool, developed by Atlassian and used primarily by software and services teams for managing product lifecycles and support-related issues.  

The Clarizen integration with JIRA has been developed to support a variety of use cases to allow Clarizen customers configure the integration between the two systems in a way that better fits their business needs.

One of the main use cases is to support the ability to manage cross-functional projects, where the detailed R&D part of the project is managed by developers in JIRA, and the effort and status updates are synchronized back into Clarizen. Project managers, executives or any other stakeholders are provided with a clear view of the entire product launch, regardless of whether part of it follows Agile methodologies (the R&D part), or the traditional ‘waterfall’ practices. 

INTEGRATION AND SYNCHRONIZATION PROCESS

Clarizen is integrating with JIRA using Clarizen’s iHub integration platform which established a connection with JIRA by calling JIRA's API.

During the initial one-time setup process, the iHub performs a handshake between the two systems in a secure manner.

After the integration is established, the synchronization process can be triggered from both JIRA or Clarizen based on configured triggering events, or scheduled to run on a daily basis.

Triggered synchronization

  • When synchronization process is triggered from JIRA, for example, when a new issue is created in JIRA, JIRA uses JIRA’s REST API webhooks to call back to Clarizen’s iHub.
  • When synchronization process is triggered from Clarizen, for example, when issue details are updated in Clarizen, Clarizen web service connects to the iHub which then sends a call to JIRA API.

Scheduled synchronization

Clarizen supports daily synchronization process using iHub in 2 separate cycles (JIRA to Clarizen and Clarizen to JIRA). Once initiated, the scheduled process iterates on all records that are mapped in the iHub sync registry (e.g. Clarizen task to JIRA Issue) and executes over both systems API’s.

In each scenario, an active connection or network route must be opened, enabling iHub to access the JIRA server internal API from an external network.

INTEGRATION WITH MULTIPLE INSTANCES OF JIRA

If your organization employs multiple JIRA instances, for example, have a separate instance of JIRA for each customer, you can now integrate each JIRA instance with your Clarizen account leveraging Clarizen's integration iHub.

Clarizen supports integration between a single Clarizen account and multiple instances (up-to ten) of JIRA. The integration supports both on-demand and on-premise versions of JIRA and all previously supported use cases.

Each JIRA integration has its’ own set of mappings and events, that can be configured independently. You can switch between integrations using the drop-down list of JIRA organization names at the top of the iHub screen.

You must have administrative privileges for both JIRA and Clarizen to enable and configure each integration.

SYSTEM REQUIREMENTS

Clarizen supports integration with the cloud and on-premise JIRA (and JIRA Agile) version 6.1 or later.

BEFORE YOU BEGIN

Consider the following before starting the integration:

  • This integration obsoletes the previously released application for JIRA integration. If the application has been installed in your environment, you must uninstall it (in Settings > Applications) before configuring the integration.
  • Below instructions assume that you have a working instance of JIRA.
  • A basic understanding of JIRA is required. You can review the self-paced training material provided by Atlassian.
  • When integrating with an on-premise installation of JIRA, ensure that JIRA’s TCP listening port is open. JIRA’s default port number is 8080.
  • You must have administrative privileges for both JIRA and Clarizen to configure the integration.

Back to top

BASIC SETUP

To configure a basic integration of Clarizen with JIRA, follow these steps:

  1. Configure Authentication of Clarizen in JIRA
  2. Configure Authentication of JIRA in Clarizen
  3. Enable Mappings and Events
  4. Configure Synchronization Options

1) CONFIGURE AUTHENTICATION OF CLARIZEN IN JIRA

  1. Log in to JIRA as a system administrator.
  2. Click the Gear icon in the top-right corner.
  3. Select Applications.
  4. Click the Application Links in the left menu.

    JIRA_int_image_4.PNG

  5. In Configure Application Links enter in the Application text box: http://www.clarizen.com
    JIRA_int_image_5.PNG


  6. Click the Create New Link button.
    In the Configure Application Link prompt window, click Continue.
    If setting up the JIRA On-Demand version, select the Use this URL checkbox to prevent further validation messages.

    JIRA_int_image_6.PNG

  7. In the Link Applications screen, enter the following values and click Continue:
    • Application Name: Clarizen
    • Application Type: Generic Application

      JIRA_int_image_7.PNG

      A message appears confirming that the application link was created successfully.
  8. Click Edit to edit the new application link.

    JIRA_int_image_8.PNG

  9. In the Configure Clarizen screen, click the Incoming Authentication link and enter the following values (use the scrollbar on the left to view all the fields):
    • Consumer Key: 940E44CF4FCF4E988D96AAF2B75AD93D
    • Consumer Name: Clarizen

  10. Public Key: 

    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzru98MCpINB0/7Zt9s3YCTDQvRIxJRmthHMMWuUCwxRDPn055uUyL/+Qj9Ta8trwdq6DXpLybgjEHrttQvt2v25fxfbmzknR/ik9DspEg2lEgei3i1HstAb70wUhrkKmUVd8xTi9osiS/O10UWzoBNezPhX4Q8Umq/inAXGfqR1Z3DtRCHBrLYghuh8dS9q7nJdTsnzR3SAYTJ30L1jjFN4YMOYR/DPe2VD5ldjRgaN/pOX10tyeRo4Dj4xHezbGSD0qtYC7mJ0xNrO42IoJEyjo5ePXmFJqkS9vE9srxFrZ3AvOHW1xggFnVXADnUNkawAHAZBp6n2Iz65Jg/XM7QIDAQAB
    JIRA_int_image_10.PNG

  11. Click Save and Close to close the dialog box. Authentication has been configured in JIRA for Clarizen.

 

2) CONFIGURE AUTHENTICATION OF JIRA IN CLARIZEN

  1. Log into Clarizen as the system administrator.
  2. Click your name in the top-right corner and select the Settings option.
  3. Click the Extensions tab.
  4. In the Connected Web Apps section, click the Allow Access link for JIRA Integration.
    Note: Allow Access changes to Revoke Access which indicates that the integration status is enabled.

    JIRA_int_image_11.PNG
     
  5. In the Settings column click Open.
  6. In the Authentication tab enter the fully qualified domain name for your JIRA instance. The domain name is different depending on whether you use a cloud or on-premise version of JIRA.
    • If you are authenticating with a cloud-based JIRA, the domain name will look like:
      https://<org_name>.atlassian.net
      Where: <org_name> is the name of your instance of JIRA.
    • If you are authenticating with an on-premise JIRA installation, the domain name will look like:
      https://<domain_name>:<port_number>
      Where:
      <domain_name> is the domain name used by your JIRA integration.
      <port_number> is the port number for your JIRA installation (default is 8080).
  7. Click Login.
  8. In the Welcome to JIRA screen, click Allow to give Clarizen read and write permissions to your JIRA data.

    JIRA_int_image_12.PNG

  9. Click the Add Clarizen credentials button.

    JIRA_int_image_14.PNG
     
  10. In the Authorized access screen, click Grant Access.

    JIRA_int_image_15.PNG
     
  11. Once the authentication has been successfully completed, the following screen will appear listing details for your Clarizen and JIRA applications.


JIRA_int_image_16.PNG

 

As part of the integration configuration, you must map objects and events in Clarizen with objects and events in JIRA.

Clarizen provides a pre-defined set of mappings (best practices) which are installed by default.

The best practice package contains Clarizen configurations (workflows, custom fields etc.) and integration hub (iHUB) mappings and events to help you with the configuration.

Note: The best practices package is not counted against the usage quota.

To better understand what objects and events you need to configure, consult the Use Cases for Clarizen and JIRA Integration topic.

While, the best practices include mappings for most of the scenarios, you may find it necessary to create additional mappings, or modify the existing ones.

For more information about how to create or modify mappings, refer to Mappings and Events topic.

 

4) ENABLE MAPPINGS AND EVENTS

Once you have identified and configured mappings and events required for your integration, you must enable them.

To enable mappings and events:

  1. Select the checkbox next to each mapping and event you wish to enable.
  2. Click the Enable button.

 

5) CONFIGURE SYNCHRONIZATION OPTIONS

Configure synchronization options to specify when data synchronization happens between the two systems. For instructions on how to perform this task, refer to the Synchronization Options topic.

Back to top

INTEGRATION USE CASES

RESEARCH AND DEVELOPMENT USE CASES

Manage cross-functional projects, where the detailed Research and Development part of the project is managed by the development team in JIRA, while the effort and status updates are synchronized back into Clarizen, so that project managers, executives or any other stakeholders are provided with a clear view of the entire product launch, regardless of whether part of it follows Agile methodologies (the R&D part), or the traditional ‘waterfall’ practices.

 

Note: Due to JIRA hierarchy limitations, only three levels of work items can be synchronized from Clarizen to JIRA.
By default, any work item on the 1st, 2nd and 3rd level is synchronized. Clarizen administrators can reconfigure the levels in Clarizen iHub settings.

Minimum Mapping Requirements

Process

Minimum Mappings

Required

Best Practice Mapping or Event

(Must be enabled)

Clarizen Fields

JIRA Fields

Creating a project in Clarizen

Project Manager

Lead

Mappings > Projects

Events > Clarizen Project creation trigger

Name

Name

JIRA Project key

Key

Creating a task in  Clarizen

 

Task

Issue

Mappings > Link existing Clarizen Task to JIRA Issue
 

Note: You must create a field mapping for each mandatory field in JIRA for creating new issues.

 

Events > Clarizen Task Creation event

 

 

SYNCING ANY TYPE OF JIRA ISSUE WITH A CLARIZEN CASE

In JIRA, a project can contain multiple issues, where each issue can be a different type field. An issue in JIRA can be a bug, new feature, documentation subtask, etc. An out-of-the-box mapping for JIRA issue types and Clarizen cases is available, but a Clarizen administrator can change the mapping and events at any time. During the sync between JIRA issue types and Clarizen cases, the cases are automatically related to a Clarizen parent project.

Benefit: Since JIRA issue types may be mapped differently than issues in Clarizen cases, you can customize the mapping to sync cases in a way that makes sense for your organization.

 

Note: Bugs should be enabled in your Clarizen account. To enable bugs, go to Settings > Profiles > Cases (under Item Types) > Turn Bugs On.

 

LINKING CLARIZEN TASKS WITH JIRA ISSUES AND PROJECTS

Linking a Clarizen task/issue to a JIRA issue

You can link issues or tasks in Clarizen to separate JIRA issues without having to sync the project. For example, two tasks from the same project in Clarizen can be connected to issues in JIRA under different projects.

To link a specific issue / task in Clarizen to an issue in JIRA without syncing to a project, follow these steps:

  1. In Clarizen, go to an existing task in a project.
  2. In the Work Plan ribbon, click Utilities > JIRA Sync.
  3. In the new window, click Link to Existing tab to link to an existing issue.
  4. Select the use case in the Define Use Case dropdown.
  5. Search for an existing Clarizen work item to link the task.

 

Creating a new Clarizen task under an issue within a JIRA project

Since each issue holds projects for a different purpose, you can manage the object where a new issue is created in JIRA based on the Clarizen task it is linked to.

SYNCING SUPPORT TICKETS

Creating support tickets in Clarizen

If a support team member creates a case in Clarizen, such as a customer request or bug, it is not related to any particular Clarizen Project. However, in JIRA, issues must have a parent project. Therefore during the integration setup, a project for support tickets needs to be created in JIRA to ensure these customer cases are synced and addressed in a specific JIRA project.

Creating support tickets in JIRA

If a support ticket is created in JIRA (by support or a third party application like Zendesk), it is replicated in Clarizen as a taskissue, or request in Clarizen.

Note: Bugs should be enabled in your Clarizen account. To enable bugs, go to Settings > Profiles > Cases (under Item Types) > Turn Bugs On.

 

SYNCING TIMESHEETS AND WORKLOGS

Software developers report time worked in specific JIRA issues, which are synced with the corresponding tasks in Clarizen, providing project managers transparency across systems when approving reported times.

SYNCING SOCIAL COMMUNICATIONS

Syncing JIRA and Clarizen social communications promotes purposeful collaboration between different teams (Software Development, Sales, QA, Marketing, etc.). For example, R&D may comment on a JIRA issue while a project manager posts a reply from a Clarizen task. Social posts and comments are synced between Clarizen and JIRA issues every 60 minutes.

SYNCING FILE ATTACHMENTS

All file attachments are accessible from both systems via an external web link. Files can be attached to JIRA issues or Clarizen tasks. When files are synced between the two systems, a file object link is created in Clarizen and a download link is created in JIRA.

Note: To avoid file management issues, only links to the files are synced.

 

MANAGING PROJECTS IN A JIRA-INTEGRATED ENVIRONMENT

ADDING A CLARIZEN PROJECT TO JIRA

This topic assumes that you have an existing project in Clarizen, if not, create the project first. The user specified as the Project Manager for the project will become the Project Lead in JIRA.

  1. Click the Gear icon in the Work Plan and select Columns.
  2. Add the following fields:

    Field Name

    Field Type

    Description

    Create in JIRA

    Toggle

    Use to synchronize the project or a work plan item with JIRA.

    JIRA Project Key

    Text field

    Must be 2-10 upper-case letters from the Latin alphabet.

  3. In the Create in JIRA column, switch the toggle.
  4. In the JIRA Project Key field, enter the new key for the project.
  5. A corresponding project will be created in JIRA at the scheduled sync time. You can also check if the tasks have been added to the Sync Registry in iHub.
    Once the project is created in JIRA, you will see it in Projects > View All Projects page.

ADDING A CLARIZEN TASK TO JIRA

This topic assumes that a tasks exists in Clarizen, if not, create the tasks first.

  1. Click the Gear icon in the Work Plan and select Columns.
  2. Add fields that are required fields in JIRA for creating a new issue (For example, JIRA Assignee).
    You must also add the JIRA Issue Type field.
  3. In the Create in JIRA column, switch the toggle.
  4. In the JIRA Issue Type column, enter the type of issue you are creating (for example, Task).
  5. Complete other fields that are required for creating an issue in JIRA.
    A corresponding project will be created in JIRA at the scheduled sync time. You can also check if the tasks have been added to the Sync Registry in iHub.


Back to top

Have more questions? Submit a request

Comments

Powered by Zendesk