Confluence Basic Concepts

Jim Mason

https://www.atlassian.com/software/confluence

Key Points on Confluence

Wikis allow organizations and groups to benefit from rapid, secure collabortion of information that is easily created, edited and integrated with other resources
You have a variety of wiki choices, a number of which are a great fit to different use cases for organizations, groups and teams
Confluence is a popular, affordable, flexible, easy to use wiki that has both server versions and cloud versions
The wiki features are so easy to use, many users never both learning what other features Confluence offers
Confluence offers a good range of extension and integration options as needed
Sky Web Team provides support for a number of leading wiki solutions including Confluence

SWTR ranks Confluence as a "GOLD" rated wiki

The SWTR ( Sky Web Technology Rank ) of 8.5 is based on 4 summary factors scaled from 1 ( worse ) to 10 ( better )

Value - 9 for value ( combination of function, features, integration )
Cost - 7 for net costs ( combination of pricing, administration work )
Risk - 9 for low operations risks for users and administrators
Support - 9 for good product support, user input to Atlassian and an active user community with good tips

Wikis help solve information sharing problems for organizations and groups

What problems do wikis solve?

Maybe. There are many ways to share different types of information across organizations and groups including applications, databases, documents, shared drives, files, media, chat services and more.

Wikis provide organizations and groups a way to rapidly, securely collaborate different types of information that is easily created, edited and integrated with other resources. Many other solutions require more extensive training and expertise to implement ( Web and mobile applications, complex data analytics tool suites, databases etc ). Wikis provide a simple, easy way to

integrate those existing resources as a flexible, simple "front-door" for users to find and access a wide variety of information
add a variety of information and content types quickly by users without extensive training requirements
add new types of information with "low-code" frameworks for developers

Confluence makes it easy to see if it adds value for your needs

Wikis differ in features, technologies and costs. Some are open-source and free to download and use. Some are commercial with a variety of licensing models. Confluence offers a low-end free to see how it adds value to your teams. Unlike some "try and buy" products that are free for 90 days or a year, the Confluence free tier is permanently free so you can learn to use it on your schedule.

Most wikis offer a good variety of integration features for different information and content types right of out of the box.

In addition, good wikis offer both an active 3rd party marketplace with plugin applications to extend the wiki and a simplified development model to add your own application plugins. Confluence scores well here too.

The SWT Wiki Audit - Should your organization use wikis?

Does your organization need to securely integrate a variety of content across teams and groups internally or externally?
Is it easy to create and update new content quickly as needed at a low cost now?
Is it easy to maintain and manage an accurate history of the content changes over time?
Beyond chat and Web meeting video recordings, is there a good way to create and manage curated, searchable content easily for teams?
For major projects is there a solid way to integrate solution options, design documentation, decision history with feedback across all parties?
For on-boarding new members or updating member skills and knowledge, is there a productive way to do that effectively now?

Symptoms you may need a wiki

You have training sessions where developers show everyone how to regex your email or chat sessions to find answers to problems
Like Garth in "Wayne's World", our organization fears change
Your existing documentation for users and IT is often out of date
You failed compliance and change management audits
What your project teams define, developers build and users get trained on are out of synch
Projects and solution upgrades take longer than expected and it's not clear why

Some "wins" for wikis

Team Knowledge base

Problem - small staff with rapidly expanding technology needs

One IT infrastructure team I managed during a recession had a slow RIF ( Reduction In Force ) while we rapidly grew our servers and added new OS stacks to our backlog in addition to all the normal software maintenance, support, compliance audits and new projects. A challenge?

Solution - Knowledge base wiki

Yes. I created an "extended" wiki that used added plugins. All of our team work tickets and support tickets were reviewed against the team knowledge base. Initially there were few solutions there but we added and tagged our solutions going forward. It also offered quick dashboards with integrated SQL queries on our operating environments.

Impacts - With fewer staff expanded infrastructure technology capability 300% in 18 months

18 months later the team was smaller but our ability to cover a wide range of technologies productively had grown 300% - not a bad payoff ! Other teams also started using our knowledge base as well - a real win for the company.

Sharing content with local and remote users

Companies may not be setup to easily share content securely across teams. Internally, we were able to share content to authorized users quickly using the wiki.

Problem - on-demand content sharing

High volume data and document sharing applications are normally well engineered by organizations. Lower volume or on-demand sharing of content is a challenge

Solution - wikis setup easy on-demand content sharing with authorized users

Easy to setup a wiki space, add users and permissions for content upload and access

Impacts - where automated content sharing didn't exist, wikis provide another secure option

In minutes, users can setup secure content sharing

Voluntary Data quality, sharing supports the Information Maturity Life Cycle

Problem - too many spread sheets create too many versions of the truth

One company I worked at had solid "systems of record" and "trusted data stores" with many Web services and APIs, multiple databases to validate, ingest, integrate and distribute information centrally. Despite that, users created thousands of separate spread sheets. Every user had a different story to tell with different data at different ages. The problems getting useful answers were large. Rolling out an enterprise-wide data quality infrastructure initiatives isn't a quick project. It usually requires a culture change starting at the top as well.

Solution - voluntary data sharing with round-trip data stores

I offered a simple, self service data integration app in the wiki that authorized teams could access as a short-term alternative. Users could search the catalog of integrated data stores. If one didn't exist, they could submit a spread sheet that was validated and posted to a data store. When needed, users could edit the data directly or download the data again to a spread sheet and re-publish their data.

Impacts - natural data quality and efficiency improved informally

As users starting using this "round trip" process to search for data, download data if available and upload data if not available, the user teams gradually started reusing data, checking data quality and reducing data conflicts across teams. This "voluntary" data quality system paid off quickly. We improved data sharing, data services, data ownership and data qualtiy. Eventually, some of these data stores will "migrate" into formal "systems of record" with normal corporate data governance which is good. In the interim, voluntary data integration sources did improve data quality.

Does a wiki make sense for you?

You have many choices for wikis that fit different use cases. If you need help defining the value for your use cases and looking at candidate wiki solutions or getting started, let us know.

Confluence offers Multiple Versions

Confluence is a collaboration software program created by Atlassian. Like many wikis, Confluence makes it very easy to create and publish custom web pages. Confluence is developed primarily in Java. Wikipedia has a long list of wiki software that includes both open-source and commercial offerings.

Confluence has 2 licensed package offerings:

Confluence Server
1. a server version that a client licenses, installs and maintains
2. offers more features and more control over updates, potentially reducing runtime issues
Confluence Cloud
1. a subscription service with different subscription options including a low-end, free tier
2. a very easy, affordable way to get started with your own wikis

This overview is limited to the Cloud version.

Warning –

Any sample hyperlinks in this document that reference one of our sites ( skywebteam ) won't work since the site is not a public site. The urls are for reference only to show the format of the url to access a similar resource

Sample Confluence Web Page Layout

The pencil icon in the upper right allows a registered user with permission to edit the page or create a new one.

For long pages, you can add a Table of Contents macro control at the top of the page to generate a table of contents automatically from headings in content ( similar to Word docs )

The space header above includes ( from left to right ):

+ to create a new page ( if you have permission )
search box to enter either full text search through the site or a CQL query ( more about CQL later )
The bell icon indicates there is a notification available for this user from the site
The ? mark is provides help, keyboard short cuts and more
The gear icon allows a registered user to edit their personal settings
The JM circle shows the initials of the logged in user

On the page itself is the page header which includes:

A pencil icon ( if you have permission, click to edit the page )
An eye icon - click to watch this page, you will be notified every time someone else changes this page
The Share icon to email a link to this page to someone
The unstar message shows I have selected the star icon to make this page a priority in my searches
The 3 dot menu icon ( highlighted as selected ). Here the expanded 3 dot menu shows a dropdown of a long list of page options because I have administrator authority in the space. A user would have fewer options on the dropdown menu
1. Attachments (8) - on this page
2. Page History - view the history of changes to the page
3. .. more ( not shown here )

On the left, the hierarchical space page menu for this space shows on the left ( abbreviated here ) for easy navigation across the space.

The user can easily collapse or expand the left space page menu as needed.

Confluence Administration concepts

Confluence Sites and Spaces

When a Confluence license, you get an assigned Web address. In my case, the web site is: skywebteam.atlassian.net.

Spaces are a way to organize pages and content into logical categories that can be separately managed ( much like a simple, flat folder system ). Administrators can provide different access and permissions easily to a space. In addition, you can optionally set a space to public access allowing anonymous users access to the space.

Spaces ( and their pages can be imported, exported and archived. I can email you a small space with a few pages that an administrator at your site can import.

Confluence registered users

As a Web CMS ( Content Management System ), Confluence makes it easy for registered users with the right permissions to add, edit and delete pages

Confluence anonymous users

The Confluence Cloud paid licenses offer optional access to anonymous users. If I want to create a general knowledge base to share with anyone, I can set my Confluence site or an individual space to allow anonymous user access.

Admin Page showing Spaces and default permissions by role

Spaces are a convenient way to segregate content. The Space administration page below shows 3 categories of users:

Confluence users - normal users registered on the site
Administrators - manage the space
Site Administrators - manage all spaces on the site

In the page below, you can manage the specific permissions eacch role has on the space.

In addition, adminstrators can create individual spaces and set individual permissions

Confluence Support Page

https://support.atlassian.com/confluence-cloud/resources/

The Cloud version has a dedicated support page.

It covers a wide variety of topics: Getting Started, Organizing Work, Collaborating on Content etc.

Confluence Page Designer Options

Confluence Page Features

This article would go on forever if I detail all the options a Page Designer or Editor has to create content in Confluence.

Instead I'll only list the highlights and ask you to download the free version of Confluence to do more.

This is a list of features available that can be added or used on Confluence pages

Help and Ask the Community - ( I set a record on Ask the Community ). The help is easy to access and understand.
Admin Tools a wide variety of tools to manage spaces, the site, permissions etc
Spaces - separate users and pages logically into groups that can be managed for different users, permissions
Users - can be registered or anonymous. Registered users can be assigned a wide variety of permissions ( vs view for anonymous users)
Space permissions - define the basic roles in a space typically are: admin, editor, viewer
Space Page Templates - view default set, copy and edit one as needed or create your own
Blueprint Templates - add dynamic XML content to a web page - ( not as simple as other wikis = JSPWiki ) - Blueprint Developer Guide
Import, export pages from spaces - Administrators typically can export a space to the file system or import a space and it's associated pages from the file system
Managing Pages and parents - Pages can be created, deleted, moved, copied and archived
User Page actions - Registered users typically have permissions to view, edit, star, watch, share. Anonymous users can view pages
Page Title ( heading ), Page Table of Contents, anchor links,
Page comments - provide a permanent record of comments by registered users on page content including replies to comments
Labels ( Tags ) on a page - can improve targeted searches, create custom content menus using Content Report Table or Content by Label list
Space Searches - full text, labels ( tags ) or CQL queries for pages matching the search criteria
Page Searches - in most browsers, use Control F key combination to open a box to search the Web page for a string
Page Editor - ( WYSIWYG almost ) -- lists, indentations and more ( choice of New or Old version - see below for details )
Page history - imagine you made changes to page and deleted a section you later discover you need ( I did writing this article ). Wouldn't it be great if it were super easy to get the deleted content from Page History ? Yes - it was !
Links to any resources in wiki or other external resources by URL - links can be to uploaded attachments, external Web urls, other Confluence pages etc
Files - Documents, Images & Videos ( via url, attachments via upload or embedded via Google connector )
Tables - for content and layout
Controls - MANY - collapsible code block w syntax checker is one I use frequently to save real estate on long pages
Plugin apps usually have custom controls to add to a page
Team Calendar plugin - works well enough for most needs but is a billable plugin
Google Drive and Google Docs integration - great for teams doing RFCs, whitepapers, design docs etc that require frequent edits, changes ( see m Hyperledger Fabric Concepts )
https://marketplace.atlassian.com/apps/1213092/google-drive-for-confluence-official?hosting=cloud&tab=overview
https://support.atlassian.com/confluence-cloud/docs/insert-the-google-drive-macro/#GoogleDrivemacros-install
Drawing tools integration - draw.io, Lucidchart offer plugins

Confluence App Plugins

Confluence has many application plugins available that add new controls and features to Confluence pages.

Many are billable but there are some excellent free plugins that are very useful.

The Manage apps screen has "Find New Apps" link to search for more app plugins. It is available for an admin to searh and load app plugins.

Clicking the "Find New Apps" opens a page to search all the Confluence apps available

Some other Confluence Plugins that may add value

The site offers some plugins for email as well as calendars including Google Calendar and more.

Confluence Google Docs integration plugin

Google Docs has provided a free plugin that supports integration of Google Drive and the GSuite applications ( Google Docs, Slides, Sheets etc ).
You can present documents easily from Google drive within a Confluence page. Here's an example of a slide show in a Confluence Web page below.
While directly editing docs from Google drive is easy in a Web browser, IF you want to edit the document in the Confluence page you can do that directly as well.
There is a Confluence site that lists any known issues for the Google Docs plugin:
https://confluence.atlassian.com/confkb/office-connector-limitations-and-known-issues-170492994.html

Google Slides in a Confluence page ( Note you can EDIT in Confluence as well )

Google Sheet can be directly edited in Confluence page

Confluence Calendar Plugins

There are multiple calendar plugins available in the Confluence marketplace.

There are a few good candidates, one of which is lower cost than the others

There also is an option conceptually to embed an iFrame control in Confluence that calls a standard Google Calendar

Some calendars found in the Manage Apps Confluence Marketplace

https://marketplace.atlassian.com/search?moreFilters=free&query=calendar

The Google Calendar plugin is free but only works for the server version - not the cloud version

https://marketplace.atlassian.com/apps/231/google-calendar-for-confluence?hosting=server&tab=overview#

The Google Calendar plugin for the server version is referenced here:

https://marketplace.atlassian.com/vendors/1212722/servicerocket-labs

Google Team Calendars ( from Atlassian )

https://skywebteam.atlassian.net/wiki/plugins/servlet/ac/com.atlassian.confluence.emcee/discover#!/discover/app/com.atlassian.confluence.extra.team-calendars

This plugin is from Atlassian

While it is expensive ( about $30 per year per registered user ), there may be discounts for a non-profit organization.

This plugin has some constraints as well for Jira

Team Calendars for Confluence provides one place for fast-moving teams working in Confluence to stay in sync – so they know who’s doing what and when. Teams can stay organized and communicate availability with a schedule of personal and team events linked to their personal calendars and Confluence pages. Sync Team Calendars for Confluence with Outlook, Google Calendar (Android) and Apple Calendar.

Visit the Atlassian website to learn more.

Plugin Dependency - To enable the Jira Software integration features for Team Calendars for Confluence you must install the Team Calendars for Confluence for Jira Integration Plugin in Jira. This plugin is bundled in Jira 4.4.x and or later.

Google Calendar Page Macro

This app is billable starting about $.25 per month per registered user or less than $3 per year per registered user

After installing the app on a page, it shows either a 7 day or a 30 day list of events

If I select any event in the list, it opens a new window showing the standard Google Calendar with all the options I normally have.

Here, I can add subscriptions to other calendars, import calendar events etc - everything we normally do in Google Calendar

Overall not a bad solution and reasonably affordable compared to other Google Calendar plugins

Confluence Global Templates

Templates are pre-defined pages that can be used as prototypes across the site.
This screen displays the templates currently defined for the site. You can add a new template or edit existing ones.

You can see I credited a custom template ( Article template ). Confluence also comes with a nice set of pre-built
templates that you copy, customize etc.

When you create a new page you have the option of using an existing template

Confluence pages have a New editor and an Old editor

Generally, the editors are "almost" WYSIWYG ( What You See Is What You Get )

After editing a page, you "Publish" it to see the changes.

Atlassian has been working on the new editor for a while to make it useful.

The old editor used a plugin editor that is a widely used Web page editor for wikis.

By default, all pages have the new editor.

To use the old editor, you need to import pages from ANOTHER space that still has the old editor.

Confluence has been smart enough to allow users to use the old editor if they already have it

Editing a Table in the New Editor

When you create a page from a template, you are using the new editor.

To add a row to a table, you have to hover carefully over the plus sign and click to open up the next row

Editing a Table in the Old Editor

When you copy a page that uses the old editor, the new page has the old editor.

To add a row to a table, you just click the add row icon on the editor menu bar. Very fast to add or delete many rows.

Page Edit History - a great feature !

Here I've selected 2 versions of a page to compare and the view shows all the details of what was added, changed or deleted.

Confluence Search Query, Advanced Search and CQL - Confluence Query Language

The space header search bar

The search bar at the top of the space provides an easy way to enter a search string to show all pages that match to a degree in a hyperlinked results list. ( see the results list below )

Default Search Results

By default, you can enter a text string into the search bar for the space.

Confluence will search the spaces you have access to and build a results list of hyperlinked documents

You have an option to run an advanced search at the bottom.

Advanced Search

Using the advanced search button at the bottom of the search results list allows access to Advanced Search.

The filter fields are listed on the right side of the page.

Here, I entered a search for pages that have Grails label ( Tag ) on the page

You can see how well I can use page labels for targeted searches

CQL - Confluence Query Language

If you know SQL, you'll love the extra precision you can achieve using a CQL query. CQL

Similar to the filters page in advanced search, a user can enter a query using CQL - Confluence Query Language. CQL has a set of pre-built attributes similar to the advanced query form. This allows you to create a detailed query script that can used later by a user or via the Confluence REST API.

For details on the keywords and syntax in CQL, see these links

https://confluence.atlassian.com/doc/confluence-search-fields-161188.html

https://support.atlassian.com/confluence-cloud/docs/confluence-search-syntax/

Confluence Development Options

Development is easier with Confluence Server where a developer can have access to server logs on runtime errors.

In Cloud version, there is a simple failure message but you don't have full access to the runtime logs to debug issues.

Confluence Blueprints

Confluence Blueprints are a special type of Template that supports creation of dynamic content when the page runs.

Other wiki platforms offer similar dyanmic page loading development options.

A JSPWiki knowledge base I created had Javascript code that could query any JDBC database with a standard SQL

Select statement returning a scrollable data table. The plugin eliminated creating many custom report apps in typical BI tools

Create a simple Blueprint

https://developer.atlassian.com/server/confluence/write-a-simple-confluence-space-blueprint/

Confluence Developer Site

https://developer.atlassian.com/

The developer guide is the starting place to learn how to develop a Confluence app.

https://developer.atlassian.com/developer-guide/start-building-with-atlassian/

Who hosts the app?

If you build an app for a cloud product, then you'll be responsible for hosting your app, whereas on a server or Data Center product the app will be hosted by the customer.

At a glance

Cloud apps:

Can be written in any language
Hosted by the developer (you)
Interact with the product through REST and JavaScript APIs
Can access the public internet

The Cloud developer documentation includes API info

https://developer.atlassian.com/cloud/

Confluence REST API

https://developer.atlassian.com/cloud/confluence/rest/

This is the reference for the Confluence Cloud REST API. This API is the primary way to get and modify data in Confluence Cloud, whether you are developing an app or any other integration. Use it to interact with Confluence entities, like pages and blog posts, spaces, users, groups, and more.

NOTE: Personal data that is used to identify users, such as username and userKey, has been removed from the Confluence Cloud REST API. In addition, other personal data (for example, email) is now restricted by a user's profile settings (or in the case of managed accounts, the visibility settings decided by the site administrator).

For more on Confluence development, see