diff --git a/docs/system-admin-guide/files/external-file-storages/file-storage-troubleshooting/README.md b/docs/system-admin-guide/files/external-file-storages/file-storage-troubleshooting/README.md index 8785c1dffe18..3cc13c5fd807 100644 --- a/docs/system-admin-guide/files/external-file-storages/file-storage-troubleshooting/README.md +++ b/docs/system-admin-guide/files/external-file-storages/file-storage-troubleshooting/README.md @@ -8,29 +8,52 @@ keywords: file storages, Nextcloud error, Nextcloud troubleshooting, OneDrive er # File storage errors and troubleshooting -## Unhealthy file storages email notifications +If a file storage is not working as expected, users can find additional information about possible errors in the details +view of the file storage. This can be accessed by clicking on the file storage name in the list under +*Administration* -> *Files* -> *External file storages*. -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. +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. + +There are a couple of possible errors and warnings that can occur during the connection test. The following table lists +the error codes with a description of the possible reasons and how to solve them. + +| 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 labeled 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 lately. | 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 a expiration date. If a secret is expired, you'll have to generate a new one. | +| ERR_DRIVE_INVALID | The configured drive cannot be found. | The request for the drive id failed with not 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 manage 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. 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 as with 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:` | + +#### Nextcloud compatibility + +This connection validation test is currently only available for OneDrive/SharePoint integrations. + +## Health checks for automatically managed project folders + +File storages configured 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 via email of the detected error. +Administrators will be notified once a day of the faulty integration, 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. 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 | |--------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|