TimeDef Integration

The TimeDef integration connects the Stratpoint Timesheet Application with the TimeDef system, providing access to timelog deficiency data, reporting capabilities, and filter information for time tracking compliance and analysis.

Integration Overview

TimeDef System Architecture

graph TB
    A[TimeDef Application] --> B[TimeDef Integration Layer]
    B --> C[Deficiency Data API]
    B --> D[Reporting API]
    B --> E[Filter Data API]

    C --> F[Basic Deficiency Data]
    C --> G[User Timelog Status]
    C --> H[Compliance Tracking]

    D --> I[Deficiency Reports]
    D --> J[Compliance Analysis]
    D --> K[Time Tracking Metrics]

    E --> L[Filter Options]
    E --> M[Report Parameters]

    N[Timesheet Application] --> B

Key Features

• Timelog Deficiency Tracking: Monitor and report employee timelog deficiencies
• Compliance Reporting: Generate comprehensive deficiency reports for management
• Filter Data Access: Retrieve filter options for timelog deficiency queries
• Automated Analysis: Basic data processing for deficiency identification
• Authentication Security: App-to-app authentication with rate limiting

API Endpoints

The TimeDef integration provides three main endpoints for accessing deficiency data:

Base URL

/api/v2/timedef/

Authentication

All TimeDef endpoints use app-to-app authentication with the timesheet.authAppBulongOnly:timedef middleware.

Rate Limiting

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

Available Endpoints

1. Filter Data Retrieval

Endpoint: POST /api/v2/timedef/getIdList

Provides bulk filter data for timelog deficiency queries and reporting.

Request Parameters:

{
    "filters": ["departments", "user_types", "deficiency_types", "time_periods"]
}

Response: Returns available filter options for deficiency queries including department IDs, user types, deficiency categories, and time period options.

2. Basic Deficiency Data

Endpoint: POST /api/v2/timedef/timelogDeficiencyBasicData

Retrieves basic timelog deficiency information for specified parameters.

Request Parameters:

{
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "user_ids": [1, 2, 3],
    "department_ids": [10, 20],
    "include_resolved": false
}

Response: Returns basic deficiency data including user information, deficiency types, and timestamps.

Example Response:

{
    "deficiencies": [
        {
            "user_id": 1,
            "user_name": "John Doe",
            "department": "Engineering",
            "deficiency_date": "2024-01-15",
            "deficiency_type": "Missing Timelog",
            "hours_missing": 8,
            "status": "pending"
        },
        {
            "user_id": 2,
            "user_name": "Jane Smith",
            "department": "Design",
            "deficiency_date": "2024-01-16",
            "deficiency_type": "Incomplete Hours",
            "hours_missing": 2,
            "status": "pending"
        }
    ],
    "summary": {
        "total_deficiencies": 2,
        "total_missing_hours": 10,
        "affected_users": 2
    }
}

3. Deficiency Report

Endpoint: POST /api/v2/timedef/timelogDeficiencyReport

Generates comprehensive timelog deficiency reports with advanced filtering options.

Request Parameters:

{
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "includeOnlyUsersWithDeficiency": true,
    "includeLwopAwolRejected": true,
    "includeProjectsPmSm": true,
    "department_ids": [1, 2, 3],
    "user_ids": [10, 20, 30]
}

Response: Returns detailed deficiency report with user breakdowns, project impacts, and management insights.

Example Response:

{
    "report_metadata": {
        "generated_at": "2024-01-20T10:30:00Z",
        "period": "2024-01-01 to 2024-12-31",
        "total_users_analyzed": 50,
        "users_with_deficiencies": 12
    },
    "deficiency_summary": {
        "total_deficiencies": 25,
        "total_missing_hours": 120,
        "most_common_type": "Missing Timelog",
        "departments_affected": 5
    },
    "user_deficiencies": [
        {
            "user_id": 1,
            "user_name": "John Doe",
            "department": "Engineering",
            "total_deficiencies": 3,
            "total_missing_hours": 24,
            "deficiency_details": [
                {
                    "date": "2024-01-15",
                    "type": "Missing Timelog",
                    "hours": 8,
                    "project_impact": "Project Alpha delayed"
                }
            ]
        }
    ],
    "recommendations": [
        "Implement daily timelog reminders",
        "Review project assignment processes",
        "Increase manager oversight for frequent offenders"
    ]
}

Usage Guidelines

Integration Usage

The TimeDef integration is designed for:

• Compliance Monitoring: Track employee timelog compliance and identify deficiencies
• Management Reporting: Generate reports for HR and project managers
• Process Improvement: Identify patterns in timelog deficiencies for process optimization
• Resource Planning: Understand time tracking gaps for better resource allocation

Error Handling

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

    logTimeDefError(errorLog);

    switch (error.type) {
        case 'timeout':
            return retryWithBackoff(endpoint, requestData);
        case 'authentication_failed':
            return refreshAuthAndRetry(endpoint, requestData);
        case 'invalid_date_range':
            return handleInvalidDateRange(requestData);
        case 'no_data_found':
            return handleNoDataFound(requestData);
        default:
            return escalateError(errorLog);
    }
}

// Example usage for deficiency reporting
function generateDeficiencyReport(parameters) {
    try {
        return fetch('/api/v2/timedef/timelogDeficiencyReport', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Bearer ' + getTimeDefAuthToken()
            },
            body: JSON.stringify(parameters)
        }).then(response => response.json());
    } catch (error) {
        return handleTimeDefError(error, 'timelogDeficiencyReport', parameters);
    }
}

Best Practices

Report Generation

• Regular Monitoring: Schedule weekly deficiency reports for proactive management
• Filtered Analysis: Use department and user filters to focus on specific areas
• Trend Analysis: Compare deficiency patterns across different time periods
• Action Planning: Use report recommendations to implement process improvements

Data Quality

• Parameter Validation: Always validate date ranges and user selections
• Filter Optimization: Use appropriate filters to reduce data volume and improve performance
• Error Handling: Implement robust error handling for data quality issues

This TimeDef integration provides essential timelog deficiency tracking and compliance monitoring capabilities for the Stratpoint Timesheet Application, enabling proactive management of time tracking compliance and process optimization.