Feature Overview
The Notebook Workspaces feature transforms the Syntasa JupyterLab integration from a single-user, single-environment model into a multi-workspace architecture. Previously, users were limited to a single JupyterLab instance. This update allows users to create, manage, and organize multiple distinct workspaces, enabling better project segregation and collaboration.
Key Capabilities:
- Multi-Workspace Management: Create, edit, and delete multiple independent workspaces.
- Legacy Migration: Automatically migrates all existing notebooks into a new "Default Workspace" upon upgrade.
- Workspace Isolation: Each workspace acts as a container for specific notebooks, allowing for logical grouping of analytical assets.
- Flexible Views: Toggle between Grid and List views for managing workspace assets.
Configuration Reference
Workspace Object Model
When creating or editing a workspace, the following fields are managed.
| Field Name | Description | Options/Constraints |
|---|---|---|
| Workspace Name | The display name for the workspace. | • Required • Must be unique per user (implied standard). |
| Description | Optional context about the workspace's purpose. | • Optional text field. |
| Default Workspace | System-generated workspace for legacy content. | • Created automatically during system upgrade. • Cannot be deleted if it contains the user's primary migration data (logic dependent). |
API Resources (Technical Reference)
For advanced users or automation, the feature exposes the following REST endpoints:
| Method | Endpoint | Description |
|---|---|---|
GET | /workspaces | Retrieve a paginated list of user workspaces. |
GET | /workspaces/{id} | Retrieve details for a specific workspace. |
POST | /workspaces | Create a new notebook workspace. |
PUT | /workspaces/{id} | Update workspace details (e.g., Name, Description). |
DELETE | /workspaces/{id} | Delete a workspace. |
GET | /workspaces/{id}/notebooks | List all notebooks contained within a specific workspace. |
Operational Behavior
Migration Logic (Upgrade Event)
Upon upgrading to the version containing Notebook Workspaces, the system performs an automatic one-time migration:
- Creation: A new workspace named "Default Workspace" is created for every user.
- Consolidation: All existing notebooks associated with the user are moved into this Default Workspace.
Data Safety & "Soft Delete" Side-Effect
Critical Note on Deleted Notebooks:
The migration process scans the underlying file system for notebook artifacts. Historically, deleting a notebook in the UI performed a "soft delete" (removing the UI entry but retaining the physical files).
- Consequence: During migration, previously deleted notebooks may reappear in the Default Workspace.
- Reason: The migration script identifies valid notebook files on the disk and restores them to ensure no data is accidentally lost.
- Action: Users must manually delete these unwanted notebooks again if they are no longer needed.
Deletion Logic
- Workspace Deletion: Deleting a workspace will typically require the workspace to be empty or will cascade delete the contained notebooks (Standard behavior to be confirmed in UI).
- Notebook Deletion: Deleting a notebook from a workspace now performs the standard delete operation defined by the new API.
Troubleshooting
| Error / Symptom | Technical Cause | Recommended Action |
|---|---|---|
| "Why do I see old/deleted notebooks in my Default Workspace?" | The migration script detected "soft-deleted" files on the backend storage that were never physically removed. | This is expected behavior to prevent data loss. Review the notebooks and manually delete any that are truly obsolete. |
| "Default Workspace" already exists | The system attempts to create a workspace with the reserved name "Default Workspace" during initialization. | If you manually created a workspace with this name before the migration script ran, the system may append a suffix or merge contents (System dependent). |
| Migration Failed | Network or Storage connectivity issues during the initial launch upgrade script. | Check system logs for Notebook Service: Upgrade script errors. Retry the migration or contact support. |