Introduction

ConnectALL supports syncing information from Atlassian Confluence. Below are some of the features that ConnectALL supports in syncing Confluence pages.

Create and update records in supported ALM/CRM systems from Confluence pages
Create and update records in supported ALM/CRM systems from table rows on a Confluence page
Update Confluence page properties and values in the table records on the Confluence page
Sync comments and attachments of the Confluence page
Filter pages to sync based on search fields and CQL
Poll the Confluence for page modifications based on the modification timestamp

Things To Know

If you sync updates to a Confluence page, the contents in the macro that are saved as CDATA are removed.
If you try to update multiple table records at the same time, some of the updates to the Confluence pages might fail due to versioning issues.
Confluence to Jira Issue linking will only work for the EPIC linking usecase and standard issue links will not be created as of date.

Configuring Confluence

For configuring the Confluence adapter you will need the below details

URL Confluence base URL, along with context if one exists.

Examples:
- http://localhost:4040 (without context)
- http://localhost:4040/conf (with context)
username should be of a space admin
The password of the space admin user
version 5.7+ accepts true/false values, and denotes the version of Confluence being used. This option plays a crucial role in deciding which API to use for reading and writing data.
More details on configuration option version 5.7+
Confluence application for version 4.x to 5.5 exposes the content using RPC api, and this will be added using a JSON-RPC plugin which can be downloaded from Atlassian Marketplace.
Confluence application for version 5.7 and above exposed all the REST API's used by ConnectALL, and hence if you are using the Confluence version 5.7 and above then set the value of Version 5.7+ as true. This will enable the users to add filters based on CQL and also use the streams instead of buffers while syncing attachments and hence uses less memory footprint.

Example:

Entity Mapping

Metadata

The Confluence adapter lets you create the field mappings based on existing pages using them as templates. The Entity Mapping screen of Confluence gives options displayed below.

Note: As displayed in the above image, only the content type 'Page' is supported.

Space

Space is used as a filter to restrict the pages being picked when querying for modified records, and ConnectALL will list the existing spaces in the dropdown for selection.

template

The template is a combo box where you can enter the PageID as a template to be used in the field mappings.

Q. what is a template page?

A template page is a Confluence page that is created using a Confluence template. Furthermore, this page should have all the headings, page properties, and tables that will be added to pages that are created from the same template.

A template page is used as a schema for identifying what content needs to be synced to the destination system for the pages alike.

Q. why do we need a page id?

A PageID is a unique key representing a Confluence page, and the content of the page can directly be referenced using this PageID. You can think of a page id as the "issueKey" of a Jira record.

Q. will this page be synced by ConnectALL?

A page will be synced by ConnectALL if and only if the page is under the "space" key selected and if all the "Filter Criteria" defined in the poll query match. So, no hard and fast rule says the template page will be synchronized by ConnectALL. Furthermore, a template page doesn't need to fall under the "Space" defined in the metadata.

content type

Content-type is a drop down which lists two options, "Page" and "Table". A "Page" type will populate the headings and properties as field mappings, while the "Table" type will populate the field mappings based on page properties and table column headers.

heading

The heading will be populated from the template page selected if the content type selected is "Table;" otherwise, the only option selected is "N/A". It defines from which heading the table records have to be synchronized.

Advanced Properties

Flow Filter

The Flow Filter is used to filter the records being synced from Confluence to other systems.

The format of the poll query is tightly coupled with the "Version 5.7+" configuration parameter. Due to the differences in the APIs used for retrieving the data, the filter queries are different for adapters with the "Version 5.7+" value set to true and false.

Version 5.7+ set to false: JSON-RPC API is used by the Confluence adapter and will use the Confluence search fields for filtering criteria. Confluence search fields available for filtering are listed here Confluence Search Fields

Only tested search fields are "labelText", "title" and "type"

Version 5.7+ set to true: REST API is used by the Confluence adapter and hence will use the CQL fields to filter the results.

In addition to the normal search field queries and CQL queries, ConnectALL provides a custom query language for advanced filtering of data based on the content, but it is advised to use the Confluence filters as much as possible to reduce the data transfers and cost of processing the content.

Custom query language

ConnectALL provides a custom query language for filtering the records to be synced based on the content of the pages. This feature enables you to control the pages and table records that need to be synced at the content level rather than the high level metadata.

First, let us observe a couple of use-case's and custom queries before going on the internals of the custom query language.

Usecase 1

User wants to sync pages that are having "label" value "requirement" having page property "sync enabled" with value set to "true" or if the "designer" property has any of value "john" or "jack" but not when "document status" property value is "draft"

Poll Query :

Version 5.7+ (false): labelText: requirement #PF# sync enabled[true] or designer[john,jack] and document status[^draft]
Version 5.7+ (true): labels = requirement #PF# sync enabled[true] or designer[john,jack] and document status[^draft]

Usecase 2

User wants to sync table records from pages that are having "label" value "requirement" having page property "sync enabled" with value set to "true" or if the "designer" property has any of value "john" or "jack" but not when "document status" property value is "draft" or "review" and the table records with table column"sync" value set to "enabled" or if the "remote key" is "N/A"

Poll Query :

Version 5.7+ (false): labelText: requirement #PF# sync enabled[true] or designer[john,jack] and document status[^draft] #TF# sync[enabled] or remote key[N/A]
Version 5.7+ (true): labels = requirement #PF# sync enabled[true] or designer[john,jack] and document status[^draft] #TF# sync[enabled] or remote key[N/A]

Query Language semantics

Custom filter query should start with #PF# or "#TF#"
Regular query should precede #PF# query and #PF# filters should precede #TF# (ordering cannot be changed)
Conjunction operators supported are and and or only
Filter condition semantics for each operation
- Equals: if your condition is field1 == value then the query is written as field1[value]
- In: if your condition is field1 in (value1, value2) then the query is written as field1[value1,value2]
- Not Equals: if your condition is field1 != value then the query is written as field1[^value]
- Not In: if your condition is field1 not in (value1, value2) then the query is written as field1[^value1,value2]
Conditions are evaluated from left to right
An and condition followed by a sequence of or conditions are considered alternatives of the and condition
Ex: if your query is a[x] or a[y] or a[z] and b[1] then all records with a having values of x or y or z and having b value as 1 will be returned
A field name can have spaces and special characters but not the reserved words and and or

Field Configuration

ConnectALL populates the field grid, by parsing the Confluence page in the template and the content-type chosen in the Automation Properties section of "Entity Mapping" tab.

Page Properties and Table columns are marked with "Editable?" as true and the rest of the fields are not editable by ConnectALL

When syncing the table record information, in addition to the table columns user can also sync the information in page properties of that page along with the other standard fields like UpdatedBy and CreatedBy etc., While the page property values will not be updated when syncing the records of a "Table".

Assumptions

As the content stored in the Confluence pages is raw text, ConnectALL will assume some semantics for parsing the content and is documented below. These assumptions are documented based on the user's record type/content type.

Content type (Page)

Page-level records will expose the "Page Properties" and "Headings" as field names for mapping in addition to standard fields.

Page Properties

Page properties is a macro in Confluence, the earlier versions of Confluence also called this macro the "Details" macro. This macro exposes a container for data, where you can have a table or raw text. Currently, ConnectALL supports only this macro.

For ConnectALL to read the data properly, it expects

only a table is defined under the macro
the table is a two-column table with any number of rows
the first column of the table in any row will be a header cell (<th>) and is referred to as "Property Name"
the second column of the table in any row will be a data cell (<td>) and is referred to as "Property Value"
you can have any number of page property macros in the page
all the names of the properties are unique

Example:

Heading

Headings of a Confluence page are used to separate sections of text, and ConnectALL lets you sync the content under these headings as values to destination systems. There are a couple of assumptions for parsing the content under headings.

headings of a page are created using the "Heading" formatting style and not by font size
no additional formatting to be done on the heading text
no two headings have the same name
if sub-headings exist, then the content is parsed only till the beginning of the sub-heading.

Content type (Table):

Table-level records will expose the "Page Properties" and "Table columns" as field names for mapping in addition to standard fields.

Assumptions for the page properties are similar to the ones defined above.

Table Columns

Parsing and updating the values of a table is more tricky, and hence ConnectALL assumes quite several semantics to be followed for syncing the information without any deviations. It is mandatory to have an auto-sequencing column at the beginning of the table. This sequence number will be concatenated with the PageID to create a RecordID that can be synced to the destination system.

A numbering column should be added to the table as shown below (How to add a numbering column for a table?)
The number of columns in any row of the table should be the same
there should not be any merged columns or rows
Once the table record is synced the sequence no. of that row should not be changed
All the columns in the first row should be header ("<th>") cells
All other cells in a table other than the ones in the first row should be data ("<td>") cells
There should not be any content between the table and the heading

Example:

Known Issues

If you sync updates to Confluence pages, the contents in the macro that are saved as CDATA is being removed.
If you try to update multiple table records at the same time, then some of the updates to Confluence pages might fail due to versioning issues.
Confluence to Jira Issue linking will only work for the EPIC linking usecase and standard issue links will not be created as on date.

Time Difference Configuration

To know how to calculate the time difference, and configure it in the ConnectALL UI, read the topic Time Difference Configuration.