Implementation: inc/Abilities/HandlerAbilities.php Since: v0.6.25 (migrated to Abilities API in v0.11.7)

Overview

The Handler Defaults system provides a hierarchical configuration management layer that ensures consistent settings across the Data Machine ecosystem while maintaining maximum flexibility. It allows administrators to establish site-wide standards that automatically apply to all workflows.

Configuration Hierarchy

Data Machine applies configuration values using a three-tier priority system (highest to lowest):

1. Explicit Configuration

   • Values specifically set for an individual Flow Step.
   • Defined in the Pipeline Builder or Flow configuration.
   • Always overrides site-level or schema defaults.

2. Site-wide Defaults

   • Global standards established for the entire site.
   • Managed via Settings → Handler Defaults in the Admin UI.
   • Stored in the datamachine_handler_defaults WordPress option.
   • Applied when a value is not explicitly provided in the Flow Step.

3. Schema Defaults

   • Built-in fallbacks defined in the code.
   • Located in the handler’s Settings class via the get_fields() method.
   • Applied only when no explicit or site-wide value is found.

Implementation Details

HandlerAbilities::applyDefaults()

Explicit Configuration

// Called via wp_get_ability('datamachine/apply-handler-defaults')->execute([...])
public static function applyDefaults(array $args): array {
    $handler_slug = $args['handler_slug'];
    $config = $args['config'] ?? [];

    $fields = self::getConfigFields($handler_slug);
    $site_defaults = self::getSiteDefaults();
    $handler_site_defaults = $site_defaults[$handler_slug] ?? [];

    $complete_config = [];

    foreach ($fields as $key => $field_config) {
        if (array_key_exists($key, $config)) {
            // Priority 1: Explicit value
            $complete_config[$key] = $config[$key];
        } elseif (array_key_exists($key, $handler_site_defaults)) {
            // Priority 2: Site-wide default
            $complete_config[$key] = $handler_site_defaults[$key];
        } elseif (isset($field_config['default'])) {
            // Priority 3: Schema default
            $complete_config[$key] = $field_config['default'];
        }
    }

    // Preserve unknown keys for forward compatibility
    return array_merge($complete_config, array_diff_key($config, $fields));
}

AI Agent Integration

Site-wide Defaults

• Values specifically set for an individual Flow Step.
• Defined in the Pipeline Builder or Flow configuration.
• Always overrides site-level or schema defaults.

API Endpoints

Schema Defaults

• Global standards established for the entire site.
• Managed via Settings → Handler Defaults in the Admin UI.
• Stored in the datamachine_handler_defaults WordPress option.
• Applied when a value is not explicitly provided in the Flow Step.

Benefits

• Built-in fallbacks defined in the code.
• Located in the handler’s Settings class via the get_fields() method.
• Applied only when no explicit or site-wide value is found.

Related Documentation

• Values specifically set for an individual Flow Step.
• Defined in the Pipeline Builder or Flow configuration.
• Always overrides site-level or schema defaults.

Migration Note

Explicit Configuration

• Global standards established for the entire site.
• Managed via Settings → Handler Defaults in the Admin UI.
• Stored in the datamachine_handler_defaults WordPress option.
• Applied when a value is not explicitly provided in the Flow Step.