Principle:Datahub project Datahub Action Plugin Development

Metadata

Field	Value
Principle ID	P-DHACT-004
Title	Action Plugin Development
Category	Event-Driven Automation
Status	Active
Last Updated	2026-02-10
Repository	Datahub_project_Datahub
Knowledge Sources	GitHub - datahub-project/datahub, DataHub Documentation
Domains	Event_Processing, Automation, Metadata_Management

Overview

The pattern for implementing custom event handlers that react to metadata changes in DataHub. Action plugin development follows an abstract base class pattern where custom actions extend the Action ABC and implement the act(event) method to define behavior. The plugin registry discovers actions via Python entry points, enabling third-party extensions without modifying framework code.

Description

Action plugin development centers on the Action abstract base class, which defines the contract every action must fulfill. The development pattern involves:

The Action Interface

Every action must implement two abstract methods:

create(cls, config_dict, ctx): A class method that serves as a factory. It receives the raw configuration dictionary from the YAML file and a PipelineContext providing access to the DataHub graph API. It must return an initialized Action instance.

act(self, event): The core method invoked for each event that passes through the pipeline's filter and transform stages. It receives an EventEnvelope containing the event type, the event payload, and metadata. The method should perform whatever side effect the action requires (send notification, write metadata, call external API, etc.) and return None.

The Action class also extends Closeable, meaning actions should implement close() to release resources when the pipeline shuts down.

Plugin Discovery

Actions are discovered via the datahub_actions.action.plugins Python entry point namespace. To register a custom action:

Create a Python package with a class extending Action
Add an entry point in the package's setup.py or pyproject.toml
Install the package in the same Python environment as acryl-datahub-actions

The action registry will automatically discover and make the plugin available by name in pipeline YAML configurations.

Configuration Pattern

Actions typically define a Pydantic config model for their specific settings. The create() factory method validates the raw config dict against this model, providing type checking and default values. This separates configuration concerns from action logic.

Usage

Use this principle when building custom automation logic that should execute in response to metadata changes. Common use cases include:

Custom notification integrations (beyond built-in Slack/Teams)
Metadata quality checks and enforcement
External system synchronization
Audit logging to external systems
Custom tag or term propagation logic

Theoretical Basis

Plugin/Strategy pattern: The framework defines the Action interface (the strategy), and concrete implementations provide specific behavior. The factory method (create) handles instantiation with configuration, cleanly separating object creation from usage.

Entry point discovery: Python's entry_points mechanism provides a service-locator pattern at the package level. The framework does not need to know about concrete action implementations at compile time -- they are discovered at runtime from installed packages. This is a form of inversion of control where the framework calls into plugin code rather than plugins depending on framework internals.

Template method with hooks: The pipeline orchestrates the lifecycle (create, act, close), while the action provides the specific behavior at each hook point. This ensures consistent error handling, retries, and statistics tracking across all action implementations.

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment