@cplace/mcp-server 1.6.0 → 1.6.1

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-platform-batchJobQuickGlance/research.md

@@ -1,372 +0,0 @@
-# Batch Job Quick Glance Widget Research
-
-**Widget ID:** `cf.cplace.platform.batchJobQuickGlance`
-**Widget Name:** Batch Job Quick Access
-**Repository:** main
-**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/BatchJobQuickGlanceWidgetDefinition.java`
-
----
-
-## 1. Purpose
-
-The Batch Job Quick Glance widget provides a quick overview and control panel for background batch jobs in cplace. It displays the status of the most recent execution of a selected batch job and provides actions to start, configure, suspend, or resume the job directly from the widget.
-
-### Core Functionality
-
-- **Job Status Monitoring**: Shows real-time status of the last executed job instance (running, success, failed, etc.)
-- **Quick Actions**: Provides buttons to start, configure, suspend/resume jobs without navigating away
-- **Job Details Access**: Links to detailed job information and download results
-- **Auto-refresh**: Automatically polls for updates when a job is running
-
----
-
-## 2. Use Cases
-
-### When to Use This Widget
-
-1. **Administrative Dashboards**: Display status of critical system jobs (e.g., data synchronization, cleanup tasks) on admin pages
-2. **Department/Team Pages**: Allow department managers to monitor and trigger department-specific export or processing jobs
-3. **Configuration Pages**: Embed on pages related to job configuration to provide immediate execution and status feedback
-4. **Operational Monitoring**: Create overview pages that display multiple batch jobs using multiple widget instances
-
-### Specific Examples
-
-Based on the implementation example found in `cf.cplace.training.extended.ExtendedPlugin`:
-
-**Export Employees Job**
-- Embedded on Department pages
-- Allows department managers to export employee data for their department
-- Provides download button to retrieve the exported file
-- Custom configuration through a modal dialog before starting the job
-
-### When NOT to Use This Widget
-
-- For real-time operations that don't use the batch job infrastructure
-- When jobs don't create persistent job records in the system
-- For simple actions that complete immediately (use regular action handlers instead)
-
----
-
-## 3. Configuration Concepts
-
-### Required Configuration
-
-The widget requires two main configuration attributes:
-
-1. **Quick Glance Provider ID** (`cf.cplace.platform.quickGlanceProviderId`)
-   - Selects which batch job to monitor and control
-   - Dynamic enumeration populated by `BatchJobQuickGlanceExtension` implementations
-   - Only shows jobs that are selectable for the page where the widget is embedded
-
-2. **Title** (`cf.cplace.platform.title`)
-   - Optional custom title for the widget
-   - Falls back to the job's label if not provided
-
-### Extensibility Through BatchJobQuickGlanceExtension
-
-Plugin developers extend this widget's capabilities by implementing `BatchJobQuickGlanceExtension`:
-
-```java
-public abstract class BatchJobQuickGlanceExtension extends PluginExtension {
-    // Unique identifier for the job
-    public abstract String getIdentifier();
-
-    // Label shown in the widget
-    public abstract Message getLabel();
-
-    // The QueuedBatchJob class this widget manages
-    public abstract Class<? extends QueuedBatchJob> getJobClass();
-
-    // Optional: Suspendable task for activate/deactivate functionality
-    public PerTenantTimerTask getSuspendableTask();
-
-    // Optional: Custom start job handler URL
-    public String getStartBatchJobUrl(PersistentEntity embeddedIn);
-
-    // Optional: Configuration handler URL
-    public String getConfigurationUrl(PersistentEntity embeddedIn);
-
-    // Control which buttons are shown
-    public boolean showConfigurationButton();
-    public boolean showDownloadButton();
-
-    // Control where the extension can be used
-    public boolean isSelectableIn(PersistentEntity embeddedIn);
-}
-```
-
-### Widget Features
-
-The widget automatically provides:
-
-1. **Job State Display**
-   - Job ID and creation timestamp
-   - Current status (created, running, success, failed, cancelled, waitForCancel)
-   - Link to detailed job view page
-
-2. **Action Buttons** (conditionally shown)
-   - **Run**: Starts a new job instance
-   - **Configure**: Opens configuration dialog (if enabled by extension)
-   - **Download File**: Downloads job results (if enabled by extension)
-   - **Activate/Deactivate**: Suspends or resumes scheduled jobs (if suspendable task provided)
-   - **Go to Job**: Links to the last job instance detail page
-
-3. **Real-time Updates**
-   - Polls every 5 seconds when a job is running
-   - Automatically updates status without page refresh
-   - Loading indicators during operations
-
----
-
-## 4. Context and Relationships
-
-### Related Platform Components
-
-1. **QueuedBatchJob**
-   - Base class for background jobs in cplace
-   - Jobs are executed outside of HTTP requests
-   - Creates `PersistentJob` records that track execution state
-
-2. **PersistentJob**
-   - Entity that stores job execution information
-   - Tracks status, creation time, creator, and results
-   - Accessible through job details page
-
-3. **PerTenantTimerTask**
-   - Scheduler for recurring jobs
-   - Can be suspended/resumed if made suspendable
-   - Widget can control task activation if connected to extension
-
-4. **Job Execution Service**
-   - Platform service that executes batch jobs
-   - Manages job queuing and execution
-   - Handles job lifecycle (created → running → success/failed)
-
-### Integration Points
-
-**Frontend (TypeScript)**
-- Directive: `cplaceBatchJobQuickGlanceWidget`
-- Controller: `BatchJobQuickGlanceWidgetCtrl`
-- Location: `/build/resources/cf.cplace.platform/assets/ts/directives/cplaceBatchJobQuickGlanceWidget.ts`
-
-**Backend Handlers**
-- `BatchJobQuickGlanceDetailsHandler`: Fetches current job status
-- `StartBatchJobFromQuickGlanceHandler`: Starts new job instances
-- `SuspendResumeFromQuickGlanceHandler`: Controls task suspension
-
-**Extension System**
-- Plugins register `BatchJobQuickGlanceExtension` implementations
-- Extensions are discovered through the plugin system
-- Dynamic enumeration provider filters available jobs based on embedding context
-
----
-
-## 5. Technical Details
-
-### Widget Embedding Rules
-
-The widget checks if it can be embedded using:
-```java
-public void checkEmbeddableIn(PersistentEntity entity, WidgetEmbedding embedding) {
-    defaultCheckEmbeddableIn(entity, embedding);
-    if (BatchJobQuickGlanceEnumerationProvider.getOptionsForEmbeddingEntity(entity).isEmpty()) {
-        throw new NotEmbeddableException("no suitable quick glance providers found");
-    }
-}
-```
-
-This means:
-- Widget can only be embedded if at least one `BatchJobQuickGlanceExtension` is selectable for that page
-- Extensions control their selectability via `isSelectableIn(embeddedIn)`
-- Common pattern: restrict to specific custom types (e.g., only on Department pages)
-
-### Job Status States
-
-The widget recognizes these job states:
-- `created`: Job created but not yet started
-- `running`: Job is currently executing
-- `waitForCancel`: Job is being cancelled
-- `success`: Job completed successfully
-- `failed`: Job encountered errors
-
-### Security Considerations
-
-- Access control is delegated to extension implementations
-- Extensions can check user permissions in `getStartBatchJobUrl()` and `getConfigurationUrl()`
-- Default behavior: anyone who can view the page can start the job
-- Job details respect standard entity read permissions
-
----
-
-## 6. Example Implementation
-
-From `cf.cplace.training.extended.ExtendedPlugin` (lines 482-519):
-
-```java
-final BatchJobQuickGlanceExtension exportEmployeesQuickGlance = new BatchJobQuickGlanceExtension() {
-    @Nonnull
-    @Override
-    public String getIdentifier() {
-        return "cf.cplace.training.extended.exportEmployees";
-    }
-
-    @Nonnull
-    @Override
-    public Message getLabel() {
-        return exportEmployeesLabel;  // "Export Employees"
-    }
-
-    @Nonnull
-    @Override
-    public Class<? extends QueuedBatchJob> getJobClass() {
-        return ExportEmployeesJob.class;
-    }
-
-    @Nonnull
-    @Override
-    public String getStartBatchJobUrl(@Nonnull PersistentEntity embeddedIn) {
-        Preconditions.checkArgument(embeddedIn instanceof Page);
-        final Page page = (Page) embeddedIn;
-        Preconditions.checkArgument(DEPARTMENT.TYPE.isTypeOf(page));
-        // Custom handler that shows configuration dialog before starting
-        return Forwarder.getFullUrl(
-            ConfigureHandler.class,
-            NameValue.fromId(ConfigureHandler.PARAMETER_DEPARTMENT_ID, page)
-        );
-    }
-
-    @Override
-    public boolean showDownloadButton() {
-        return true;  // Enable download of exported employee data
-    }
-
-    @Override
-    public boolean isSelectableIn(@Nonnull PersistentEntity embeddedIn) {
-        // Only show on Department pages
-        return WidgetDefinitionUtil.isTypeForPageOrType(DEPARTMENT.TYPE, embeddedIn);
-    }
-};
-```
-
-**Use Case**: Department managers can export employee lists for their department, configure export options, and download the resulting file.
-
----
-
-## 7. Localization
-
-The widget supports full internationalization:
-
-### English (messages_en.properties)
-- **Name**: "Batch Job Quick Access"
-- **Description**: "Provides a brief overview of a selected job. The job can be started or configured."
-- **Actions**: Run, Configure, Download File, Go to Job, Activate, Deactivate
-- **Messages**: "Last Execution", "Job has not yet been executed", "You do not have sufficient rights to access the last executed job."
-
-### German (messages_de.properties)
-- **Name**: "Batch-Job Schnellzugriff"
-- **Description**: "Gibt einen kurzen Überblick über einen ausgewählten Job. Der Job kann gestartet oder konfiguriert werden."
-- **Actions**: Ausführen, Konfigurieren, Datei herunterladen, Job öffnen, Aktivieren, Deaktivieren
-
----
-
-## 8. Design Patterns
-
-### Extension Pattern
-The widget uses the plugin extension pattern to allow third-party plugins to register their batch jobs for monitoring and control.
-
-### Template-Based Rendering
-Widget content is rendered server-side using the template system, with initial state passed to frontend as JSON.
-
-### Polling for Updates
-The frontend implements smart polling:
-- Only polls when job is in an active state
-- Uses 5-second intervals
-- Automatically stops when job completes
-- Restarts on new job creation
-
-### No Padding Design
-The widget sets `isNoPadding() = true` to provide a clean, integrated appearance suitable for dashboard layouts.
-
----
-
-## 9. Best Practices
-
-### For Plugin Developers
-
-1. **Implement isSelectableIn() carefully**
-   - Restrict to relevant page types
-   - Prevents widget from appearing where it doesn't make sense
-   - Improves user experience by reducing clutter
-
-2. **Provide meaningful job names**
-   - Job name should indicate what the job does and its context
-   - Include entity information when relevant (e.g., "Export Employees for IT Department")
-
-3. **Use custom start handlers for complex jobs**
-   - Override `getStartBatchJobUrl()` to show configuration dialogs
-   - Validate parameters before starting the job
-   - Return `JobCreatedJsonPage` to trigger automatic widget update
-
-4. **Enable download button appropriately**
-   - Only set `showDownloadButton() = true` if job produces downloadable files
-   - Ensure job stores results in a way compatible with `DownloadExportHandler`
-
-5. **Consider suspendable tasks for scheduled jobs**
-   - Implement `getSuspendableTask()` for recurring batch jobs
-   - Allows users to temporarily disable scheduled execution
-   - Useful for maintenance windows or troubleshooting
-
-### For Solution Designers
-
-1. **Use on appropriate pages**
-   - Configuration pages for the job's domain
-   - Admin dashboards
-   - Type-specific overview pages
-
-2. **Group related jobs**
-   - Create dedicated monitoring pages with multiple widget instances
-   - Each widget can monitor a different batch job
-
-3. **Set descriptive custom titles**
-   - When embedding multiple instances, use distinct titles
-   - Helps users quickly identify which job each widget represents
-
----
-
-## 10. Limitations
-
-1. **Single Job per Widget**: Each widget instance can only monitor one batch job at a time
-2. **Last Instance Only**: Widget shows only the most recent job execution, not historical runs
-3. **No Job History**: For full job history, users must navigate to job management pages
-4. **Polling-Based Updates**: Uses polling rather than push notifications (WebSockets)
-5. **Extension Required**: Cannot be used without a corresponding `BatchJobQuickGlanceExtension` implementation
-
----
-
-## 11. Related Widgets
-
-- **Attributes Widget**: Often used alongside to show job configuration settings
-- **Comments Widget**: Useful for team communication about job issues or results
-- **Embedded Search Widgets**: Can display list of all historical job executions if configured properly
-
----
-
-## 12. File References
-
-### Java Files
-- **Widget Definition**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/BatchJobQuickGlanceWidgetDefinition.java`
-- **Extension Base Class**: `cf.cplace.platform/src/main/java/cf/cplace/platform/core/application/job/extension/BatchJobQuickGlanceExtension.java`
-- **Enumeration Provider**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/BatchJobQuickGlanceEnumerationProvider.java`
-- **Details Handler**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/batchJob/BatchJobQuickGlanceDetailsHandler.java`
-- **Start Handler**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/batchJob/StartBatchJobFromQuickGlanceHandler.java`
-- **Suspend/Resume Handler**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/batchJob/SuspendResumeFromQuickGlanceHandler.java`
-
-### TypeScript Files
-- **Widget Directive**: `/build/resources/cf.cplace.platform/assets/ts/directives/cplaceBatchJobQuickGlanceWidget.ts`
-
-### Localization Files
-- **English**: `cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_en.properties` (lines 4235-4238, 4334-4342)
-- **German**: `cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_de.properties` (lines 4235-4238, 4334-4342)
-
-### Example Implementation
-- **Training Plugin**: `cplace-paw/cf.cplace.training.extended/src/main/java/cf/cplace/training/extended/ExtendedPlugin.java` (lines 482-519)