Skip to content

Latest commit

 

History

History
97 lines (60 loc) · 4.46 KB

README.md

File metadata and controls

97 lines (60 loc) · 4.46 KB
Raw

confluence-outdated - Constant validation of Confluence document outdates

Docker

Introduction

confluence-outdated searches a Confluence space for documents that haven't been updated for a specified time and notifies the author of the last version of each document or a separate page maintainer.

Usage

confluence-outdated can be used with Docker to quickly run it without any further dependencies.

docker run --rm -it ghcr.io/dodevops/confluence-outdated:main <arguments>

Configuration Document

confluence-outdated needs several things configured before it can start working. To simplify this, confluence-outdated reads its configuration from a Confluence document.

The structure of this document is based on Panels and tables. To ease the creation of this document, confluence-outdated includes a command to create a template document:

confluence-outdated CreateConfigurationDocument --url <Confluence base URL> --user <Username> --password <Password> --space <Key of space that should hold the document> --title <Title for the configuration document> --parentId <Page ID that the configuration document is place under>

Example:

confluence-outdated CreateConfigurationDocument --url https://example.com/confluence --user somebody --password secret --space CM --title "My configuration document" --parentId 12345

The command will output the page ID for the configuration document and a link to it.

The configuration is based on several panels. The configuration for the different panels is as follows:

Panel "Configuration"

  • Space: The key of the space where confluence-outdated should check for outdated documents
  • Domain: A default domain, that will be appended to all author usernames (should be set if the usernames aren't email addresses themselves)
  • NotificationFrom: <The address used as the sender in the notification mails

Panel "Checks"

A table of checks that will be carried out.

  • Labels: A list of all labels (separated by ,) that a checked document has to match
  • MaxAge: The maximum age of a checked document. If a document was modified before that, a notification is send

Panel "Maintainer"

A table of maintainers for pages.

  • PagePattern: A regular expression that is matched against the full document path. Parent pages are separated through a "/".
  • Maintainer: The users that should receive all notifications for pages matching this pattern (separated by ,). You can use _lastauthor to reference the last author of the page and _creator to reference the first author of the page.

Panel "Exceptions"

A list of regular expressions that are matched against all document paths. If a pattern matches, that document will be excluded from notifications.

Panel "Notification Template"

This panel includes two child panels which hold Handlebars templates for the subject and the body of the notification mails.

They will be provided with the following context:

  • author: E-Mail address of the recipient
  • documentsCount: The number of documents that are outdated for this recipient
  • multipleDocuments: A boolean whether there are multiple documents or just one
  • documents: An array of this object

Usage

After the configuration document is properly setup, run confluence-outdated on a regular basis:

confluence-outdated Check --url https://example.com/confluence --user somebody --password secret -i 123456 -s "smtp://localhost:25/?ignoreTLS=true"

This will fetch the confluence document with the id 123456 as the configuration and check all required documentation as configured. The SMTP url is based on the nodemailer smtp transport.

Development

The tests subdirectory contain unit tests run by mocha for all parts of the api. If you want to help developing, please follow the following workflow:

  • Create an issue describing the bug or feature
  • For this repository
  • Create a branch named "issue-"
  • Write a test that tests the feature or bug
  • Run the test => the new test should fail
  • Write or fix the code for the change
  • Run the test again => the new test should succeed
  • Push and create a pull request

To test and build this package, simply use grunt:

grunt test