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 known macro, 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.
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 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 process and the result it produces are unique within the Confluence instance and all Confluence 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 has been completed and the in-memory list of unused attachments has been built, it is persisted in the database and can be viewed by all administrators entering the administration screen from any other administrator user session.
The resulting list of unused attachments is organized on a space by space basis and in addition to Confluence administrators, user having space view permissions
can see the list of unused attachments in each space. They can also delete these attachments if they have attachment delete permissions in the respective spaces
and should be able to manage these attachments as they see fit.
The space administrators access the list of unused attachments for a given space from the Content Tools tab of the Space Tools page, where there is an
Unused Attachments sub-tab available.
In addition to the space level list of unused attachments, there is also the possibility to view the list of unused attachments at page or blog post level,
for users having page view permissions. The users can delete the unused attachments at page or blog post level if they have attachment delete permissions
at parent space level.
The list of unused attachments for a given page or blog post can be accessed using the Unused Attachments option in the top left page menu.
Search results upkeep
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 list of unused attachments might not be 100% accurate by the time it is viewed/inspected.
Once the 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 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 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 list of unused attachments is organized by space, to facilitate filtering of results when displayed and to allow space administrators to view and manage the list of unused attachments in their respective spaces. 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 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 list
of unused attachments, if any.
Attachments being renamed
The plugin allows ignoring unused attachments that have names matching certain patterns that can be specified in the Configuration page
(see the Configuration section below).
The plugin listens for the attachment rename events and removes the attachments from the list of unused attachments, if their new names match
any of the specified filter patterns.
Search results age and refresh
Considering the fact that once generated, the 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.
Due to the fact that the Extent of Search configuration can vary from one search process to the next and can thus cover a different set of
spaces each time, the search results persisted at space level might not be the result of the latest search and could be in fact produced by a
previous/older search, having a different configuration and filtering criteria.
This is not necessarily a problem as the older space level results are still representing unused attachments in that space with respect to the
criteria used to detect them. Keeping them around allows certain attachment management scenarios in which independent sets of spaces are scanned
separately by the Confluence administrator.
The fact that the space unused attachment list pertains to the latest search and thus the current search configuration is indicated with a label
next to the search results creation date value and could be either:
- (latest)
- (from older search, not latest)
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.
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 Delete Selected
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
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.
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 pages containing these macros
Attachments can be referenced from within macros. The plugin processes the Confluence built-in attachment macros as explained in the
Macro Processing section below. However, it cannot process unknown macros brought into the Confluence instance by custom
plugins, which reference attachments in unknown ways.
For such situations, it is sometimes useful to simply look for macros with a certain name inside the page or blog post and if such macros are found,
then all attachments of the page or blog post should be considered used or referenced.
This means that the mere presence of a specified macro on a page or blog post marks all attachments of that page or blog post as being used or referenced.
The use of this configuration setting should be considered as a temporary solution until the particular macro which references the attachments is processed
properly during the unused attachments search. Please contact us at support@alutustech.com to let us know
which macros from which Confluence plugin you are using and would like us to support in our product. This is how we added support for Gliffy and draw.io diagram macros.
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.
Macro Processing
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.
Ignore Gliffy macros and draw.io macros
Gliffy and draw.io
are popular Confluence plugins which offer the possibility to embed diagrams in pages and blog posts. They create special attachments
in Confluence and during the search for unused attachments, occurrences of these macros are properly processed to correctly identify the attachments they use.
The processing of these two types of macros is controlled with two configuration options.
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.
Processing Custom Macros
The plugin has support for known macros referencing attachments such as the Confluence built-in attachments macro, space attachments macro and galley macro.
In addition to those, it supports other popular Confluence plugin macros such as Gliffy and draw.io, but it cannot process all macros in a generic way
because they all have different and unknown ways to reference attachments.
This limitation can only be worked around by using the configuration setting to exclude
pages and blog post which contain certain named macros or by writing to us at support@alutustech.com and letting us know
which macro from which Confluence plugin you would like us to support in future releases.
Support
For any issues or questions related to the use of this add-on, please see our Service Level Agreement.