[#55950] updated documentation for storage health checks

docs/system-admin-guide/files/external-file-storages/README.md

@@ -32,6 +32,11 @@ Please also remember to activate the **File storages** module under [project set
 
 For instructions on using the integration after the setup has been complete please refer to [SharePoint/OneDrive integration user guide](../../../user-guide/file-management/one-drive-integration/).
 
-## File storage troubleshooting
-
-For troubleshooting guidance related to file storages, visit the [File storage troubleshooting](./file-storage-troubleshooting) page. Here you will find possible explanations and suggested solutions. If you encounter any  challenges not addressed here, do not hesitate to reach out to the [OpenProject community](https://community.openproject.org/projects/openproject/forums) or [support team](https://www.openproject.org/contact/) for further assistance.
+## Health status
+
+For troubleshooting guidance related to file storages, visit
+the [File storage troubleshooting](./health-status) page. Here you will find possible explanations and
+suggested solutions and will be able to conduct health status checks with immediate results. If you encounter any
+challenges not addressed here, do not hesitate to reach out to
+the [OpenProject community](https://community.openproject.org/projects/openproject/forums)
+or [support team](https://www.openproject.org/contact/) for further assistance.

docs/system-admin-guide/files/external-file-storages/file-storage-troubleshooting/README.md → docs/system-admin-guide/files/external-file-storages/health-status/README.md

@@ -1,36 +1,62 @@
 ---
 sidebar_navigation:
-  title: File storages troubleshooting
+  title: Health status / Troubleshooting
   priority: 999
-description: File storages troubleshooting in OpenProject.
-keywords: file storages, Nextcloud error, Nextcloud troubleshooting, OneDrive error, Sharepoint error, OneDrive, Sharepoint, error, troubleshooting
+description: Health status checks and troubleshooting for file storages in OpenProject.
+keywords: file storages, health, health status, error, troubleshooting, Nextcloud, OneDrive, SharePoint, Connection validation, Connection test
 ---
 
-# File storage errors and troubleshooting
+# Health status checks and troubleshooting
 
-## Unhealthy file storages email notifications
+If a file storage is not working as expected, you can find additional information about possible errors in the details
+view of the file storage. You can access this view by clicking on the file storage's name in the list under *Administration* -> *Files* -> *External file
+storages*.  In addition, administrator can manually trigger a connection validation. 
 
-In some cases it is possible that a file storage has been set-up incorrectly, the connection is faulty or the storage
-itself has problems. In this case the respective message will appear under *Administration* -> *File storages*.
+## Connection validation
 
-> Please note that this only applies to file storages where **automatically managed project folders** have been
-> selected.
+### Connection validation for OneDrive/SharePoint 
+
+Every file storage for OneDrive/SharePoint has the ability to run a connection test. This test is triggered manually by
+clicking on **Recheck connection** in the sidebar on the right side of the file storage's details view. This check is
+available after the file storage is fully configured.
+
+![Recheck connection for OneDrive/SharePoint in OpenProject administration](openproject_file_storages_recheck_connection.png)
+
+There are several possible errors that can occur during the connection test. The following table lists the error codes with a description of the possible reasons and suggested solutions.
+
+| Error code             | Error description                                            | Possible reasons                                             | Next steps and solutions                                     |
+| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| WRN_NOT_CONFIGURED     | The file storage is not fully configured.                    | Important data is missing, so that the file storage is labelled incomplete. | Check the input fields and fill in the missing data.         |
+| ERR_TENANT_INVALID     | The configured directory (tenant) id is invalid.             | There might be a typo or the tenant name or ID has changed recently. | Go to the correct Microsoft Entra ID overview in the [Azure Portal](https://portal.azure.com/) and copy the correct tenant id to the input field. |
+| ERR_CLIENT_INVALID     | The configured client credentials are invalid.               | Either the client id or the client secret are invalid. The error descriptions should help you finding the culprit. | Go to the correct application overview in the [Azure Portal](https://portal.azure.com/). Copy the correct client ID to the input field, or check whether the client secret is still valid. Attention: secrets might have an expiration date. If a secret is expired, you will have to generate a new one. |
+| ERR_DRIVE_INVALID      | The configured drive cannot be found.                        | The request for the drive ID failed without finding the drive ID. The drive might be deleted, or your application has no permissions to see it. | Consult the [drive guide](../../../integrations/one-drive/drive-guide/) and fetch the desired drive ID again, to fill out the input field. |
+| WRN_UNEXPECTED_CONTENT | The connection request was successful, but unexpected content was found in the drive. | This warning is only shown, if the file storage is configured to automatically managed project folder permissions. There was data found in the drive, that is not a project folder created by OpenProject. | Go to your drive and migrate or delete the data from the drive root, that was not created by OpenProject. Further information about the unexpected data is found in the server logs. A drive configured for usage with the *Automatically managed project folders* option has a disrupted inheritance chain. Any data in here can only be seen by site owner. It is discouraged to use this drive for other purposes than the OpenProject integration. |
+| ERR_UNKNOWN            | An unknown error occurred.                                   | There can be multiple reasons and the error source was not foreseen. | Errors of this kind are logged to the server logs. Look for a log entry starting with `Connection validation failed with unknown error:` |
+
+### Connection validation for Nextcloud
+
+The connection validation test is currently only available for OneDrive/SharePoint integrations.
+
+## Health checks for automatically managed project folders
+
+File storages with the *Automatically managed project folders* option will have reoccurring synchronization
+runs, that update the user permissions on the external system and report possible errors. An additional section is
+displayed for those file storages in the side bar.
 
 ![Health check for automatically managed folders in file storage integrations in OpenProject](openproject_file_storages_health_message.png)
 
-If a problem has been detected for a file storage with automatically managed folders enabled, the OpenProject
-administrators will be notified via email of the detected error. Admin will be notified once a day of the faulty
-integration, including the specific error description and solution suggestions (see the section below).
+If a problem has been detected, the OpenProject administrators will be notified of the detected error via email.
+Administrators will be notified of the faulty integration once a day, including the specific error description and
+solution suggestions (see the table below).
 
-Once the error has been resolved, the admin will also receive an email informing him/her/them of this.
+Once the error has been resolved, the administrators will also receive an email informing them of this.
 
 You can choose to subscribe or unsubscribe to these email notifications by clicking the respective button under the
 error message.
 
-## File storage errors description
+### File storage errors description
 
-Once you have set up your files storages, it is possible that a technical error may occur. Please consult the following
-table for possible reasons behind the errors and suggested solutions.
+Please consult the following table for possible reasons behind the errors and suggested solutions.
 
 | Error name   | Error description                       | Possible reasons                                                                                                                                                                                                                                                                                                                                                                 | Next steps and solutions                                                                                                                                                                                                                                              |
 |--------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

docs/system-admin-guide/integrations/one-drive/README.md

@@ -104,7 +104,10 @@ information the redirect URI will get generated again and thus needs to be copie
 by clicking on the **Copy-to-Clipboard** element next to the information text, or by entering the form by clicking the
 **View** icon.
 
-**Note**: if you have selected that automatically managed access and folders you will also see the *Health status* message on the right side. If the file storage set-up is incomplete or faulty, an error message will be displayed in that section. Read more about errors and troubleshooting [here](../../files/external-file-storages/file-storage-troubleshooting/).
+**Note**: if you have selected automatically managed access and folders you will also see the *Health status*
+message on the right side. If the file storage set-up is incomplete or faulty, an error message will be displayed in
+that section. Read more about errors and
+troubleshooting [here](../../files/external-file-storages/health-status/).
 
 ![Edit OneDrive/SharePoint in OpenProject](openproject_system_guide_edit_icon_onedrive_storage.png)
 

docs/system-admin-guide/users-permissions/roles-permissions/README.md

@@ -25,7 +25,7 @@ Following are the permissions for file storages within OpenProject:
 
 - **View file links**: Allows a user to see file links to external storages in the Files tab of work packages
 - **Manage file links**: Allows a user to create and edit file links to work packages
-- **Manage file storages in project**: Allows a user to add or edit file storages for a project
+- **Manage files in project**: Allows a user to add or edit file storages for a project
 
 Following user permissions are set on files and folder in **External Storages**:
 

docs/user-guide/projects/project-settings/files/README.md

@@ -27,7 +27,7 @@ To activate or de-activate the attachments being shown under **Files** tab in wo
 
 ![Show attachments in the work packages files tab in OpenProject](project-settings-attachments.png)
 
-
+> Please note that you need a *Manage files in project* permission to be able to activate or deactivate this work package attachment option.
 
 ## Add a new storage to a project