Dynamic File Upload Configuration API

Overview

This API allows companies to configure their own Excel file upload formats and validation rules. Companies can define custom headers, data types, validation rules, and template settings for their file uploads, making the system completely flexible for any company’s data format.

Key Features

✅ Custom Header Configuration - Define your own Excel headers
✅ Data Type Validation - String, number, date, boolean, stringOrNumber
✅ Custom Validation Rules - Min/max length, value ranges, patterns, allowed values
✅ Template Generation - Generate Excel templates based on configuration
✅ Dynamic Validation - Validate files against company-specific rules
✅ Multiple Upload Types - Support for new_members, renewal, cancellation, etc.
✅ Configuration Cloning - Copy configurations from other companies
✅ Statistics & Analytics - Track configuration usage and performance

API Endpoints

File Upload Configuration Management

Create File Upload Configuration


POST /api/v1/private/dynamic/file-upload/company/{companyUuid}/file-upload-configurations
Content-Type: application/json
 
{
  "insurerId": "maxicare",
  "uploadType": "new_members",
  "configName": "Standard New Members Upload",
  "description": "Standard configuration for new member uploads",
  "templateSettings": {
    "sheetIndex": 1,
    "range": 1,
    "headerRow": 2,
    "dataStartRow": 3,
    "maxRows": 1000
  },
  "validationRules": {
    "requiredFields": ["EmpNo", "LastName", "FirstName", "Email"],
    "uniqueFields": ["EmpNo", "Email"],
    "customValidations": [
      {
        "field": "Email",
        "rule": "email_format",
        "message": "Invalid email format"
      }
    ]
  },
  "headers": [
    {
      "headerName": "EmpNo",
      "displayName": "Employee Number",
      "dataType": "string",
      "isRequired": true,
      "isUnique": true,
      "columnIndex": 0,
      "validationRules": {
        "minLength": 3,
        "maxLength": 20,
        "pattern": "^[A-Z0-9]+$"
      },
      "description": "Unique employee identifier"
    },
    {
      "headerName": "LastName",
      "displayName": "Last Name",
      "dataType": "string",
      "isRequired": true,
      "isUnique": false,
      "columnIndex": 1,
      "validationRules": {
        "minLength": 2,
        "maxLength": 50
      },
      "description": "Employee's last name"
    },
    {
      "headerName": "FirstName",
      "displayName": "First Name",
      "dataType": "string",
      "isRequired": true,
      "isUnique": false,
      "columnIndex": 2,
      "validationRules": {
        "minLength": 2,
        "maxLength": 50
      },
      "description": "Employee's first name"
    },
    {
      "headerName": "Email",
      "displayName": "Email Address",
      "dataType": "string",
      "isRequired": true,
      "isUnique": true,
      "columnIndex": 3,
      "validationRules": {
        "pattern": "^[^@]+@[^@]+\\.[^@]+$"
      },
      "description": "Employee's email address"
    },
    {
      "headerName": "BirthDate",
      "displayName": "Birth Date",
      "dataType": "date",
      "isRequired": true,
      "isUnique": false,
      "columnIndex": 4,
      "description": "Employee's birth date"
    },
    {
      "headerName": "Salary",
      "displayName": "Monthly Salary",
      "dataType": "number",
      "isRequired": false,
      "isUnique": false,
      "columnIndex": 5,
      "validationRules": {
        "minValue": 0,
        "maxValue": 1000000
      },
      "description": "Employee's monthly salary"
    }
  ]
}

Get Company File Upload Configurations


GET /api/v1/private/dynamic/file-upload/company/{companyUuid}/file-upload-configurations?uploadType=new_members

Response:


{
  "success": true,
  "data": [
    {
      "configUuid": "config-uuid-1",
      "uploadType": "new_members",
      "configName": "Standard New Members Upload",
      "description": "Standard configuration for new member uploads",
      "templateSettings": {
        "sheetIndex": 1,
        "range": 1,
        "headerRow": 2,
        "dataStartRow": 3,
        "maxRows": 1000
      },
      "validationRules": {
        "requiredFields": ["EmpNo", "LastName", "FirstName", "Email"],
        "uniqueFields": ["EmpNo", "Email"],
        "customValidations": []
      },
      "isActive": true,
      "isDefault": false,
      "sortOrder": 0,
      "headers": [
        {
          "headerUuid": "header-uuid-1",
          "headerName": "EmpNo",
          "displayName": "Employee Number",
          "dataType": "string",
          "isRequired": true,
          "isUnique": true,
          "columnIndex": 0,
          "validationRules": {
            "minLength": 3,
            "maxLength": 20,
            "pattern": "^[A-Z0-9]+$"
          },
          "description": "Unique employee identifier",
          "isActive": true,
          "sortOrder": 0
        }
      ],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Update File Upload Configuration


PUT /api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}
Content-Type: application/json
 
{
  "configName": "Updated Configuration Name",
  "description": "Updated description",
  "isActive": true,
  "isDefault": false,
  "sortOrder": 1
}

Delete File Upload Configuration


DELETE /api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}

Header Management

Add Header to Configuration


POST /api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/headers
Content-Type: application/json
 
{
  "headerName": "Department",
  "displayName": "Department",
  "dataType": "string",
  "isRequired": false,
  "isUnique": false,
  "columnIndex": 6,
  "validationRules": {
    "allowedValues": ["IT", "HR", "Finance", "Operations"]
  },
  "description": "Employee's department"
}

Update Header Configuration


PUT /api/v1/private/dynamic/file-upload/header/{headerUuid}
Content-Type: application/json
 
{
  "displayName": "Updated Display Name",
  "isRequired": true,
  "validationRules": {
    "minLength": 5,
    "maxLength": 100
  }
}

Remove Header from Configuration


DELETE /api/v1/private/dynamic/file-upload/header/{headerUuid}

File Processing

Get Available Upload Types


GET /api/v1/private/dynamic/file-upload/company/{companyUuid}/available-upload-types

Response:


{
  "success": true,
  "data": {
    "insurerId": "maxicare",
    "insurerName": "Maxicare",
    "uploadTypes": [
      {
        "type": "new_members",
        "displayName": "New Members",
        "configurations": [
          {
            "configUuid": "config-uuid-1",
            "configName": "Standard New Members Upload",
            "description": "Standard configuration for new member uploads",
            "isDefault": false,
            "companyCount": 1
          }
        ],
        "totalConfigurations": 1
      },
      {
        "type": "renewal",
        "displayName": "Renewal",
        "configurations": [],
        "totalConfigurations": 0
      }
    ]
  }
}

Generate Excel Template


GET /api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/excel-template

Response:


{
  "success": true,
  "data": {
    "configUuid": "config-uuid-1",
    "configName": "Standard New Members Upload",
    "uploadType": "new_members",
    "templateSettings": {
      "sheetIndex": 1,
      "range": 1,
      "headerRow": 2,
      "dataStartRow": 3,
      "maxRows": 1000
    },
    "headers": [
      {
        "headerName": "EmpNo",
        "displayName": "Employee Number",
        "dataType": "string",
        "isRequired": true,
        "isUnique": true,
        "columnIndex": 0,
        "description": "Unique employee identifier",
        "validationRules": {
          "minLength": 3,
          "maxLength": 20,
          "pattern": "^[A-Z0-9]+$"
        }
      }
    ],
    "sampleData": {
      "EmpNo": "Sample Text",
      "LastName": "Sample Text",
      "FirstName": "Sample Text",
      "Email": "Sample Text",
      "BirthDate": "2024-01-01",
      "Salary": 123
    }
  }
}

Validate File Against Configuration


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

Response:


{
  "success": true,
  "data": {
    "isValid": true,
    "errors": [],
    "warnings": [],
    "validatedData": [
      {
        "EmpNo": "EMP001",
        "LastName": "Doe",
        "FirstName": "John",
        "Email": "john.doe@company.com",
        "BirthDate": "1990-01-01T00:00:00.000Z",
        "Salary": 50000
      }
    ],
    "headerMapping": {
      "EmpNo": "EmpNo",
      "LastName": "LastName",
      "FirstName": "FirstName",
      "Email": "Email",
      "BirthDate": "BirthDate",
      "Salary": "Salary"
    }
  }
}

Upload File with Dynamic Validation


POST /api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/upload-file
Content-Type: application/json
 
{
  "fileData": [
    {
      "EmpNo": "EMP001",
      "LastName": "Doe",
      "FirstName": "John",
      "Email": "john.doe@company.com",
      "BirthDate": "1990-01-01",
      "Salary": 50000
    }
  ],
  "headers": ["EmpNo", "LastName", "FirstName", "Email", "BirthDate", "Salary"]
}

Statistics and Management

Get Configuration Statistics


GET /api/v1/private/dynamic/file-upload/company/{companyUuid}/file-upload-statistics

Response:


{
  "success": true,
  "data": {
    "totalConfigurations": 3,
    "uploadTypes": {
      "new_members": 2,
      "renewal": 1,
      "cancellation": 0
    },
    "totalHeaders": 15,
    "activeConfigurations": 3,
    "defaultConfigurations": 1
  }
}

Clone Configuration


POST /api/v1/private/dynamic/file-upload/company/{companyUuid}/clone-configuration
Content-Type: application/json
 
{
  "sourceConfigUuid": "source-config-uuid",
  "newConfigName": "Cloned Configuration",
  "newDescription": "Configuration cloned from another company"
}

Data Types Supported

Basic Types

string - Text data
number - Numeric data
boolean - True/false values
date - Date values (supports Excel dates and ISO strings)
stringOrNumber - Flexible type that accepts both strings and numbers

Validation Rules

String Validation


{
  "validationRules": {
    "minLength": 3,
    "maxLength": 50,
    "pattern": "^[A-Z0-9]+$",
    "allowedValues": ["Option1", "Option2", "Option3"]
  }
}

Number Validation


{
  "validationRules": {
    "minValue": 0,
    "maxValue": 1000000
  }
}

Date Validation

Automatically handles Excel date serial numbers
Supports ISO date strings (YYYY-MM-DD)
Validates date format and range

Template Settings


{
  "templateSettings": {
    "sheetIndex": 1,        // Which sheet to read (0-based)
    "range": 1,             // Data range start
    "headerRow": 2,         // Row containing headers
    "dataStartRow": 3,      // First row of actual data
    "maxRows": 1000         // Maximum number of data rows
  }
}

Workflow Example

1. Create File Upload Configuration


# Company creates their custom upload configuration
POST /api/v1/private/dynamic/file-upload/company/{companyUuid}/file-upload-configurations
{
  "insurerId": "maxicare",
  "uploadType": "new_members",
  "configName": "Company Custom Upload",
  "headers": [
    {
      "headerName": "EmployeeID",
      "dataType": "string",
      "isRequired": true,
      "columnIndex": 0
    }
  ]
}

2. Generate Excel Template


# Generate template for company to use
GET /api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/excel-template

3. Upload and Validate File


# Company uploads their file with custom format
POST /api/v1/private/dynamic/file-upload/file-upload-configuration/{configUuid}/upload-file
{
  "fileData": [...],
  "headers": [...]
}

4. Process Validated Data


# Use validated data for further processing
# The system now has clean, validated data in the expected format

Benefits

For Companies

✅ Custom Format Support - Use their existing Excel formats
✅ Flexible Validation - Define their own validation rules
✅ Template Generation - Get Excel templates automatically
✅ Error Prevention - Validate data before processing
✅ Self-Service - Configure uploads without developer help

For System

✅ Dynamic Processing - Handle any file format
✅ Data Quality - Ensure data integrity through validation
✅ Scalability - Support unlimited custom formats
✅ Maintainability - Single system handles all upload types
✅ Flexibility - Easy to add new data types and validation rules

For Insurers

✅ Standardization - Provide base configurations
✅ Customization - Allow company-specific modifications
✅ Quality Control - Ensure data meets requirements
✅ Analytics - Track upload patterns and issues

This system makes file uploads completely dynamic and flexible, allowing each company to use their preferred Excel format while maintaining data quality and validation! 🚀