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 2018 - 2023 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? |
This version of the connector is certified with Jira 9.4.7 LTS as well as the Cloud version as of July 2023 (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.
The Micro Focus Jira Connector supports the following asset types
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.
Supports all assets which supports MFC connections.
This connector requires at least build 23.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.
In order for Micro Focus Connect to see and update a field, that field must be visible on Jira Create Item Screen.
The user configured in the Jira data source must have the following access:
The following information contains notes regarding installation, but does not replace the entire process.
In order to use this connector, you will need to collect and enter this information in the Micro Focus Connect user interface:
MF Connect will exclude comments that were created before this date (exclusive).
The date format is <year>-<month>-<day>.
For example: The value '2022-01-01' will make MF Connect only process comments that were created
on January, 1, 2022 and after.
Leaving it empty will result in all comments being included for synchronization.
Only applies to 'Micro Focus Connect (MFC)' context type.
Enables (true) or disables (false) the injection of a comment header to comments that are created or
updated by MF Connect. The comment header consists of: Updated by MF Connect: 'Author' 'UpdateTime'.
'Author' and 'UpdateTime' values are taken from the comment on the opposite side of the connection.
Only applies to 'Micro Focus Connect (MFC)' context type.
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.
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.
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.
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.
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.
Only scrum projects using Agile boards are listed.
Changing of IssueTypes (e.g. from a Story to an Epic in Jira) is not currently supported.
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.
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.
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 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.
There is a bug in Jira associated with the "relates to" relationship. When the Jira connector attempts to add an "outward relates to" relationship to an item, the Jira server creates an "inward relates to" relationship. So, the Jira connector does NOT allow "relates to" as a Default Link Type. Also, "relates to" relationships may not be synchronized correctly.
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".
Duplicate items can be created in the master project during a synchronization from Jira if the following conditions are met:
If you have a connection that has been run at least once and change the project key in Jira.
Edit the connection settings by changing the project pair to include the new Jira project key.
After this has happened and you start the connection and start updating items, duplicates can be created in the master project.
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).
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)".
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.
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.
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 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.
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.
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 ...".
For IssueTypes, Rank is not a syncable field because the value is internal to Jira to establish a relative rank.
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.
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".
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
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.
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.
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 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.
When Micro Focus Connect creates attachments with non-ASCII names, the attachment names appear URLEncoded in the Jira UI.
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.
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.
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.
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.
Get support enables you to open a support incident or to submit a bug. You can also browse many helpful support resources.