jira_get_worklogs
Retrieve all worklog entries for a specific JIRA issue, enabling tracking of time spent, filtering by date range, and managing task data efficiently within the workflow.
Instructions
Get all worklog entries for a specific issue
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | ||
| maxResults | No | ||
| startAt | No | ||
| startedAfter | No | ||
| startedBefore | No |
Implementation Reference
- The GetWorklogsHandler class that implements the core execution logic for the 'jira_get_worklogs' tool. It validates input parameters, executes the GetWorklogsUseCase, formats the worklog list response, and provides enhanced error messages with usage examples.export class GetWorklogsHandler extends BaseToolHandler< GetWorklogsParams, string > { private formatter: WorklogListFormatter; /** * Create a new GetWorklogsHandler with use case and validator * * @param getWorklogsUseCase - Use case for retrieving worklog entries * @param worklogValidator - Validator for worklog parameters */ constructor( private readonly getWorklogsUseCase: GetWorklogsUseCase, private readonly worklogValidator: WorklogValidator, ) { super("JIRA", "Get Worklogs"); this.formatter = new WorklogListFormatter(); } /** * Execute the handler logic * Retrieves worklog entries and formats them * * @param params - Parameters for worklog retrieval */ protected async execute(params: GetWorklogsParams): Promise<string> { try { // Step 1: Validate parameters const validatedParams = this.worklogValidator.validateGetWorklogsParams(params); this.logger.info( `Getting worklogs for issue: ${validatedParams.issueKey}`, ); // Step 2: Get worklogs using use case const response = await this.getWorklogsUseCase.execute({ issueKey: validatedParams.issueKey, }); // Step 3: Format worklogs using the formatter return this.formatter.format(response.worklogs); } catch (error) { this.logger.error(`Failed to get worklogs: ${error}`); throw this.enhanceError(error, params); } } /** * Enhance error messages for better user guidance */ private enhanceError(error: unknown, params?: GetWorklogsParams): Error { const issueContext = params?.issueKey ? ` for issue ${params.issueKey}` : ""; if (error instanceof JiraNotFoundError) { return new Error( `❌ **Issue Not Found**\n\nNo issue found${issueContext}.\n\n**Solutions:**\n- Verify the issue key is correct\n- Check if the issue exists\n- Verify you have permission to view the issue\n\n**Example:** \`jira_get_worklogs issueKey="PROJ-123"\``, ); } if (error instanceof JiraPermissionError) { return new Error( `❌ **Permission Denied**\n\nYou don't have permission to view worklog entries${issueContext}.\n\n**Solutions:**\n- Check your JIRA permissions\n- Contact your JIRA administrator\n- Verify you have browse projects permission\n\n**Required Permissions:** Browse Projects`, ); } if (error instanceof JiraApiError) { return new Error( `❌ **JIRA API Error**\n\n${error.message}\n\n**Solutions:**\n- Check the issue key is valid (format: PROJ-123)\n- Verify your JIRA connection\n- Try with a different issue\n\n**Example:** \`jira_get_worklogs issueKey="PROJ-123"\``, ); } if (error instanceof Error) { return new Error( `❌ **Worklog Retrieval Failed**\n\n${error.message}${issueContext}\n\n**Solutions:**\n- Check your parameters are valid\n- Verify your JIRA connection\n- Try with a different issue\n\n**Example:** \`jira_get_worklogs issueKey="PROJ-123"\``, ); } return new Error( `❌ **Unknown Error**\n\nAn unknown error occurred during worklog retrieval${issueContext}.\n\nPlease check your parameters and try again.`, ); } }
- Zod schema (getWorklogsParamsSchema) and TypeScript type (GetWorklogsParams) defining the input parameters for the 'jira_get_worklogs' tool, including required issueKey and optional pagination/date filters.* Schema for getting worklogs parameters */ export const getWorklogsParamsSchema = z.object({ issueKey: issueKeySchema, // Optional pagination startAt: z.number().int().min(0).optional().default(0), maxResults: z.number().int().min(1).max(1000).optional().default(1000), // Optional date filtering startedAfter: z .string() .datetime("Started after must be a valid ISO datetime") .optional(), startedBefore: z .string() .datetime("Started before must be a valid ISO datetime") .optional(), }); /** * Type for get worklogs parameters */ export type GetWorklogsParams = z.infer<typeof getWorklogsParamsSchema>;
- Tool configuration object in createWorklogToolsConfig that registers the 'jira_get_worklogs' tool with its name, description, params schema, and handler binding.{ name: "jira_get_worklogs", description: "Get all worklog entries for a specific issue", params: getWorklogsParamsSchema.shape, handler: tools.jira_get_worklogs.handle.bind(tools.jira_get_worklogs), },
- Factory function createWorklogHandlers that instantiates the GetWorklogsHandler with dependencies and creates the jira_get_worklogs tool wrapper object with a handle method delegating to the handler.function createWorklogHandlers(dependencies: JiraDependencies) { const addWorklogHandler = new AddWorklogHandler( dependencies.addWorklogUseCase, dependencies.worklogValidator, ); const getWorklogsHandler = new GetWorklogsHandler( dependencies.getWorklogsUseCase, dependencies.worklogValidator, ); const updateWorklogHandler = new UpdateWorklogHandler( dependencies.updateWorklogUseCase, dependencies.worklogValidator, ); const deleteWorklogHandler = new DeleteWorklogHandler( dependencies.deleteWorklogUseCase, dependencies.worklogValidator, ); return { jira_add_worklog: { handle: async (args: unknown) => addWorklogHandler.handle(args), }, jira_get_worklogs: { handle: async (args: unknown) => getWorklogsHandler.handle(args), }, jira_update_worklog: { handle: async (args: unknown) => updateWorklogHandler.handle(args), }, jira_delete_worklog: { handle: async (args: unknown) => deleteWorklogHandler.handle(args), }, }; }