Integration and Synchronization Process

AdaptiveWork is integrating with Jira using AdaptiveWork’s iHub integration platform which establishes a connection to 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 AdaptiveWork based on configured triggering events, or scheduled to run on a daily basis.

Triggered synchronization

• When the 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 AdaptiveWork’s iHub.
• When the synchronization process is triggered from AdaptiveWork, for example, when issue details are updated in AdaptiveWork, AdaptiveWork web service connects to the iHub, which then sends a call to Jira's API.

Scheduled synchronization

AdaptiveWork supports a daily synchronization process using iHub in 2 separate cycles (Jira to AdaptiveWork and AdaptiveWork to Jira). Once initiated, the scheduled process iterates on all records that are mapped in the iHub sync registry (e.g. AdaptiveWork task to Jira Issue), and executes a sync using both systems' APIs.

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

Working with Multiple Instances of Jira

If your organization employs multiple Jira instances, for example, separate instances of Jira per customer, you can now integrate each Jira instance with your AdaptiveWork account. You can also work with a mix of on-premise and online instances of Jira.
AdaptiveWork supports up to 10 Jira instances, however this can be expanded if needed. 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, which can be configured independently. You can switch between integrations using a list of Jira organization names in the iHub application.
Note: You must have administrative privileges for both Jira and AdaptiveWork to enable and configure each integration.

Using Multiple Instances

You can add another Jira instance in the Authentication tab in iHub. Each Jira instance will be identified by its unique name.

After adding additional instances, you will be able to switch between instances by clicking on the Jira instance selector.

For each instance, you can configure events/mappings and check the sync.

Important Note: Avoid creating identical events (same conditions) for different Jira instances, because iHub does not support a one-to-many (one Work Item to multiple Jira issues) sync process, however it does not block it.

A best practice is to create a custom field in AdaptiveWork, which will identify the target Jira instance, and then add it to the event’s conditions. This is to ensure that an event is triggered in only one Jira instance. This way the automatic (event-based or scheduled) sync will work properly.

When invoking the Sync to Jira action for a particular item in AdaptiveWork for the first time, you will be asked to specify a mapping as well as the target Jira instance. This info will be logged in the sync registry, and this way iHub will know the target Jira instance to sync with for any consecutive syncs.

System Requirements

AdaptiveWork supports integration with the cloud and on-premise versions of 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.
• The instructions below 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 AdaptiveWork to configure the integration.

Back to top

1) Configure Authentication of AdaptiveWork in Jira

1. Log into 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.
   
   
   
   
5. In Configure Application Links, enter in the Application text box: http://www.clarizen.com
   
6. Click Create New Link.
   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.
   
   
7. In the Link Applications screen, enter the following values and click Continue:
   • Application Name: AdaptiveWork
   • Application Type: Generic Application
     
     
     
     A message appears confirming that the application link was created successfully.
8. Click Edit to edit the new application link.
   
   
9. In the Configure AdaptiveWork 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: AdaptiveWork
10. Public Key:
    
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzru98MCpINB0/7Zt9s3YCTDQvRIxJRmthHMMWuUCwxRDPn055uUyL/+Qj9Ta8trwdq6DXpLybgjEHrttQvt2v25fxfbmzknR/ik9DspEg2lEgei3i1HstAb70wUhrkKmUVd8xTi9osiS/O10UWzoBNezPhX4Q8Umq/inAXGfqR1Z3DtRCHBrLYghuh8dS9q7nJdTsnzR3SAYTJ30L1jjFN4YMOYR/DPe2VD5ldjRgaN/pOX10tyeRo4Dj4xHezbGSD0qtYC7mJ0xNrO42IoJEyjo5ePXmFJqkS9vE9srxFrZ3AvOHW1xggFnVXADnUNkawAHAZBp6n2Iz65Jg/XM7QIDAQAB
    ​
11. Click Save and Close to close the dialog box. Authentication has been configured in JIRA for AdaptiveWork.

2) Configure Authentication of Jira in AdaptiveWork

1. Log into AdaptiveWork as the system administrator.
2. Click your name in the top-right corner and select the Settings option.
3. Open the Extensions tab.
4. In the Connected Web Apps section, click Allow Access for Jira Integration.
   Note: Allow Access changes to Revoke Access which indicates that the integration status is enabled.
   
   
   
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 AdaptiveWork read and write permissions to your Jira data.
   
   
9. Click Add AdaptiveWork credentials.
   
   
   
10. In the Authorized Access screen, click Grant Access.
    
    
    
11. Once the authentication has been successfully completed, the following screen will appear listing details for your AdaptiveWork and Jira applications.

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

AdaptiveWork provides a predefined set of mappings (best practices) which are installed by default.

The best practice package contains AdaptiveWork 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 AdaptiveWork 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.

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

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 AdaptiveWork, 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.

Minimum Mapping Requirements

Syncing Any Type of Jira Issue with a AdaptiveWork 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 AdaptiveWork cases is available, but a AdaptiveWork administrator can change the mapping and events at any time. During the sync between JIRA issue types and AdaptiveWork cases, the cases are automatically related to a AdaptiveWork parent project.

Benefit: Since Jira issue types may be mapped differently than issues in AdaptiveWork 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 AdaptiveWork account. To enable bugs, go to Settings > Profiles > Cases (under Item Types) > Turn Bugs On.

Linking AdaptiveWork Tasks with Jira issues and Projects

Linking a AdaptiveWork task/issue to a Jira issue

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

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

1. In AdaptiveWork, 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 AdaptiveWork work item to link the task.

See also Using the Unlinked Indication for Work Items and triggering workflows

Creating a new AdaptiveWork 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 AdaptiveWork task it is linked to.

See also Using the Unlinked Indication for Work Items and triggering workflows

Syncing Support Tickets

Creating support tickets in AdaptiveWork

If a support team member creates a case in AdaptiveWork, such as a customer request or bug, it is not related to any particular AdaptiveWork 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 AdaptiveWork as a task, issue, or request in AdaptiveWork.

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