Introduction

ConnectALL supports the syncing of records from the Atlassian Jira to other applications. 

Supported Authentication

The ConnectALL Jira adapter supports Basic Auth and OAuth 1 to connect to Jira(on-prem) and supports API Key and Basic Auth to connect to Jira Cloud. 

Cookie-based authentication is disabled in the adapter.

Supported Entities

(tick)  Bug

(tick)  Epic

(tick)  Story

(tick)  Sprint

(tick)  Sub-Task

(tick)  Task

(tick)  Test

Supported Functionalities

(tick)  Attachment Visibility (with Jira Service Desk)

(tick)  Comment Author Configuration

(tick)  Customizing Comment Synchronization

(tick)  Delete Attachments 

(tick)  Multi-Project Configuration

(tick)  Status Transition Mapping

(tick)  Synchronizing Weblinks

(tick)  Webhook Configuration

(tick)  Worklog Synchronization

(tick)  Sync Sprints

(tick)  Sync Issue Links

Configuration

You will need the below details to create a Jira connection.

  • URL 
  • User Name
  • Password
  • Time Zone



NOTE: Ensure that you provide the email address and API token value in the Username and Password field respectively.

Authentication using OAuth 1.0 for Jira (on-prem) Server

ConnectALL requires access to your Jira server to sync data. To gain access, it allows you to authenticate using OAuth 1.0 to connect to a Jira server. Enabling the OAuth1.0 authentication involves the following steps:

  • Step 1: Creating the Key Pairs (Public Key and Private Key)
  • Step 2: Configuring the Jira server to accept the Public and Private keys
  • Step 3: Creating a connection in ConnectALL

Step 1 – Creating the Key Pairs (Public and Private Key)

A private key and a public key are required to configure and enable OAuth1 authentication. To generate a public and private key, use the commands provided below. If you have any other options to generate a public and private key pair, you need not opt to use the below commands.

  • openssl genrsa -out jira_privatekey.pem 1024
  • openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365
  • openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8
  • openssl x509 -pubkey -noout -in jira_publickey.cer > jira_publickey.pem

The second command specifies the validity period (in days) of the certificate as ‘(-days)’. You could increase this based on the requirement. After you run the above commands, the following files are generated:

  1. jira_privatekey.pem
  2. jira_publickey.cer
  3. jira_privatekey.pcks8
  4. jira_publickey.pem
Open the jira_publickey.pem in a text editor. It will look like below.

Open jira_privatekey.pcks8 in a text editor. It will look like below.


Copy both the public and private key content and keep them handy. You will be using it in the next step. If you have any queries about these commands, reach out to our support team.

Step 2 – Configuring Jira to accept the Public and Private Keys

  1. Log into Jira.
  2. Navigate to the Administration section and click on Application Links. The Configure Application Links page will be displayed.
  3. Configure the application link by entering the URL of the application that you want to link and click Create new link. Enter the other details requested in the subsequent screens.

When you are configuring the application link, you will be required to enter the public key that you generated earlier and a consumer key. The consumer key that you enter here is a key of your choice and you have to note it down as it will have to be used later while you are going to create a connection in ConnectALL. After you complete the configuration, the application link you configured will be displayed as shown below, and that is your confirmation. For more information on how to configure an application link, refer to this page.

Step 3 – Creating a Connection with the Public and Private Keys

The next step is to create a connection in ConnectALL using the consumer key that you entered in Jira and the private key that you generated earlier. Note that this connection creation will work only for Jira Server installations and not Jira (cloud). To do that,

  1. Log into ConnectALL.
  2. Click Connections from the top navigation bar.
  3. Click Add Connection to add a new connection.
  4. Select Authentication type as OAuth 1.
  5. Enter the Consumer Key and Private Key and click Save. The Authorize Credentials screen will be displayed. 
  6. Click Authorize to authorize the connection. You will be redirected to Jira again. Note that if not logged in to the Jira instance, login to Jira. You will be redirected to the Welcome to Jira screen. On this screen, you will be notified that the ConnectALL application will be allowed to use your credentials to authenticate you. If the prompt is not displayed, check the pop-up blocker settings and make sure it is turned off. 
  7. Click Allow. You will be redirected to Authorize Connection screen in ConnectALL.
  8. Click Proceed to complete the creation of a connection.

The new connection that you have configured will be displayed in the Manage Connections screen.

Note

The app-links associated with a connection will be disabled if there is an error while refreshing a connection’s OAuth token.

Jira Cloud GDPR Compatibility

The ConnectALL Jira adapter is enhanced to support Jira Cloud GDPR (https://www.atlassian.com/trust/privacy/gdpr) compatibility. As per their regulations, Atlassian has disabled the ability to read user sensitive information without consent. Instead of using readable usernames, Atlassian will be using computer generated account identifiers. 

Jira GDPR compliance impacts the integrations with Jira Cloud user fields. In order to seamlessly synchronize the data for these user fields, ConnectALL provides the following options: 

  • Uni-directional Mapping of Jira Cloud user fields to Custom text fields in destination: ConnectALL will synchronize the Display Name of the user if consented.
  • Importing user mapping for User fields: ConnectALL provides an option for users to import a user list mapping for the source and destination system using the value mapping feature (CSV template for user field mapping).

Important Information

Let's say you are trying to update a user type field such as 'Assignee' in the Jira cloud.  While you update, if you don't provide the account ID and update using only display name or email address or both, the Jira ticket that gets created will not reflect the Assignee value. Similarly, when you update the 'Assignee' field in on-prem Jira without providing the name (and use only display name or email address or both), the update will fail. Note that, if you try to create this scenario in Postman to see if this update is successful, you will get the following result (image):



As that’s the case, please note that,

  • The 'accountID' field is mandatory for updating any user type field in Jira cloud and
  • The 'Name' field is mandatory for updating the user type field in on-prem Jira.

Entity Mapping

ConnectALL validates the project and issue type selection before proceeding with the configuration of fields. The validation is done when you click the Configure Fields button. If an invalid Issue type is selected for the project, ConnectALL prompts by displaying an error.

If you are configuring an application link using multi-project configuration by selecting All in the project drop-down list, then the issue type validation will be done based on the project key mentioned in the Template Project under advanced properties.

Jira Status

Whenever a Jira Status field is mapped, it is mandatory to provide the value mapping even when the values are the same between both systems. This is mandatory to handle multiple transitions in Jira.

Sync Sprints

When you trigger a sync for sprint synchronization, all the Jira sprints will be fetched and updated in the destination application, even if you have not made changes. 

Field Mapping

Cascade Select

The Cascade Select field of Jira has been split and displayed in two fields in the mapping.  The parent name will be displayed as it is displayed in Jira, and the child name will be suffixed with the word 'child'.



The child value of the cascade field in Jira will have the prefix of the parent value
.


Note — Multi Status Transition

ConnectALL is capable of handling 'Multi-Status Transition' as it can recognize the different stages in a transition. For ConnectALL to recognize the status transition, you have to map all the statuses in an application with the corresponding application. For example, map the statuses—‘To do’, ‘In Progress’, and ‘Done’ of one application with the corresponding values of the other application. When you do, ConnectALL will recognize the status transition of the record and it’ll sync the final value.

Mapping Status Transitions

Starting from version 2.10.32.3 ConnectALL allows mapping of status transitions. For more information, click here.

Value Mapping 

If you do not see any values displayed in the value mapping screen, note that the field must be on the Jira create screen in order for its values to show up in value mapping drop-down list. 

SubTask

  1. In Jira, we have enabled the Sub-task in the issue types. To sync it, the parent issue types should also be mapped in ConnectALL.
    Example:

Link 1 – Jira Bug <-> ClearQuest ALMRequest
Link 2 – Jira Subtask <-> ClearQuest ALMTask

2. To configure the subtasks under the same parent, use the mapping as shown in the below screenshot.

       


Advanced Formatting Options

Support for Code Blocks, Panels, and Quotes

Starting from Version 2.10.23, ConnectALL supports advanced formatting options for the Jira adapter. These options include Code blocks, Panels, Quotes, and No Formats. Note that,

  • ‘Code blocks’ and ‘Quotes’ are supported when you sync from Wiki to HTML (and vice-versa) and from Wiki to Wiki.

  • ‘Panel Items’ and ‘No formats’ can be synced only in Wiki to Wiki synchronizations and cannot be synced from Wiki to HTML.

Support for ADF Format

Starting from version 2.10.24, ConnectALL supports ADF format for Jira (Cloud). Let’s say you are mapping a Description field of Jira (Cloud) to sync into Jira (On-Prem). When you are doing so, it is possible to sync ADF formatted content. As ADF is supported in Jira (Cloud), the formatting can be preserved as it is when it is syncing into Jira Server. All you have to do is, select the Data Type for Jira (Cloud) as ‘ADF’.

To set the Data Type,

  1. Click the cogwheel icon against the Description field (in which you want to choose the ADF format).
  2. Select ADF from the drop-down list of the Data Type field.

Once you save it, it will be displayed as below:


Multi-Project configuration

Multi-Project synchronization can be done when Jira has the same workflow and other configurations common for the projects that are being synced via ConnectALL. This feature is supported only between Jira–Jira app-links and for one QC project to many Jira projects.

  1. Set the "jira.multi.project.enable=Y" in the ConnectALL.properties file available in the <MULE_HOME>\conf folder.
  2. Restart both Tomcat and ConnectALL core services.
  3. In the project selection, select Multiple.



  4. Select the Template Project from the drop-down list.. Based on the Template Project selected, the fields will be retrieved for mapping.
  5. In the Field Mapping section, add the Project (project) field and select the sync direction for that row. This mapping is mandatory for synchronization.


When the drop-down value is changed, the issue will be moved to the appropriate project in Jira. To achieve this, please complete the configuration provided in the "Move Issue" topic.

The Jira–QC synchronization is supported only between one QC project to multiple Jira projects. A custom field has to be created in QC with the keys of the Jira projects as values, and then map the custom field value to the projects in Jira. The issue will be synchronized to the corresponding Jira project based on the custom field values selected in QC. The mapping of a Jira Project field to the custom project field in QC is required for synchronization.

Jira Project Field

When trying to map the Jira Project(project) in the Field Mapping section (below), only bi-directional mapping is allowed. Please avoid uni-directional mapping in the field mapping or in the value mapping screens for this field. This might cause synchronization issues as this field (project field) is a mandatory field to identify the project from Jira.


CreateMeta API

If you are using createmeta endpoint to return a list of fields given a project and an issue type, (/rest/api/2/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId}), Note that the default maximum results (maxResult) returned is 1000. But, you can change it to have a desired result by making a change in the ConnectAll.properties file. Let’s say you want to make the maxResult to 100 (or any desired value). Change it as provided below:

jira.max.field.list=100

Comment Author Configuration

In Jira, due to security reasons, when ConnectALL syncs a comment into Jira, the actual author of a comment (in the source system) will be ignored; The comment will be added to Jira via the ReST API and therefore the logged-in user (the ConnectALL sync user) will appear as the comment author in Jira. Jira users, however, would prefer to see the name of the source-system users who added the original comment. To achieve this, ConnectALL provides two approaches, each of which has its pros and cons.

  1. Modifying the Properties File
  2. Using ConnectALL Jira Plugin

Modifying the Properties File

In this approach, when you add a comment in Jira, the comment author will be added to the comment body. You can opt for this method if you do not want to install the ConnectALL Jira plugin. All you need to do is add a property in the properties file. This method can be used in both Jira (on-prem) and Jira (cloud). The steps to configure this approach are listed in the How to sync comment author information article.

Using ConnectALL Jira plugin

Using the ConnectALL Jira plugin, ConnectALL reroutes the CRUD operations of comments to a custom API that adds the comments (with the user id) passed to it. For details, please refer to ConnectALL Jira Plugin.

Customizing Comment Synchronization

ConnectALL provides the capability to restrict a specific set of comments to be written to the destination.

Jira – ServiceNow

When you map Jira's Comment field and ServiceNow's Additional comments field, select the Enable Comment Visibility Value Mapping option in the Value Mapping screen. This will enable the value mapping for restricted comments. Please refer to the ServiceNow Adapter page for more information. 

Jira – Jira

When you map two Jira instances linking the 'Comments' fields from both,  click to select the Enable Comment Visibility Value Mapping option in the Value Mapping screen. This enables the value mapping for restricted comments.

Some Jira users might need to restrict their developer comments from being synced to other instances, or some Jira instances might have different role names than the destination which might need a value mapping to be completed. These scenarios are addressed via the "Enable Comment Visibility Value Mapping" feature.

The below mapping shows:

  • Restricted "Developers" comments from the source will not be written to the destination.
  • Restricted "Administrators" comments from the destination will be written as restricted "Users" comments in the source.
  • Other comments other than the mapped values from the destination will be skipped or will not be written to the source.

The entered values are validated by clicking Save Mappings in the Value Mapping screen (below).

Move Issue

Moving an issue between projects is supported only in the Multi-Project configuration. To support this, the ConnectALL Jira plugin has to be installed and the below configuration should be completed.

Configure the below properties in the MULE_HOME/conf/ConnectAll.properties file.


# Below configurations required to enable move issue in Jira
jira.customized.rest.url=/rest/jirarestservice/1.0
jira.handshake.enabled=true
TEXT

Syncing Test Steps of Zephyr Test

ConnectALL provides the capability to sync the Test Steps information of a Zephyr Test issue type. Zephyr for Jira is an add-on in Jira to add Test Management capabilities to your Jira instance. Currently, ConnectALL supports syncing of the "Step Name", "Step Data" and "Step Result" fields of a Test Step. 

Configuring Test Step Sync

To sync the Test Step information, an app-link needs to be created for the Zephyr Test issue type, and the field mapping needs to be done, as shown below. 

Since the Test issue type and Test Steps field are custom fields added by the Zephyr for Jira add-on, In addition to the field mapping, the below properties need to be added in the "$MULE_HOME/conf/ConnectAll.properties" file. (Change the values as required based on your instance configuration)

zephyr.test.issuetype=TestJira2Jira.Source:10100,TestJira2Jira.Destination:10200
zephyr.teststep.field=TestJira2Jira.Source:customfield_10200,ProdJiraQC:customfield_10250
CODE

The values for the above properties can be obtained from the Add-ons option available under JIRA ADMINISTRATION (below screen) following these steps.

  1. Click the Add-ons option. 



  2. Click the General Information option under the ZEPHYR FOR JIRA menu.



  3. Take a note of the values displayed and update it back to property values. 

ConnectALL will do a text comparison when creating/updating a test step. So if an existing test step is edited in the linked application, then it will be created as a new test step in Jira. 

Updating a test step in a Zephyr test will not trigger a ConnectALL sync, as the issue update date will not be set. Adding a comment or any other parent level field modification is needed to sync the edits in test steps.

Worklog Synchronization

To configure work log field, please refer here.

Jira Elements Connect (formerly nFeed) Plugin Support

ConnectALL supports the synchronization of the Elements Connect Plugin fields. The fields should have the data type listed below to be successfully synced.

Field TypeDataType in JiraDataType in ConnectALL
AutoCompletearrayLabel
Userarrayarray
Datedatedate
DateTimedatetimedatetime

Automatic User Value Mapping

ConnectALL supports Automatic user value mapping for Jira. Below is a screenshot that illustrates this; where

id=Username

name=Full name

email=Email


For more information on automatic user value mapping and to find out how it works, click here.

WebLinks

To sync the WebLinks fields of two Jira instances, create a mapping between the WebLinks fields (below image).

  • When you map two Jira WebLinks fields, the mapped WebLinks in the source application will be synced to the destination record WebLinks. 
  • You can also map a WebLinks field to any ‘String’ field in the destination application. This will sync the links and they will be separated by a comma (below image).
  • During synchronization, ConnectALL will reconcile the WebLinks and will sync only the available links on both the source and destination applications.
  • A 'WebLinks' field can also be mapped with a _URL field to sync the URL of a record.

Support for Delete Attachments Feature

To enable ConnectALL to support the deletion of attachments between Jira-Jira or Jira-QC, set the below property configuration in MULE_HOME/conf/ConnectAll.properties and restart both Tomcat and ConnectALL core services.

enable.delete.attachments=true

Smart Attachment Plugin for Jira

ConnectALL allows you to enable the smart attachment synchronization for Jira. You can enable the smart attachment synchronization, if the smart attachment plugin has been installed and enabled for the project and the issue type for which you are configuring the app-link. 

To enable the smart attachment configuration,

  1. Click the cogwheel icon against the attachment field. The Field Configuration screen will be displayed.
  2. Select the Smart Attachment Plugin option against the ATTACHMENT_EXTERNAL_PLUGIN field.



  3. Click Save to save the configuration.

Note
  • If you have enabled the smart attachment plugin in an app-link, only the attachments for which the sync user has access will be synchronized to the destination application.
  • The attachments created by ConnectALL will be synchronized under the un-categorized section.
  • ConnectALL will not synchronize the categories if you have enabled the smart attachments in both the source and destination Jira instances.

Attachment Visibility in Synchronizations with Jira Service Desk

Pre-Requisite

Any ticket created from the Jira Service Desk portal will have the "Request type" field populated by default. And if the "Request type" is not set in a ticket, the ticket itself will not be visible in the portal. There is a remote chance of this field not being populated if an agent submitted a ticket on behalf of the customer and failed to populate the field appropriately. Therefore, when synchronizing attachments to Jira Service Desk and want public attachments visible to all users, make sure the "Request type" is properly set in the issue itself. (The "Request type" cannot be updated via ConnectALL due to an API restriction.)

Configuration

  • By default, all attachments from Jira Service Desk will be synchronized to the destination, and they will be synchronized in the "public" mode.
  • Attachment visibility is configured similarly to Comment Visibility which is described in Advanced Value MappingTo set the internal attachment / public attachment visibility for attachments synchronized to Jira Service Desk, configure the attachment visibility setting against the attachment field in the value mapping section.

Example 1

  • Based on the visibility settings in the example below, the attachments will be filtered from the right Service Desk – they will not be synchronized to the left Service Desk (because of the arrow direction).
  • Also, public attachments from the left Service Desk ("* Null") will be synchronized as private ("Internal") into the right Service Desk.
  • Private attachments from the left Service Desk ("* Value Else") will be synchronized as private attachments to the right Service Desk ("*Value Same").

         

Note
  • Due to a Jira Service Desk on-prem server API limitation, ConnectALL cannot distinguish between public and internal attachments coming from Jira Service Desk on-prem. For example, if you configure an application link between Jira Service Desk on-prem server to ServiceNow, and configure the visibility to "Skip" the internal attachment from Jira Service Desk on-prem, all attachments from Jira on-prem service desk tickets will be treated as public and will be synchronized (instead of being skipped as configured). The limitation is only for reading attachments from Jira on-prem service desk. 
  • When you are syncing comments and attachments separately into Jira Service Management from Jira, it is sufficient if you enable comment visibility mapping in the ‘Comments’ row alone. This is because JSM combines the attachment with the comment. So, even if you don’t enable the comments visibility setting for attachments, the attachment will be combined with the comment and will be displayed along with it.

Example 2

Create an application link between ServiceNow and Jira Service Desk and map the Attachments field for synchronization as follows:


Create a record in ServiceNow with attachments and synchronize it to Jira Service Desk. The attachment will be visible in the service desk portal. The "* Null <> * Null" visibility mapping means that if visibility is not specified or cannot be determined, sync the attachment as public. "* Value Same < * Value Else" specifies that if the attachment visibility can be determined from the right application, then use the same visibility when syncing that attachment to the left application.

Time Difference Configuration

To know how to calculate the time difference, and configure it in the ConnectALL UI,  read the topic Time Difference Configuration.