Tenant Portfolios

Overview

Tenant Portfolios provide a higher-level organization structure above Tenant Clusters, allowing for the grouping of multiple clusters into logical collections. This hierarchical approach enables more effective management of large multi-tenant environments. Each portfolio can have a designated "Managing Tenant Cluster" which is responsible for overseeing the entire portfolio.

Implementation

Tenant Portfolios are implemented as a one-to-many relationship with tenant clusters, with an additional reference for the managing cluster:

• A Portfolio can have many Tenant Clusters
• A Tenant Cluster belongs to one Portfolio (or none)
• A Portfolio can have one Managing Tenant Cluster

The system uses a tenant_portfolio_id foreign key in the tenant_clusters table and a managing_tenant_cluster_id foreign key in the tenant_portfolios table to establish these relationships.

Database Schema

The implementation involves two primary database tables:

1. tenant_portfolios table:

   • id: Primary key
   • name: Name of the portfolio
   • slug: URL-friendly version of the name (auto-generated)
   • description: Optional description of the portfolio
   • managing_tenant_cluster_id: Foreign key to the tenant_clusters table (nullable), indicating the managing cluster for this portfolio
   • Standard timestamp fields

2. tenant_clusters table includes:

   • tenant_portfolio_id: Foreign key to the tenant_portfolios table (nullable)

Models

TenantPortfolio Model

The TenantPortfolio model provides a way to create and manage portfolios.

The TenantPortfolio model uses an observer (TenantPortfolioObserver) which ensures that a portfolio with existing tenant clusters cannot be updated to have no managing_tenant_cluster_id. This enforces that a Portfolio with clusters must have a Managing Tenant Cluster.

TenantCluster Model

The TenantCluster model includes a relationship to portfolios:

public function portfolio()
{
    return $this->belongsTo(TenantPortfolio::class, 'tenant_portfolio_id');
}

public function isPortfolioManager(): bool
{
    return $this->portfolio && $this->portfolio->managing_tenant_cluster_id == $this->id;
}

Tenant Model

The Tenant model includes a method to access its portfolio through the cluster:

public function portfolio(): ?TenantPortfolio
{
    return $this->cluster ? $this->cluster->portfolio : null;
}

public function isPortfolioManager(): bool
{
    return $this->isClusterManager() && $this->cluster->isPortfolioManager();
}

User Interface

Tenant Portfolios can be managed in the Landlord admin area, within the "Multitenancy" section. The interface provides:

1. Creating Portfolios: Administrators can create portfolios with a name and description
2. Managing Portfolios: Administrators can edit or delete existing portfolios
3. Assigning Tenant Clusters: Tenant Clusters can be assigned to portfolios through the Portfolio management interface
4. Setting the Managing Tenant Cluster: The Managing Tenant Cluster can be assigned or changed from the Portfolio management interface

Usage

Creating a Tenant Portfolio

1. Navigate to the Tenant Portfolios page in the Multitenancy section
2. Click "New Tenant Portfolio"
3. Provide a name and optional description
4. Save the portfolio

Assigning Tenant Clusters to a Portfolio

1. From the Tenant Portfolios page, click on a portfolio
2. In the Tenant Clusters tab, click "Attach Existing"
3. Select one or more clusters to add to the portfolio
4. Alternatively, edit a tenant cluster directly and select a portfolio from the dropdown

Setting/Changing the Managing Tenant Cluster

1. Navigate to the Tenant Portfolios page
2. Click on the portfolio you wish to manage
3. Select a tenant cluster to serve as the managing cluster for the portfolio
4. Note: A portfolio that has tenant clusters must always have a managing tenant cluster

Accessing Data Across a Portfolio

The ScopedToTenantTrait provides a convenient way to filter data by portfolio:

// Get all records in the current tenant's portfolio
$records = YourModel::ofCurrentTenantPortfolio()->get();

Best Practices

1. Hierarchical Organization: Use portfolios to create logical groupings of related tenant clusters
2. Managing Cluster Selection: Choose a managing tenant cluster that has appropriate oversight responsibilities for the entire portfolio
3. Portfolio Organization: Consider organizing portfolios by:
   • Business divisions or departments
   • Geographic regions or territories
   • Client categories or market segments
4. Regular Maintenance: Periodically review portfolio and cluster assignments to ensure they align with organizational needs