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 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.

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 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 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, space administrators can view the list of unused attachments in their own 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.

Space Unused Attachments Tab
Space Unused Attachments Tab

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).

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 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.

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.

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.

Note that space administrators need to have attachment delete permission on the space if they want to be able to remove unused attachments. Normally, they can grant this permission to themselves as space administrators have the right to manage space permissions.

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.

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.

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.

Unused Attachments Configuration Tab
Unused Attachments Configuration Tab

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.