# File Management Module

The File Management module gives users a structured way to upload, organize, download, and manage files within OtisEd.Nimble. Files are grouped inside a navigable directory tree, and every file carries metadata — name, type, and size — that the system tracks automatically. Access to the module and its individual actions is controlled by a permission set that administrators configure per user or role.

## Table of Contents

* [Overview](#overview)
* [Key Concepts](#key-concepts)
* [Navigating the Directory Tree](#navigating-the-directory-tree)
* [Working with Directories](#working-with-directories)
  * [Creating a Directory](#creating-a-directory)
  * [Renaming a Directory](#renaming-a-directory)
  * [Moving a Directory](#moving-a-directory)
  * [Deleting a Directory](#deleting-a-directory)
* [Working with Files](#working-with-files)
  * [Uploading a File](#uploading-a-file)
  * [Renaming a File](#renaming-a-file)
  * [Moving a File](#moving-a-file)
  * [Downloading a File](#downloading-a-file)
  * [Deleting a File](#deleting-a-file)
* [File Metadata](#file-metadata)
* [Storage Limits](#storage-limits)
* [Permissions](#permissions)
* [Troubleshooting](#troubleshooting)

***

## Overview

The File Management module provides a two-level organizational structure: **directories** and **files**. Directories can be nested to any depth, forming a tree. Files always belong to exactly one directory (or to the root if no directory is specified).

When you upload a file, the system records its name, MIME type, and size, then stores the file content in the platform's blob storage. Download links are secured by short-lived tokens to prevent unauthorized access.

The module is feature-gated. If your tenant does not have the File Management feature enabled, the module and all its API endpoints will be unavailable. Contact your system administrator if you believe you should have access.

***

## Key Concepts

**Directory** — A named container that holds files and other directories. Directories form a tree structure, with the root being directories that have no parent. A directory name must be unique within its parent. Names may be up to 255 characters and cannot contain characters that are invalid in file system names (for example, `\`, `/`, `:`, `*`, `?`, `"`, `<`, `>`, `|`).

**File Descriptor** — The metadata record for an uploaded file. It stores the file's name, MIME type, size in bytes, the directory it belongs to, and audit timestamps (who created it and when, who last modified it and when). The actual file content is stored in blob storage and linked to the descriptor by a unique identifier.

**MIME Type** — A label that identifies the kind of content a file contains (for example, `application/pdf` or `image/png`). This is recorded automatically from the file being uploaded and is used by the system to serve downloads with the correct content type.

**Download Token** — A short-lived, single-use token that the system generates on demand. Download links include this token. Tokens expire after 60 seconds, so download links should be used immediately after they are generated.

**Blob Storage** — The underlying storage system where file content is kept. The module uses ABP's blob storage abstraction, so the physical storage location (local disk, Azure Blob Storage, AWS S3, etc.) is determined by the platform configuration and is transparent to users.

**Storage Quota** — An optional per-tenant limit on total storage used. When a quota is configured, the system checks before each upload whether the new file would exceed it.

***

## Navigating the Directory Tree

The directory tree is displayed as a hierarchical list. Root-level directories appear at the top. Expand a directory to see its subdirectories. Selecting a directory loads its contents — both subdirectories and files — in the main panel.

The content list shows directories first, followed by files, both sorted alphabetically by name. You can sort files by other columns (such as size or modification date) if the interface provides those controls. You can also filter the content list by entering a search term; the system matches against both directory names and file names within the current directory.

***

## Working with Directories

### Creating a Directory

1. Select the parent directory where you want the new directory to appear. To create a root-level directory, deselect any current directory or navigate to the root level.
2. Choose the option to create a new directory. The interface will prompt you for a name.
3. Enter a name of up to 255 characters. The name must be unique within the selected parent and cannot contain invalid file system characters.
4. Confirm. The new directory appears immediately in the tree.

If a directory with the same name already exists in the same parent, the system will display an error and the directory will not be created.

### Renaming a Directory

1. Locate the directory in the tree or content list.
2. Choose the rename action for that directory.
3. Enter the new name. The same naming rules apply as when creating.
4. Confirm. The directory name updates immediately throughout the tree.

Renaming a directory does not move it or affect its contents.

### Moving a Directory

1. Locate the directory you want to move.
2. Choose the move action.
3. Select the destination parent directory. The root level is also a valid destination.
4. Confirm.

The system prevents invalid moves. You cannot move a directory into one of its own descendants — for example, you cannot move a folder called "Reports" into a subfolder that already lives inside "Reports". If you attempt this, the system will display an error. You also cannot move a directory to a parent that already contains a directory with the same name.

### Deleting a Directory

1. Locate the directory you want to remove.
2. Choose the delete action.
3. Confirm the deletion when prompted.

Deleting a directory is permanent and removes all of its contents recursively — every file and every subdirectory within it, down to any depth. There is no recycle bin or undo. Review the directory contents carefully before deleting.

***

## Working with Files

### Uploading a File

Before uploading, the system performs a pre-upload check that confirms:

* The file name is valid (no invalid file system characters, not blank, not exceeding 255 characters).
* A file with the same name does not already exist in the target directory (unless you choose to overwrite it).
* The file size does not exceed any configured storage quota remaining for your tenant.

To upload a file:

1. Navigate to the directory where you want the file to reside. Files uploaded without selecting a directory are placed at the root level.
2. Choose the upload action.
3. Select the file from your computer using the file picker, or drag and drop it onto the upload area.
4. If the system detects that a file with the same name already exists in that directory, you will be asked whether to overwrite it. Overwriting replaces the file content and updates the file size, but retains the original file descriptor record.
5. Confirm the upload.

The file appears in the directory listing once the upload completes. The system records your name and the upload timestamp automatically.

### Renaming a File

1. Locate the file in the directory listing.
2. Choose the rename action.
3. Enter the new name. The same naming constraints apply as for directory names.
4. Confirm.

The new name must be unique within the same directory. If another file in that directory already has the name you entered, the system will reject the rename.

### Moving a File

1. Locate the file you want to move.
2. Choose the move action.
3. Select the destination directory, or choose the root level.
4. Confirm.

The system verifies that the destination directory exists before completing the move. If the target directory no longer exists when the move is processed, you will see an error.

### Downloading a File

1. Locate the file in the directory listing.
2. Choose the download action.
3. The system generates a short-lived download token (valid for 60 seconds) and initiates the download automatically.

The file is served with its original file name and the correct MIME type. Because the download token expires quickly, do not interrupt or delay the download after initiating it. If the download fails or times out, simply request a new download from the file listing.

### Deleting a File

1. Locate the file in the directory listing.
2. Choose the delete action.
3. Confirm the deletion when prompted.

File deletion is permanent. Both the file content in blob storage and the file descriptor record are removed immediately. There is no recovery path after deletion is confirmed.

***

## File Metadata

Each file in the module carries the following metadata:

| Field            | Description                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| Name             | The file's display name, including its extension.                                                                   |
| MIME Type        | The content type detected at upload time (for example, `application/pdf`).                                          |
| Size             | The file size in bytes, recorded at upload. Displayed in human-readable units (KB, MB, GB, or TB) in the interface. |
| Directory        | The identifier of the directory the file belongs to. Empty if the file is at the root level.                        |
| Created By       | The user who uploaded the file.                                                                                     |
| Created At       | The timestamp when the file was first uploaded.                                                                     |
| Last Modified By | The user who most recently updated the file (for example, via a rename or overwrite).                               |
| Last Modified At | The timestamp of the most recent update to the file's metadata or content.                                          |

Metadata is read-only from the user's perspective except for the file name, which can be changed via the rename action.

***

## Storage Limits

The platform may enforce a storage quota for your tenant. When a quota is in place, the system checks total storage used before each upload. If the upload would cause the total to exceed the configured limit, the upload is rejected with an error message showing the maximum quota and the amount of space remaining.

If no quota is configured, uploads are limited only by the maximum individual file size permitted by the platform.

Contact your system administrator to review or increase your tenant's storage quota.

***

## Permissions

Access to the File Management module and its individual actions is controlled by the following permissions. Your administrator assigns these permissions to roles, which are then assigned to users.

### Directory Permissions

| Permission                                | What it allows                                 |
| ----------------------------------------- | ---------------------------------------------- |
| FileManagement.DirectoryDescriptor        | View directories and browse the directory tree |
| FileManagement.DirectoryDescriptor.Create | Create new directories                         |
| FileManagement.DirectoryDescriptor.Update | Rename and move directories                    |
| FileManagement.DirectoryDescriptor.Delete | Delete directories and all their contents      |

### File Permissions

| Permission                           | What it allows                                       |
| ------------------------------------ | ---------------------------------------------------- |
| FileManagement.FileDescriptor        | View the file list and file metadata; download files |
| FileManagement.FileDescriptor.Create | Upload new files                                     |
| FileManagement.FileDescriptor.Update | Rename and move files                                |
| FileManagement.FileDescriptor.Delete | Delete files                                         |

Users who have directory view permission but not file view permission can still browse the directory tree; they will not see file listings within directories.

The module itself requires the **FileManagement.Enable** tenant feature to be active. If this feature is not enabled for your tenant, none of the above permissions will grant access to the module.

***

## Troubleshooting

**I cannot see the File Management module at all.** The module requires the FileManagement.Enable feature to be active for your tenant, and you must have at least the FileManagement.DirectoryDescriptor view permission. If both conditions are met but the module is still not visible, contact your administrator to verify your role assignments and tenant feature configuration.

**The upload fails with a "file already exists" error.** A file with that exact name already exists in the target directory. Either rename your file before uploading, choose a different directory, or use the overwrite option if it is presented to you and you intend to replace the existing file.

**The upload fails with a "not enough storage" error.** Your tenant has reached or nearly reached its storage quota. The error message shows the configured quota and the remaining space. Delete files you no longer need to free up space, or ask your administrator to increase the quota.

**My download link expired or failed.** Download tokens are valid for 60 seconds from the moment they are generated. If the download did not begin in time, return to the file listing and initiate the download again to receive a fresh token.

**I cannot rename or move a directory or file.** You need the Update permission for the respective resource type. Contact your administrator if you believe you should have this permission.

**A directory or file name I entered is being rejected.** Names cannot be blank, cannot exceed 255 characters, and cannot contain characters that are invalid in file system names: `\`, `/`, `:`, `*`, `?`, `"`, `<`, `>`, and `|`. The name `con` is also reserved and cannot be used. Additionally, the name must be unique within its parent container.

**Deleting a directory takes longer than expected.** When a directory has many nested subdirectories and files, the system deletes all contents recursively before removing the directory itself. This may take a moment for large directory trees. Do not navigate away or retry during this process.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nimble.docs.otised.com/guides/file-management-module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.