Tenant Logo White Labeling

Allows each CX tenant to display its own logo instead of the default ExpertFlow branding on the login screen and application header (Unified Admin and Unified Agent). This enables tenant-specific branding without requiring any application rebuilds or redeployments.

This feature provides:

• Per-tenant logos on login and header.

• Configuration via APIs without rebuilds.

• Secure storage and tenant isolation for branding assets.

• Session-based caching for performance.

• Graceful fallback to default branding on errors.

It addresses the core need for basic white labeling in a multi-tenant CX environment and serves as a foundation for future enhancements such as full theme customization.

What This Feature Delivers

The feature provides the following capabilities:

How It Works (Functional Overview)

At a high level, the feature works as follows:

1. Configuration at Tenant Level

   • At tenant registration or via the updateTenant API, a logo file is uploaded.

   • The backend:

     • Validates the file type.

     • Stores the file on the file server.

     • Saves a reference (logoURL / logoPath) in the tenant’s settings.

2. Tenant Login / App Access

   • When users from a tenant access the application:

     • The frontend identifies the tenant (e.g., via subdomain).

     • It retrieves the tenant configuration, including logoPath.

3. Logo Retrieval

   • Frontend calls a tenant logo endpoint:

     • GET https://<FQDN>/cx-tenant/tenant/logo

   • Response:

     {
       "logoPath": "expertflow-logo.png"
     }
     

   • Using this path, the frontend downloads the logo from the file server.

4. Runtime Replacement

   • After download, the frontend:

     • Replaces the default logo in:

       • Application header

       • Login page

     • Stores the resolved logo in sessionStorage as tenantLogo.

5. Session-Level Caching

   • While the browser tab/session is active:

     • The frontend reads the logo from sessionStorage instead of re-calling APIs.

   • On session end or tab close:

     • sessionStorage is cleared.

     • Logo is fetched again on the next login/app bootstrap.

Configuration

Who Configures

• System integrators / DevOps / Admins responsible for:

  • Onboarding new tenants.

  • Maintaining or updating tenant configuration.

• Not configurable by end users inside the CX UI (no in-app logo upload screen in the current scope).

Configuring Logo for New Tenants

When creating a new tenant (CX 5.1+):

1. Use the Tenant Registration API:
   https://expertflow.postman.co/workspace/Expertflow~f8480e26-6001-4a5f-8435-d0adbf5d7f5c/request/21457238-8a344826-2e07-4d6b-9af1-595ef63387a5

2. Include the logo file in the request payload as tenantLogo (as per API specification).

3. On successful request:

   • The backend:

     • Validates type (JPEG, PNG, GIF, SVG, WebP).

     • Saves the file on the file server.

     • Stores a path reference in the tenant schema under tenantSettings.logoURL (or equivalent).

4. Once the tenant is created:

   • Login and header will display the configured logo for that tenant’s users.

Configuring / Updating Logo for Existing Tenants

To add or change a logo for an existing tenant:

1. Call the updateTenant API

2. Provide the new logo file as per the API contract.

3. Backend behavior is the same:

   • Validates file type.

   • Stores the file on the file server.

   • Updates the tenant’s tenantSettings.logoURL with the new path.

4. For users to see the updated logo:

   • They may need to:

     • Open a new browser session, or

     • Reload the app to clear/reload the logo from sessionStorage.

Where the Logo is Stored

• Logos are stored on a file server, and the tenant object maintains a reference:

  {
    ...
    "tenantSettings": {
      ...
      "logoURL": "expertflow-logo.png"
    },
    ...
  }
  

• The tenant logo API:

  • Resolves this reference.

  • Returns a logoPath to the frontend:

    {
      "logoPath": "expertflow-logo.png"
    }
    

• The frontend then downloads the binary via the file server using this path (e.g., using a downloadFileStream-style mechanism).

Frontend Behavior (What the UI Does)

Initialization logic on app bootstrap:

1. Check sessionStorage for tenantLogo:

   sessionStorage.getItem("tenantLogo");
   

2. If found:

   • Use this value to render:

     • Header logo

     • Login logo

3. If not found:

   • Call GET /cx-tenant/tenant/logo to get logoPath.

   • Download the logo from the file server.

   • Store it:

     sessionStorage.setItem("tenantLogo", logoFile);
     

   • Replace the default logos with the tenant logo.

Branding replacement points:

Validation Rules & Constraints

Supported File Types

• Allowed formats:

  • JPEG

  • PNG

  • GIF

  • SVG

  • WebP

Recommended Dimensions

• Recommended aspect ratio: 4:1 (width: height)

  • Example: 200×50 px or similar, for best rendering in the header and login page.

Size & Optimization (Recommended)

• While no explicit size limit is documented here, it is recommended to:

  • Keep logo size small (e.g. under ~100 KB) to:

    • Reduce load time.

    • Improve perceived performance.

Security & Isolation

The feature is designed with multi-tenant and file security in mind.

File Validation

• The backend:

  • Validates MIME type.

  • Validates file extension.

• Only the allowed formats are accepted; others are rejected.

Tenant Isolation

• Logo file references are tied to the tenant via configuration.

• File paths are isolated so tenants cannot access each other’s logos.

Path Safety

• File path handling is protected against:

  • Directory traversal.

  • Direct injection of user-controlled paths into filesystem operations.

Actual storage layout and access control can vary by deployment, but the design assumes tenant-level isolation is enforced.

Error Handling & Fallback Behavior

Runtime Behavior

If a problem occurs while loading or resolving the logo, the system:

• In all non-critical logo-related failures:

  • The application remains usable.

  • Branding reverts to the default ExpertFlow logo.

Logging

• Errors are logged on the backend when:

  • File validation fails.

  • File retrieval fails.

  • Tenant config lookups fail.

• Frontend may log browser-console errors where relevant.

Performance Characteristics

Caching Strategy

• Session-level caching using sessionStorage:

  • Logo is downloaded once per browser session per tenant.

  • Subsequent page loads within the same tab/session re-use cached logo.

Network Impact

• Reduced calls to:

  • Tenant logo API.

  • File server.

• Only the first access in a new session requires logo retrieval.

Rendering Performance

• A properly sized and optimized logo yields:

  • Faster page load.

  • Minor rendering overhead.

• Heavy or oversized images may marginally affect initial load times.

Limitations & Known Behaviors

This section lists important limitations to consider when planning or troubleshooting this feature.

Theming Scope

• Out of scope:

  • Color themes

  • Fonts

  • Layout changes

• Only logo replacement is supported in the current implementation.

Session-Based Behavior

• The logo is not persisted beyond:

  • Browser restart

  • Tab close

• On a new session:

  • Logo is fetched again (API + file download).

• Each browser tab has its own sessionStorage:

  • Opening a new tab to the same tenant may trigger a fresh logo load.

Change Visibility

• When updating a tenant logo:

  • Existing logged-in users may continue to see the old logo until:

    • They hard refresh the page, or

    • Start a new browser session.

• There is no live “push” of new logos to currently active sessions.

No In-App UI for Logo Management

• Logo upload/update must be performed using:

  • Tenant Registration API (for new tenants).

  • updateTenant API (for existing tenants).

• There is currently no dedicated admin UI in CX to upload or change logos directly.