@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,372 @@
+# 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)