getProjectsReportingUtilization
Generate utilization reports for your team in CSV, HTML, PDF, or XLSX format. Filter by dates, projects, users, and more to get tailored insights.
Instructions
Generate utilization report in various formats (CSV, HTML, PDF, XLSX). Generates a utilization report containing all people for the provided filters. Only the people that the logged-in user can access will be returned.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | The format of the report | |
| zoom | No | determine the type of zoom filter used to display on the report | |
| startDate | No | filter by start date | |
| sortOrder | No | order mode | |
| sort | No | sort by (deprecated, use orderBy) | |
| searchTerm | No | filter by user first or last name | |
| reportFormat | No | define the format of the report | |
| orderMode | No | group by | |
| orderBy | No | sort by | |
| groupBy | No | group by | |
| endDate | No | filter by end date | |
| pageSize | No | number of items in a page | |
| page | No | page number | |
| skipCounts | No | SkipCounts allows you to skip doing counts on a list API endpoint for performance reasons. | |
| legacyResponse | No | return response without summary and its legacy body structure | |
| isReportDownload | No | generate a report document | |
| isCustomDateRange | No | determine if the query is for a custom date range | |
| includeUtilizations | No | adds report rows for individual entities | |
| includeTotals | No | adds report summary to response | |
| includeCollaborators | No | include collaborators | |
| includeClients | No | include client users | |
| includeArchivedProjects | No | include archived projects | |
| IncludeCompletedTasks | No | include completed tasks | |
| userIds | No | filter by userIds | |
| teamIds | No | filter by team ids | |
| selectedColumns | No | customise the report by selecting columns to be displayed. | |
| projectIds | No | filter by project ids | |
| jobRoleIds | No | filter by jobrole ids | |
| include | No | include | |
| fieldsUtilizations | No | Query parameter: fields[utilizations] | |
| fieldsUsers | No | Query parameter: fields[users] | |
| companyIds | No | filter by company ids |
Implementation Reference
- The handler function that executes the getProjectsReportingUtilization tool logic. Calls the getUtilization service and returns JSON response.
export async function handleGetProjectsReportingUtilization(input: any) { try { const data = await getUtilization({ ...input, format: input.format.toLowerCase() }); return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] }; } catch (error: any) { return createErrorResponse(error, 'Getting utilization report'); } } - The tool definition (name, description, input schema) for getProjectsReportingUtilization, including all input properties and annotations.
export const getProjectsReportingUtilizationDefinition = { name: "getProjectsReportingUtilization", description: "Generate utilization report in various formats (CSV, HTML, PDF, XLSX). Generates a utilization report containing all people for the provided filters. Only the people that the logged-in user can access will be returned.", inputSchema: { type: 'object', properties: { format: { type: 'string', description: 'The format of the report', enum: ['csv', 'html', 'pdf', 'xlsx'] }, zoom: { type: 'string', description: 'determine the type of zoom filter used to display on the report', enum: [ 'week', 'month', 'last3months', 'quarterbyweek', 'quarterbymonth' ] }, startDate: { type: 'string', description: 'filter by start date' }, sortOrder: { type: 'string', description: 'order mode', enum: [ 'asc', 'desc' ] }, sort: { type: 'string', description: 'sort by (deprecated, use orderBy)', enum: [ 'name', 'percentutilization', 'percentestimatedutilization', 'availableminutes', 'unavailableminutes', 'loggedminutes', 'billableminutes', 'unbillableminutes', 'billableutilization', 'nonbillableutilization' ] }, searchTerm: { type: 'string', description: 'filter by user first or last name' }, reportFormat: { type: 'string', description: 'define the format of the report', enum: [ 'pdf' ] }, orderMode: { type: 'string', description: 'group by', enum: [ 'weekly', 'monthly' ] }, orderBy: { type: 'string', description: 'sort by', enum: [ 'name', 'percentutilization', 'percentestimatedutilization', 'availableminutes', 'unavailableminutes', 'loggedminutes', 'billableminutes', 'unbillableminutes', 'companycount', 'achieved', 'target', 'allocatedutilization', 'totalworkingminutes', 'availableutilization', 'unavailableutilization' ] }, groupBy: { type: 'string', description: 'group by', enum: [ 'day', 'week', 'month' ] }, endDate: { type: 'string', description: 'filter by end date' }, pageSize: { type: 'integer', description: 'number of items in a page' }, page: { type: 'integer', description: 'page number' }, skipCounts: { type: 'boolean', description: 'SkipCounts allows you to skip doing counts on a list API endpoint for performance reasons.' }, legacyResponse: { type: 'boolean', description: 'return response without summary and its legacy body structure' }, isReportDownload: { type: 'boolean', description: 'generate a report document' }, isCustomDateRange: { type: 'boolean', description: 'determine if the query is for a custom date range' }, includeUtilizations: { type: 'boolean', description: 'adds report rows for individual entities' }, includeTotals: { type: 'boolean', description: 'adds report summary to response' }, includeCollaborators: { type: 'boolean', description: 'include collaborators' }, includeClients: { type: 'boolean', description: 'include client users' }, includeArchivedProjects: { type: 'boolean', description: 'include archived projects' }, IncludeCompletedTasks: { type: 'boolean', description: 'include completed tasks' }, userIds: { type: 'array', description: 'filter by userIds' }, teamIds: { type: 'array', description: 'filter by team ids' }, selectedColumns: { type: 'array', description: 'customise the report by selecting columns to be displayed.' }, projectIds: { type: 'array', description: 'filter by project ids' }, jobRoleIds: { type: 'array', description: 'filter by jobrole ids' }, include: { type: 'array', description: 'include' }, fieldsUtilizations: { type: 'array', description: 'Query parameter: fields[utilizations]' }, fieldsUsers: { type: 'array', description: 'Query parameter: fields[users]' }, companyIds: { type: 'array', description: 'filter by company ids' } }, required: ['format'] }, annotations: { title: "Get the Utilization of People in Projects", readOnlyHint: false, destructiveHint: false, openWorldHint: false } }; - src/tools/index.ts:99-100 (registration)Registration of the tool definition and handler pair in the toolPairs array
{ definition: getProjectsReportingUserTaskCompletion, handler: handleGetProjectsReportingUserTaskCompletion }, { definition: getProjectsReportingUtilization, handler: handleGetProjectsReportingUtilization }, - src/tools/index.ts:148-148 (registration)Re-export of handleGetProjectsReportingUtilization from the tools index
export { handleGetProjectsReportingUtilization } from './people/getUtilization.js'; - The service layer helper that makes the actual API call to /reporting/precanned/utilization.{format} endpoint
import { ensureApiClient } from '../core/apiClient.js'; interface GetUtilizationParams { format: 'csv' | 'html' | 'pdf' | 'xlsx'; zoom?: string; startDate?: string; sortOrder?: string; sort?: string; searchTerm?: string; reportFormat?: string; orderMode?: string; orderBy?: string; groupBy?: string; endDate?: string; pageSize?: number; page?: number; skipCounts?: boolean; legacyResponse?: boolean; isReportDownload?: boolean; isCustomDateRange?: boolean; includeUtilizations?: boolean; includeTotals?: boolean; includeCollaborators?: boolean; includeClients?: boolean; includeArchivedProjects?: boolean; IncludeCompletedTasks?: boolean; userIds?: number[]; teamIds?: number[]; selectedColumns?: string[]; projectIds?: number[]; jobRoleIds?: number[]; include?: string[]; fieldsUtilizations?: string[]; fieldsUsers?: string[]; companyIds?: number[]; } async function getUtilization(params: GetUtilizationParams) { const api = ensureApiClient(); const endpoint = `/reporting/precanned/utilization.${params.format}`; const response = await api.get(endpoint, { params }); return response.data; } export default getUtilization;