Add Autotask Special Operation

Use this skill when

• •Adding a new non-CRUD operation to an existing resource (e.g. slaHealthCheck on tickets, searchByDomain on companies, whoAmI on resources)
• •The operation needs to be exposed as an AI tool in AutotaskAiTools.node.ts
• •The operation has custom parameters, logic, or output formatting that differs from standard get/getMany/create/update/delete/count

Do NOT use this skill when

• •Adding a new standard CRUD entity or child entity — use the add-autotask-child-entity skill instead
• •The operation follows the standard CRUD pattern and is auto-derived from entity metadata

End-to-end workflow

Phase 1: Resource-level implementation

1. •

   Add operation to resource description.ts

   • •Add the operation to the operationOptions array
   • •Add any new input fields (with appropriate displayOptions)
   • •If the operation reuses existing fields (e.g. id), update their displayOptions.show.operation arrays
2. •

   Implement logic in resource execute.ts

   • •Add a case for the new operation in the execute function's switch
   • •Implement the business logic (API calls, data transformation, etc.)
   • •Use processOutputMode if the operation should support picklist/reference label enrichment
3. •

   Update picklist/reference label visibility (if applicable)

   • •operations/common/picklist-labels/description.ts — add operation to the operation array in displayOptions.show
   • •operations/common/reference-labels/description.ts — same

Phase 2: AI Tools layer (critical — 10 touchpoints)

Read the full checklist at: .docs/autotask/change-guidelines/ai-tools-special-operation-checklist.md

The summary of mandatory steps is:

Phase 3: Shared executor and tool resource

1. •Wire in resources/tool/execute.ts (if the operation has custom parameter routing)
   • •Add parameter mapping in the getNodeParameter override within executeToolOperation
   • •Map AI tool flat parameters to the internal parameter names expected by the resource executor

Phase 4: Documentation

1. •Update CHANGELOG.md — add an Added entry under the current version
2. •Update README.md — add the operation to the features/operations list

Phase 5: Validation

1. •Run corepack pnpm build — must compile clean
2. •Run corepack pnpm lint — no new errors in changed files
3. •Run manual audit against the full checklist in .docs/autotask/change-guidelines/ai-tools-special-operation-checklist.md

Critical hazards

normaliseOperation() — the silent killer

File: ai-tools/tool-executor.ts

This function lowercases its input and then uses a switch to restore camelCase for known operations. If a new camelCase operation is not added here, it stays lowercase (e.g. slahealthcheck instead of slaHealthCheck). This compiles and lints clean but silently breaks every runtime comparison:

• •noIdOperations.includes() fails (case-sensitive)
• •effectiveOperation === 'slaHealthCheck' fails in getNodeParameter overrides
• •case 'slaHealthCheck' fails in formatToolResponse
• •Net effect: the operation is completely non-functional for AI tools

Rule: Any operation name containing uppercase letters must have an explicit case in normaliseOperation. Single-word lowercase names (get, count, create, update, delete) don't need one.

Zod schema — no .refine() on the return

Schema generator functions must return z.ZodObject<Record<string, z.ZodTypeAny>>. Using .refine(), .transform(), or .superRefine() produces ZodEffects which is not assignable to ZodObject — this causes a TypeScript compilation error. Put cross-field validation in the execute function instead.

getNodeParameter throws in shared code

Any shared helper code accessing parameters only injected by the AI tool executor must use try/catch, not just a fallback value. Newer n8n versions throw even with a fallback when the parameter name is absent from the node schema.

WRITE_OPERATIONS safety gate omissions

SUPPORTED_TOOL_OPERATIONS controls visibility, but allowWriteOperations is enforced by WRITE_OPERATIONS. If a mutating special operation is omitted from WRITE_OPERATIONS, it can still be invoked while write operations are disabled.

Rule: Add all mutating special operations (clone/move/upload/orchestrated copy) to WRITE_OPERATIONS.

Quality gates

• • Resource description.ts — operation added to dropdown, new fields defined
• • Resource execute.ts — operation implemented, case added to switch
• • Picklist/reference label descriptions — operation added (if applicable)
• • SPECIAL_AI_OPERATIONS — operation registered for the resource
• • AI_OPERATION_ORDER — operation in logical position
• • SUPPORTED_TOOL_OPERATIONS — operation listed
• • WRITE_OPERATIONS — operation listed if operation mutates data
• • opLabels — human-readable label added
• • Schema generator — function exported, returns ZodObject (no refine/transform)
• • Description builder — function exported
• • supplyData() switch — case added with schema + description + imports
• • normaliseOperation() — case added for lowercase → camelCase restoration
• • getNodeParameter override — custom parameter mapping added (if needed)
• • formatToolResponse() — case added for structured output
• • noIdOperations — operation added (if it doesn't require entity ID)
• • tool/execute.ts — parameter mapping added (if needed)
• • Impersonation (move/copy ops): If the operation creates records and the entity supports impersonation, follow .docs/autotask/impersonation.md — add optional impersonationResourceId to the UI, schema, and description builder. Use getOptionalImpersonationResourceId in the executor. Only pass to write calls. Always pair with proceedWithoutImpersonationIfDenied (boolean, default true) in the same display context. Both must appear in the UI description, execute handler, helper interface/options, AI schema, and be passed as the 7th argument to every autotaskApiRequest write call.
• • For multi-step orchestrator operations, add retry/throttling/partial-failure handling and audit notes
• • README.md and CHANGELOG.md — updated
• • corepack pnpm build — compiles clean
• • corepack pnpm lint — no new errors in changed files

Reference implementations

• •slaHealthCheck (ticket resource): Custom operation with dual identifier input (ticket ID or ticket number), custom SLA computation logic, label enrichment
• •searchByDomain (company resource): Custom operation with domain normalisation, contact email fallback search, structured multi-source output
• •whoAmI (resource): Simple operation that resolves the current authenticated user, reuses read field schema

Existing files quick-reference