Configuration area

The Attachment Filter plugin's administration area is located in the Confluence Administration. You can navigate to the plugin's administration by clicking the link "Attachment Filter" in the Configuration section.

Manage file extensions and file extension categories

Starting Point:

1. Click "Attachment Filter" in the Confluence "Configuration" section on the left side. The plugin's administration UI will be displayed.
2. Select "File Extension Categories" in the top navigation. 

Create a new file extension category with file extensions

1. Click the "New Category" button to create a new file extension category.
   
   
   
   
2. At the end of the table a new entry appears.
   
   
3. Fill in a unique name for the category. If you choose a name which is already used by another category an error message will be shown.
   
   
4. Having chosen a unique name you could already save your category by clicking the "Add New" button and later add file extensions to this category.
5. You will directly want to fill the new category with file extensions, so put the cursor into to the "Extensions" input field and type in a comma-separated list of extensions (or just one). Please keep in mind that any file extension can only be part of one file extension category. Note that you only need to define the file extension itself. More specifically, you're not supposed to define file name patterns, as this is not supported by the add-on. So, you'll use txt for text files and not *.txt or similar globs.
6. Press "Enter" or click the "+" button next to the input field to add the extensions. The extensions are now displayed as part of the category. Next to each file extension a small icon with a cross is displayed. It allows you to remove file extensions from this category.
   
   
7. If you define an extension that is already part of another category, a corresponding error message will be shown. 
   
   
8. After creating your file extensions press "Enter" again or click the "Add New" button to add the new file extension category. The category is now ready to be used for defining filter rules.

Edit a file extension category (Add/Remove file extensions)

1. For every file extension category an "Edit" button is provided at the end of the table row. Click the "Edit" button to change an existing file extension category.
   
   
2. Now you can change the name of the category or add and remove file extensions. All changes you make have to be confirmed by clicking the "Save" button!
3. To remove file extensions press the cross icon next to the extension you want to delete. The selected extensions will disappear but are not removed until you confirm your changes with "Save".
4. To add new file extensions insert a comma-separated list of extensions (or just one). Every file extension must be unique and can only be part of one file extension category.
5. Press "Enter" or click the "+" button next to the input field to add the extensions. The extensions are now displayed as part of the category.
6. If you have provided an extension that is already part of another category an error message will be displayed.
   
   
7. Click the "Save" button to persist your changes or "Cancel" if you want to discard your edits.
   
   

Delete a file extension category

1. For every file extension category a "Delete" link is provided at the end of the table row. Click "Delete" to remove a complete file extension category.
   
   
2. A warning message appears - this is a reminder of how deleting this file extension category might affect existing filter rules. The extensions of the category will be removed in every filter rule containing them! If an affected filter rule does not contain any further extension the rule will also be deleted.
   
   
3. Click "Delete" to remove the file extension category and to update the affected filter rules. Click "Cancel" to abort.

Define the global filter rule

Starting Point:

1. Click "Attachment Filter" in the administrator's "Configuration" section on the left side. The plugin's administration UI will be displayed.
2. Select "Global Filter Rule" in the top navigation. A page for global filter rule administration appears.
   
   
3. Click "New Filter Rule" to open the global filter rule template. ( Keep in mind that the file extensions available for defining the global filter rule and any other rule can be managed in the "File Extension Categories" section - a direct link is presented on the global filter rule page).
4. You can now select all file extensions allowed to be uploaded by users. 
   
   
5. Confirm the filter rule by clicking the "Save" button. A filter rule can only be persisted if it contains at least one file extension! If you do not want to save the filter rule, click "Cancel".
6. The global filter rule will be shown. You can edit the rule or even delete it (this will deactivate the filter!).
   
   

Define a group or user filter rule

You can define attachment filter rules which are valid for either an entire user group or for an individual user. As described in the introduction, if a user is a member of more than one group with filter rules defined, then the union of the file extensions defined in these group rules are available for uploads for this user. If there is a specific filter rule defined for one individual user, only the file types from this user rules are available for this users. In this case, rules defined for this user's groups are not longer taken into account when validating uploads by this user.

Group and user rules can be defined on the tab labeled "Group/User Filter Rules" in the Attachment Filter configuration area. To manage such rules proceed as follows.

1. Navigate to the Attachment Filter plugin's configuration area.
2. Select "Group/User Filter Rules" in the top navigation. A page for group and user specific rule administration appears. Group filter rules are displayed on the top of this page, followed by user filter rules. A table shows all currently defined filter rules. Below each table, a search field is provided to select a group or a user for which you can define a filter rule.
3. Click inside the input field "Search group" / "Search user" and start writing at least one character to activate the auto-complete search. The search implicitly performs an infix search. Please keep in mind that the search will only present groups or users that match the search string and do not currently have a filter rule installed. (You can only have one filter rule per group / per user). The following figures show a group filter rule definition, the user part works exactly the same.
   
   
4. Select a group from the drop down search result.
   
   
5. If you have selected a valid group, the button "New Filter Rule" will be enabled to open a new filter rule template for this group. Even quicker - press "Enter". If you change the group search result manually (e.g. removing characters) you cannot open a filter rule template as long as the group name is valid. 
6. Select all file extensions allowed to be uploaded by the group you have selected.
    
    
7. Persist the filter rule using the "Save" button. A filter rule can only be persisted if it contains at least one file extension!
   
   
8. Finally, your new filter rule will be presented in the group filter rule table. An abstract shows all allowed file extensions for this group. For a more detailed view you can expand the rule by clicking the arrow at the beginning of the table entry.
   
   

Presets for new group/user rules

When creating new filter rules for user groups or individual users, the newly created rules are preconfigured with a set of file extensions. These presets are calculated from the set of filter rules that are already in effect for the configured entity. For any user group, the global filter rule is in effect by definition. So, when you are creating a new filter rule for a user group, all file extensions allowed by the global filter rule are preselected for this rule. In your new rule, you can now either restrict this set of file extensions by deselecting file extensions or broaden it by adding file extensions to the set of allowed file types.

The same applies to user filter rules. A new user filter rule is preset with the union of all group filter rules that are in effect for this user. If, for instance, a user is member of two groups each with its own group filter rule, a new user filter rule for this user is preset with all allowed file extensions from both of the group filter rules.

If you don't change the presets for a new group or user rule, this new rule is in fact useless, since it doesn't change the rules that are in effect for the group/user anyway.

Using the copy filter function

Filter rules can act as templates for creating or editing existing filter rules. You can copy any existing group filter rule into another group filter rule. The same mechanism is provided for user filter rules - they can also be used as templates for other user filter rules. To use the copy filter function, at least one filter rule must exist to copy its settings. Let's examine creating a new group filter rule by copying settings from another group filter rule. Again, for user filters the mechanism is the same.

1. Click "Attachment Filter" in the administrator's "Configuration" section on the left side. The plugin's administration UI will be displayed.
2. Select "Group/User Filter Rules" in the top navigation. A page for group and user specific rule administration appears. Group filter rules are displayed on top of this page, followed by the user filter rules. A table presents all defined filter rules. Below each table a search field is provided to select a group or a user for which you can define a filter rule.
3. Click inside the input field "Search group" / "Search user" and start writing at least one character to activate the auto-complete search. In this example, we have already defined a group filter rule for group "confluence-users". Now we search for group "confluence-administrators" and click "New Filter Rule".
   
   
4. Go to the "Copy filter from group" section on top of the filter rule template and click the dropdown list. Choose "confluence-users" and click the "Copy filter" button.
   
   
5. All extensions defined by the "confluence-users" group filter rule are now selected in the new filter rule for "confluence-administrators".
   
   
6. Feel free to select or deselect extensions and persist the new filter rule by clicking the "Save" button.

Define a space filter rule

 Available since version 1.1

Space filter rules are filter rules which are only valid for one particular Confluence space. If such a rule set is active for a space then only the file uploads into this space are affected by these rules. Space filter rules are effective for any user who is permitted to upload files into a space. In order to define such rules, navigate to the Attachment Filter plugin's configuration area and click item "Space Filter Rules" on the navigation bar.

This will open the space rule configuration panel. In order to create a new filter rule for an individual Confluence space, perform the following steps:

1. Find the target space by entering the name of the space into the search box labeled with "Search space". This search allows using wildcards and implicitly performs an infix search for spaces.
2. After having chosen the desired Confluence space, the button labeled "New Filter Rule" is enabled.
    
3. Click this button to open a configuration panel where you can select all file extensions that you want to allow for the selected space.
4. Note that in this new filter rule all file extensions from the global filter rule are preselected. These are the file extensions which are allowed for any space by default by virtue of the global rule. See the next section below for an explanation of this feature.
5. You can now either select individual file extensions or copy an existing filter rule from a different space as a template into your current selection.
6. To copy an existing filter rule, select the source space from the drop-down box at the top of the rule definition panel and click button "Copy Filter Rule". All file extensions allowed for this space are copied into the current selection.
7. After you have selected all allowed file extensions for a space, click on "Save" to persist your new filter rule.
   

As a result of these steps, in the space overview table at the bottom of the page the edited space is shown as having a filter rule defined.

Presets for new space filter rules

When you create a new space filter rule, you will notice that there are already some file extensions preselected. These settings are adopted from the current global filter rule. This feature is intended to assist you in defining new space filter rules. It allows you to either broaden or restrict the set of allowed file extensions for a space based on the global filter rule.

Edit and delete space filter rules

You can edit an existing space filter rule by clicking on the "Edit" button in the overview table showing the currently configured space filter rules. By clicking on the link "Delete" you can choose to delete a specific rule.

Define a filter rule for anonymous access

A filter rule for anonymous access might be required if unauthenticated (non-logged in) users are allowed to use Confluence and have permission to upload attachments. If you are not sure if anonymous access to your Confluence instance is enabled you can check this configuration in the "Global Permissions" section. Anonymous access is allowed if you find the "Use Confluence" option selected:

If anonymous access is enabled each space can define individual space permissions for non-logged-in users and may allow to upload attachments. 

Starting point:

1. Click "Attachment Filter" in the administrator's "Configuration" section on the left side. The plugin's administration UI will be displayed.
2. Select "Group/User Filter Rules" in the top navigation. A page for group and user specific rule administration appears. At the bottom of the page you find the "Filter Rule for Anonymous Access" section.
   
   
3. Click "New Filter Rule" to open a new filter rule template.
4. You can select all file extensions allowed to be uploaded by anonymous users.
   
   
5. Persist the filter rule using the "Save" button. A filter rule can only be persisted if it contains at least one file extension! (If you do not want to save the filter rule click "Cancel".)
6. Finally, your new filter rule will be presented in the filter rule table. An abstract shows all allowed extensions for anonymous users. For a more detailed view you can expand the rule using by clicking the arrow at the beginning of the table entry.

Handling extensionless files

Besides the filter rule facility, the attachment filter has a common filter setting - the option to allow or disallow uploading files without a file extension. This setting is global and independent from any other rule definition. 

To allow or disallow the upload of extensionless files, perform the following steps:

1. Go to the Attachment Filter plugin configuration in the Confluence administration area. If the configuration is already opened, choose "Global Plugin Settings" in the top navigation.
2. Below the filter activation section you'll find the "Common Filter Settings"
   
3. By default, files without extensions are allowed to be uploaded. If you want to disallow the upload of such files, click button "Disallow". Now the filter (unless deactivated) will disallow the upload of extensionless files.
   
4. Changing this setting back to allow uploading of files without extension can be done by clicking the button "Allow".

Filter rule precedence

If you have more than one filter rule type in place (global rule, group/user rule, or space rule), a specific order of precedence of the individual rule types applies. This is depicted by the following figure: