@backstage-community/plugin-search-backend-module-confluence-collator

Confluence Search Backend Module

This plugin provides the ConfluenceCollatorFactory, which can be used in the search backend to index Confluence space documents to your Backstage Search.

Installation

Add the module package as dependency:

# From your Backstage root directory
yarn --cwd packages/backend add @backstage-community/plugin-search-backend-module-confluence-collator

New Backend System

This backend plugin has support for the new backend system, here's how you can set that up:

In your packages/backend/src/index.ts, Add the collator to your backend instance, along with the search plugin itself:

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();
backend.add(import('@backstage/plugin-search-backend/alpha'));
backend.add(
  import(
    '@backstage-community/plugin-search-backend-module-confluence-collator'
  ),
);
backend.start();

Legacy backend

Index Confluence Spaces to search

Before you are able to start index confluence spaces to search, you need to go through the search getting started guide.

When you have your packages/backend/src/plugins/search.ts file ready to make modifications, add the following code snippet to add the ConfluenceCollatorFactory. Note that you can optionally modify the spaces or query, otherwise it will resolve and index all spaces and documents authorized by the token.

indexBuilder.addCollator({
  schedule,
  factory: ConfluenceCollatorFactory.fromConfig(env.config, {
    logger: env.logger,
    requestParams: {
      tagged: ['backstage'],
      site: 'confluence',
      pagesize: 100,
    },
  }),
});

Configuration

There is some configuration that needs to be setup to use this action, these are the base parameters:

confluence:
  baseUrl: 'http://confluence.example.com'
  auth:
    type: 'bearer' # can also be 'basic' or 'userpass'
    token: '${CONFLUENCE_TOKEN}'
  spaces: [] # It is highly recommended to safely list the spaces that you want to index, otherwise all spaces will be indexed.
  query: '' # If your spaces contain documents you don't want to index, you can use a CQL query to more precisely select them. This is combined with the spaces parameter above.

Documentation about CQL can be found here

The sections below will go into more details about the Base URL and Auth Methods.

Base URL

The baseUrl for Confluence Cloud should include the product name which is wiki by default but can be something else if your Org has changed it. An example baseUrl for Confluence Cloud would look like this: https://example.atlassian.net/wiki

If you are using a self-hosted Confluence instance this does not apply to you. Your baseUrl would look something like this: https://confluence.example.com

Auth Methods

The default authorization method is bearer but basic and userpass are also supported. Here's how you would configure each of these:

For bearer:

confluence:
  baseUrl: 'https://confluence.example.com'
  auth:
    type: 'bearer'
    token: '${CONFLUENCE_TOKEN}'

For basic:

confluence:
  baseUrl: 'https://confluence.example.com'
  auth:
    type: 'basic'
    token: '${CONFLUENCE_TOKEN}'
    email: '[e-mail]'

For userpass

confluence:
  baseUrl: 'https://confluence.example.com'
  auth:
    type: 'userpass'
    username: 'your-username'
    password: 'your-password'

Note: For basic and bearer authorization methods you will need an access token for authorization with Read permissions. You can create a Personal Access Token (PAT) in Confluence. The value used should be the raw token as it will be encoded for you by the action.

Search Schedule

By default the Confluence documents indexing will run every two hours. Here's how to configure the schedule:

search:
  collators:
    confluence:
      schedule:
        frequency:
          minutes: 45
        timeout:
          minutes: 3
        initialDelay:
          seconds: 3

Special thanks & Disclaimer

Thanks to K-Phoen for creating the confluence plugin found here. As an outcome of this discussion, he gave us permission to keep working on this plugin.