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.
Search for unused attachments
Confluentis Unused Attachments plugin adds a new
Unused Attachments menu option in the
Administration section of the
Confluence Administration console.
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.
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.
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).
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
(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
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
Deleting 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.
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
Normally, for each attachment found unused by the program, we would recommend investigating the reasons it ended up in this state and addressing
the situation on a one by one case approach.
However, if many unused attachments are found and investigating each one of them would take too much time and would not worth the effort, multiple attachments can be deleted simultaneously by using the selection checkboxes on the right side of each row, and then hitting the
link under the search results table.
All the unused attachments in the list can be removed at once using the
Delete All /
Delete Filtered links at the top of the table,
which are available depending on the search results list being filtered or not.
Labeling unused attachments
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.
Referencing unused attachments
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 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.
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
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
Number of rows per page in search results list
This setting specifies the number of rows per page to be displayed in the unused attachments search results list.
Configuration settings in this section are applicable to all user sessions and are persisted permanently in the database.
Extent of the Search
Configuration settings in this subsection limit the extent of the search for unused attachments process.
Ignore page history
By default, the program looks for attachment references only in the current version of pages and blog posts. This is mainly for performance reasons,
as searching through the entire history could take a significant amount of time, depending on the size of your Confluence database.
Uncheck this configuration option if an attachment should be considered used when referenced from an older version of a page or blog post.
Ignore archived spaces
When this option is checked, the content of the archived spaces is not processed at all during the search for unused attachments. Not only that attachments from the archived spaces will not be considered unused, but neither references to attachments in other spaces would be considered when deciding if those attachments are used or not.
Include spaces with these keys only
Only spaces having one of the keys in this comma separated list of space keys will be included in the search for unused attachments and attachment references.
Include spaces with these labels only
Only spaces having at least one of the labels in this comma separated list of space labels will be included in the search for unused attachments and attachment references.
Exclude spaces with these keys
Spaces having one of the keys in this comma separated list of space keys will be excluded from the search for unused attachments and attachment references.
Exclude spaces with these labels
Spaces having at least one of the labels in this comma separated list of space labels will be excluded from the search for unused attachments and attachment references.
Search Results Filters
Configuration settings in this subsection filter the output of the unused attachments search process.
Ignore archived spaces attachments
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 in accordance with the Extent of the Search configuration, to account for attachment references, although the attachments themselves would be excluded from the search results list.
Exclude spaces with these 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 still processed in accordance with the Extent of the Search configuration, to account for attachment references, although the attachments themselves would be excluded from the search results list.
Exclude pages with these 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 still processed in accordance with the Extent of the Search configuration, to account for attachment references, although the attachments themselves would be excluded from the search results list.
Exclude attachments with these labels
Individual attachments can be marked using one of the labels in this comma separated list of labels setting so that they are excluded from the search results list.
Exclude attachments with these patterns
A comma separated list of file name patterns can be specified in this setting so that attachments matching at least one of these patterns be excluded from the search results list.
Configuration settings in this subsection control the processing of macros for attachment references detection.
Ignore attachments macros, space attachments macros and gallery macros
Attachments macros, space attachments macros and gallery macros are Confluence built-in macros that can be used to display a list of attachments attached
to one or more pages, or to a space, optionally filtering them using file name patterns or labels.
When an attachment appears in such a list, it is considered referenced/used.
There are three configuration options that can be checked to avoid this behavior for each of the three built-in types macros.
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.
For any issues or questions related to the use of this add-on, please contact us by email at email@example.com.