Skip to content

Commit

Permalink
[#55950] updated documentation for storage health checks
Browse files Browse the repository at this point in the history 
- https://community.openproject.org/work_packages/55950
- updated text and overall structure
- missing current screenshots
  • Loading branch information
@Kharonus
Kharonus committed Jun 26, 2024
1 parent 697c7a4 commit 939de9b
Showing 1 changed file with 34 additions and 11 deletions.
45 changes: 34 additions & 11 deletions ...admin-guide/files/external-file-storages/file-storage-troubleshooting/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|--------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
Expand Down

0 comments on commit 939de9b

Please sign in to comment.