Dynamic UI Button Configuration API

Overview

This API allows insurers to configure dynamic UI buttons for their companies with role-based permissions and file upload validation. Each insurer can define custom buttons (upload new members, renewal, account number, etc.) that are shown to specific user roles (HR, Broker, Principal) with proper validation against configured file upload settings.

Key Features

✅ Dynamic Button Configuration - Insurers define their own UI buttons
✅ Role-Based Permissions - Control which buttons each role can see/use
✅ File Upload Integration - Connect buttons to file upload configurations
✅ Header Validation - Validate uploaded files against configured headers
✅ Button Categories - Group buttons by functionality
✅ Custom Styling - Icons, colors, sizes, and positioning
✅ Template System - Pre-built button templates for common use cases
✅ Statistics & Analytics - Track button usage and performance

API Endpoints

UI Button Configuration Management

Create UI Button Configuration


POST /api/v1/private/dynamic/ui-buttons/insurer/{insurerId}/ui-buttons
Content-Type: application/json
 
{
  "buttonKey": "upload_new_members",
  "buttonLabel": "Upload New Members",
  "description": "Upload new member data from Excel file",
  "buttonType": "upload",
  "uploadType": "new_members",
  "icon": "user-plus",
  "color": "primary",
  "size": "medium",
  "buttonConfig": {
    "apiEndpoint": "/api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/upload-file",
    "method": "POST",
    "requiresFile": true,
    "fileTypes": [".xlsx", ".xls"],
    "maxFileSize": 10485760,
    "confirmationMessage": "Are you sure you want to upload new members?",
    "successMessage": "New members uploaded successfully",
    "errorMessage": "Failed to upload new members",
    "showProgress": true,
    "allowMultipleFiles": false,
    "customValidation": {
      "rules": [
        {
          "field": "EmpNo",
          "rule": "required",
          "message": "Employee number is required"
        }
      ]
    }
  },
  "uiConfig": {
    "position": 1,
    "category": "member_management",
    "isVisible": true,
    "isEnabled": true,
    "tooltip": "Upload new member data from Excel file",
    "badge": {
      "text": "New",
      "color": "success",
      "condition": "hasNewMembers"
    },
    "modal": {
      "title": "Upload New Members",
      "size": "large",
      "showFooter": true
    }
  },
  "permissions": [
    {
      "role": "HR",
      "permissionType": "upload",
      "isAllowed": true,
      "description": "HR can upload new members"
    },
    {
      "role": "PRINCIPAL",
      "permissionType": "upload",
      "isAllowed": true,
      "description": "Principal can upload new members"
    },
    {
      "role": "BROKER",
      "permissionType": "view",
      "isAllowed": true,
      "description": "Broker can view upload button"
    }
  ]
}

Get Insurer UI Button Configurations


GET /api/v1/private/dynamic/ui-buttons/insurer/{insurerId}/ui-buttons?userRole=HR

Response:


{
  "success": true,
  "data": [
    {
      "buttonUuid": "button-uuid-1",
      "buttonKey": "upload_new_members",
      "buttonLabel": "Upload New Members",
      "description": "Upload new member data from Excel file",
      "buttonType": "upload",
      "uploadType": "new_members",
      "icon": "user-plus",
      "color": "primary",
      "size": "medium",
      "buttonConfig": {
        "apiEndpoint": "/api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/upload-file",
        "method": "POST",
        "requiresFile": true,
        "fileTypes": [".xlsx", ".xls"],
        "maxFileSize": 10485760,
        "confirmationMessage": "Are you sure you want to upload new members?",
        "successMessage": "New members uploaded successfully",
        "errorMessage": "Failed to upload new members",
        "showProgress": true,
        "allowMultipleFiles": false
      },
      "uiConfig": {
        "position": 1,
        "category": "member_management",
        "isVisible": true,
        "isEnabled": true,
        "tooltip": "Upload new member data from Excel file",
        "badge": {
          "text": "New",
          "color": "success",
          "condition": "hasNewMembers"
        },
        "modal": {
          "title": "Upload New Members",
          "size": "large",
          "showFooter": true
        }
      },
      "permissions": [
        {
          "permissionUuid": "permission-uuid-1",
          "role": "HR",
          "permissionType": "upload",
          "isAllowed": true,
          "conditions": null,
          "description": "HR can upload new members",
          "isActive": true
        }
      ],
      "isActive": true,
      "isDefault": false,
      "sortOrder": 0,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Company UI Buttons (Filtered by User Role)


GET /api/v1/private/dynamic/ui-buttons/company/{companyUuid}/ui-buttons?userRole=HR

Response:


{
  "success": true,
  "data": {
    "insurerId": "maxicare",
    "insurerName": "Maxicare",
    "userRole": "HR",
    "buttonCategories": [
      {
        "category": "member_management",
        "displayName": "Member Management",
        "buttons": [
          {
            "buttonUuid": "button-uuid-1",
            "buttonKey": "upload_new_members",
            "buttonLabel": "Upload New Members",
            "description": "Upload new member data from Excel file",
            "buttonType": "upload",
            "uploadType": "new_members",
            "icon": "user-plus",
            "color": "primary",
            "size": "medium",
            "buttonConfig": {
              "apiEndpoint": "/api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/upload-file",
              "method": "POST",
              "requiresFile": true,
              "fileTypes": [".xlsx", ".xls"],
              "maxFileSize": 10485760,
              "confirmationMessage": "Are you sure you want to upload new members?",
              "successMessage": "New members uploaded successfully",
              "errorMessage": "Failed to upload new members",
              "showProgress": true,
              "allowMultipleFiles": false
            },
            "uiConfig": {
              "position": 1,
              "category": "member_management",
              "isVisible": true,
              "isEnabled": true,
              "tooltip": "Upload new member data from Excel file",
              "badge": {
                "text": "New",
                "color": "success",
                "condition": "hasNewMembers"
              },
              "modal": {
                "title": "Upload New Members",
                "size": "large",
                "showFooter": true
              }
            },
            "permissions": [
              {
                "permissionUuid": "permission-uuid-1",
                "role": "HR",
                "permissionType": "upload",
                "isAllowed": true,
                "conditions": null,
                "description": "HR can upload new members",
                "isActive": true
              }
            ]
          }
        ],
        "buttonCount": 1
      }
    ],
    "totalButtons": 1
  }
}

File Upload Validation

Validate File Upload Against Button Configuration


POST /api/v1/private/dynamic/ui-buttons/ui-button/{buttonUuid}/validate-upload
Content-Type: application/json
 
{
  "fileData": [
    {
      "EmpNo": "EMP001",
      "LastName": "Doe",
      "FirstName": "John",
      "Email": "john.doe@company.com",
      "BirthDate": "1990-01-01"
    }
  ],
  "headers": ["EmpNo", "LastName", "FirstName", "Email", "BirthDate"]
}

Response:


{
  "success": true,
  "data": {
    "isValid": true,
    "errors": [],
    "warnings": [],
    "validatedData": [
      {
        "EmpNo": "EMP001",
        "LastName": "Doe",
        "FirstName": "John",
        "Email": "john.doe@company.com",
        "BirthDate": "1990-01-01"
      }
    ],
    "buttonInfo": {
      "buttonUuid": "button-uuid-1",
      "buttonKey": "upload_new_members",
      "buttonLabel": "Upload New Members",
      "uploadType": "new_members",
      "expectedHeaders": ["EmpNo", "LastName", "FirstName", "Email", "BirthDate"]
    }
  }
}

Permission Management

Add Permission to Button


POST /api/v1/private/dynamic/ui-buttons/ui-button/{buttonUuid}/permissions
Content-Type: application/json
 
{
  "role": "BROKER",
  "permissionType": "view",
  "isAllowed": true,
  "conditions": {
    "companyTypes": ["corporate"],
    "userLevels": ["senior"]
  },
  "description": "Senior brokers can view this button for corporate clients"
}

Update Button Permission


PUT /api/v1/private/dynamic/ui-buttons/button-permission/{permissionUuid}
Content-Type: application/json
 
{
  "isAllowed": false,
  "description": "Temporarily disabled for this role"
}

Statistics and Management

Get Button Statistics


GET /api/v1/private/dynamic/ui-buttons/insurer/{insurerId}/button-statistics

Response:


{
  "success": true,
  "data": {
    "totalButtons": 5,
    "buttonTypes": {
      "upload": 3,
      "download": 1,
      "action": 1
    },
    "uploadTypes": {
      "new_members": 1,
      "renewal": 1,
      "cancellation": 1
    },
    "activeButtons": 5,
    "defaultButtons": 2,
    "totalPermissions": 15
  }
}

Clone Button Configuration


POST /api/v1/private/dynamic/ui-buttons/ui-button/{sourceButtonUuid}/clone
Content-Type: application/json
 
{
  "targetInsurerId": "icare",
  "newButtonKey": "upload_new_members_icare",
  "newButtonLabel": "Upload New Members (Icare)"
}

Utility Endpoints

Get Available Button Types


GET /api/v1/private/dynamic/ui-buttons/button-types

Response:


{
  "success": true,
  "data": [
    {
      "type": "upload",
      "displayName": "Upload",
      "description": "File upload buttons",
      "icon": "upload",
      "color": "primary"
    },
    {
      "type": "download",
      "displayName": "Download",
      "description": "File download buttons",
      "icon": "download",
      "color": "success"
    },
    {
      "type": "action",
      "displayName": "Action",
      "description": "General action buttons",
      "icon": "play",
      "color": "info"
    },
    {
      "type": "view",
      "displayName": "View",
      "description": "View/display buttons",
      "icon": "eye",
      "color": "secondary"
    }
  ]
}

Get Available Roles


GET /api/v1/private/dynamic/ui-buttons/roles

Response:


{
  "success": true,
  "data": [
    {
      "role": "HR",
      "displayName": "Human Resources",
      "description": "HR department users"
    },
    {
      "role": "BROKER",
      "displayName": "Broker",
      "description": "Insurance broker users"
    },
    {
      "role": "PRINCIPAL",
      "displayName": "Principal",
      "description": "Principal/company admin users"
    },
    {
      "role": "ADMIN",
      "displayName": "Administrator",
      "description": "System administrators"
    },
    {
      "role": "ALL",
      "displayName": "All Users",
      "description": "All user types"
    }
  ]
}

Get Button Configuration Template


GET /api/v1/private/dynamic/ui-buttons/button-template/upload_new_members

Response:


{
  "success": true,
  "data": {
    "buttonKey": "upload_new_members",
    "buttonLabel": "Upload New Members",
    "description": "Upload new member data",
    "buttonType": "upload",
    "uploadType": "new_members",
    "icon": "user-plus",
    "color": "primary",
    "size": "medium",
    "buttonConfig": {
      "apiEndpoint": "/api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/upload-file",
      "method": "POST",
      "requiresFile": true,
      "fileTypes": [".xlsx", ".xls"],
      "maxFileSize": 10485760,
      "confirmationMessage": "Are you sure you want to upload new members?",
      "successMessage": "New members uploaded successfully",
      "errorMessage": "Failed to upload new members",
      "showProgress": true,
      "allowMultipleFiles": false
    },
    "uiConfig": {
      "position": 1,
      "category": "member_management",
      "isVisible": true,
      "isEnabled": true,
      "tooltip": "Upload new member data from Excel file",
      "modal": {
        "title": "Upload New Members",
        "size": "large",
        "showFooter": true
      }
    }
  }
}

Button Configuration Structure

Button Types

upload - File upload buttons (connects to file upload configurations)
download - File download buttons
action - General action buttons
view - View/display buttons

Button Configuration


{
  "buttonConfig": {
    "apiEndpoint": "string",           // API endpoint to call
    "method": "string",                // HTTP method (GET, POST, PUT, DELETE)
    "requiresFile": "boolean",         // Whether file upload is required
    "fileTypes": ["string"],           // Allowed file types
    "maxFileSize": "number",           // Maximum file size in bytes
    "confirmationMessage": "string",   // Confirmation dialog message
    "successMessage": "string",        // Success notification message
    "errorMessage": "string",          // Error notification message
    "redirectAfterSuccess": "string",  // URL to redirect after success
    "showProgress": "boolean",         // Show upload progress
    "allowMultipleFiles": "boolean",   // Allow multiple file selection
    "customValidation": {              // Custom validation rules
      "rules": [
        {
          "field": "string",
          "rule": "string",
          "message": "string",
          "value": "any"
        }
      ]
    }
  }
}

UI Configuration


{
  "uiConfig": {
    "position": "number",              // Order in UI (1, 2, 3...)
    "category": "string",              // Group buttons by category
    "isVisible": "boolean",            // Show/hide button
    "isEnabled": "boolean",            // Enable/disable button
    "tooltip": "string",               // Tooltip text
    "badge": {                         // Optional badge
      "text": "string",
      "color": "string",
      "condition": "string"
    },
    "modal": {                         // Modal configuration
      "title": "string",
      "size": "string",                // small, medium, large
      "showFooter": "boolean"
    }
  }
}

Permission Configuration


{
  "permissions": [
    {
      "role": "string",                // HR, BROKER, PRINCIPAL, ADMIN, ALL
      "permissionType": "string",      // view, create, update, delete, upload, download
      "isAllowed": "boolean",          // Allow/deny permission
      "conditions": {                  // Optional conditions
        "companyTypes": ["string"],
        "userLevels": ["string"],
        "customRules": [
          {
            "field": "string",
            "operator": "string",
            "value": "any"
          }
        ]
      },
      "description": "string"
    }
  ]
}

Workflow Example

1. Insurer Creates Button Configuration


# Maxicare creates upload new members button
POST /api/v1/private/dynamic/ui-buttons/insurer/maxicare/ui-buttons
{
  "buttonKey": "upload_new_members",
  "buttonLabel": "Upload New Members",
  "buttonType": "upload",
  "uploadType": "new_members",
  "permissions": [
    {
      "role": "HR",
      "permissionType": "upload",
      "isAllowed": true
    },
    {
      "role": "PRINCIPAL", 
      "permissionType": "upload",
      "isAllowed": true
    }
  ]
}

2. Company Gets Their UI Buttons


# Company gets buttons for HR role
GET /api/v1/private/dynamic/ui-buttons/company/{companyUuid}/ui-buttons?userRole=HR

3. User Uploads File Through Button


# User uploads file, system validates against button configuration
POST /api/v1/private/dynamic/ui-buttons/ui-button/{buttonUuid}/validate-upload
{
  "fileData": [...],
  "headers": [...]
}

4. System Processes Validated Data


# System processes the validated data according to button configuration
# File is validated against the connected file upload configuration
# Data is stored in the dynamic data table

Benefits

For Insurers

✅ Custom UI - Define their own button layouts and functionality
✅ Role Control - Control which users see which buttons
✅ Validation Integration - Connect buttons to file validation
✅ Branding - Custom colors, icons, and styling
✅ Analytics - Track button usage and performance

For Companies

✅ Role-Based Access - Users only see relevant buttons
✅ Consistent Experience - Standardized button behavior
✅ File Validation - Automatic validation against configured headers
✅ Error Prevention - Clear error messages and validation
✅ Progress Tracking - Upload progress and status updates

For System

✅ Dynamic UI - No hardcoded button structures
✅ Scalable - Easy to add new buttons and insurers
✅ Maintainable - Single system handles all UI configurations
✅ Flexible - Support any button type and validation rule
✅ Secure - Role-based permissions and validation

This system makes the UI completely dynamic and flexible, allowing each insurer to create their own button layouts with proper role-based access control and file validation! 🚀