Skip to content

Organizational Units

The Organizational Units module manages the hierarchical structure of the organization within the UBU Digital Finance Solution.

Overview

This module provides functionality for defining and managing the organizational structure, including:

  • Creating and managing organizational units
  • Establishing hierarchical relationships between units
  • Assigning users to organizational units
  • Using organizational units for access control

Features

Organizational Unit Management

The system supports creating and managing organizational units:

  • Each unit has a name, description, and active status
  • Units can be created, updated, and deleted by administrators
  • Units can be organized in a hierarchical structure
  • Units can be activated or deactivated

Hierarchical Structure

The organizational structure is hierarchical:

  • Each unit can have a parent unit
  • Units without a parent are considered top-level units
  • The hierarchy can have multiple levels
  • The hierarchy is used for reporting and access control

User Assignment

Users can be assigned to organizational units:

  • Each user can be assigned to one or more units
  • Assignments can be activated or deactivated
  • User-unit assignments are used for access control and reporting

Organizational Unit-Based Access Control

The system can restrict access based on organizational unit membership:

  • Access to certain resources can be limited to users in specific units
  • This provides an additional layer of access control beyond role-based permissions
  • Useful for implementing branch-level or department-level restrictions

API Endpoints

Endpoint Method Description
/organization/ POST Create a new organizational unit
/organization/ GET Get all organizational units
/organization/{unit_id} GET Get a specific organizational unit
/organization/{unit_id} PUT Update an organizational unit
/organization/{unit_id} DELETE Delete an organizational unit
/organization/{unit_id}/users GET Get users in an organizational unit
/organization/user/{user_id} GET Get organizational units for a user

Data Model

The Organizational Units module uses the following database tables:

  • OrganizationalUnitsModel: Stores organizational unit definitions
  • UserOrganizationalUnitModel: Maps users to organizational units (many-to-many)

For detailed schema information, see the Database Schema documentation.

Implementation Details

Hierarchical Structure Implementation

The hierarchical structure is implemented using a self-referencing relationship:

class OrganizationalUnitsModel(Base):
    __tablename__ = "organizational_units"

    unit_id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    unit_name = Column(String, nullable=False)
    unit_description = Column(String, nullable=True)
    parent_unit_id = Column(UUID(as_uuid=True), ForeignKey("organizational_units.unit_id"), nullable=True)
    is_active = Column(Boolean, default=True)

    # Self-referential relationship
    parent = relationship("OrganizationalUnitsModel", remote_side=[unit_id], backref="children")

This allows for querying parent-child relationships:

  • Get a unit's parent: unit.parent
  • Get a unit's children: unit.children

User Assignment Implementation

User assignments are implemented using a many-to-many relationship:

class UserOrganizationalUnitModel(Base):
    __tablename__ = "user_organizational_units"

    user_id = Column(UUID(as_uuid=True), ForeignKey("users.user_id"), primary_key=True)
    unit_id = Column(UUID(as_uuid=True), ForeignKey("organizational_units.unit_id"), primary_key=True)
    is_active = Column(Boolean, default=True)

    # Relationships
    user = relationship("UsersModel", back_populates="organizational_units")
    unit = relationship("OrganizationalUnitsModel", back_populates="users")

Organizational Unit Hierarchy Traversal

The system provides methods for traversing the organizational unit hierarchy:

  • Get all ancestors of a unit
  • Get all descendants of a unit
  • Get the full path from a unit to the root
  • Get all units in a subtree

Default Organizational Units

The system can be configured with default organizational units:

  • Headquarters
  • Regional Offices
  • Branch Offices
  • Departments (Finance, IT, Operations, etc.)

Best Practices

When implementing organizational units:

  1. Clear Hierarchy: Establish a clear hierarchical structure that reflects the organization
  2. Appropriate Granularity: Define units at an appropriate level of granularity
  3. Consistent Naming: Use consistent naming conventions for organizational units
  4. Regular Maintenance: Periodically review and update the organizational structure
  5. Access Control Integration: Integrate organizational units with access control mechanisms

Future Enhancements

Planned enhancements for the Organizational Units module include:

  1. Geographical Mapping: Associate organizational units with geographical locations
  2. Resource Allocation: Assign resources (equipment, facilities) to organizational units
  3. Advanced Reporting: Generate reports based on organizational structure
  4. Organizational Charts: Visualize the organizational structure as charts
  5. Dynamic Restructuring: Support for reorganizations and restructuring