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
- 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.
For configuring the Confluence adapter you will need the below details
- URL Confluence base URL, along with context if one exists.
- 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.
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 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.
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 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.
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.
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.
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]
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#filters should precede
#TF#(ordering cannot be changed)
- Conjunction operators supported are
- Filter condition semantics for each operation
- Equals: if your condition is
field1 == valuethen the query is written as
- In: if your condition is
field1 in (value1, value2)then the query is written as
- Not Equals: if your condition is
field1 != valuethen the query is written as
- Not In: if your condition is
field1 not in (value1, value2)then the query is written as
- Equals: if your condition is
- 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 bthen 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
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".
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 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
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.
- 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
- If you sync updates to Confluence pages, the contents in the macro that are saved as
CDATAis 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.