Readme for Micro Focus Connect Octane Connector 24.2

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

The Micro Focus Octane for Micro Focus Connect (Micro Focus Octane Connector) lets you synchronize Octane assets like Stories and Defects with assets in other Micro Focus Connectors, for example assets found in the Micro Focus Azure DevOps 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 Octane 16.2.100 and Octane 24.1.8.24.

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 Octane Connector supports the following asset types

For general connections (MFC):

For Value Stream Management (VSM):

 

Top

Prerequisites

This connector requires at least build 24.2 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.

In order to configure the Micro Focus Octane Connector, you need to make sure the Octane Server is configured to accept attachments with file type 'bin'. You can customize the supported file types by modifying the ATTACHMENTS_FILE_EXTENSION_WHITE_LIST configuration parameter. Visit https://admhelp.microfocus.com/octane/en/latest/Online/Content/API/Attachments.htm for more information.

The Micro Focus Octane Connector requires you to generate an Octane API Client ID and Secret. Generate and use both values when you configure your datasource.

 

Top

Installation and Upgrade Information

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

A Note About Octane Read Only Rules
Read only field rules in Octane impact the ability of Connect to synchronize data. Please see the Technical Notes section.

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:


The "API ClientId" that you choose when configuring an Octane Data Source must have roles "Workspace Admin" and "Space Admin". You can configure those in the Octane UI via settings -> Default Shared Space -> API ACCESS.

Optional Connection Information

 

Top

Known Issues

Limitations for Synchronizing Test Assets Can Be Found in the Core Readme Document

After clearing and saving the "Default Release For Sprints" data source property, it cannot be reset.

The "Default Release For Sprints" data source property is no longer required. The property will be editable for existing data sources. If the value is cleared and saved, it can no longer be set. The property will be displayed as read-only. If this happens, a calculated value should be used in it's place.

Shared Epics/Releases/Milestones Are NOT Fully Supported

MFConnect can synchronize shared items from Octane to any other repository (i.e. one way sync from Octane). However, MFConnect cannot create, update, or delete shared items in Octane. A future release of MFConnect will include full support for shared items.

External Filtering Using Octane Query Syntax

Starting in release 4.4.2, users can configure an external filter that can narrow the items to be synchronized. The external filter is configured in MFConnect and applied within the Octane server. For example, the synchronization could be configured to synchronize defects where the release assigned to the defect must have id equal to "1001" (e.g. GET .../defects?query="release={id EQ 1001}"). The query syntax is Octane specific. Information about this syntax can be found here: https://admhelp.microfocus.com/octane/en/16.0.100/Online/Content/API/query_Clause.htm If you are already logged into the Octane UI, you can test your query using the browser via a URL like the following: https://<yourOctaneServerName>/api/shared_spaces/<sharedSpaceId>/workspaces/<workspaceId>/defects?query=%22id%20GT%20293087%22 (Note: defects is plural, and query is URLEncoded from "id GT 293087").

Restrictions on External Named Filters (Favorites)

Octane users can specify "favorites" in the Octane UI. In general, these can be used as named filters within MFConnect. However, filter terms that Octane exposes within the "navFilter" are not supported by MFConnect. These include, but are not limited to "environment" filters. Also, favorites containing "ME" or "current_user" are not appropriate for MFConnect. For example, a favorite that specifies "defects OwnedBy ME" will not be exposed in the MFConnect UI because the "ME" refers to the user specified in the dataSource. Users can create the desired favorite by selecting a specified user instead of a value which is dependent on the dataSource user.

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 "type=releaseItems", and you are currently synchronizing defect items. So, make sure you choose a filter that is appropriate for the type of items you are synchronizing.

Some HTML formatting may be lost when synchronizing into Octane

For example, the following HTML does not appear underlined or in color in the Octane UI: <font color="#57d9a3"><ins>Underlined colored</ins></font>

Requirements and RequirementFolders

Requirements and requirementFolders have different fields. But, the Octane Connector surfaces the union of the fields. If you want to synchronize both requirements and requirementFolders you will need two type mappings with the appropriate syncCriteria and fields.

Comment mapping for the Task type

Earlier versions of Octane do not support comments for the Task type.

Micro Focus Connect automatically maps comments for the Task type.

If using an older Octane server, do not map comments for the Task type.

Image/Attachment Deletions

Micro Focus Octane stores embedded images from rich text fields together with other attachments.

This release does not perform any image/attachment deletions because an attachment could be associated with an unmapped rich text field.

A future release will fix this known issue.

Image Upload Duration

Uploading attachments or embedded images to Micro Focus Octane is time consuming.

If the upload duration limit is exceeded, the upload will fail and Micro Focus Connect will report an error.

New Tags cause a synchronization error

When Micro Focus Connect creates or updates a item in Octane, and the item has tags that do not exist in Octane, the first attempt to synchronize the item will fail.

The new tag(s) will be created in Octane during the failed synchronization.

On the next synchronization the item will be created or updated with the tags specified.

Relationship fields

The relationship fields 'linked_items1' and 'linked_items2' will have different labels depending on the Octane type.

The labels may cause confusion depending on the target Octane type.

Here is a list of the known labels for the 'linked_items1' and 'linked_items2' relationship fields.

		
		'linked_items1' relationship field:

		Octane Type            Target Types                     Label
		----------------------------------------------------------------------------
		feature                story, feature                   Feature(Trace to)
		story                  story                            Story(Trace from)
		defect                 story, feature, defect           Linked Story
		epic                   epic                             Epic(Trace to)

		'linked_items2' relationship field:

		Octane Type            Target Types                     Label
		-----------------------------------------------------------------------------
		feature                feature, defect                  Feature(Trace from)
		story                  story, feature, defect           Linked Defect
		defect                 defect                           Defect(Trace from)
		epic                   epic                             Epic(Trace from)
		

Support uppercase attachment extensions

To support attachments that have uppercase extensions, the 'ATTACHMENTS_FILE_EXTENSION_WHITE_LIST' must be edited.


1) Open the Octane Settings for Spaces.

2) Select the 'Default Shared Space' from the spaces column.

3) Select the 'PARAMETERS' tab.

4) Find the 'ATTACHMENTS_FILE_EXTENSION_WHITE_LIST' entry, and edit the file extension list, adding all uppercase extensions that need to be supported.

5) Use the 'Save' button to save changes.


See documentation for 'ATTACHMENTS_FILE_EXTENSION_WHITE_LIST' below.


		ATTACHMENTS_FILE_EXTENSION_WHITE_LIST
		
		Defines a list of the permitted extensions for file types for ALM Octane attachments.

		To permit all attachments, regardless of file extension, enter an * (asterisk). 
		For security purposes, this is not recommended.

		Separate each extension with a semi-colon (;).

		You cannot add extensions that are prohibited, as specified in the ATTACHMENTS_FILE_EXTENSION_BLACK_LIST configuration parameter.

		Note: 
		You can also add additional, custom file extensions to the list of permitted extensions for ALM Octane attachments. 
		The file types (mime types) must be one of ALM Octane's supported mime types, but you can choose any extension you like. 
		For details, see the EXTENSION_TO_MIME_TYPE and the VALIDATE_MIME_TYPE_MATCH_TO_EXTENSION configuration parameters.

		Type: string

		Default: 
		ngalink; links;
		jpg; bmp; png;
		pdf; word; doc;
		docx; msg; xml;
		xls; xlsx; ppt;
		pptx; zip; txt;
		wmv; mp4; m4p;
		mkv; vob; log;
		wrf; fbr; jpeg

		Customizable for: Both site and space
		

 

Syncing description field to Dimensions RM

Items created in Octane with no value for description will get value "null" from Dimensions RM description fields with the text "null"

 

Top

Technical Notes

Strict Association Between Stories/Sprints/Releases

In Micro Focus Octane, a sprint must be associated with a release and a story must be associated with a release before it can be associated with a sprint.

Other products are not strict about these associations.

In fact in some other products, stories are NOT associated with a release.

This strictness may cause problems synchronizing with other products.

Syncing parents of Stories

In Micro Focus Octane the parent field of a Story is a Feature type of entity.

If you wish to sync these relationships you need to map the parent field to the equivalent field that represents a Feature in the other connector.

Syncing parents of Features

In Micro Focus Octane the parent field of a Feature is an Epic type of entity.

If you wish to sync these relationships you need to map the parent field to the equivalent field that represents a Feature in the other connector.

Sprints and Releases

Micro Focus Octane requires Sprint items to be associated with a specific Release.

If the product that you are synchronizing with Octane does not support releases, you should configure the synchronizing of Sprint items to be one direction (from Octane).

Unique Names

Micro Focus Octane does not allow duplicate names for Releases.

Changing Your Read Only Rules

You can bypass any read only rules by dedicating a separate role for Connect and excluding it from those rules.

Create a new role named CONNECTROLE based on workspace admin and grant just that role without any others for the Connect token to the workspace you’re planning to sync.

Enclose any rules containing read only flag in parentheses and add the following statement:
AND Not("Current User Role" include "CONNECTROLE")

UserMap Entries

When synchronizing user fields with Octane, you will need to enter UserMaps via the Micro Focus Connect UI.

The user value that you specify for the Octane dataSource must match the email address visible in the Octane UI.

Requirement Parent

Octane requires that a requirement have a parent folder, and must have a folder at the root of the requirements.

You can set the default parent folder for requirements to which folder you require via Micro Focus Connect calculated value functionality

Comment Support

Comment synchronization is supported for all types except Releases and Sprints.

NOTE: The Requirement type does not support update or delete of comments.

Comment synchronization is controlled by three type specific properties for a data source.

From the data source TYPE tab; the properties are: Allow Comment Create, Allow Comment Update, and Allow Comment Delete.

When creating a comment, if a valid user is not specified via the User Mappings, the Connect User will be the author of the new comment.

To enable the updating and deletion of comments in Octane, the user configured in the Octane data source must have the "Synchronizer Service" role; which enables updating and deletion of comments authored by others - this is not set by default.

To enable this access right:

  1. cd to the directory where Micro Focus Connect is installed - by default: C:\Program Files\Micro Focus\Connect
  2. execute: jre\bin\java -cp WebServer\webapps\connectRest\WEB-INF\lib\*;AppData\connectors\mfcConnectorOctane\* com.connect.octane.OctaneServiceUpdateMain <host> <siteAdmin> <spaceId> <clientId>
    where <host> is of the form: http://localhost:8080, siteAdmin, spaceId, and clientId are the values from the datasource definition.
  3. Respond to the prompt for the site admin password.

Application Modules/AppModuleTree

The "Application Modules" field value within Octane is a tree. In prior releases, the value was exposed in MFConnect as an enumerated value containing only the leaf node names. This works fine as long as the leaf nodes are unique. In this release, MFConnect exposes the "Application Modules" with full paths to the leaf e.g. "Payroll->Reporting" instead of just "Reporting". The full path is exposed as the field "AppModuleTree". For backwards compatibility, MFConnect still supports both fields. But, new MFConnect users should prefer "AppModuleTree" over "Application Modules".

Non-Ascii Attachment Names

There is an outstanding issue in the OctaneSDK that causes synchronizing of non-ascii attachment files to fail in Micro Focus Connect. A work around for this problem is to perform the following steps:

  1. Go to C:\Program Files\Micro Focus\Connect\WebServer\bin
  2. Copy tomcat8w.exe as ConnectWebServerw.exe
  3. Launch ConnectWebServerw.exe (alternatively, start tomcat8w //ES/ConnectWebServer)
  4. Go to the "Java" tab
  5. In the "Java Options" append to the end argument list the following, every statement should be on a new line: -Dfile.encoding=UTF8

Milestones

In Octane, Milestones require a valid Release. To sync with systems that do not support Milestone to Release relationships use a Calculated Value. Configure the Calculated Value as follows, add Is New for the When component, Set field: Release, To Value: Release.1234. In this example the Release to be used has id 1234.

Creation Time

The Creation time property can now be updated in Octane. Previously, the property was read-only.

 

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