Readme for Micro Focus Connect Jira Connector 24.4

This readme describes how to configure Micro Focus Jira Connector. Refer to the Micro Focus Community and Micro Focus Connect Help Center for further configuration instructions.

The Micro Focus Jira Connector for Micro Focus Connect (Micro Focus Jira Connector) lets you synchronize Jira assets like Bugs with assets in OpenText Products, for example assets found in the Micro Focus Octane Connector.

Copyright

Copyright 2018 - 2024 Open Text.

The only warranties for products and services of Open Text and its affiliates and licensors ("Open Text") are as may be set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. Open Text shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice.

Except as specifically indicated otherwise, this document contains confidential information and a valid license is required for possession, use or copying. If this work is provided to the U.S. Government, consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Contents
  Installation and Upgrade Information Technical Notes
Prerequisites Known Issues Need assistance with the product?

Features

Supported Versions

This version of the connector is certified with Jira 9.12.10 LTS as well as the Cloud version (hosted)

Unless otherwise specified, for any given MF Connect connector from OpenText, all versions of the connector product that are officially released and supported by it's vendor both four months before the time of the release of the connector as well as at the time of using the connector, are supported by OpenText. Not all product versions will be tested and validated by OpenText for each connector release. Instead, OpenText chooses a subset of versions that we deem representative or most important to run validation and certification tests against. These selected versions are mentioned in the respective connector read-me, clearly identifying them as "validated" or "certified". As stated above, this does not mean that Micro Focus Connect does not support other product versions – it only means that no validation test cycle was executed for the other versions.

Supported Assets

The Micro Focus Jira Connector supports the following asset types

For general connections (MFC):

This version of the connector supports common Jira asset types, as well as custom fields in Jira. The connector also supports asset types and fields in Jira plugins that conform to standard Jira data structures.

For Value Stream Management (VSM):

Supports all assets which supports MFC connections.

 

Top

Prerequisites

This connector requires at least build 24.4 of Micro Focus Connect and can be configured using the Micro Focus Connect UI.

The thesaurus.properties file should be copied to the Micro Focus Connect's AppData\data folder.

The following are required to run the Connector. For further configuration instructions, see the Micro Focus Connect Release Notes.

  1. Create a Connector directory. For example: C:\Program Files\Micro Focus\Connect\AppData\connectors\mfcConnectorJira
    • NOTE: If this is being installed into an existing connector directory, you must remove the existing mfc*.jars
  2. Copy the following libraries (and the provided Connector jar and if provided mfcConnectorUtil jar) into the connector directory you created.

Setup fields in Jira Screens Prior to using

In order for Micro Focus Connect to see and update a field, that field must be visible on Jira Create Item Screen.

Jira User Permissions

The user configured in the Jira data source must have the following access:

 

Top

Installation and Upgrade Information

The following information contains notes regarding installation, but does not replace the entire process.

Required Connection Information

In order to use this connector, you will need to collect and enter this information in the Micro Focus Connect user interface:

Optional Connection Information

 

Top

Known Issues

Storing embedded images in rich text fields

Jira internally stores all embedded images in rich text fields as attachments in its data store. In case attachment synchronization is turned off, it is essential to give attachment access to Connect user. Failure to do so would result in Connect constantly throwing "Basic Auth with password is disabled by the API Token Authentication app" ( Error code 403) in the logs.

Importing Jira Data Source from Prior to 4.4.3

If you import a version of a data source prior to 4.4.3, you must edit the data source and set the "Authorization Mechanism" field. Then, save the data source.

Incorrect password entered in a data source

Entering an incorrect password for a user while creating a Jira data source can lead to the account requiring a CAPTCHA reset, before Connect will accept the password for the data source.

The user will receive a 'Basic Authentication Failure - Reason : AUTHENTICATION_DENIED' in Connect when the password is incorrect.

The same error will appear in the connection messages for a connection that attempts start. Connections is this state will have a 'Disabled due to error' status.

If this happens, administer the user within Jira and click the 'Reset failed login count' link.

This operation will allow the password to be accepted in Connect.

Overlapping Field Names

Jira will permit users to define custom field names that overlap with system field names. MFConnect will only expose one of the duplicate field names. Ideally, the user should eliminate the overlap by removing one of the duplicate field names from the create/edit screens.

Conversion Between Item Types Causes Errors

The conversion between item type for existing items (issue to subtask, for example) will cause errors in the logs. The error indication can be resolved by deleting the converted item.

Changing Issue Types Not Supported

Changing of IssueTypes (e.g. from a Story to an Epic in Jira) is not currently supported.

Project Specific Status Values

Jira supports project specific status values. Currently, the Jira Connector cannot determine which status values are associated with each project. Therefore, users should only map the status values that are appropriate for their project.

Synchronizing Multiple Value Fields to Single Value Fields

If you are synchronizing multiple value fields to single value fields such as text fields, only the first value will be synchronized by MF Connect.

Values from HTML properties may not display as expected

Some Jira add-ons use custom html styling to display content. When RichText fields in Jira are mapped to HTML properties in other connectors, those connectors may not render the styling tags in the Jira content. The result may be the user in the other connector seeing additional characters in the field.

Jira LinkedIssue Relationships

Jira supports several different types of LinkedIssue relationships (e.g. is blocked by, is caused by, is duplicated by). The Jira Connector exposes these different types of relationships as different relationship fields (e.g. rel.inward.is.blocked.by). It is expected that each of these relationship fields will be mapped to a unique field on the other side (e.g. jiraDefect.rel.inward.is.caused.by could be mapped to octaneDefect.causedBy). Users will see undesirable behavior if multiple Jira LinkedIssue fields are mapped to a single field on the other side.

Jira "relates to" Relationship

Jira connector does NOT allow "relates to" as a Default Link Type.

Comments with only image links will not be created

When syncing a comment that only contains an image link, a comment will not be created in Jira.

Micro Focus Connect will generate an audit record that indicates a AddCommentFailed action.

The error cause will be: "Comment body cannot be empty".

Duplicates when project key is changed

Duplicate items can be created in the master project during a synchronization from Jira if the following conditions are met:

After this has happened and you start the connection and start updating items, duplicates can be created in the master project.

Bidirectional Synchronizing of Resolution Field in Jira May Cause Unexpected Results

The value of the "resolution field" in Jira is dependent on the value of the "phase field". For example, changing phase=done to phase=inProgress automatically changes resolution to "Unresolved". Also, the Jira REST API does not permit changing the resolution from any value to "Unresolved". We recommend synchronizing this field from Jira to other products (one way).

Team field in Plan plugin

When working with values for the field generated by the Team field in the Plan plugin, Micro Focus Connect displays the value as <TeamName>(<IDNumber>). For example, the team named "My Shared Team" with IDNumber 3, is displayed as "My Shared Team(3)".

External Named Filters (Jira Filters)

Jira users can save their searches as Filters and use later in his work. MFConnect users can use Jira favorite filters as named external filters. However, filter functions that Jira exposes within the Jira Filters are not fully supported by MFConnect. Filters containing, for example, "currentUser()" or "currentLogin()" are not appropriate for MFConnect. For example, a query that specifies "assignee = currentUser()" will not properly work in the MFConnect because the "currentUser()" refers to the user specified in the dataSource.
Additionally, Release and Sprint types do not support external filtering with Filters or JQL.

External Free Form Filtering Using Jira Query Language (JQL)

Users can configure the free form external filter that can narrow the Jira items to be synchronized. The external filter is configured in MFConnect and applied on the Jira side. The query syntax is Jira specific and information about this syntax can be found here . It's possible to play with your JQL on Jira Filter configuration.

Undesirable Filters in Named Filter List

Some filters in the named filter list can be undesirable for the items being synchronized. For example, the filter might indicate "issueType=Bug", and you are currently synchronizing user story items. So, make sure you choose a filter that is appropriate for the type of items you are synchronizing.

Jira Cloud Team field representation update

Jira Cloud made update with Team Field representation of ID value if erlier it was just 1,2..... now it is ProjectUID-1,ProjectUID-2,..., if syncronization is in Jira direction both representation types are suitable but when syncronization direction is from jira than re-mapping is possible neded.

 

Top

Technical Notes

Atlassian Cloud TeamField support

As Atlassian migrated TeamField type from plugin specific type (Advanced Roadmaps Plugin for Jira) to built-in type on cloud, a non-documented method to obtain a list of Teams has emerged. This requires the Organization ID DataSource property to be filled. To find your Organization ID, you can refer to: How to find organization ID.

Security Level support

To ensure that Opentext Connector for Jira operates smoothly with Security Levels, the Jira Data Source user must have all the necessary permissions, including access to all security levels and visibility into items marked with an Empty (NONE) Security Level value. It's important to note that different versions of Jira may display the empty security level differently; in some versions, it might appear as the absence of a value, while in others, it might be shown as "NONE".

Discovery and Synchronization of Items

Micro Focus Connect relies on the JQL query configured in the chosen board for the project configured. It will only see and sync items that are visible in that JQL query.

Difficulty Recognizing Access Rights Errors

Access Rights errors can be difficult to recognize in the error log. Often they will show up as "A JSONObject text must begin with '{' at character 0 of ...".

Unable to Synchronize Rank

For IssueTypes, Rank is not a syncable field because the value is internal to Jira to establish a relative rank.

Sprints and Releases Do Not Support Bi-Directional Mapping

Because Jira does not maintain history on Sprints and Releases, MF Connect will treat both Sprint and Release items as having been most recently modified in a bi-directional mapping. The result will be that the Sprint or Release property value will overwrite the value from the other connector. OpenText recommends that Sprints and Releases be mapped one-way - either from Jira or to Jira.

User Maps for Jira

The Jira UI exposes three ways to identify a user ("Full name", "Public name", "Email address"). User Map entries in Micro Focus Connect for Jira must use the "Full name".

Data Source Setup

The number of "Sample Project Key with Name" values in the drop down list is limited to 500. Project not in the list can be entered in the format as those listed, Key:Project Name

Mapping Rich Text Fields to and from Jira (outgoing)

In some cases, Jira surfaces Rich Text ( aka HTML ) content that references style sheets local to Jira. For example, Jira tables reference a style sheet named confluenceTh. When mapped from Jira into a RichText property, this data will not render correctly because this style is not available.

Mapping Rich Text Fields to and from Jira (incoming)

Micro Focus Connect leverages the Atlassian wiki renderer used by Jira to convert from html to its wiki format. This renderer is able to translate a limited set of HTML into its internal wiki markup language. In many cases, incoming HTML will be translated into Jira as plain text.

Overriding ReadOnly Properties

In some cases in Jira, based on workflow, a read only property may become writable. MF Connect mappings do not allow a read only property to be target. However, it is possible to force the property to be writable by specifying the property on the "Force Properties to be Writable" datasource attribute. The format for this attribute is <type>:<property> pairs separated by commas. To force the property for all types then do not specify the type or colon. For example, "Story:Resolution, ModifyByUser" specifies that the Resolution property for te Story type, and the ModifyByUser for all types should be writable. In many cases a similar capability may be available through one or two calculated value statements. The main difference is that to determine the data flow direction a bi-directional mapping queries the connector as to when a particular field changed, whereas the best a calculated value statement can do in a When clause is execute if the Other side modify time was more recent than the current item's modify time.

Comment Support

Comment syncing is supported for all types except Releases and Sprints. By default, comment syncing is enable for each type. Comment functionality is controlled for each type via 3 type specific properties on the datasource properties TYPE tab - Allow Comment Delete, Allow Comment Update, and Allow Comment Create. When comments are created via Micro Focus Connect synchronizations the comment creator will always be the Jira data source user.

Non ASCII Attachment Names

When Micro Focus Connect creates attachments with non-ASCII names, the attachment names appear URLEncoded in the Jira UI.

Connect Express (formerly NFeed) Plugin Is Now Supported

SQL and JQL text fields are surfaced as enum type properties. User fields are surfaced as user type properties. If a field is not displayed in the Micro Focus Connect UI, it could be that it has been improperly configured in Connect Express. An examination of the .err file in the logs directory should provide some assistance. In most cases, the error occurs for an enum field for which the query to get the possible enum values failed.

When synchronizing Connect Express fields which contain user values, the synchronized value will be the standard Jira user field UI display value, and not what the custom field was configured to display in the UI. Note that you can configure Connect Express fields to display the same value as displayed by standard Jira user fields.

User fields

When updating Jira, the Connector identifies users based on closest match. When the match isn't exact, log messages will show information on users which were not selected.

Support for Custom Sub-task types

The Jira Connector now supports custom sub-task types. For a new datasource, assuming you have less than 20 types, your custom sub-task types will appear in the Types tab and the Relationships tab. For an existing datasource, you must "Apply Default Model" to refresh the Relationships tab with custom sub-task types. On the Relationships tab, sub-types will show a property called Parent which will have referred to types for all valid issue types which are not sub-task types. Note that while this property is named parent, sub-task types are not heirarchical - the Parent or Include children properties on the Type tab are not displayed. The valid issue types can be fewer than all the issue-types for a project if the types have been restricted in the datasource via the Types attribute.

The Jira REST API does not support changing the parent of an existing Subtask or custom Subtask, even though this operation is available in the Jira UI. However, the Parent relationship property must be mapped in order to create a Subtask because Jira does not allow a Subtask to have an empty parent. Therefore, it is suggested that the mapping be 1 way, from Jira. The direction of the mapping is not used when creating an item, only when updating items.

Attemping to delete a parent item having sub-tasks will fail with a Jira error. This behavior hasn't changed with the new support of custom sub-tasks.

Authorization Mechanism

In prior releases, the JiraConnector only supported authorization via jiraUser/jiraPassword. This is still supported. But, now the JiraConnector supports 4 other OAuth 2.0 authorization flows. OAuth 2.0 is the industry-standard protocol for authorization. If you choose one of the OAuth 2.0 flows, you will be directed to enter additional information (e.g. clientId, clientSecret) so that the JiraConnector can negotiate with the authorization server to obtain an authorization token. The authorization token allows the JiraConnector to communicate with the Jira server.

Boards in Jira with issue type filter

Jira Board only displays issues that meet the specified criteria. Note that when the board is filtered based on a specific issue type, Jira connector will replace the issue type by the syncset type while querying for issues. For example, when syncing Story (Jira) -> Story (Octane) by selecting a Jira board that has a filter of "bug" issue type, Jira connector will replace it with Story type.

 

Top

Need assistance with the product?

Get support enables you to open a support incident or to submit a bug. You can also browse many helpful support resources.

 

Top