Leave Management APIs

The Leave Management APIs provide functionality for leave reporting, leave eligibility management, and leave adjustment operations in the Stratpoint Timesheet Application. These APIs are designed for business-specific leave operations with complex accrual calculations and adjustment workflows.

Authentication Headers

All leave management endpoints require authentication:

Authorization: Bearer {jwt_token}
galingsa: timesheetweb
Content-Type: application/json

Leave Reporting Operations

Individual Leave Report

Retrieves detailed leave report for a specific user.

POST /api/v2/leaves/individual_report/{userId}

Permission Required: Permission ID 125 (or 126 for viewing other users)

Parameters: - userId: User ID (required)

Request Body:

{
  "year": "2024",
  "userId": 123,
  "filtersToGet": true
}

Response:

{
  "header": {
    "status": 200,
    "title": "Leaves",
    "description": ""
  },
  "body": {
    "data": {
      "year": "2024",
      "user": {
        "id": 123,
        "firstname": "John",
        "lastname": "Doe",
        "email": "john.doe@stratpoint.com",
        "startDate": "2023-01-15",
        "leaveEligibilityDate": "2023-07-15",
        "employments": [
          {
            "startDate": "2023-01-15",
            "endDate": null,
            "employmentType": "Regular"
          }
        ]
      },
      "records": {
        "1": {
          "taskType": {
            "id": 1,
            "name": "Annual Leave",
            "accrualType": "monthly",
            "accrualValue": "1.25"
          },
          "earned": "15.00",
          "used": "8.00",
          "balance": "7.00",
          "adjustments": [
            {
              "id": 456,
              "type": "manual_adjustment",
              "hours": "2.00",
              "reason": "Bonus leave credit",
              "date": "2024-01-15"
            }
          ]
        }
      }
    },
    "filters": {
      "leaveTypes": [
        {
          "id": 1,
          "name": "Annual Leave",
          "isActive": 1
        }
      ]
    }
  }
}

Get All User Report

Retrieves leave report for all users with filtering options.

POST /api/v2/leaves/getAllUserReport

Permission Required: Permission ID 126 and 26

Request Body:

{
  "year": "2024",
  "companyBooking_id": 1,
  "selectLeaveType": "1,2,3",
  "selectBusinessUnit": "1,2",
  "selectProjectType": "1,2",
  "selectEmploymentType": "1,2",
  "selectJobFamily": "1,2",
  "selectCapability": "1,2"
}

Validation Rules: - year: Required, format YYYY - selectLeaveType: Required, comma-separated integers - Other filters: Optional comma-separated integers

Get Leaves Per User Project Report

Retrieves leave data grouped by user and project.

POST /api/v2/leaves/getLeavesPerUserProject/{groupBy?}

Parameters: - groupBy: Optional grouping parameter

Get CTO Usage Report

Retrieves Compensatory Time Off usage report.

POST /api/v2/leaves/getCtoUsageReport

Leave Adjustment Operations

Update Leave Availability

Updates leave availability for users.

POST /api/v2/leaves/updateAvailability

Request Body:

{
  "userId": 123,
  "taskTypeId": 1,
  "year": "2024",
  "adjustmentHours": "8.00",
  "reason": "Manual adjustment for special circumstance"
}

Delete Leave Availability

Deletes specific leave availability record.

GET /api/v2/leaves/deleteAvailability/{id}/{userId}

Parameters: - id: Leave availability record ID (required) - userId: User ID (required)

Save Mass Leave Adjustments

Performs bulk leave adjustments for multiple users.

POST /api/v2/leaves/saveMassAdjustments

Request Body:

{
  "adjustments": [
    {
      "userId": 123,
      "taskTypeId": 1,
      "hours": "4.00",
      "reason": "Bonus leave credit"
    },
    {
      "userId": 124,
      "taskTypeId": 1,
      "hours": "8.00",
      "reason": "Leave adjustment"
    }
  ]
}

Process Offset Hours with Discrepancies

Processes offset hours that have discrepancies.

GET /api/v2/leaves/processOffsetHoursWithDiscrepancies/{year}

Parameters: - year: Year to process (required)

Leave Adjustment Resource Operations

The Leave Adjustment resource supports standard CRUD operations:

GET /api/v2/leave_adjustments

POST /api/v2/leave_adjustments

GET /api/v2/leave_adjustments/{id}

PUT /api/v2/leave_adjustments/{id}

DELETE /api/v2/leave_adjustments/{id}

Dashboard Integration

Dashboard Leaves

Retrieves leave data for dashboard display.

GET /api/v2/dashboard/leaves/{userId}

Parameters: - userId: User ID (required)

Response:

{
  "header": {
    "status": 200,
    "title": "Dashboard",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "leaveBalances": [
        {
          "taskTypeId": 1,
          "taskTypeName": "Annual Leave",
          "earned": "15.00",
          "used": "8.00",
          "balance": "7.00"
        },
        {
          "taskTypeId": 2,
          "taskTypeName": "Sick Leave",
          "earned": "5.00",
          "used": "2.00",
          "balance": "3.00"
        }
      ],
      "upcomingLeaves": [
        {
          "startDate": "2024-02-15",
          "endDate": "2024-02-16",
          "taskTypeName": "Annual Leave",
          "totalDays": 2
        }
      ]
    }
  }
}

Business Rules and Leave Types

Leave Accrual Types

Leave types use different accrual patterns:

Monthly Accrual: - Annual Leave: 1.25 days per month - Sick Leave: 0.417 days per month

Annual Accrual: - Vacation Leave: 15 days per year

Accrual Calculation Rules

1. Leave Eligibility: Users become eligible after regularization date
2. Accrual Day: Leave credits accrue on specific day of month (configurable)
3. Daily Required Hours: Leave calculations based on daily required hours (configurable)
4. Pro-rating: Leave accrual is pro-rated for partial employment periods

Employment Status Impact

Leave calculations consider employment status: - Active Employees: Full accrual calculation - Resigned Employees: Accrual stops at resignation date - Inactive Employees: Accrual may be suspended

Leave Task Types

Task Type Integration

Leaves are implemented as special task types with isLeaveType = 1:

Leave Task Type Properties: - id: Task type ID - name: Leave type name (e.g., "Annual Leave") - accrualType: "monthly" or "annual" - accrualValue: Decimal accrual rate - isLeaveType: Always 1 for leave types

Error Handling

Common Error Responses

Access Denied:

{
  "header": {
    "status": 401,
    "title": "Leaves",
    "description": "Access not allowed"
  },
  "body": []
}

Validation Error:

{
  "header": {
    "status": 412,
    "title": "Leaves",
    "description": "Validation error encountered"
  },
  "body": {
    "errors": {
      "year": ["The year field is required"],
      "selectLeaveType": ["The selectLeaveType field is required"]
    }
  }
}

User Not Found:

{
  "header": {
    "status": 412,
    "title": "Leaves",
    "description": "User not found"
  },
  "body": []
}

Key Implementation Notes

1. Leave as Task Types: Leave management integrated with task type system
2. Accrual Calculations: Complex business logic for leave accrual based on employment dates
3. Adjustment System: Comprehensive leave adjustment tracking with reasons
4. Permission-Based Access: Granular permissions for viewing own vs others' leave data
5. Business Rule Integration: Leave eligibility tied to employment status and regularization
6. Reporting Focus: Heavy emphasis on leave reporting and analytics
7. CTO Integration: Compensatory Time Off managed within leave system
8. Mass Operations: Support for bulk leave adjustments and processing

This Leave Management API is designed for enterprise leave management with complex accrual calculations, comprehensive reporting, and business rule enforcement.