F1 Integration

The F1 integration connects the Stratpoint Timesheet Application with the F1 Resource Management Platform, providing essential workforce analytics, project assignment reporting, and employee utilization tracking capabilities.

Integration Overview

F1 System Architecture

graph TB
    A[F1 Resource Management Platform] --> B[F1 Integration Layer]
    B --> C[Project Assignment Reporting]
    B --> D[Employee Utilization Analytics]
    B --> E[Resource Planning Data]

    C --> F[Project Assignments]
    C --> G[Resource Allocation]
    C --> H[Assignment History]

    D --> I[Monthly Utilization]
    D --> J[Capacity Planning]
    D --> K[Performance Metrics]

    E --> L[Resource Forecasting]
    E --> M[Skill Mapping]
    E --> N[Availability Tracking]

    O[Timesheet Application] --> B

Key Integration Features

• Project Assignment Reporting: Comprehensive project assignment data and analytics
• Employee Utilization Tracking: Monthly utilization reports and capacity analysis
• Resource Management Data: Access to resource planning and allocation information
• Performance Analytics: Employee performance and utilization insights
• Workforce Planning: Strategic resource planning and forecasting capabilities

API Endpoints

The F1 integration provides three main API endpoints for accessing resource management data:

Base URL

/api/v2/f1/

Authentication

All F1 endpoints use app-to-app authentication with the timesheet.authAppBulongOnly:f1 middleware, ensuring secure communication between the F1 platform and the timesheet system.

Rate Limiting

• Rate Limit: 50 requests per minute
• Throttling: Automatic throttling applied via Laravel middleware

Available Endpoints

1. Project Assignment Report

Endpoint: POST /api/v2/f1/getProjectAssignments

Provides comprehensive project assignment data for resource planning and allocation analysis.

Request Parameters:

{
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "endingFromDate": "2024-01-01",
    "dateCreatedOnwards": "2024-01-01",
    "firstname": "John",
    "lastname": "Doe",
    "selectPositionId": [1, 2, 3],
    "selectProject": [10, 20, 30],
    "selectProjectBusinessUnit": [1, 2],
    "selectProjectBusinessLine": [1, 2],
    "selectProjectStatus": [1, 2],
    "selectUserBusinessUnit": [1, 2]
}

Response: Returns detailed project assignment information including employee assignments, project details, business unit information, and assignment timelines.

2. Employee Utilization Report

Endpoint: POST /api/v2/f1/getUtilizationReportByMonth

Generates monthly utilization reports for workforce capacity planning and performance analysis.

Request Parameters:

{
    "startYearMonth": "2024-01",
    "endYearMonth": "2024-12",
    "selectReportType": ["estimated", "actual", "generic"],
    "selectAllocPercentage": [50, 75, 100],
    "currentMonth": "2024-01-01",
    "cadetInclusion": true,
    "selectStatus": [1, 2, 3]
}

Response: Returns employee utilization metrics, capacity data, allocation percentages, and performance indicators.

3. Resource Filter Data

Endpoint: POST /api/v2/f1/getIdList

Provides bulk filter data for resource management queries and reporting.

Request Parameters:

{
    "filters": ["positions", "projects", "business_units", "users"]
}

Response: Returns available filter options for resource queries including position IDs, project IDs, business unit IDs, and user IDs.

Resource Management Use Cases

Project Assignment Analysis

The F1 integration enables advanced project assignment analysis for optimal resource allocation:

// Project Assignment Analysis
function analyzeProjectAssignments(filters) {
    const requestData = {
        startDate: filters.startDate,
        endDate: filters.endDate,
        selectProject: filters.projectIds,
        selectProjectBusinessUnit: filters.businessUnitIds,
        selectUserBusinessUnit: filters.userBusinessUnitIds
    };

    // Call F1 API for project assignment data
    const response = fetch('/api/v2/f1/getProjectAssignments', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + getF1AuthToken()
        },
        body: JSON.stringify(requestData)
    });

    return response.json().then(data => {
        return {
            assignments: data.assignments,
            summary: {
                total_projects: data.total_projects,
                total_employees: data.total_employees,
                avg_utilization: data.avg_utilization,
                capacity_analysis: data.capacity_analysis
            }
        };
    });
}

// Resource Allocation Optimization
function optimizeResourceAllocation(projectId, requirements) {
    const availableResources = getAvailableResources();
    const projectRequirements = requirements;

    return {
        recommended_assignments: calculateOptimalAssignments(availableResources, projectRequirements),
        capacity_gaps: identifyCapacityGaps(projectRequirements, availableResources),
        skill_matches: findSkillMatches(projectRequirements, availableResources)
    };
}

Employee Utilization Tracking

The F1 integration provides comprehensive employee utilization tracking and capacity planning capabilities:

// Employee Utilization Analysis
function generateUtilizationReport(period, filters) {
    const requestData = {
        startYearMonth: period.startMonth,
        endYearMonth: period.endMonth,
        selectReportType: filters.reportTypes || ['actual', 'estimated'],
        selectAllocPercentage: filters.allocationPercentages || [25, 50, 75, 100],
        currentMonth: new Date().toISOString().slice(0, 10),
        cadetInclusion: filters.includeCadets || false,
        selectStatus: filters.employeeStatus || [1, 2] // Active, on leave, etc.
    };

    // Call F1 API for utilization data
    return fetch('/api/v2/f1/getUtilizationReportByMonth', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + getF1AuthToken()
        },
        body: JSON.stringify(requestData)
    }).then(response => response.json());
}

// Capacity Planning Analysis
function analyzeCapacityTrends(utilizationData) {
    const trends = {
        monthly_averages: calculateMonthlyAverages(utilizationData),
        capacity_gaps: identifyCapacityGaps(utilizationData),
        over_allocation: findOverAllocatedResources(utilizationData),
        under_utilization: findUnderUtilizedResources(utilizationData),
        forecasting: generateCapacityForecast(utilizationData)
    };

    return {
        current_capacity: calculateCurrentCapacity(utilizationData),
        utilization_trends: trends,
        recommendations: generateCapacityRecommendations(trends)
    };
}

// Resource Availability Tracking
function trackResourceAvailability(employeeIds, period) {
    return {
        available_capacity: calculateAvailableCapacity(employeeIds, period),
        scheduled_allocations: getScheduledAllocations(employeeIds, period),
        flexible_capacity: calculateFlexibleCapacity(employeeIds, period),
        skill_availability: mapSkillAvailability(employeeIds, period)
    };
}

Resource Planning and Forecasting

Strategic Resource Planning

The F1 integration supports strategic resource planning and forecasting:

// Strategic Resource Planning
function planResourceAllocation(projects, timeframe) {
    const resourcePlan = {
        timeframe: timeframe,
        projects: projects,
        resource_requirements: [],
        capacity_analysis: {},
        recommendations: []
    };

    // Analyze current resource allocation
    projects.forEach(project => {
        const currentAssignments = getProjectAssignments(project.id);
        const utilizationData = getUtilizationData(project.id, timeframe);

        resourcePlan.resource_requirements.push({
            project_id: project.id,
            required_skills: project.required_skills,
            estimated_effort: project.estimated_effort,
            current_allocation: currentAssignments,
            utilization_target: project.utilization_target
        });
    });

    return optimizeResourcePlan(resourcePlan);
}

// Resource Forecasting
function generateResourceForecast(timeframe, historicalData) {
    const forecast = {
        timeframe: timeframe,
        projected_demand: calculateProjectedDemand(historicalData),
        capacity_trends: analyzeCapacityTrends(historicalData),
        skill_requirements: forecastSkillRequirements(historicalData),
        recommendations: []
    };

    // Analyze historical utilization patterns
    const utilizationTrends = analyzeUtilizationTrends(historicalData);

    forecast.projected_demand = {
        by_month: calculateMonthlyDemand(utilizationTrends),
        by_skill: calculateSkillDemand(utilizationTrends),
        by_business_unit: calculateBusinessUnitDemand(utilizationTrends)
    };

    // Generate resource planning recommendations
    forecast.recommendations = generateResourceRecommendations(forecast);

    return forecast;
}

// Workforce Analytics
function generateWorkforceAnalytics(period) {
    return {
        utilization_summary: getUtilizationSummary(period),
        capacity_analysis: getCapacityAnalysis(period),
        productivity_metrics: getProductivityMetrics(period),
        resource_efficiency: getResourceEfficiency(period),
        skill_distribution: getSkillDistribution(period)
    };
}

Resource Reporting and Analytics

Comprehensive Resource Reports

The F1 integration provides comprehensive resource reporting capabilities:

// Integrated Resource Reporting
function generateResourceReport(reportType, parameters) {
    const reportGenerators = {
        utilization_summary: generateUtilizationSummaryReport,
        project_assignments: generateProjectAssignmentReport,
        capacity_analysis: generateCapacityAnalysisReport,
        resource_efficiency: generateResourceEfficiencyReport
    };

    const generator = reportGenerators[reportType];
    if (!generator) {
        throw new Error(`Unknown report type: ${reportType}`);
    }

    return generator(parameters);
}

// Project Resource Efficiency Report
function generateResourceEfficiencyReport(parameters) {
    const projects = getProjectsInPeriod(parameters.period);
    const efficiencyData = [];

    projects.forEach(project => {
        // Get project assignment data from F1
        const assignmentData = getF1ProjectAssignments(project.id, parameters.period);

        // Get utilization data from F1
        const utilizationData = getF1UtilizationData(project.id, parameters.period);

        const efficiency = {
            project_id: project.id,
            project_name: project.name,
            client_name: project.client.name,
            resource_metrics: {
                assigned_resources: assignmentData.total_assigned,
                average_utilization: utilizationData.avg_utilization,
                capacity_utilization: utilizationData.capacity_usage
            },
            performance_indicators: {
                delivery_efficiency: calculateDeliveryEfficiency(assignmentData),
                resource_optimization: calculateResourceOptimization(utilizationData),
                skill_match_score: calculateSkillMatchScore(assignmentData)
            }
        };

        efficiencyData.push(efficiency);
    });

    return {
        report_type: 'resource_efficiency',
        period: parameters.period,
        projects: efficiencyData,
        summary: calculateEfficiencySummary(efficiencyData),
        generated_at: new Date()
    };
}

Integration Health and Monitoring

System Health Monitoring

// F1 Integration Health Monitoring
function monitorF1Integration() {
    const healthStatus = {
        overall_status: 'healthy',
        last_check: new Date(),
        endpoints: {},
        data_quality: {},
        performance_metrics: {}
    };

    // Monitor each F1 endpoint
    const endpoints = [
        'getProjectAssignments',
        'getUtilizationReportByMonth',
        'getIdList'
    ];

    endpoints.forEach(endpoint => {
        try {
            const response = testF1Endpoint(endpoint);
            healthStatus.endpoints[endpoint] = {
                status: 'healthy',
                response_time: response.response_time,
                last_successful_call: response.timestamp
            };
        } catch (error) {
            healthStatus.endpoints[endpoint] = {
                status: 'unhealthy',
                error: error.message,
                last_error: new Date()
            };
            healthStatus.overall_status = 'degraded';
        }
    });

    // Monitor data quality
    healthStatus.data_quality = {
        completeness: checkDataCompleteness(),
        accuracy: checkDataAccuracy(),
        timeliness: checkDataTimeliness()
    };

    return healthStatus;
}

// Resource Data Validation
function validateResourceData(data, endpoint) {
    const validation = {
        valid: true,
        errors: [],
        warnings: []
    };

    switch (endpoint) {
        case 'getProjectAssignments':
            validation = validateProjectAssignmentData(data);
            break;
        case 'getUtilizationReportByMonth':
            validation = validateUtilizationData(data);
            break;
        case 'getIdList':
            validation = validateFilterData(data);
            break;
    }

    return validation;
}

Best Practices and Guidelines

Integration Usage Guidelines

When working with the F1 resource management integration, follow these best practices:

Data Quality: - Always validate request parameters before calling F1 endpoints - Implement proper error handling for all API calls - Monitor data quality and completeness regularly

Performance Optimization: - Use appropriate date ranges to limit data volume - Implement caching for frequently accessed data - Use filters to reduce payload sizes

Security Considerations: - Ensure proper authentication for all F1 API calls - Log access for audit purposes - Follow rate limiting guidelines

Error Handling

// F1 Error Handling
function handleF1Error(error, endpoint, requestData) {
    const errorLog = {
        timestamp: new Date(),
        endpoint: endpoint,
        error_type: error.type || 'unknown',
        message: error.message,
        request_data: requestData,
        severity: determineSeverity(error)
    };

    logF1Error(errorLog);

    // Determine recovery action based on error type
    switch (error.type) {
        case 'timeout':
            return retryWithBackoff(endpoint, requestData);
        case 'authentication_failed':
            return refreshAuthAndRetry(endpoint, requestData);
        case 'validation_error':
            return handleValidationError(errorLog);
        case 'rate_limit_exceeded':
            return scheduleRetry(endpoint, requestData);
        default:
            return escalateError(errorLog);
    }
}

This F1 integration provides essential resource management capabilities for the Stratpoint Timesheet Application, enabling comprehensive workforce analytics, project assignment tracking, and employee utilization reporting for optimal resource planning and strategic decision-making.