Introduction

ConnectALL supports syncing information from Atlassian Confluence. Listed 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 in 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 modification timestamp

Things To Know

  1. If you sync updates to a Confluence page, the contents in the macro that are saved as CDATA are being removed. 
  2. 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. 
  3. Confluence to Jira Issue linking will only work for the EPIC linking usecase, standard issue links will not be created as on date. 

Configuring Confluence

For configuring Confluence adapter you will need the below details

  • URL Confluence base url, along with context if one exist. 
    server base url
    Examples:
  • username should be of a space admin
  • password of the space admin user
  • version 5.7+ accepts true/false values, denotes the version of Confluence being used. This option plays a crucial role in deciding which API to use for reading and writing data. 

    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 off existing pages using them as templates. The Entity Mapping screen of Confluence gives options to select the below metadata.  


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 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 "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 "space" key selected, and if all the "Filter Criteria" defined in the poll query match. So, there is no hard and fast rule that says the template page will be synchronized by ConnectALL. Furthermore, a template page doesn't even 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 has 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 API's used for retrieving the data the filter queries are different for adapters with "Version 5.7+" value set to true and false. 

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

(warning) Only tested search fields are "labelText", "title" and "type"

(info) 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 : 

  1. Version 5.7+ (false): labelText: requirement #PF# sync enabled[true] or designer[john,jack] and document status[^draft]
  2. 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 : 

  1. 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]
  2. 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 Integration 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, 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 under. These assumptions are documented based on the record type/content type chosen by the user.

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 as "Property Name"
  • the second column of the table in any row will be a data cell (<td>) and is referred 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 a number of semantics to be followed for syncing the information without any deviations. It is mandatory to have an auto-sequencing column in 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 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 first row should be data ("<td>") cells 
  • There should not be any content between the table and the heading

Example: 

Known Issues

  1. If you sync updates to Confluence pages, the contents in the macro that are saved as CDATA is being removed. 
  2. 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. 
  3. Confluence to Jira Issue linking will only work for the EPIC linking usecase, 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.