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 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? |
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.
The Micro Focus Octane Connector supports the following asset types
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.
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.
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.
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.
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.
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.
In Octane, Sprints require a valid Release. The Micro Focus Octane Connector will use this default
release if one is not supplied.
Only applies to 'Micro Focus Connect (MFC)' context type.
This property has been removed since version 4.5 for new data sources. However, if it was set in
a previous version, the property will still be present and used.
Since version 4.5, the Calculated Values should be used instead of this property.
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.
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.
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").
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.
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.
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 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.
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.
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.
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.
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.
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)
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
Items created in Octane with no value for description will get value "null" from Dimensions RM description fields with the text "null"
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.
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.
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.
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).
Micro Focus Octane does not allow duplicate names for Releases.
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")
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.
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 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:
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".
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:
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.
The Creation time property can now be updated in Octane. Previously, the property was read-only.
Get support enables you to open a support incident or to submit a bug. You can also browse many helpful support resources.