createSubTask
Create a subtask under a parent task. Provide parent task ID and configure assignees, dates, attachments, and more.
Instructions
Creates a subtask. Create a new subtask under the provided parent task.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| taskRequest | Yes | Request body: taskRequest | |
| taskId | Yes | Path parameter: taskId |
Implementation Reference
- src/tools/tasks/createSubTask.ts:505-585 (handler)Main handler function for the createSubTask tool. Extracts taskId and taskRequest from input, validates them, calls the teamwork service, and returns the created subtask response.
export async function handleCreateSubTask(input: any) { logger.info("=== createSubTask tool called ==="); logger.info(`Input: ${JSON.stringify(input || {})}`); try { // Get the taskId from input let taskId = input.taskId ? String(input.taskId) : null; // If taskId is not provided, return an error if (!taskId) { logger.info("No taskId provided"); return { content: [{ type: "text", text: "No taskId provided. Please provide a taskId of the parent task." }] }; } // Prepare the task request const taskRequest = input.taskRequest as TaskRequest; // Validate task request if (!taskRequest || !taskRequest.task) { logger.error("Invalid task request: missing task object"); return { content: [{ type: "text", text: "Invalid task request: missing task object. Please provide a taskRequest.task object." }] }; } // Ensure task has name (Teamwork API requires 'name' for the task title) if (!taskRequest.task.name) { logger.error("Invalid task request: missing task name"); return { content: [{ type: "text", text: "Invalid task request: missing task name. Please provide taskRequest.task.name." }] }; } logger.info(`Creating subtask "${taskRequest.task.name}" for parent task ${taskId}`); // Call the service to create the subtask const createdSubTask = await teamworkService.createSubTask(String(taskId), taskRequest); logger.info("Subtask created successfully"); logger.info(`Created subtask response: ${JSON.stringify(createdSubTask).substring(0, 200)}...`); // Ensure we return a properly formatted response const response = { content: [{ type: "text", text: JSON.stringify(createdSubTask, null, 2) }] }; // Validate that the response can be serialized try { JSON.stringify(response); logger.info("Response is valid JSON"); } catch (jsonError: any) { logger.error(`Invalid JSON in response: ${jsonError.message}`); // Return a safe response return { content: [{ type: "text", text: "Subtask created successfully, but there was an error formatting the response." }] }; } logger.info("=== createSubTask tool completed successfully ==="); return response; } catch (error: any) { return createErrorResponse(error, 'Creating subtask'); } } - Tool definition (createSubTaskDefinition) containing the input JSON schema for the createSubTask tool, including all properties for taskRequest, taskId, and annotations.
export const createSubTaskDefinition = { name: "createSubTask", description: "Creates a subtask. Create a new subtask under the provided parent task.", inputSchema: { type: "object", properties: { taskRequest: { type: "object", properties: { attachmentOptions: { type: "object", properties: { removeOtherFiles: { type: "boolean" } }, required: [] }, attachments: { type: "object", properties: { files: { type: "array", items: { type: "object", properties: { categoryId: { type: "integer" }, id: { type: "integer" } }, required: [], description: "File stores information about a uploaded file." } }, pendingFiles: { type: "array", items: { type: "object", properties: { categoryId: { type: "integer" }, reference: { type: "string" } }, required: [], description: "PendingFile stores information about a file uploaded on-the-fly." } } }, required: [] }, card: { type: "object", properties: { columnId: { type: "integer" } }, required: [], description: "Card stores information about the card created with the task." }, predecessors: { type: "array", items: { type: "object", properties: { id: { type: "integer" }, type: { type: "string" } }, required: [], description: "Predecessor stores information about task predecessors." } }, tags: { type: "array", items: { type: "object", properties: { color: { type: "string" }, name: { type: "string" }, projectId: { type: "integer" } }, required: [], description: "Tag contains all the information returned from a tag." } }, task: { type: "object", properties: { assignees: { type: "object", properties: { companyIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, teamIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, userIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." } }, required: [], description: "UserGroups are common lists for storing users, companies and teams ids together." }, attachmentIds: { type: "array", items: { type: "integer" } }, changeFollowers: { type: "object", properties: { companyIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, teamIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, userIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." } }, required: [], description: "UserGroups are common lists for storing users, companies and teams ids together." }, commentFollowers: { type: "object", properties: { companyIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, teamIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, userIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." } }, required: [], description: "UserGroups are common lists for storing users, companies and teams ids together." }, completedAt: { type: "string" }, completedBy: { type: "integer" }, createdAt: { type: "string" }, createdBy: { type: "integer" }, crmDealIds: { type: "array", items: { type: "integer" } }, customFields: { type: "object", properties: { Values: { type: "array", items: { type: "object", properties: { countryCode: { type: "string" }, currencySymbol: { type: "string" }, customfieldId: { type: "integer" }, urlTextToDisplay: { type: "string" }, value: { type: "string" } }, required: [], description: "CustomFieldValue contains all the information returned from a customfield." } } }, required: [], description: "CustomFields is the custom fields type." }, description: { type: "string" }, descriptionContentType: { type: "string" }, dueAt: { type: "string", format: "date", description: "NullableDate implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted. Date format '2006-01-02'" }, estimatedMinutes: { type: "integer" }, grantAccessTo: { type: "object", properties: { companyIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, teamIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, userIds: { type: "array", items: { type: "integer" }, description: "NullableInt64Slice implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." } }, required: [], description: "UserGroups are common lists for storing users, companies and teams ids together." }, hasDeskTickets: { type: "boolean" }, name: { type: "string" }, originalDueDate: { type: "string", format: "date", description: "NullableDate implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted. Date format '2006-01-02'" }, parentTaskId: { type: "integer" }, priority: { type: "string", enum: [ "low", "normal", "high" ], description: "NullableTaskPriority implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, private: { type: "boolean" }, progress: { type: "integer" }, reminders: { type: "array", items: { type: "object", properties: { isRelative: { type: "boolean" }, note: { type: "string" }, relativeNumberDays: { type: "integer" }, remindAt: { type: "string" }, type: { type: "string" }, userId: { type: "integer" } }, required: [], description: "Reminder stores all necessary information to create a task reminder." } }, repeatOptions: { type: "object", properties: { duration: { type: "integer" }, editOption: { type: "string" }, endsAt: { type: "string", format: "date", description: "NullableDate implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted. Date format '2006-01-02'" }, frequency: { type: "object", description: "NullableTaskRepeatFrequency implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, monthlyRepeatType: { type: "object", description: "NullableTaskRepeatMonthlyType implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." }, rrule: { type: "string", description: "Adds the RRule definition for repeating tasks. It replaces all other repeating fields." }, selectedDays: { type: "object", description: "NullableWorkingHourEntryWeekdays implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted." } }, required: [], description: "RepeatOptions stores recurring information for the task." }, startAt: { type: "string", format: "date", description: "NullableDate implements json.Unmarshaler to allow testing between a value that explicitly set to null or omitted. Date format '2006-01-02'" }, status: { type: "string" }, tagIds: { type: "array", items: { type: "integer" } }, taskgroupId: { type: "integer" }, tasklistId: { type: "integer" }, templateRoleName: { type: "string" }, ticketId: { type: "integer" } }, required: [], description: "Task contains all the information returned from a task." }, taskOptions: { type: "object", properties: { appendAssignees: { type: "boolean" }, checkInvalidusers: { type: "boolean" }, everyoneMustDo: { type: "boolean" }, fireWebhook: { type: "boolean" }, isTemplate: { type: "boolean" }, logActivity: { type: "boolean" }, notify: { type: "boolean" }, parseInlineTags: { type: "boolean" }, positionAfterTaskId: { type: "integer" }, pushDependents: { type: "boolean" }, pushSubtasks: { type: "boolean" }, shiftProjectDates: { type: "boolean" }, useDefaults: { type: "boolean" }, useNotifyViaTWIM: { type: "boolean" } }, required: [], description: "Options contains any options which can be set for the task request" }, workflows: { type: "object", properties: { positionAfterTask: { type: "integer" }, stageId: { type: "integer" }, workflowId: { type: "integer" } }, required: [], description: "Workflows stores information about where the task lives in the workflow" } }, required: [], description: "Request body: taskRequest" }, taskId: { type: "integer", description: "Path parameter: taskId" } }, required: [ "taskRequest", "taskId" ] }, annotations: { title: "Create a Subtask", readOnlyHint: false, destructiveHint: false, openWorldHint: false } }; - Service-layer function that makes the actual API call to POST /tasks/{taskId}/subtasks.json to create the subtask in Teamwork.
export const createSubTask = async (taskId: string, taskData: TaskRequest) => { try { logger.info(`Creating subtask for parent task ${taskId}`); // Ensure we have a valid task object if (!taskData || !taskData.task) { throw new Error('Invalid task data: missing task object'); } // Ensure task has name field (Teamwork API requires 'name' for the task title) if (!taskData.task.name) { throw new Error('Invalid task data: missing task name'); } logger.info(`Subtask data: ${JSON.stringify(taskData).substring(0, 200)}...`); const api = ensureApiClient(); const response = await api.post(`/tasks/${taskId}/subtasks.json`, taskData); logger.info(`Subtask creation successful, status: ${response.status}`); // Validate response data if (!response.data) { logger.warn('Subtask created but response data is empty'); return { success: true, message: 'Subtask created successfully, but no details returned' }; } // Ensure response data is serializable try { JSON.stringify(response.data); logger.info('Response data is valid JSON'); } catch (error: any) { logger.error(`Response data is not valid JSON: ${error.message}`); return { success: true, message: 'Subtask created successfully, but response contains non-serializable data', partial: typeof response.data === 'object' ? Object.keys(response.data) : typeof response.data }; } return response.data; } catch (error: any) { logger.error(`Error creating subtask for parent task ${taskId}: ${error.message}`); // Log detailed error information if (error.response) { logger.error(`API error status: ${error.response.status}`); logger.error(`API error data: ${JSON.stringify(error.response.data || {})}`); } if (error.stack) { logger.error(`Stack trace: ${error.stack}`); } throw new Error(`Failed to create subtask for parent task ${taskId}: ${error.message}`); } }; - src/tools/index.ts:18-75 (registration)Import and registration of createSubTaskDefinition and handleCreateSubTask in the tools index, with the tool pair added to the toolPairs array on line 75.
import { createSubTaskDefinition as createSubTask, handleCreateSubTask } from './tasks/createSubTask.js'; import { updateTaskDefinition as updateTask, handleUpdateTask } from './tasks/updateTask.js'; import { deleteTaskDefinition as deleteTask, handleDeleteTask } from './tasks/deleteTask.js'; import { getTasksMetricsCompleteDefinition as getTasksMetricsComplete, handleGetTasksMetricsComplete } from './tasks/getTasksMetricsComplete.js'; import { getTasksMetricsLateDefinition as getTasksMetricsLate, handleGetTasksMetricsLate } from './tasks/getTasksMetricsLate.js'; import { getTaskSubtasksDefinition as getTaskSubtasks, handleGetTaskSubtasks } from './tasks/getTaskSubtasks.js'; import { getTaskCommentsDefinition as getTaskComments, handleGetTaskComments } from './tasks/getTaskComments.js'; // Comments import { createCommentDefinition as createComment, handleCreateComment } from './comments/createComment.js'; // People import { getPeopleDefinition as getPeople, handleGetPeople } from './people/getPeople.js'; import { getPersonByIdDefinition as getPersonById, handleGetPersonById } from './people/getPersonById.js'; import { getProjectPeopleDefinition as getProjectPeople, handleGetProjectPeople } from './people/getProjectPeople.js'; import { addPeopleToProjectDefinition as addPeopleToProject, handleAddPeopleToProject } from './people/addPeopleToProject.js'; import { deletePersonDefinition as deletePerson, handleDeletePerson } from './people/deletePerson.js'; import { updatePersonDefinition as updatePerson, handleUpdatePerson } from './people/updatePerson.js'; // Companies import { createCompanyDefinition as createCompany, handleCreateCompany } from './companies/createCompany.js'; import { updateCompanyDefinition as updateCompany, handleUpdateCompany } from './companies/updateCompany.js'; import { deleteCompanyDefinition as deleteCompany, handleDeleteCompany } from './companies/deleteCompany.js'; import { getCompaniesDefinition as getCompanies, handleGetCompanies } from './companies/getCompanies.js'; import { getCompanyByIdDefinition as getCompanyById, handleGetCompanyById } from './companies/getCompanyById.js'; // Reporting import { getProjectsPeopleMetricsPerformanceDefinition as getProjectsPeopleMetricsPerformance, handleGetProjectsPeopleMetricsPerformance } from './people/getPeopleMetricsPerformance.js'; import { getProjectsPeopleUtilizationDefinition as getProjectsPeopleUtilization, handleGetProjectsPeopleUtilization } from './people/getPeopleUtilization.js'; import { getProjectPersonDefinition as getProjectPerson, handleGetProjectPerson } from './people/getProjectPerson.js'; import { getProjectsReportingUserTaskCompletionDefinition as getProjectsReportingUserTaskCompletion, handleGetProjectsReportingUserTaskCompletion } from './reporting/getUserTaskCompletion.js'; import { getProjectsReportingUtilizationDefinition as getProjectsReportingUtilization, handleGetProjectsReportingUtilization } from './people/getUtilization.js'; // Time-related imports import { getTimeDefinition as getTime, handleGetTime } from './time/getTime.js'; import { getProjectsAllocationsTimeDefinition as getAllocationTime, handleGetProjectsAllocationsTime } from './time/getAllocationTime.js'; // Core import { getTimezonesDefinition as getTimezones, handleGetTimezones } from './core/getTimezones.js'; // Define a structure that pairs tool definitions with their handlers interface ToolPair { definition: any; handler: Function; } // Create an array of tool pairs const toolPairs: ToolPair[] = [ { definition: getProjects, handler: handleGetProjects }, { definition: getCurrentProject, handler: handleGetCurrentProject }, { definition: createProject, handler: handleCreateProject }, { definition: getTasks, handler: handleGetTasks }, { definition: getTasksByProjectId, handler: handleGetTasksByProjectId }, { definition: getTaskListsByProjectId, handler: handleGetTaskListsByProjectId }, { definition: getTasksByTaskListId, handler: handleGetTasksByTaskListId }, { definition: getTaskById, handler: handleGetTaskById }, { definition: createTask, handler: handleCreateTask }, { definition: createSubTask, handler: handleCreateSubTask }, - src/utils/config.ts:251-257 (registration)Tool grouped under 'Tasks' in the config toolGroups mapping.
'Tasks': ['getTasks', 'getTasksByProjectId', 'getTaskListsByProjectId', 'getTaskById', 'createTask', 'createSubTask', 'updateTask', 'deleteTask', 'getTasksMetricsComplete', 'getTasksMetricsLate', 'getTaskSubtasks', 'getTaskComments'], 'People': ['getPeople', 'getPersonById', 'getProjectPeople', 'addPeopleToProject', 'deletePerson', 'getProjectsPeopleMetricsPerformance', 'getProjectsPeopleUtilization', 'getProjectPerson'], 'Reporting': ['getProjectsReportingUserTaskCompletion', 'getProjectsReportingUtilization'], 'Time': ['getTime', 'getProjectsAllocationsTime', 'getTimezones'], 'Comments': ['createComment'], 'Companies': ['createCompany', 'updateCompany', 'deleteCompany', 'getCompanies', 'getCompanyById'] };