Readme for Micro Focus Connect Confluence Connector 24.2

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

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

Copyright

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 Confluence (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

This version of the connector supports common Confluence asset types, such as page, comment, and attachment.

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 following are required to run the Connector. For further configuration instructions, see the Micro Focus Connect Release Notes.

Create a Connector directory. For example: C:\Program Files\Micro Focus\Connect\AppData\connectors\mfcConnectorConfluence

NOTE: If this is being installed into an existing connector directory, you must remove the existing mfc*.jars

Copy the following libraries (and the provided Connector jar, and the provided mfcConnectorUtil jar) into the connector directory you created.

Confluence Setup

Your Confluence space should have "User Created" templates configured, see the example templates below.

Once you create the custom User Template, make sure to attach a label to the template (example: "epic-feature" to be attached to Epic custom User Template).

This label will be auto-attached to new pages based on the template, and will be used to fetch such pages to sync.

You will see the label in the "Label" dropdown list when creating Data Source.

User Templates can be created under: Space Settings / Content Tools / Templates

Epic This template configures Epic as Type and Feature as SubType.
Requirement This template configures Requirement as Type and Story as SubType
Story This template configures Story as Type and Task as SubType

User Created Templates

Use the "Create New Template" button to create your new user defined template.

Do these steps after you have created a template.

Use the edit pencil to add a "Description" for your template.
Use the Promote link to move your template up in the Templates list.
Use the Edit link to change your template.

Creating a new Template

The "Page title" becomes the item type of your new entity:
The "Page title" will also become a rich text syncable field named "Title".
Add a "Page Properties" table for defining your entity fields.
Place your cursor below the "Page title" and use the icon to add a table for your entity fields.
Your entity fields table should have 2 columns, left column wil be the field name, right column will be for the field value.
Add your list of entity fields.
You should have something similar to this example:
Select your table and bring up the table options, select only the "Header column", if this step is omitted, your entity fields will not be known to Micro Focus Connect.
Table options:
In the area below your page properties, you can add any number of rich text entity fields. These fields will be available to Micro Focus Connect.
Leave a blank line between your rich text fields. Use the "Text styles" control and select "Heading 2" for all of your rich text fields.
Rich text entity fields example:
If you want a entity sub-type, add a text line below your rich text fields, and enter [TYPE] {Sub-Type-Name}, where {Sub-Type-Name} is the name for your entity type.
Be sure to use the "Text styles" control and select "Heading 2" for the entire "[TYPE] {Sub-Type-Name}" line.
Next, use the icon to add a table below the sub-type declaration.
The sub-type table should be one row. Each column will be a sub-type entity field.
The first column of the sub-type table must be a field named "Auto-generated Sync ID". The field value will be auto-populated by Micro Focus Connect.
Example sub-type definition:
Select your sub-type table and bring up the table options, select only the "Header row" and "Header column" options.
Sub-type table options:
Use the "..." and select "Add labels":
Give your template a unique label. You will refer to this label when creating a data source.

Epic Template Example

Requirement Template Example

Story Template Example

Confluence User Permissions

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

Read Spaces and its contents
Read Blueprint templates and custom templates
Read Space and Template labels
Create rights on page, comment, and attachment.
Update rights on page, comment, and attachment.
Browse users on a give space.

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:

URL - Enter the Confluence URL to connect to.
User Name - Enter the user name.
Password - Enter the password/API token for the user. We recommend using Confluence API tokens instead of clear passwords. Some Confluence servers only support API tokens for REST access.
Space - You must select a space name when configuring a Confluence Data Source.
Template - You must select a template name for which you plan to use.
Template Label - You must select, or enter, a template label name. Template Labels are attached to the pages targeted for sync, example 'epic-feature'.

Top

Known Issues

Changing Page Types Not Supported

Changing of Page types (e.g. from a Story to an Epic in Confluence) is not currently supported.

Moving a Page under another Page will not be detected

If a user changes the parent of a Page, this will not be detected by Micro Focus Connect. The user will need to change some content of the Page as well.

Optional Connection Information

Include comments since date (yyyy-MM-dd)

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.

Top

Technical Notes

Discovery and Synchronization of Items

Micro Focus Connect relies on Confluence Rest API to search, read, update, create, and delete Confluence items. CQL is also used through Confluence Rest API calls.

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 ...".

User Maps for Confluence

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

Data Source Setup

The number of 'Space' values in the drop down list is limited to 500. Spaces not in the list can be entered in the format as those listed, 'space key:space name'

Mapping Rich Text Fields to and from Confluence (outgoing)

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

Mapping Rich Text Fields to and from Confluence (incoming)

Micro Focus Connect leverages the Atlassian wiki renderer used by Confluence 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 Confluence as plain text.

Attachments and Comment Support

Attachments and Comment syncing is available for Pages. In Confluence, adding, updating, or deleting a comment or attachment doesn't change Page modified time. Based on this, MF Connet won't be able to sync any changes in Comments or Attachments until the page is modified.

Invalid values in data source properties can show as greyed-out italicized text

The Space value format consists of 'space key:space name', example: 'CON:ConfluenceConnect'. Normally in the Connect UI, only the 'space name' will be shown.
The Template value format will consist of the 'space key:template name:template id', example: 'CON:Epic:82346010'. Normally in the Connect UI, only the 'template name' will be shown.

Property Type Discovery for Dates and DateTimes

The connector uses the name of the property to determine if it is a LocalDate or a ZonedDateTime field. If the property ends with "date", e.g. Due Date, then it is recognized as a LocalDate type. If it ends with "time", e.g Completion Time then it is a ZonedDateTime type. LocalDate types use the format YYYY-MM-dd for input. ZonedDateTime types use the format YYYY-MM-dd HH:mm:ss-XX where XX is the GMT offset. For example, 08 is the offset for PST. If the property name doesn't end with "date" or "time" the contents can still be synced into a LocalDate or ZonedDateTime property on the opposite side of the sync. The only difference is ZonedDateTime is parsed using DateTimeFormatter.ISO_ZONED_DATE_TIME - which requires .AAA following the seconds indicating the milliseconds.

Type (Page)

Type is a Confluence Page, and creating a type object is like creating a page. The name of the type object will be Page title.

Type Properties (String datatype)
Type properties are treated a String fields, and are entered into Confluence Page as headerless vertical two column table, the first colum is for property name, and the second colum is for property value.
Type Properties (Rich Text datatype)
Type properties which are entered under h2 header in Confluence Page, are treated as Rich Text fields. Such field must be outside the headerless table mentioned earlier. Any content below h2 header will be included into Rich Text property value until next h2 header is detected.

SubType (Custom)

SubType is entered into Confluence page as following:

SubType name should be entered as [TYPE] {TYPE_NAME}, example: [TYPE] Story
SubType should be H2 header
SubType properties are always String fields and definded in a table with two colums, at minimum, header. The first column name must be: "Auto-generated Sync ID", and this is a read-only property, no users can modifiy it's name or value. The second column is a property name of a SubType property (example: name).
The "Auto-generated Sync ID" is managed by the Connector, and it will assign a sync id once the sync starts
SubTypes and SubType records can't be moved across Confluence Pages

Modifying Property Name

Modifying a property name after a type (page) or Subtype are created, will cause that property not to be synced. In case, you want to change the property name, then first you need to do so in the Template, then update the mapping in Connect, and finally update the property name in the existing pages.

Bi-directional Syncing

The Confluence Connector does not use history to determine if a property has changed. This can result in fields synchronizing in the wrong direction.

Instead the Connector simply uses if the page update time has changed since the stored watermark ( which in most cases is the last synchronization time ). During a synchronization, the Connector will report that each property was last updated when the page was last updated. This may result in Confluence values overwriting values from the Other side when both sides have changed and the Confluence item was changed more recently, even if the change to the Confluence item was not to the specific property being synchronized.

Non ASCII Attachment Names

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

DEFAULT_HTTP_READ_TIMEOUT_MILLIS

MF Connect uses a read socket timeout of 300000 ms (5 minutes) and this value cannot be updated

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