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.
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>
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:
- 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
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
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
_lastauthorto reference the last author of the page and_creatorto reference the first author of the page.
A list of regular expressions that are matched against all document paths. If a pattern matches, that document will be excluded from notifications.
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
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.
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