add_optional_process
Initiate optional case actions configured as processes and retrieve the next assignment details for stage-specific or case-wide workflows.
Instructions
Add stage or case-wide optional process and return details of the next assignment in the process. The API is invoked when a user tries to initiate an optional action listed under case actions which are configured and designed as a process under case wide actions or stage-only actions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| caseID | Yes | Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces."MYORG-SERVICES-WORK S-293001". a complete case identifier including spaces and special characters. | |
| processID | Yes | Process ID - Name of the process which is the ID of a flow rule. Example: "UpdateContactDetails". ProcessID can be retrieved with a lookup for ID attribute under availableProcesses node of a DX API response. | |
| viewType | No | UI resources to return. "none" returns no uiResources, data.caseInfo.content contains the fields of the pyDetails view (default), "form" returns the form UI metadata (read-only review mode, without page-specific metadata) in the uiResources object, "page" returns the full page (read-only review mode) UI metadata in the uiResources object. | none |
| sessionCredentials | No | Optional session-specific credentials. If not provided, uses environment variables. Supports two authentication modes: (1) OAuth mode - provide baseUrl, clientId, and clientSecret, or (2) Token mode - provide baseUrl and accessToken. |
Implementation Reference
- The main handler function that executes the tool's core logic: validates inputs, initializes session, and calls the Pega API to add an optional process to a case.
async execute(params) { const { caseID, processID, viewType } = params; let sessionInfo = null; try { // Initialize session configuration if provided sessionInfo = this.initializeSessionConfig(params); // Validate required parameters using base class const requiredValidation = this.validateRequiredParams(params, ['caseID', 'processID']); if (requiredValidation) { return requiredValidation; } // Validate enum parameters using base class const enumValidation = this.validateEnumParams(params, { viewType: ['none', 'form', 'page'] }); if (enumValidation) { return enumValidation; } // Execute with standardized error handling return await this.executeWithErrorHandling( `Add Optional Process: ${processID} to case ${caseID}`, async () => await this.pegaClient.addOptionalProcess(caseID.trim(), processID.trim(), { viewType }), { processID, viewType, sessionInfo } ); } catch (error) { return { content: [{ type: 'text', text: `## Error: Add Optional Process\n\n**Unexpected Error**: ${error.message}\n\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*` }] }; } } - Defines the tool schema for MCP, including name, description, input parameters (caseID, processID, optional viewType and sessionCredentials), and validation rules.
static getDefinition() { return { name: 'add_optional_process', description: 'Add stage or case-wide optional process and return details of the next assignment in the process. The API is invoked when a user tries to initiate an optional action listed under case actions which are configured and designed as a process under case wide actions or stage-only actions.', inputSchema: { type: 'object', properties: { caseID: { type: 'string', description: 'Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces."MYORG-SERVICES-WORK S-293001". a complete case identifier including spaces and special characters.' }, processID: { type: 'string', description: 'Process ID - Name of the process which is the ID of a flow rule. Example: "UpdateContactDetails". ProcessID can be retrieved with a lookup for ID attribute under availableProcesses node of a DX API response.' }, viewType: { type: 'string', enum: ['none', 'form', 'page'], description: 'UI resources to return. "none" returns no uiResources, data.caseInfo.content contains the fields of the pyDetails view (default), "form" returns the form UI metadata (read-only review mode, without page-specific metadata) in the uiResources object, "page" returns the full page (read-only review mode) UI metadata in the uiResources object.', default: 'none' }, sessionCredentials: getSessionCredentialsSchema() }, required: ['caseID', 'processID'] } }; } - src/tools/cases/add-optional-process.js:8-10 (registration)Static method returning the tool category 'cases', used by the dynamic tool loader for categorization and discovery.
static getCategory() { return 'cases'; } - src/api/pega-client.js:359-364 (helper)Helper method in PegaClient that routes the addOptionalProcess call to the appropriate API version client (V1/V2), enforcing feature availability checks.
async addOptionalProcess(caseID, processID, options = {}) { if (!this.isFeatureAvailable('stageNavigation')) { this.throwUnsupportedFeatureError('stageNavigation', 'addOptionalProcess'); } return this.client.addOptionalProcess(caseID, processID, options); } - src/registry/tool-loader.js:278-279 (helper)Dynamic tool loader instance that discovers and registers all tools, including add_optional_process, by scanning directories and using getDefinition().
export const toolLoader = new ToolLoader();