get_attachment_categories
Retrieve attachment categories for a specific Pega case, filtered by type (File or URL). Includes metadata and user permissions for each category, enabling users to manage attachments effectively based on case type.
Instructions
Retrieve the list of attachment categories available for a specific Pega case, filtered by attachment type (File or URL). Returns category metadata including user permissions (view, create, edit, delete) for each attachment category associated with the case type. The API uses the class name from the caseID to get attachment categories and filters them based on the type parameter. Only attachment categories configured in the Attachment Category rule are returned. Useful for understanding what attachment categories are available and what operations the current user can perform on each category.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| caseID | Yes | Full case handle (case ID) to retrieve attachment categories for. Must be the complete case identifier including spaces and special characters. Example: "OSIEO3-DOCSAPP-WORK T-561003". The API uses the class name from this caseID to determine which attachment categories are associated with the case type. | |
| type | No | Filter for the attachment type to retrieve categories for. Case insensitive. "File" or "file" returns all attachment categories of type File. "URL" or "url" returns attachment categories of type URL. Default value is "File". The API returns attachment categories of either type File or type URL during a particular API call, not both simultaneously. | File |
Implementation Reference
- Main handler function that destructures parameters, validates inputs, normalizes the attachment type, calls the Pega API via pegaClient.getCaseAttachmentCategories, and handles errors with standardized error handling.async execute(params) { const { caseID, type = 'File' } = params; let sessionInfo = null; try { sessionInfo = this.initializeSessionConfig(params); // Basic parameter validation using base class const requiredValidation = this.validateRequiredParams(params, ['caseID']); if (requiredValidation) { return requiredValidation; } // Additional comprehensive parameter validation for complex logic const validationResult = this.validateParameters(caseID, type); if (!validationResult.valid) { return { error: validationResult.error }; } // Normalize type parameter to handle case insensitivity const normalizedType = type.toLowerCase() === 'file' ? 'File' : 'URL'; // Execute with standardized error handling return await this.executeWithErrorHandling( `Attachment Categories: ${caseID} (${normalizedType})`, async () => await this.pegaClient.getCaseAttachmentCategories(caseID, { type: normalizedType }), { caseID, type: normalizedType, sessionInfo } ); } catch (error) { return { content: [{ type: 'text', text: `## Error: Attachment Categories\n\n**Unexpected Error**: ${error.message}\n\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*` }] }; } }
- Tool definition including name, description, and input schema specifying required caseID and optional type (File/URL) parameters.static getDefinition() { return { name: 'get_attachment_categories', description: 'Retrieve the list of attachment categories available for a specific Pega case, filtered by attachment type (File or URL). Returns category metadata including user permissions (view, create, edit, delete) for each attachment category associated with the case type. The API uses the class name from the caseID to get attachment categories and filters them based on the type parameter. Only attachment categories configured in the Attachment Category rule are returned. Useful for understanding what attachment categories are available and what operations the current user can perform on each category.', inputSchema: { type: 'object', properties: { caseID: { type: 'string', description: 'Full case handle (case ID) to retrieve attachment categories for. Must be the complete case identifier including spaces and special characters. Example: "OSIEO3-DOCSAPP-WORK T-561003". The API uses the class name from this caseID to determine which attachment categories are associated with the case type.' }, type: { type: 'string', enum: ['File', 'URL', 'file', 'url'], description: 'Filter for the attachment type to retrieve categories for. Case insensitive. "File" or "file" returns all attachment categories of type File. "URL" or "url" returns attachment categories of type URL. Default value is "File". The API returns attachment categories of either type File or type URL during a particular API call, not both simultaneously.', default: 'File' }, sessionCredentials: getSessionCredentialsSchema() }, required: ['caseID'] } }; }
- Helper method for validating caseID and type parameters, providing specific error messages for invalid inputs.validateParameters(caseID, type) { // Validate caseID if (!caseID || typeof caseID !== 'string' || caseID.trim() === '') { return { valid: false, error: 'Invalid caseID parameter. Case ID must be a non-empty string containing the full case handle (e.g., "OSIEO3-DOCSAPP-WORK T-561003").' }; } // Validate type parameter (optional) if (type !== undefined) { if (typeof type !== 'string') { return { valid: false, error: 'Invalid type parameter. Must be a string value ("File" or "URL").' }; } const normalizedType = type.toLowerCase(); if (normalizedType !== 'file' && normalizedType !== 'url') { return { valid: false, error: 'Invalid type parameter. Only "File" and "URL" are supported (case insensitive). Provided value: "' + type + '".' }; } } return { valid: true }; }
- Custom formatter for successful responses, providing detailed markdown output with category lists, permissions matrix, summaries, and related tool suggestions.formatSuccessResponse(operation, data, options = {}) { const { caseID, type, sessionInfo } = options; const { attachment_categories = [] } = data; let response = `## ${operation}\n\n`; response += `*Operation completed at: ${new Date().toISOString()}*\n\n`; if (sessionInfo) { response += `### Session Information\n`; response += `- **Session ID**: ${sessionInfo.sessionId}\n`; response += `- **Authentication Mode**: ${sessionInfo.authMode.toUpperCase()}\n`; response += `- **Configuration Source**: ${sessionInfo.configSource}\n\n`; } if (attachment_categories.length === 0) { response += `No ${type.toLowerCase()} attachment categories found for this case.\n\n`; response += `### ℹ️ Information\n`; response += `- Only attachment categories configured in the Attachment Category rule are returned\n`; response += `- The API uses the class name from the caseID to determine available categories\n`; response += `- Try with the other type filter: ${type === 'File' ? 'URL' : 'File'}\n`; response += `- Use \`get_case_attachments\` tool to see actual attachments for this case\n`; } else { response += `Found **${attachment_categories.length} ${type.toLowerCase()} attachment ${attachment_categories.length === 1 ? 'category' : 'categories'}** available for this case.\n\n`; response += `### 📋 Category Details and Permissions\n\n`; // Display each category with comprehensive permission details attachment_categories.forEach((category, index) => { response += `#### ${index + 1}. ${category.name}\n`; // Basic category information response += `- **Category ID**: \`${category.ID}\`\n`; response += `- **Category Name**: ${category.name}\n`; response += `- **Type**: ${type}\n`; // Permission matrix response += `- **Permissions**:\n`; response += ` - **View**: ${category.canView ? '✅ Allowed' : '❌ Denied'}\n`; response += ` - **Create**: ${category.canCreate ? '✅ Allowed' : '❌ Denied'}\n`; response += ` - **Edit**: ${category.canEdit ? '✅ Allowed' : '❌ Denied'}\n`; response += ` - **Delete Own**: ${category.canDeleteOwn ? '✅ Allowed' : '❌ Denied'}\n`; response += ` - **Delete All**: ${category.canDeleteAll ? '✅ Allowed' : '❌ Denied'}\n`; // Available operations summary const allowedOperations = []; if (category.canView) allowedOperations.push('View'); if (category.canCreate) allowedOperations.push('Create'); if (category.canEdit) allowedOperations.push('Edit'); if (category.canDeleteOwn) allowedOperations.push('Delete Own'); if (category.canDeleteAll) allowedOperations.push('Delete All'); if (allowedOperations.length > 0) { response += `- **Available Operations**: ${allowedOperations.join(', ')}\n`; } else { response += `- **Available Operations**: ❌ No operations allowed\n`; } response += `\n`; }); // Permission summary response += `### 📊 Permission Summary\n`; const viewCount = attachment_categories.filter(cat => cat.canView).length; const createCount = attachment_categories.filter(cat => cat.canCreate).length; const editCount = attachment_categories.filter(cat => cat.canEdit).length; const deleteOwnCount = attachment_categories.filter(cat => cat.canDeleteOwn).length; const deleteAllCount = attachment_categories.filter(cat => cat.canDeleteAll).length; response += `- **View Permission**: ${viewCount}/${attachment_categories.length} categories\n`; response += `- **Create Permission**: ${createCount}/${attachment_categories.length} categories\n`; response += `- **Edit Permission**: ${editCount}/${attachment_categories.length} categories\n`; response += `- **Delete Own Permission**: ${deleteOwnCount}/${attachment_categories.length} categories\n`; response += `- **Delete All Permission**: ${deleteAllCount}/${attachment_categories.length} categories\n`; } // Configuration and usage information response += `\n### ⚙️ Configuration Details\n`; response += `- **Category Source**: Attachment Category rule configuration for case type\n`; response += `- **Filter Applied**: ${type} attachment categories only\n`; response += `- **Case Class**: Determined from case ID "${caseID}"\n`; response += `- **API Behavior**: Returns either File or URL categories per request, not both\n`; // Display related operations response += `\n### 🔗 Related Operations\n`; response += `- Use \`get_case_attachments\` to view actual attachments for this case\n`; response += `- Use \`add_case_attachments\` to add attachments using these categories\n`; response += `- Use \`upload_attachment\` to prepare files before attaching to case\n`; response += `- Use \`get_case\` to view complete case information\n`; if (type === 'File') { response += `- Run again with \`type: "URL"\` to see URL attachment categories\n`; } else { response += `- Run again with \`type: "File"\` to see File attachment categories\n`; } return response; }
- src/tools/attachments/get-attachment-categories.js:8-10 (registration)Static method declaring the tool's category 'attachments', used by the dynamic tool loader for automatic discovery and registration.static getCategory() { return 'attachments'; }