README

This module provides seamless integration between the Custom Field module and the Event Condition Action (ECA) module, enabling powerful workflow automation based on custom field data changes.

Overview

Field ECA Bridge connects Drupal's Custom Field module (which allows for multi-column field storage) with the Event Condition Action (ECA) module (which provides workflow automation). This integration enables creating sophisticated workflows triggered by changes to custom field data.

Features

Field Change Event Detection: Automatically detects when custom field values change and triggers corresponding ECA events.
Column-Level Granularity: Monitors changes to specific columns within custom fields for fine-grained workflow control.
Custom Conditions: Provides conditions to check custom field values and column data.
Field Manipulation Actions: Offers actions to modify custom field values from within ECA workflows.
Token Integration: Makes custom field data available through tokens for use in ECA workflows.
LLM Integration: Seamlessly works with the LLM module for AI-powered workflows.
Interactive Workflow Visualization: Visualize and interact with field-based workflows using modern, interactive diagrams.
Layout Builder Integration: Display field workflows in Layout Builder with custom layouts and blocks.
Modern UI Components: Includes modern, responsive UI components with accessibility support.

Use Cases

Model Selection Workflows: Automatically select appropriate AI models based on content metadata stored in custom fields.
Agent Configuration: Create workflows that configure agent profiles based on custom field changes.
Cost Tracking System: Implement usage tracking with custom fields and automate actions based on thresholds.
Conditional UI Reactions: Build reactive UIs that respond to changes in custom field data.
Multi-Column Data Processing: Process individual columns within custom fields for fine-grained control.
Visual Workflow Diagrams: Create interactive visualizations of complex field workflows.
Responsive Admin Dashboards: Build custom admin dashboards with field workflow metrics.

Requirements

Drupal 10 or 11
Custom Field module (^3.0.0)
ECA module (^1.1.0) and its submodules:
- ECA Content
- ECA Form
LLM module (for AI-related workflows)
Layout Builder module (for visualization and UI components)

Installation

Install the module using Composer:

composer require drupal/field_eca_bridge

Enable the module via Drush:
```
drush en field_eca_bridge
```
Ensure the required dependencies (Custom Field and ECA) are also installed and enabled.

Configuration

No special configuration is needed. Once installed, the module automatically registers events, conditions, and actions with the ECA system.

Creating Workflows

Go to Configuration → ECA → Models
Create a new ECA model
Add events using the "Custom Field" event type
Configure conditions and actions using the provided custom field plugins

Modern UI Features

The Field ECA Bridge includes modern UI components designed for the latest Drupal admin themes:

Responsive Dashboards

Card-based Layouts: Display field workflows in modern, responsive card layouts with elevation, shadows, and smooth transitions
CSS Grid & Flexbox: Utilize modern CSS layout techniques for optimal display across all device sizes
Theme Integration: Seamless integration with Claro, Gin, Olivero, and other Drupal admin themes through CSS custom properties
Dark Mode Support: Automatic detection and styling for dark mode preferences with prefers-color-scheme media queries
Variable-based Theming: Complete theme system built on CSS custom properties for easy customization and consistency
Responsive Breakpoints: Optimized layouts for mobile, tablet, and desktop views with precise breakpoints
Print Styles: Printer-friendly styles for dashboard exports and reports

/* Example: Custom theme integration */
[data-theme="custom"] {
  --field-eca-color-primary: #6200ee;
  --field-eca-color-accent: #03dac6;
  --field-eca-font-size-xl: 1.5rem;
}

Interactive Workflow Visualization

Interactive Diagrams: Visualize field workflows with interactive, draggable diagrams using modern D3.js
Node Selection: Click nodes to view detailed information about workflow components in a side panel
Keyboard Navigation: Full keyboard support for accessibility with arrow key navigation between nodes
Zoom Controls: Zoom in/out and reset controls for complex workflows with mouse wheel and pinch support
Responsive Design: Adapts to different screen sizes and orientations with mobile-optimized controls
Custom Node Types: Distinct visual styles for events, conditions, actions, and field components
Edge Highlighting: Highlight connected paths when hovering over nodes
Search & Filter: Find specific workflow components with integrated search functionality
Export Options: Export visualizations as SVG or PNG with one click
Live Updates: Optional real-time updates when workflow configurations change

// Example: Custom node selection event handling
document.querySelector('.workflow-visualization').addEventListener('nodeselect', (event) => {
  const node = event.detail.node;
  console.log(`Selected ${node.type}: ${node.label}`);
  
  // Custom handling based on node type
  if (node.type === 'field') {
    showFieldDetails(node.data);
  }
});

Layout Builder Integration

Custom Layouts: Specialized layouts for field workflow data with flexible region configurations
Workflow Blocks: Display field workflows in Layout Builder sections with multiple display modes
Interactive Components: Rich interaction with field workflow data through custom block plugins
Custom Styling: Theme-specific styling with CSS variables for complete design consistency
Context-aware Components: Blocks that adapt based on entity context in Layout Builder
Section Templates: Pre-configured section templates for common field workflow displays
Drag-and-Drop Interface: Intuitive interface for arranging field workflow components
Visual Indicators: Status indicators for workflow states and field validations
Configuration UI: Rich configuration options with live preview

// Example: Create a field workflow section with custom styling
$section = new Section('field_eca_workflows_section', [
  'section_title' => 'Field Validation Workflows',
  'background_color' => 'light-blue',
  'display_style' => 'cards',
  'column_layout' => '2-1', // Two-thirds / one-third split
  'content_width' => 'wide',
]);

Field Mapping Visual UI

Interactive Field Mapper: Drag-and-drop interface for mapping fields between systems
Live Validation: Real-time validation of field mapping configurations
Intelligent Suggestions: AI-powered suggestions for optimal field mappings
Visualization Tools: Visual representation of complex field relationships
Mapping Templates: Reusable mapping templates for common field structures
Conflict Detection: Automatic detection and resolution of mapping conflicts
Bulk Operations: Apply mapping patterns to multiple fields simultaneously
History Tracking: Track changes to field mappings over time

Accessibility Enhancements

WCAG 2.1 AA Compliance: All UI components meet or exceed accessibility standards
Screen Reader Support: Comprehensive ARIA attributes and proper semantic markup
Keyboard Navigation: Complete keyboard accessibility throughout all interactive components
Focus Management: Clear visual focus indicators and logical tab order
Color Contrast: All text meets minimum contrast requirements (4.5:1 for normal text)
Reduced Motion Support: Alternative animations for users with motion sensitivity preferences
Text Scaling: Proper support for browser text scaling up to 200%
Voice Control Support: Enhanced support for voice control technologies

Learn more about these features in the Layout Builder Integration Documentation.

Available Events

Custom field value changed: Triggers when any value in a custom field changes.
Custom field column value changed: Triggers when a specific column in a custom field changes.
Custom field condition met: Triggers when a custom field meets specified conditions.

Available Conditions

Custom field column value condition: Checks if a column in a custom field meets certain criteria.
Compare custom field values: Compares values across custom fields or columns.
Field token comparison: Advanced condition that uses field path notation to compare field values with various operators (equals, contains, regex, etc.).
Field history condition: Evaluates field value changes over time with historical comparison.

Available Actions

Set custom field column value: Sets the value of a specific column in a custom field.
Copy custom field data: Copies data between custom fields or columns.
Field history token access: Creates tokens with historical field values for comparison or use in other actions.

Token Support

Custom field data is available through tokens in the format:

[custom-field:field_name:column_name]
[custom-field:field_name:delta:property] (for multi-value fields)
[custom-field:field_name:entity:property] (for entity reference fields)

Advanced Token Usage

The Field ECA Bridge provides a powerful field path notation for accessing field data in a more intuitive way. This can be used in the Field Token Condition plugin and other field-related plugins.

Field path notation uses dot notation to traverse field structures:

field_name[.delta][.property][.subproperty]

Examples:

field_text - The main property of the first item in field_text
field_text.value - The 'value' property of the first item
field_text.0.value - Same as above, explicitly specifying delta
field_tags.target_id - The target_id of the first entity reference
field_tags.entity.title.value - The title value of the referenced entity
field_image.0.alt - The alt text of the first image
field_paragraphs.0.entity.field_text.value - Navigate through paragraphs

Field Token Condition

The module provides a new condition plugin that uses field path notation to compare field values:

Field token comparison: Compares field values using token path notation and supports various comparison operators.

Field History Token Action

Access historical field values with the Field History Token Action:

Field history token access: Creates tokens with historical field values for comparison.

Example: Model Selection Workflow

model_selection_workflow:
  id: "auto_model_selection"
  events:
    - entity:presave:node:ai_request
  conditions:
    - field_eca_bridge_column_value:
        field_name: "field_content_type"
        column_name: "value"
        operator: "=="
        value: "document_analysis"
    - field_eca_bridge_column_value:
        field_name: "field_has_images"
        column_name: "value"
        operator: "=="
        value: true
  actions:
    - service: "llm.model_selector"
      method: "selectOptimalModel"
      arguments:
        request_type: "[node:field_content_type:value]"
        has_images: "[node:field_has_images:value]"
        token_estimate: "[node:field_token_estimate:value]"
      result_token: "selected_model"
    - field_eca_bridge_set_column_value:
        entity: "[node]"
        field_name: "field_selected_model"
        column_name: "target_id"
        value: "[selected_model]"

Example: Custom Field Storage Schema

llm_model_capabilities:
  label: "LLM Model Capabilities"
  storage_type: "custom_field"
  columns:
    - name: "context_window"
      type: "integer"
      label: "Context Window Size"
    - name: "token_limit"
      type: "integer"
      label: "Max Token Limit"
    - name: "supports_tools"
      type: "boolean"
      label: "Supports Tool Use"
    - name: "vision_capable"
      type: "boolean"
      label: "Supports Vision Input"
    - name: "supported_languages"
      type: "array"
      label: "Supported Languages"

Integration with LLM Platform

The Field ECA Bridge integrates with the LLM Platform in several ways:

Model Metadata Storage: Use custom fields to store model metadata with multiple columns (context window size, token limits, capabilities).
AI-Powered Workflow Automation: Trigger ECA workflows based on changes to AI metadata.
Agent Profile Configuration: Automate agent configuration based on custom field values.
Cost Tracking and Analytics: Create workflows for cost monitoring and alerts based on usage thresholds.
Dynamic Content Generation: Trigger AI-powered content generation based on field changes.

Example: Interactive Workflow Visualization

To add an interactive workflow visualization to your Drupal site:

// Using the WorkflowVisualizationService
$visualization = \Drupal::service('field_eca_bridge.workflow_visualization')
  ->renderWorkflowVisualization('workflow_id', [
    'height' => 500,
    'show_controls' => TRUE,
    'show_legend' => TRUE,
  ]);

// Add to a render array
$build = [
  '#theme' => 'some_template',
  '#content' => [
    'workflow_visualization' => $visualization,
    // Other content...
  ],
];

In a Twig template:

{# Display the workflow visualization #}
{{ content.workflow_visualization }}

Example: Layout Builder Integration

Add a Field ECA Workflows section to your Layout Builder layouts:

// Create a new section with the Field ECA Workflows layout
$section = new Section('field_eca_workflows_section', [
  'section_title' => 'Field Workflows',
  'background_color' => 'light-blue',
  'display_style' => 'cards',
]);

// Add a workflow visualization component to the primary region
$visualization_component = new SectionComponent(
  $uuid_service->generate(),
  'primary',
  [
    'id' => 'field_eca_bridge_workflow_visualization',
    'workflow_id' => 'content_validation',
  ]
);
$section->appendComponent($visualization_component);

// Add the section to a layout
$display->appendSection($section);

Development

This module follows Test-Driven Development (TDD) practices. All features are developed with tests first, then implementation.

Running Tests

./vendor/bin/phpunit -c web/core/phpunit.xml.dist web/modules/custom/field_eca_bridge

Drush Commands

The Field ECA Bridge module provides several Drush commands to help administrators manage field-ECA integrations from the command line:

Available Commands

Command	Alias	Description
`field-eca:list-mappings`	`fecam-list`	Lists all field-ECA mappings configured in the system
`field-eca:show-mapping`	`fecam-show`	Shows detailed information about a specific mapping
`field-eca:enable-mapping`	`fecam-enable`	Enables a field-ECA mapping
`field-eca:disable-mapping`	`fecam-disable`	Disables a field-ECA mapping
`field-eca:validate`	`fecam-validate`	Validates all field-ECA mappings
`field-eca:export`	`fecam-export`	Exports field-ECA mappings to a file
`field-eca:import`	`fecam-import`	Imports field-ECA mappings from a file
`field-eca:clear-cache`	`fecam-cc`	Clears field-ECA bridge caches
`field-eca:list-events`	`fecam-events`	Lists available field-ECA events
`field-eca:visualize-workflow`	`fecam-vis`	Generates visualization data for a workflow

Usage Examples

List all field-ECA mappings

drush field-eca:list-mappings
drush fecam-list --format=json

Show details of a specific mapping

drush field-eca:show-mapping my_mapping_id
drush fecam-show my_mapping_id --format=yaml

Enable or disable a mapping

drush field-eca:enable-mapping my_mapping_id
drush field-eca:disable-mapping my_mapping_id

Validate mappings

drush field-eca:validate
drush fecam-validate --fix

Export mappings to a file

drush field-eca:export /path/to/export.yml
drush fecam-export /path/to/export.json --format=json

Import mappings from a file

drush field-eca:import /path/to/export.yml
drush fecam-import /path/to/export.json --overwrite

Clear field-ECA caches

drush field-eca:clear-cache
drush fecam-cc

List available field-ECA events

drush field-eca:list-events
drush fecam-events

Generate workflow visualization data

drush field-eca:visualize-workflow my_workflow_id
drush fecam-vis my_workflow_id --format=json

Example: Field Path Token Condition

Here's an example of using the field path token condition in an ECA workflow:

field_path_condition_workflow:
  id: "content_complexity_workflow"
  events:
    - entity:presave:node:article
  conditions:
    - field_token_condition:
        field_path: "field_text.value"
        comparison_operator: "contains"
        value: "AI-generated"
    - field_token_condition:
        field_path: "field_tags.entity.name"
        comparison_operator: "="
        value: "Machine Learning"
    - field_token_condition:
        field_path: "field_complexity.value"
        comparison_operator: ">"
        value: "3"
  actions:
    - field_history_token_action:
        field_path: "field_text.value"
        history_point: "previous_version"
        token_name: "previous_text"
    - service: "llm.content_analyzer"
      method: "analyzeChanges"
      arguments:
        current_text: "[node:field_text:value]"
        previous_text: "[previous_text]"
      result_token: "content_analysis"

This workflow:

Triggers when an article node is saved
Checks if the text field contains "AI-generated"
Verifies it has a tag named "Machine Learning"
Checks if the complexity rating is greater than 3
Retrieves the previous version of the text field content
Passes both current and previous content to an LLM analyzer service

Documentation

Layout Builder Integration - Comprehensive guide to the Layout Builder integration
Event-Driven Architecture - Overview of the event-driven architecture
Field History Events - Documentation for field history events
Integration Patterns - Common integration patterns
ECA Conditions - Reference for ECA conditions provided by the module

Accessibility

Field ECA Bridge UI components are designed with accessibility in mind:

All interactive elements are keyboard navigable
ARIA attributes are used for screen readers
Color contrast ratios meet WCAG 2.1 AA standards
High contrast mode support for Windows users
Focus states are clearly visible
Interactive components have accessible names and descriptions

Troubleshooting

Make sure both Custom Field and ECA modules are properly installed and enabled.
Check the Drupal logs for any error messages related to the module.
Verify that your custom fields are properly set up and registered with the system.
Run drush field-eca:validate to check for configuration issues.
If you encounter issues with events not triggering, try clearing caches with drush field-eca:clear-cache.

Contributing

Contributions are welcome! Please follow the Drupal coding standards and submit a pull request.

License

This project is licensed under the GPL v2.0 or later.

Documentation Index

For integration patterns and cross-module architecture, see docs/INTEGRATION_PATTERNS.md.
For service naming conventions, see docs/README.md (add section if needed).
For code quality and PHPStan usage, see docs/TESTING_DEBUGGING.md.

Note: All legacy integration and architecture documentation has been merged into the above locations. See module-specific docs for details.# Testing CI pipeline

bluefly / field_eca_bridge

Maintainers

Details