list-payroll-leave-periods
Retrieve detailed leave period information for a specific employee in Xero, including start and end dates, status, payment dates, and leave types.
Instructions
List all leave periods for a specific employee in Xero. This shows detailed time off periods including start and end dates, period status, payment dates, and leave types. Provide an employee ID to see their leave periods.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| employeeId | Yes | The Xero employee ID to fetch leave periods for | |
| startDate | No | Optional start date in YYYY-MM-DD format | |
| endDate | No | Optional end date in YYYY-MM-DD format |
Implementation Reference
- The main tool handler function that calls the Xero API handler and formats leave periods data into readable text responses.async ({ employeeId, startDate, endDate }) => { const response = await listXeroPayrollLeavePeriods(employeeId, startDate, endDate); if (response.isError) { return { content: [ { type: "text" as const, text: `Error listing employee leave periods: ${response.error}`, }, ], }; } const periods = response.result; return { content: [ { type: "text" as const, text: `Found ${periods?.length || 0} leave periods for employee ${employeeId}:`, }, ...(periods?.map((period: LeavePeriod) => ({ type: "text" as const, text: [ `Period Status: ${period.periodStatus || "Unknown"}`, period.periodStartDate ? `Start Date: ${period.periodStartDate}` : null, period.periodEndDate ? `End Date: ${period.periodEndDate}` : null, period.numberOfUnits ? `Number of Units: ${period.numberOfUnits}` : null, period.numberOfUnitsTaken ? `Payment Date: ${period.numberOfUnitsTaken}` : null, period.typeOfUnits ? `Payment Date: ${period.typeOfUnits}` : null, period.typeOfUnitsTaken ? `Payment Date: ${period.typeOfUnitsTaken}` : null, period.periodStatus ? `Period Status: ${period.periodStatus}` : null, ] .filter(Boolean) .join("\n"), })) || []), ], }; },
- Input schema using Zod for validating tool parameters: employeeId (required), startDate and endDate (optional).{ employeeId: z.string().describe("The Xero employee ID to fetch leave periods for"), startDate: z.string().optional().describe("Optional start date in YYYY-MM-DD format"), endDate: z.string().optional().describe("Optional end date in YYYY-MM-DD format"), },
- src/tools/list/index.ts:49-49 (registration)Registration of the list-payroll-leave-periods tool in the ListTools array export.ListPayrollLeavePeriodsToolTool,
- Core helper function that fetches leave periods from Xero Payroll NZ API, handles errors, and returns structured response.export async function listXeroPayrollLeavePeriods( employeeId: string, startDate?: string, endDate?: string, ): Promise<XeroClientResponse<LeavePeriod[]>> { try { const periods = await fetchLeavePeriods({ employeeId, startDate, endDate }); if (!periods) { return { result: [], isError: false, error: null, }; } return { result: periods, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
- Internal helper that performs the actual Xero API call to retrieve employee leave periods.async function fetchLeavePeriods({ employeeId, startDate, endDate, }: FetchLeavePeriodParams): Promise<LeavePeriod[] | null> { await xeroClient.authenticate(); if (!employeeId) { throw new Error("Employee ID is required to fetch leave periods"); } // After reviewing the SDK documentation, it appears this API call requires different parameters // Use parameters that match the SDK's expectations const response = await xeroClient.payrollNZApi.getEmployeeLeavePeriods( xeroClient.tenantId, employeeId, startDate, endDate, ); return response.body.periods ?? null; }