File Attachments
File Attachments allow objects to include and manage associated files and documents. Open Register leverages Nextcloud's powerful file storage capabilities to provide a robust and secure file management system. By building on top of Nextcloud's proven infrastructure, Open Register inherits all the benefits of Nextcloud's file handling including:
- Secure file storage and encryption
- File versioning and history
- Collaborative features like sharing and commenting
- Preview generation for supported file types
- Automated virus scanning
- Flexible storage backend support
Overview
When a register is created in Open Register, a share is also automatically created in Nextcloud. Then when a schema is created, a folder is created within that share, and when an object is created, a folder is created (using the UUID of the object) in the folder of the schema. This means that every object has a corresponding folder. Files present in that folder are assumed to be attached to the object. This gives a simple and intuitive system of coupling files to objects.
Alternatively, users can also relate (existing) files to an object by using the Nextcloud file system and tagging the file 'object:[uuid]' where '[uuid]' is the UUID of the object. In neither case is there a relation between the file and a property in the object. The files are however available through the object API because file objects are returned in the object metadata under the files array.
File Object Structure
The file object contains the following properties:
Property | Type | Description |
---|---|---|
id | integer | Unique identifier of the file in Nextcloud |
path | string | Full path to the file in Nextcloud |
title | string | Name of the file |
accessUrl | string | URL to access the file via share link |
downloadUrl | string | Direct download URL for the file |
type | string | MIME type of the file |
extension | string | File extension |
size | integer | File size in bytes |
hash | string | ETag hash for file versioning |
published | string | ISO 8601 timestamp when file was first shared |
modified | string | ISO 8601 timestamp of last modification |
labels | array | Array of tags and key-value pairs |
This hierarchical organization ensures files are properly categorized and easily accessible.
Attaching Files to Objects
Files can be attached to objects in several ways:
- Schema-defined file properties: When a schema includes properties of type 'file', these are automatically handled during object creation or updates
- Direct API attachment: Files can be added to an object after creation using the file attachment API endpoints
- Base64 encoded content: Files can be included in object data as base64-encoded strings
- URL references: External files can be referenced by URL and will be downloaded and stored locally
File Metadata and Tagging
Each file attachment includes rich metadata:
- Basic properties (name, size, type, extension)
- Creation and modification timestamps
- Access and download URLs
- Checksum for integrity verification
- Custom tags for categorization
Tagging System
Files can be tagged with both simple labels and key-value pairs:
- Tags with a colon (':') are treated as key-value pairs and can be used for advanced filtering and organization
Version Control
The system maintains file versions by:
- Tracking file modifications with timestamps
- Preserving checksums to detect changes
- Integrating with the object audit trail system
- Supporting file restoration from previous versions
Security and Access Control
File attachments inherit the security model of their parent objects:
- Files are stored in NextCloud with appropriate permissions
- Share links can be generated for controlled external access
- Access is managed through the OpenRegister user and group system
- Files are associated with the OpenRegister application user for consistent permissions
File Operations
The system supports the following operations on file attachments:
- Retrieving Files
- Updating Files
- Deleting Files
File Preview and Rendering
The system leverages NextCloud's preview capabilities for supported file types:
- Images are displayed as thumbnails
- PDFs can be previewed in-browser
- Office documents can be viewed with compatible apps
- Preview URLs are generated for easy embedding
Integration with Object Lifecycle
File attachments are fully integrated with the object lifecycle:
- When objects are created, their file folders are automatically provisioned
- When objects are updated, file references are maintained
- When objects are deleted, associated files can be optionally preserved or removed
- File operations are recorded in the object's audit trail
Technical Implementation
The file attachment system is implemented through two main service classes:
- FileService: Handles low-level file operations, folder management, and NextCloud integration
- ObjectService: Provides high-level methods for attaching, retrieving, and managing files in the context of objects
These services work together to provide a seamless file management experience within the OpenRegister application.