Learn all there is to know about the Confluentis Unused Attachments add-on for Atlassian Confluence.

Installation

Confluentis Unused Attachments is an add-on for Atlassian Confluence. It helps Confluence administrators find unused attachments which are never referenced with a link or never embedded as images into any page, blog post or comment from any of the spaces in the current Confluence instance.

It can be downloaded from the Attlassian Marketplace and installed using the Universal Plugin Manager of the target Atlassian Confluence server instance.

TRY IT FREE 

Search for unused attachments

Confluentis Unused Attachments plugin adds a new Unused Attachments menu option in the Administration section of the Confluence Administration console.

General Configuration Menu Option
General Configuration Menu Option
Unused Attachments Menu Option
Unused Attachments Menu Option

This administration menu option gives access to a search screen that can be used to launch the unused attachments search operation and then view the search results.

Unused Attachments Search Tab
Unused Attachments Search Tab

When pushing the Find button, a long running background task is launched which iterates through all the pages, blog posts and comments from all the spaces in the current Confluence installation to look for both attachments and attachment references. The program adds each attachment found to the list of possible candidates and removes the attachment from that list when it finds a reference to it either in the same page or any other page, blog post or comment from the current space or any other space. At the end of the iteration through all pages, blog posts and comments from all spaces, we are left with a list of unused attachments.

This in-memory list of unused attachments is displayed in a table on the same admin page, once the search background task has been successfully completed.

Unused Attachments Search Results
Unused Attachments Search Results

Both the search background process and its in-memory result are unique within the Confluence instance and all administrators see and interact with the same entities, regardless which administrator account they use or regardless of whom has started the search process. If the process has been started from one administrator user session and is currently in progress, this can be seen running and can even be cancelled by any other administrator entering the screen from a different user session. Once the search process completed and the in-memory list of unused attachments built, it is available and can be viewed by all administrators entering the administration screen from any user session.

Search results update

It takes some time to search for unused attachments because all content needs to be processed: all pages, all blog posts and all comments from all spaces are inspected for both attachments and attachment references. During the search, and more likely after the search has finished, some of the processed content might have been modified, or removed, while new content might have been added. Because of this reason, the in-memory list of unused attachments might not be 100% accurate by the time it is viewed/used.

Once the in-memory list of unused attachments has been produced by the search process, it is kept up to date by listening to content modification events.

The only purpose of listening for these events is for taking attachments out of the list in case they become referenced by links or embedded as images in the newly added/modified content. This is because it is not possible to add new attachments to the list of unused attachments just by processing the newly added/modified content. It is not possible to tell if an attachment became unused just because references to it were removed in a certain modified page. It can still be referenced from other pages and only processing all content as a whole could lead to it being considered unused or not.
For example, the plugin does not listen for attachment creation events because we can’t guarantee that there is no preexisting invalid attachment reference that gets fixed by the current attachment upload (see Known Limitations).

The good thing about all this is that although the list of unused attachments is not always 100% accurate, the only risk is about it not displaying some attachments that became unused after the list has been created by the thorough search process.
There is never the risk of the list showing a false positive, meaning showing an attachment that is actually used.

The plugin listens only for the following types of content modifications events:

Pages, blog posts and comments being created, updated or restored

When such content modification event occurs, the plugin looks for attachment references in the new content and removes the respective attachments from the current list of unused attachments, if it’s the case.

Spaces, pages, blog posts and attachments being deleted

When a space, page or blog post is deleted, all the attachments that belong to them are taken out of the in-memory list of unused attachments, if found in-there. Deleting a space is an operation that cannot be undone, but pages and blog posts are placed in the Trash area of the space when deleted. This means they can be restored from Trash later, but when restored, we do not put back the unused attachments in the list.
Restored pages and blog posts are processed only to check for attachment references and thus for further eliminating unused attachments from the list, as mentioned above.
Obviously, when an attachment is deleted, it is automatically removed from the in-memory list of unused attachments, even if in recent versions of Confluence, a deleted attachment is first placed in the space Trash, with the possibility of it being restored from there. But restoring an attachment does not put it back into the list of unused attachments and in order for that to happen, a new search for unused attachments operation has to be performed from scratch.

Pages, blog posts and attachments being moved

The in-memory list of unused attachments is organized by space, to facilitate filtering of results when displayed. We need to listen for these content move events to make sure the list is still accurate, even if unused attachments are moved from one space to another.

Spaces, pages, blog posts and attachments being labeled

The plugin allows ignoring unused attachments that are placed inside spaces, pages or blog posts having certain labels. This is useful for example if there are pages or spaces which act like repositories for files and the attachments in them do not necessarily need to be referenced anywhere. Marking these spaces or pages with special labels helps filter them out from the list of unused attachments.
Also, labels at individual attachment level can serve the same purpose of having the respective attachments ignored by the search process.
The labels used to ignore unused attachments at space, page or file level can be specified in the Configuration page of the plugin, as explained in the Configuration section below. The plugin listens for the events raised when a label is added to a space, page, blog post or attachment, to check if the respective attachments marked this way should be removed from the in-memory list of unused attachments.

Spaces being archived

Since most of the times an archived space is no longer supposed to be modified or cleaned up of unused attachments, the plugin allows ignoring unused attachments that are placed inside archived spaces by checking an option in the Configuration page (see the Configuration section below).
The plugin listens for the space status update event raised when a space is marked as archived and removes its attachments from the in-memory list of unused attachments, if any.

Search results age and cache cleanup

Considering the fact that once generated, the in-memory list of unused attachments cannot be kept 100% accurate just by listening to the above mentioned content update events, it is recommended to relaunch the unused attachment search background process to refresh the list of unused attachments by pushing the Refresh button as often as possible. But this approach very much depends on how much time it takes for the search process to complete, as its duration is proportional to the total number of pages, blog posts and comments from all the spaces of the current Confluence instance that need to be processed.

Refreshing the list of unused attachments more often keeps the list of unused attachments more accurate. A good indication of the accuracy of the search list is its age, which is clearly indicated at the top of the table.

For best results, Confluence administrators should deal with unused attachments during periods of lower Confluence instance usage or even lock down content editing altogether.

Once created, the list of unused attachments remains in-memory for as long as it is viewed/accessed by an administrator entering the Unused Attachments screen. If the list is not viewed/accessed for more than 10 minutes, it is removed from memory and would have to be recreated next time an administrator enters the screen, by pushing again the Find button.

Filtering and sorting unused attachments

The total number of unused attachments found during the search process is displayed at the top of the list displaying the search results.

When many unused attachments are found, they can be filtered by space using the Space filter dropdown control at the top right of the search results table.

Furthermore, the unused attachments can be filtered by file extension or by keywords in attachment file name or in the attachment comment. These can be typed into the Filter text field at the top of the search results list and the filter will be applied right away.

The search results can also be sorted by file name, by file size or by creation date when clicking on the corresponding column header in the search results table.

When a filter is in place, the number of results that currently matches the filter is displayed at the top of the search results list along with the total unused attachments count for comparison.

Manage unused attachments

The most obvious reason to search for unused attachments is to remove them and thus clean up the spaces by getting rid of the accumulated unuseful content and reduce their size.

An unused attachment can be deleted using the Delete option found in the last column of the unused attachments search list.

Delete Unused Attachment
Delete Unused Attachment

Once an attachment is deleted, the list of unused attachments is refreshed and the attachment no longer appears in it. In recent versions of Confluence, after being deleted, the attachment is placed in the space Trash area and can be restored from there later. But once removed from the list of unused attachments, the attachment is not put back in the list when restored from Trash. A new search needs to be performed so that restored attachments be correctly identified as being unused again.
By default, the plugin asks for confirmation every time an attachment is deleted using the Delete link in the list of unused attachments. When many attachments need to be deleted and confirming each operation becomes cumbersome, the plugin allows inhibiting the delete confirmation dialog by unchecking the Enable attachment delete confirmation checkbox on the Configuration page. This configuration setting affects only the current user session and is not persisted outside current user session, to prevent other users from accidentally deleting attachments (see Configuration).

Another way to have unused attachments disappear from the list of unused attachments is to have them ignored by the plugin search process. This is useful in case some attachments are stored inside the Confluence instance and do not necessarily need to be referenced from any page, blog post or comment. Entire pages or spaces could serve as repositories for files and having references to each of those files just so that they are not considered unused is out of the question.
Instead, the plugin can be configured so that it ignores attachments having certain labels or that are found inside spaces or pages that have certain labels. The labels for the spaces, pages or attachments to ignore are specified on the Configuration page of the plugin. In the list of unused attachments, there are direct links for editing space, page or attachment labels and once such label is added to the respective space, page or attachment, they are removed from the list right away.

Edit Labels
Edit Labels
Note that labels for ignoring unused attachments are for ignoring the respective attachments once the program determines they are in fact unused. The content of a page having such labels is still processed to extract attachment references, which helps in the overall unused attachment detection process.

The third option to get rid of unused attachments from the list is to reference them or make use of them somewhere, so that they no longer appear as not being used.

In order to keep the impact into the content to a minimum when creating such dummy references, a good idea could be to use an orphan page in each space or a page with restrictions so that only the administrators could edit it. Such page could contain only references to such unused attachments that later will no longer appear in the list of unused attachments.

Referencing attachments in comments could also be a way to lower the impact into space content and avoid editing pages or blog post content directly.

Configuration

The Configuration tab found under the Unused Attachments menu of the Confluence Administration module allows customizing the behavior of both the search process and the display of its list of search results using the following configuration settings.

Unused Attachments Configuration Tab
Unused Attachments Configuration Tab

Session Configuration

Configuration settings in this section are applicable and persisted only during the current user session. Modifications made to these settings are lost and they return to their default values when the current session expires or the user logs out.

Enable attachment delete confirmation

When this checkbox setting is checked, it enables the display of the confirmation dialog every time an unused attachments is deleted using a Delete link from the search results screen. By default, the attachment delete confirmation dialog is enabled and disabling it helps speed up the attachment delete process, but caution is recommended as accidental attachment deletion could occur. In older versions of Confluence, deleting an attachment cannot be reverted as the attachments are immediately removed and do not go through Trash.

Global Configuration

Configuration settings in this section are applicable to all user sessions and are persisted permanently in the database.

Ignore archived spaces

Checking this option causes the attachments from archived spaces to be ignored and not considered as unused, so they do not appear in the search results screen.
Even when this option is checked, the content of the archived spaces is still processed during the search, to account for attachment references, although the attachments themselves would be ignored in the list of search results.

Ignored spaces labels

This setting is for specifying a comma separated list of labels that would be used to mark spaces which contain attachments that should never be considered as unused. The attachments found in spaces having at least one of the specified labels are never placed in the list of unused attachments and do not appear in the search results screen.
However, the content of these spaces is processed during the search to account for attachment references, although the attachments themselves would be ignored in the list of search results.

Ignored pages labels

This setting is for specifying a comma separated list of labels that would be used to mark pages or blog posts which contain attachments that should never be considered as unused. The attachments found in pages or blog posts having at least one of the specified labels are never placed in the list of unused attachments and do not appear in the search results screen.
However, the content of these pages or blog posts is processed during the search to account for attachment references, although the attachments themselves would be ignored in the list of search results.

Ignored attachments labels

Individual attachments can be marked using one of the comma separated list of labels specified by this setting so that they are ignored by the search process do not appear in the list of unused attachments.

Known Limitations

Attachment Creation Events

The plugin does not listen for attachment creation events and will not add newly uploaded attachments to the list of unused attachments right away. It does not do that in order to avoid the situation in which the current created attachment is in fact already referenced in a page, blog post or comment, but that link/reference was pointing to an inexistent attachment which was only now uploaded in order to fix the problem.

Attachments Macros

Besides referencing an attachment with a link or by embedding it in the content as image, another way to reference an attachment is by using the Page Attachments Macro, Space Attachments Macro or the Gallery Macro of Confluence. The current version of the plugin does not process any of these attachments macro occurrences and thus does not see attachment references coming through them.

Support

For any issues or questions related to the use of this add-on, please contact us by email at support@alutustech.com.