@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-orgaTree-edit/research.md

@@ -0,0 +1,353 @@
+# Research: cf.cplace.orgaTree.edit Widget
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.orgaTree.edit`
+**Widget Name:** Edit Organizational Structure
+**Repository:** cplace-project-planning
+**Plugin:** cf.cplace.orgaTree
+**Definition Class:** `cf.cplace.orgaTree.script.EditOrgaTreeWidgetDefinition`
+
+## Short Description
+
+The Edit Organizational Structure widget provides an interactive tree view for managing organizational hierarchies, allowing users to create, edit, reorganize, and navigate departments, teams, members, and their associated schedules through drag-and-drop operations and context menus.
+
+## Purpose
+
+The `cf.cplace.orgaTree.edit` widget serves as the primary interface for managing organizational structures within cplace. It displays a hierarchical tree representation of an organization's structure, showing the relationships between departments, teams, users (persons), and their associated schedules.
+
+The widget enables users to:
+- Visualize the complete organizational hierarchy
+- Navigate through departments, subdepartments, teams, and team members
+- Reorganize the structure via drag-and-drop operations
+- Create new organizational entities (departments and teams) through context menus
+- Access and manage schedules associated with individual users
+- View access rights for organizational units
+
+## Use Cases
+
+### 1. Organizational Structure Management
+Users need to manage and maintain the organizational structure of their company or project.
+
+**Scenarios:**
+- Building an initial organizational structure for a new workspace
+- Updating the structure when teams are reorganized
+- Adding new departments when the organization grows
+- Restructuring departments by dragging and dropping them to new positions
+
+### 2. Team Management
+HR managers or department heads need to organize teams within departments.
+
+**Scenarios:**
+- Creating new teams within a department
+- Viewing all teams and their members at a glance
+- Reorganizing teams by moving them between departments
+- Managing team membership through the hierarchical view
+
+### 3. User Assignment and Overview
+Managers need to see which users belong to which departments and teams.
+
+**Scenarios:**
+- Getting an overview of all organizational members
+- Identifying which departments and teams a user belongs to (users can appear multiple times)
+- Accessing user profiles through the tree navigation
+- Managing user assignments to organizational units
+
+### 4. Schedule Management Access
+Users need to access schedules associated with organizational members.
+
+**Scenarios:**
+- Navigating to a user's own schedules through the organizational tree
+- Accessing substitute schedules where users are deputies
+- Managing project schedules in the context of organizational structure
+- Viewing and copying schedules directly from the organizational hierarchy
+
+### 5. Homepage and Navigation Hub
+The widget serves as the primary homepage for spaces with the Organizational Structure app.
+
+**Scenarios:**
+- Landing page when accessing an organizational structure workspace
+- Central navigation point for all organizational data
+- Quick access to create new organizational entities
+- Overview page for understanding organizational hierarchy
+
+## Core Functionality
+
+### Tree Structure Display
+
+The widget displays a hierarchical tree with the following node types:
+
+1. **Departments** (Root level and nested)
+   - Can have parent-child relationships (subdepartments)
+   - Contain users as direct members
+   - Contain teams as children
+   - Icon: `fa-users`
+
+2. **Teams**
+   - Must belong to a department
+   - Contain users as members
+   - Icon: `fa-user-plus`
+
+3. **Persons** (Users)
+   - Can belong to multiple departments and/or teams
+   - Expand to show associated schedules
+   - Display "Own schedules" and "Substitute schedules" as virtual nodes
+
+4. **Virtual Schedule Nodes**
+   - Own schedules: Schedules where the user is the owner
+   - Substitute schedules: Schedules where the user is a deputy
+   - These nodes expand to show actual schedule items
+
+5. **Schedules**
+   - Leaf nodes in the tree
+   - Can be copied through context menu
+   - Linked to project planning functionality
+
+### Interactive Features
+
+#### Drag-and-Drop Reorganization
+
+The widget supports drag-and-drop operations for reorganizing the hierarchy:
+
+- **Movable items:** Departments (can be moved to create subdepartments or change parent)
+- **Move validation:** Server-side validation via `CanMoveHandler` ensures only valid moves are allowed
+- **Caching:** Move validation results are cached on the target node to improve performance
+- **Permission check:** Users must have edit rights on the source node to move it
+
+**Implementation details:**
+- Position can be: "before", "after", or "inside" the target node
+- Only departments can currently be moved via drag-and-drop
+- The handler checks if the move is valid in the hierarchy (no circular references, valid parent-child relationships)
+
+#### Context Menu Actions
+
+The widget provides context-sensitive actions via right-click or dropdown menus:
+
+**For Departments:**
+- **New Department:** Create a new subdepartment
+- **New Team:** Create a new team within the department
+- **Open in new tab:** Navigate to the department page
+- **Edit access rights:** Open a user-rights matrix for all members in the department and its teams
+- **Delete:** Remove the department (if permissions allow)
+
+**For Teams:**
+- **New Team:** Create another team in the same department
+- **Open in new tab:** Navigate to the team page
+- **Edit access rights:** Open a user-rights matrix for all team members
+- **Delete:** Remove the team (if permissions allow)
+
+**For Schedules:**
+- **Copy:** Duplicate the schedule
+- **Open in new tab:** Navigate to the schedule page
+- **Delete:** Remove the schedule (if permissions allow)
+
+**For Persons and Virtual Nodes:**
+- **Open in new tab:** Navigate to the user profile or schedule
+
+### Data Loading
+
+The widget uses a lazy-loading approach:
+
+1. **Initial Load:** Root departments are loaded and displayed
+2. **Root nodes are auto-expanded:** Root elements have `load_on_demand: false` to show their immediate children
+3. **On-demand loading:** Child nodes are loaded when a parent node is expanded
+4. **Load URL:** The `LoadChildrenHandler` is called with the content provider ID to fetch child nodes
+5. **Content Provider:** `OrgaTreeContentProvider` handles all data retrieval and tree structure logic
+
+### Real-time Updates
+
+The widget listens to platform events:
+
+- **Page Creation:** When a new department or team is created, the parent node is reloaded and expanded
+- **Page Deletion:** When a department, team, or schedule is deleted, the node is removed from the tree
+- **Node Registration:** Nodes register themselves with the widget controller for event handling
+
+## Configuration
+
+The widget has minimal configuration requirements:
+
+### Widget Configuration
+
+- **Widget Kind:** `cf.cplace.orgaTree.edit`
+- **No custom parameters:** The widget automatically determines what to display based on the current workspace
+
+### Data Configuration
+
+The widget's behavior is configured through the `OrgaTreeContentProvider`:
+
+- **Root nodes:** All departments without a parent in spaces with the OrgaTree app
+- **Content Provider ID:** `orga_tree`
+- **Tab name:** "Organizational Structure"
+- **Order index:** 10 (determines position when multiple tree content providers exist)
+
+### Selection Mode
+
+The widget defines different selection modes for different node types:
+
+- **Departments:** `NONE` - Cannot be selected (navigation only)
+- **Teams:** `NONE` - Cannot be selected (navigation only)
+- **Persons:** `NONE` - Cannot be selected (navigation only)
+- **Groups:** `NONE` - Cannot be selected (navigation only)
+- **Virtual schedule nodes:** `CHILDREN` - Selecting the node selects all child schedules
+- **Schedules:** `SELF` - The schedule itself can be selected
+
+**Note:** In the current implementation, selection modes exist in the code but appear to be primarily for future functionality or integration with other widgets. The edit widget focuses on navigation and manipulation rather than selection.
+
+## Context and Relationships
+
+### Related Widgets
+
+1. **Project Tree Widget** (`cf.cplace.projectTree`)
+   - Similar hierarchical tree structure for project management
+   - Shares base classes and tree infrastructure (`TreeContentProvider`, `LoadChildrenHandler`)
+   - OrgaTree integrates with project tree through schedule management
+
+2. **Personal Tree Content Provider**
+   - Referenced from `ProjektplanungPlugin` for schedule management
+   - Provides "Own schedules" and "Substitute schedules" functionality
+   - Enables users to access their schedules through the organizational tree
+
+### App Integration
+
+The widget is part of the **Organizational Structure App** (`cf.cplace.orgaTree`):
+
+- **App display name:** "Organizational Structure"
+- **App description:** "The 'Organizational Structure' app lets you manage employees and teams in an organizational structure. This app offers you an organizational tree that helps you create, edit, and manage employees, teams, and sectors."
+- **Homepage widget:** This widget is automatically created as the homepage when the app is added to a workspace
+- **Type definitions:** The app defines DEPARTMENT and TEAM types
+
+### Dependencies
+
+**Backend dependencies:**
+- `cf.cplace.planauswahl` - Tree selection infrastructure (TreeContentProvider, TreeData, TreeItem)
+- `cf.cplace.projektplanung` - Schedule management and personal tree functionality
+- `cf.cplace.platform.frontend.handler.flexigrid.data` - Tree utilities and node interfaces
+
+**Frontend dependencies:**
+- AngularJS directive (`cfCplaceOrgaTreeEditWidget`)
+- jQuery tree widget (`cplace_jq_tree`)
+- Platform event system for real-time updates
+
+### Permission Model
+
+The widget respects cplace's permission system:
+
+- **Create:** Users need "create pages in same space" permission to add new departments/teams
+- **Edit/Move:** Users need edit rights on the source node to move it
+- **Delete:** Users need delete permissions on the entity
+- **Read:** The tree only shows entities the user has read access to
+
+## Technical Architecture
+
+### Backend Components
+
+**EditOrgaTreeWidgetDefinition.java:**
+- Widget registration and definition
+- Provides template substitution with tree data
+- Configures URLs for loading children and validating moves
+
+**OrgaTreeContentProvider.java:**
+- Implements `TreeContentProvider` interface
+- Handles data retrieval for all node types
+- Manages parent-child relationships
+- Provides bidirectional navigation (get children, get parents)
+- Handles both real nodes (pages, persons) and virtual nodes (schedule containers)
+
+**CanMoveHandler.java:**
+- Validates whether a department can be moved to a target position
+- Prevents invalid hierarchy structures
+- Uses `CanMoveMenuItemHandler.canMoveInHierarchy()` for validation
+
+**ContextMenuActionsProvider.java:**
+- Defines all available context menu actions
+- Implements permission checks for each action
+- Provides URLs for action execution
+
+### Frontend Components
+
+**cfCplaceOrgaTreeEditWidget.js:**
+- AngularJS directive that initializes the tree widget
+- Configures drag-and-drop behavior
+- Handles event listeners for page creation/deletion
+- Manages node registration for updates
+- Configures custom rendering templates
+
+**jQuery Tree Widget:**
+- Underlying tree rendering library
+- Handles tree state (expanded/collapsed)
+- Manages drag-and-drop interactions
+- Renders custom templates for different node types
+
+### Data Model
+
+**Type hierarchy:**
+```
+Department
+  - parent: Department (optional, creates hierarchy)
+  - users: Person[] (department members)
+  └─ subdepartments (incoming PARENT references)
+  └─ teams (incoming DEPARTMENT references)
+
+Team
+  - department: Department (required)
+  - users: Person[] (team members)
+
+Person (platform type)
+  └─ Virtual Node: Own Schedules
+      └─ Schedule[] (where person is owner)
+  └─ Virtual Node: Substitute Schedules
+      └─ Schedule[] (where person is deputy)
+```
+
+### Tree Node Types
+
+The implementation distinguishes between:
+
+1. **SimpleCustomEntityTreeNode:** Represents actual entities (departments, teams, persons, schedules)
+2. **VirtualSimpleTreeNode:** Represents virtual grouping nodes (schedule containers)
+3. **Node:** Legacy node interface for backward compatibility
+4. **ITreeNode:** Modern tree node interface
+
+## Key Implementation Details
+
+### Lazy Loading Mechanism
+
+1. Initial page load: Widget definition generates JSON with root departments
+2. Root nodes have `load_on_demand: false` - their children are included in initial data
+3. When user expands a node: Ajax call to `LoadChildrenHandler` with parent UID
+4. Handler delegates to `OrgaTreeContentProvider.getAllChildren()`
+5. Children are rendered and added to tree
+
+### Multi-parent Support
+
+Users can belong to multiple departments and/or teams:
+- Person nodes appear multiple times in the tree
+- Each appearance is a separate node with unique node ID
+- Node registration tracks which UIDs correspond to which node IDs
+- When a user is deleted, all instances are removed from the tree
+
+### Path Finding
+
+The widget supports finding paths from root to a specific node:
+- Used for highlighting and expanding to show a specific entity
+- Handles multiple possible paths (e.g., user belonging to multiple departments)
+- Can filter paths to only include specific required nodes
+
+### Caching Strategy
+
+The widget caches move validation results:
+- Each target node maintains a cache: `{sourceUid: {position: boolean}}`
+- Reduces server calls when dragging the same node over multiple positions
+- Cache is stored on the tree node object in the client
+
+## Limitations and Constraints
+
+1. **Move operations:** Only departments can be moved via drag-and-drop, not teams or users
+2. **Context menu:** Not all actions are available for all node types
+3. **Selection:** The edit widget is primarily for navigation and manipulation, not for selection
+4. **Permissions:** Actions are hidden if the user lacks permissions rather than being disabled
+5. **Real-time sync:** Updates are event-driven but only for create/delete, not for edit operations
+
+## Summary
+
+The `cf.cplace.orgaTree.edit` widget is a sophisticated hierarchical tree widget that serves as the central interface for managing organizational structures in cplace. It combines visualization, navigation, and manipulation capabilities in a single interactive component. The widget is designed for HR managers, department heads, and administrators who need to maintain organizational hierarchies, manage team structures, and access associated schedules. Its drag-and-drop functionality, context-sensitive actions, and integration with the broader cplace platform make it a powerful tool for organizational management.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-outlookMessageIntegration-outlookMessages/research.md

@@ -0,0 +1,233 @@
+# Widget Research: cf.cplace.outlookMessageIntegration.outlookMessages
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.outlookMessageIntegration.outlookMessages`
+**Repository:** `cplace-paw`
+**Plugin:** `cf.cplace.outlookMessageIntegration`
+**Definition Class:** `OutlookMessagesWidgetDefinition.java`
+
+## Purpose
+
+The Outlook Messages widget enables users to import and display Microsoft Outlook email messages (.msg files) within cplace pages. Users can drag and drop Outlook message files directly into the widget, which parses the email data and creates structured email records as child pages, preserving the email content, metadata, and attachments.
+
+## Core Functionality
+
+### What This Widget Does
+
+The widget provides two main functions:
+
+1. **Email Import**: Accepts Outlook .msg files via drag-and-drop upload
+2. **Email Display**: Shows imported emails in a tabular format with key metadata
+
+When a user uploads an .msg file:
+- The widget parses the file using Apache POI's HSMF library (Microsoft Outlook MSG format parser)
+- Creates a new page of type "email" as a child of the current page
+- Extracts and stores email metadata (subject, sender, recipients, date)
+- Preserves the email body content (HTML or plain text)
+- Extracts and attaches any file attachments from the email
+- Displays the new email in the widget's table
+
+### Technical Architecture
+
+**Frontend Components:**
+- Template: `outlookMessagesWidgetDefinition.htm` - Drag-and-drop zone and table display
+- Controller: `OutlookMessagesWidgetCtrl.ts` - Upload handling and table refresh
+- Based on `AbstractUploadCtrl` for file upload functionality
+
+**Backend Components:**
+- `OutlookMessagesWidgetDefinition.java` - Widget definition and rendering
+- `MessageUploadHandler.java` - Processes uploaded .msg files and creates email pages
+- `OutlookMessagesTableHandler.java` - Generates updated table data after uploads
+- `OutlookMessagesWidgetState.java` - Manages widget state (upload URL, table reload URL)
+- `OutlookMessagesTableTemplateSubstitution.java` - Renders the email table
+
+**Data Model:**
+- Type: "email" (EMAIL type definition in OutlookMessageIntegrationAppTypes.java)
+- Attributes:
+  - `subject` (SingleString) - Email subject line
+  - `from` (SingleString) - Sender information
+  - `to` (MultiString) - Recipients list
+  - `date` (SingleDate) - Email timestamp
+  - `content` (SingleRichString) - Email body (HTML or plain text)
+  - `parent` (SinglePageReference) - Reference to parent page (hierarchical relationship)
+- All attributes are read-only after import
+- Attachments stored as Document entities linked to the email page
+
+## Use Cases
+
+### Primary Use Cases
+
+1. **Project Communication Archive**
+   - Teams working on projects can archive relevant email correspondence directly in project pages
+   - Keep all project-related information (tasks, documents, emails) in one place
+   - Preserve email context and history within the project workspace
+
+2. **Issue Documentation**
+   - When issues are reported or discussed via email, import the email into the issue page
+   - Create an audit trail of email communications related to specific issues
+   - Reference email content when resolving problems
+
+3. **Client Communication Tracking**
+   - Import customer or client emails into relevant customer/account pages
+   - Maintain a complete history of email interactions
+   - Share email context with team members who weren't on the original thread
+
+4. **Compliance and Record-Keeping**
+   - Store important business emails within structured records
+   - Create searchable archives of email communications
+   - Maintain email evidence linked to specific business processes or entities
+
+5. **Knowledge Management**
+   - Preserve valuable information shared via email
+   - Convert email discussions into searchable, structured content
+   - Make email knowledge accessible to broader teams
+
+### When to Use This Widget
+
+Choose this widget when:
+- The page represents an entity that may receive related email communications (projects, issues, customers, etc.)
+- You need to integrate email conversations into your cplace workflow
+- You want to preserve email context alongside other structured data
+- Team members need access to email information without forwarding or CC'ing
+
+### What Problem It Solves
+
+- **Information Silos**: Email conversations remain isolated in individual inboxes. This widget brings email content into the shared workspace.
+- **Context Loss**: Important email discussions are disconnected from related work items. The widget links emails directly to relevant pages.
+- **Manual Data Entry**: Instead of copying email content manually, users can import the entire message with metadata and attachments intact.
+- **Attachment Management**: Email attachments are preserved and accessible through cplace's document management.
+
+## Configuration Concepts
+
+### Widget Configuration
+
+The widget has minimal configuration as it provides a fixed functionality:
+
+1. **Embedding**:
+   - Can only be embedded in Page entities (or type definitions that apply to Pages)
+   - Enforced by `checkEmbeddableIn` method in the widget definition
+   - Creates hierarchical relationship: parent page → child email pages
+
+2. **Display Options**:
+   - No padding on widget container (`isNoPadding() = true`)
+   - Fixed table layout with columns: Subject, Attachments, Date, Recipient, Sender
+   - Emails sorted by date (most recent first)
+
+3. **Upload Handling**:
+   - Only accepts .msg file format (Microsoft Outlook Message format)
+   - Validates file extension before processing
+   - Shows upload progress indicator during file processing
+   - Displays error messages for invalid files or upload failures
+
+### User Interface Elements
+
+**Drag-and-Drop Zone:**
+- Visual drop zone with envelope icon
+- Upload progress indicator with percentage
+- Shows spinner during processing
+
+**Email Table:**
+- Displays all email pages that are children of the current page
+- Columns:
+  - Subject (clickable link to email page)
+  - Number of attachments (file icon with count)
+  - Date
+  - Recipients (To field)
+  - Sender (From field)
+- Automatically refreshes after successful upload
+
+### Technical Constraints
+
+- **File Format**: Only Microsoft Outlook .msg files are supported
+- **Parsing**: Uses Apache POI HSMF library for .msg file parsing
+- **Parent-Child Relationship**: Email pages are always created as children of the page containing the widget
+- **Read-Only Data**: Once imported, email data cannot be edited (enforces data integrity)
+- **Space Context**: Emails are created in the same space as their parent page
+
+## Context and Relationships
+
+### Related Components
+
+1. **Email Type Definition** (`OutlookMessageIntegrationAppTypes.EMAIL`)
+   - Defines the structure for imported email pages
+   - Includes default layout with content, attributes, and files widgets
+   - Uses "fa-envelope" icon for email pages
+
+2. **Document Management**
+   - Email attachments are created as Document entities
+   - Documents are linked to email pages via parent-child relationship
+   - Attachments preserve original filenames and content
+
+3. **Page Hierarchy**
+   - Emails use parent reference attribute for hierarchical structure
+   - Parent page can have multiple email children
+   - Email pages inherit space context from parent
+
+### Integration Points
+
+- **Upload Framework**: Extends `AbstractUploadCtrl` for consistent upload behavior across cplace
+- **Search System**: Emails are searchable like any other page type
+- **Attribute Display**: Email content can be displayed using standard cplace attribute widgets
+- **Files Widget**: Email attachments displayed via standard files widget on email detail page
+
+### Prerequisites
+
+- The page where the widget is embedded must allow child pages (hierarchical structure)
+- User must have edit permissions on the parent page to upload emails
+- Email pages are created in the same space as the parent (requires space permissions)
+
+### No Dependencies On
+
+- External Outlook/Exchange server connections (works with exported .msg files)
+- Active email accounts or IMAP/SMTP configuration
+- Email client plugins or integrations
+
+## Implementation Details
+
+### Email Parsing Process
+
+When a .msg file is uploaded:
+
+1. **Validation**:
+   - Check file extension is ".msg"
+   - Verify file can be read
+
+2. **Parse Email Metadata**:
+   - Extract subject (used as page title)
+   - Parse sender information (name and email address)
+   - Extract recipient list with names and email addresses
+   - Get message date/time
+
+3. **Process Email Body**:
+   - Attempt to extract HTML body first
+   - Fall back to plain text if HTML not available
+   - Convert line separators to `<br>` tags for plain text
+
+4. **Extract Attachments**:
+   - Iterate through attachment chunks in .msg file
+   - Create Document entity for each attachment
+   - Copy attachment data into document version
+   - Link documents to email page
+
+5. **Create Email Page**:
+   - Create page of type "email" with subject as title
+   - Set all metadata attributes
+   - Link to parent page
+   - Persist page and documents
+
+6. **Refresh Display**:
+   - Reload table via AJAX call
+   - Display updated list of emails
+   - Enable upload for next file
+
+### Error Handling
+
+- Invalid file format: Shows specific error message
+- Parse failures: Logged and generic error shown to user
+- Attachment extraction failures: Logged individually, continue processing other attachments
+- Upload progress tracking with visual feedback
+
+## Summary
+
+The Outlook Messages widget provides a streamlined way to integrate email communications into cplace's structured information management. By accepting Outlook .msg files via drag-and-drop, it eliminates the gap between email conversations and related work items, creating a unified view of all project-relevant information. The widget is particularly valuable for teams that need to maintain audit trails, preserve context, or share email information within collaborative workspaces.