Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/flext_target_ldap/api.py
• src/flext_target_ldap/settings.py
• src/flext_target_ldap/_utilities/client.py
• src/flext_target_ldap/_models/sinks.py
• src/flext_target_ldap/models.py
• pyproject.toml

The flext-target-ldap project is a specialized FLEXT Target designed for loading data into LDAP directory services using the Singer tap-target protocol. It acts as an integration point that consumes JSONL structured data and translates it into LDAP operations such as adding, modifying, or deleting entries.

The system is built upon the flext-core and flext-ldap frameworks, ensuring standardized configuration, logging, and connectivity patterns. It provides specialized "sinks" for common LDAP object types including users, groups, and organizational units, while supporting generic directory entries through a base sink implementation.

Sources: README.md:12-14, src/flext_target_ldap/api.py:30-40, pyproject.toml:23-23

Core Architecture and Data Flow

The project follows a facade-based architecture where the FlextTargetLdap class serves as the primary entry point for the Singer CLI. The data flow starts with standard input (STDIN) processing, followed by message type identification (SCHEMA, RECORD, or STATE), and ends with high-level LDAP operations performed via a dedicated client.

Integration Flow Diagram

The following diagram illustrates how a Singer message moves from standard input through the target facade and into the LDAP directory.

The flow ensures that state messages are echoed back for checkpointing while data records are transformed into directory-specific commands.
Sources: src/flext_target_ldap/api.py:161-210, src/flext_target_ldap/_models/sinks.py:91-110

Configuration and Settings

Configuration is managed through the FlextTargetLdapSettings class. It supports both flat Singer-style configuration and nested canonical shapes. The system uses an environment prefix FLEXT_TARGET_LDAP_ for environment-based overrides.

Connection Settings

These settings define how the target connects to the directory server.

Setting	Type	Default	Description
host	String	localhost	LDAP server hostname.
port	Integer	389	Connection port.
use_ssl	Boolean	False	Whether to use SSL.
bind_dn	String	None	Distinguished Name for authentication.
bind_password	String	None	Password for the Bind DN.
timeout	Integer	30	Connection timeout in seconds.

Operational Settings

These settings control the behavior of data loading and synchronization.

Setting	Type	Default	Description
base_dn	NonEmptyStr	(Required)	Base DN for all operations.
search_scope	String	SUBTREE	Scope for existence checks.
batch_size	Integer	1000	Entries per batch operation.
create_missing_entries	Boolean	True	Create entries if they don't exist.
update_existing_entries	Boolean	True	Update entries if they already exist.
delete_removed_entries	Boolean	False	Remove entries flagged for deletion.

Sources: src/flext_target_ldap/settings.py:27-147, src/flext_target_ldap/api.py:165-170

Sink Implementation Strategy

The target utilizes specialized sinks to handle different LDAP object categories. Sinks are responsible for mapping Singer records to specific LDAP Distinguished Names (DNs) and attributes.

Class Hierarchy

The hierarchy allows specific sinks to override logic for object-specific requirements (like inetOrgPerson for users).
Sources: src/flext_target_ldap/_models/sinks.py:22-540, src/flext_target_ldap/api.py:80-100

Stream to Sink Mapping

The get_sink_class method in the main facade maps Singer stream names to these implementations:

• users: Handled by FlextTargetLdapUsersSink. It specifically looks for fields like uid or username to build the RDN.
• groups: Handled by FlextTargetLdapGroupsSink. It maps members and uses cn for the RDN.
• organizational_units: Handled by FlextTargetLdapOrganizationalUnitsSink.
• Other/Generic: Defaults to FlextTargetLdapBaseSink.

Sources: src/flext_target_ldap/api.py:82-96, src/flext_target_ldap/_models/sinks.py:348-355

LDAP Client Operations

The FlextTargetLdapClient provides a clean interface for interacting with the directory using flext-ldap. It abstracts the conversion of Python dictionaries into LDIF entries and LDAP modify changes.

Key Client Methods

• add_entry(dn, attributes, object_classes): Constructs an m.Ldif.Entry and executes a connect-add-disconnect sequence.
• modify_entry(dn, changes): Converts a dictionary of changes into LDAP REPLACE operations.
• delete_entry(dn): Removes an entry by its Distinguished Name.
• search_entry(base_dn, search_filter): Queries the directory and returns a list of m.Ldif.Entry models.

Sources: src/flext_target_ldap/_utilities/client.py:157-270

Logic for Record Persistence

When a record is processed, the system follows an "Upsert" logic based on the configuration:

Domain Models and Validation

Domain models are defined in FlextTargetLdapModels and provide business rule validation for LDAP-specific entities.

Entry Model

The Entry model validates that:

1. The Distinguished Name (DN) contains proper attribute=value pairs.
2. At least one object class is provided (automatically adding top if missing).
3. Mandatory attributes for specific classes are present (e.g., sn and cn for person objects).

Sources: src/flext_target_ldap/models.py:117-210

Attribute Mapping

Users can define transformation rules within the model namespace. Supported transformations include:

• lowercase
• uppercase
• trim
• normalize

Sources: src/flext_target_ldap/models.py:87-100

Summary

To get started with flext-target-ldap, developers should focus on the FlextTargetLdap facade for CLI interactions and the FlextTargetLdapSettings for environment configuration. The system's extensibility lies in its Sink architecture, allowing for custom directory object handling while relying on a robust, validated LDAP client for the underlying protocol operations.

Sources: src/flext_target_ldap/api.py:30-40, src/flext_target_ldap/settings.py:13-25