This readme describes how to configure Micro Focus ALM Connector. Refer to the Micro Focus Community and Micro Focus Connect Help Center for further configuration instructions.
The Micro Focus ALM for Micro Focus Connect (Micro Focus ALM Connector) lets you synchronize ALM assets like Requirements and Tests 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 ALM 17.0.1 and ALM 24.1
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.
This version of the connector supports Requirements, defects and test asset types, as well as custom fields.
This connector requires at least build 24.1.1 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 for Micro Focus Connect to see changes in ALM assets, you must enable History setting for the fields in the asset types you plan to synchronize. Refer to ALM documentation for latest method of activating history.
The Project Customization window appears.
The Project Entities page opens.
The following information contains notes regarding installation, but does not replace the entire process.
A Note About Micro Focus ALM Data Sources
Because a Micro Focus ALM Connector data source is associated with a single project, you will need to create multiple data sources for your Micro Focus ALM Connector if you are synchronizing multiple projects.
In order to use this connector, you will need to collect and enter this information in the Micro Focus Connect user interface:
Users can also provide ALM client id/secret instead of user name and password, if available.
Based on the types being mapped, the fields below may be required:
Required if you are syncing Requirements, determines the topmost folder that contains the Requirement items, typically set to Requirement (0)
Note: If you do not want to include the root requirement folder, you can set the Connection project path property to be the same id set here. The value must be an id of a parent requirement. The value of the property “Requirement Parent Folder ID” in the ALM datasource settings must be the same or a child of the one defined in the connections project RootPath.
Required if you are syncing Release-Cycles, determines where Release-Cycles are placed on create if a Release is not specified.
Required if you are syncing Tests, determines where New Tests are placed when created in ALM. Tests are not surfaced by the connector as hierarchical. This property will not act as a filter to constrain the tests that are returned by the connector.
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.
This property is disabled in current version of ALM connector.
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.
Customers can configure specific fields to be "unique". If a field is specified to be unique, then MFConnect can use that field's value to detect when new items on both sides are equivalent. When MFConnect detects equivalent new items on both sides, it will NOT create duplicate items. Instead, it will record that these new items are synchronized. This feature was added so that customers can specify that Release:Name is unique. That field can be considered unique for some customers that place all of their releases in the same folder.
If you are synchronizing release-cycles, and your release-cycle.name values are NOT unique, you can use the release-cycle.uniqueName field instead. The value of this field includes the parent release and associated folders and is therefore unique.
The "req-rich-content" field within requirements functions differently than other RICH_TEXT fields within HPALM (e.g. the "description" field). A future enhancement will correct this problem.
When building the relationship mapping for Requirements, in order for Atlas to recognize the Requirement Traceability traces the “rel.a.has-dependent-requirement-reverse.requirement” property must be used.
If using Versioning in ALM, you may see issues updating images and rich text.
If mapping a description to a non-HTML field, change the HTML to Plain setting on the field in the type mapping as Target is HTML.
ALM doesn't surface the history for types: Release, Release-cycle, Test-Step, and Run. Bi-directional mappings for these types will result in the value from ALM overwriting the value on the other side.
Users can create requirements/changeRequests without a priority. Priority is an enum field. Typically enum fields have one of the valid values. If you are synchronizing requirements/changeRequests to a product that requires valid enum values (e.g. TFS), the synchronization will fail. The workaround is to update the requirements/changeRequests with a valid enum value.
Currently setting only a single Release or Release Cycle as a value is supported. This will be fixed in the next release.
The following fields when Required will have below default values for the given types:
Some of the above fields by default are not Required, and therefore no default is set. For example, the Requirement owner by default is not a required field. For all default values, any mapping or calculated value will override these values.
It is possible that multiple connections are visible in the Site Admin Connections Tab.
Those connections are reused and will normally time out after an hour of inactivity.
Every effort has been made to close unused connections.
The number of connections shouldn't be growing and should generally be steady without impacting server performance.
Deletes in Micro Focus ALM cannot be detected by the connector.
When an item is deleted in Micro Focus ALM, the corresponding item in the other product will not be deleted.
Some customers have thousands of these items. So, MFConnect cannot retrieve them all in a timely manner. Instead, MFConnect retrieves a subset of the items. If you don't see the value you desire in the "pull-down" menu, you will need to type in the "id" of the desired item. You may need to select a folder in the ALM UI and copy the URL to see the "EntitytID" which is required by MFConnect.
When the sync criteria top level operator is AND and the below conditions use properties which are single valued Enum, String, Date, or User types and the conditional operators are "=" then a server side filter will be generated. Additionally if the property is ID or the property is a Date, then the operator can be a relation operator (<, <=, >, or >=). A server side filter will not be generated if the top level logical operator is something other than AND. If a statement beneath the AND is a logical statement it is ignored. If the statement is not one of the requirement property types or does not use the required conditional operator then it is ignored. With debug logging on, review entries related to 'convertSimpleSyncCriteriaTermsIntoQueryTerms' to determine the extent server side filtering was used. Even if statements are ignored a partial filter will be generated. For all retrieved items, the entire sync criteria will be evaluated against each item regardless of which statements of the sync criteria were used in the filter (if any). A server side filter will result in better performance due to the ALM server evaluating the sync criteria and returning less data to MF Connect.
The ALM QC "favorite" filter criteria for date and datetime fields keep the dates in a client (Web Browser / OS) locale-specific format. This format however may be different from the format required in ALM QC REST requests. At the moment there is no reliable way for MF Connect to determine this format.
Workaround: When selecting a named filter, its content should be copied into a free-form filter replacing
non-compliant dates with dates in the following format (<year>-<month>-<day> <hour>:<minute>:<second>).
For example: 2021-01-02 01:02:03; 2021-01-02
ALM/QC exposes field labels in the UI. But, the REST API requires field names in queries. If you see a stack trace containing "Unknown field name in query", it is likely that your query contains a field label instead of a field name. We recommend that you use named filters instead of "free-form" filters ("favorites") because the ALM/QC UI will resolve field name/label problems for you. Also, you can verify your named filter in the ALM/QC UI.
The Requirement, Release-Cycle, and Test Asset Types in ALM must have a parent. If your connection only synchronizes items to the configured "Default Project", Micro Focus Connect will use the DataSource properties to determine the parent (see "Requirement Parent Folder ID", "Cycle Parent ID", "Test Parent Folder ID"). But, if your connection synchronizes items to projects other than the "Default Project", Micro Focus Connect must determine the parents using alternative mechanisms:
Because ALM does not modify an item when a link/trace is deleted, it is suggested the relationship fields are mapped one-way. If they are mapped bi-directionally, when making a change to an link in an ALM item, you should make some other change that will cause the modify time to change. Not doing this could result in Micro Focus Connect updating the changed ALM item with the value from the other side.
Comments are synchronized using the Related Comments field. Comment syncing is supported for Requirements, Tests, Defects and Runs. Comment functionality is controlled via type specific properties on the datasource properties TYPE tab - Allow Comment Create and Allow Comment Update. Micro Focus Connect currently only supports synchronizing new Comments from other connectors. It doesn't support updates or deletion of comments from other connectors. ALM comments are stored in a single Rich Text property. Connect expects this property to have the format generated by ALM even though ALM allows unstructured editing. The comment text is expected to follow the generated user name / date stamp. Text not following a user name / date stamp will be ignored.
Several changes to properties have been made that will require existing DataSource definitions to Apply the Default Model within the datasource definition. However, if you customized the model, then it may be simpler to apply the changes as described below. Making no change will result in a failure to start a connection and the connection status becoming "Disabled". The exact error is "Field(s) in relationships are invalid, you need to update the datasource relationships." The following changes have been made:
The properties target-rel and target-rcyc will only support a single value, even though in the ALM UI, multiple values are supported.
Default behaviour in Requirement determining as the same object is changed. Field name in Requirement used to be unique and to be key during sync. But now it is Known that this field is unique only for one level of hierarchy. So now default unique behaviour of field Name of Requirement is turned off. If you want to use uniqueness of Requirement Name field, you should fullfill DataSource property "Force Fields to be Unique" with value: Requirement:Name.
Get support enables you to open a support incident or to submit a bug. You can also browse many helpful support resources.