Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/cases/bulk-cases-patch.js:93-191 (handler)

  The execute method of BulkCasesPatchTool class that implements the core logic for the bulk_cases_patch tool. It validates parameters, handles sessions, and calls pegaClient.patchCasesBulk to perform the bulk PATCH operation on cases.

  async execute(params) {
    const { actionID, cases, runningMode, content, pageInstructions, attachments } = params;
    let sessionInfo = null;
  
    try {
      // Initialize session configuration if provided
      sessionInfo = this.initializeSessionConfig(params);
  
    // 1. Basic parameter validation using base class
    const requiredValidation = this.validateRequiredParams(params, ['actionID', 'cases']);
    if (requiredValidation) {
      return requiredValidation;
    }
  
    // 2. Validate actionID is not empty
    if (!actionID || typeof actionID !== 'string' || actionID.trim() === '') {
      return {
        error: 'Invalid actionID parameter. ActionID must be a non-empty string containing the case action ID.'
      };
    }
  
    // 3. Validate cases array (exact specification from WIP.md)
    if (!Array.isArray(cases)) {
      return {
        error: 'Cases missing from the request body or empty. Cases must be provided as a non-empty array.'
      };
    }
  
    if (cases.length === 0) {
      return {
        error: 'Cases missing from the request body or empty. At least one case must be provided for bulk processing.'
      };
    }
  
    // Validate each case object has required ID property
    for (let i = 0; i < cases.length; i++) {
      const caseObj = cases[i];
      if (!caseObj || typeof caseObj !== 'object') {
        return {
          error: `Invalid case object at index ${i}. Each case must be an object with an ID property containing the full case handle.`
        };
      }
      if (!caseObj.ID || typeof caseObj.ID !== 'string' || caseObj.ID.trim() === '') {
        return {
          error: `Cases missing from the request body or empty. Case at index ${i} does not contain the required ID property.`
        };
      }
    }
  
    // 4. Validate enum parameters - runningMode if provided
    if (runningMode !== undefined) {
      const enumValidation = this.validateEnumParams(params, {
        runningMode: ['async']
      });
      if (enumValidation) {
        return enumValidation;
      }
    }
  
    // 5. Validate optional complex parameters
    if (content !== undefined && (typeof content !== 'object' || Array.isArray(content))) {
      return {
        error: 'Invalid content parameter. an object containing scalar properties and embedded page properties.'
      };
    }
  
    if (pageInstructions !== undefined && !Array.isArray(pageInstructions)) {
      return {
        error: 'Invalid pageInstructions parameter. an array of page-related operations.'
      };
    }
  
    if (attachments !== undefined && !Array.isArray(attachments)) {
      return {
        error: 'Invalid attachments parameter. an array of attachment objects.'
      };
    }
  
      // 6. Execute with standardized error handling
      return await this.executeWithErrorHandling(
        `Bulk Cases PATCH: ${actionID} on ${cases.length} cases`,
        async () => await this.pegaClient.patchCasesBulk(actionID.trim(), {
          cases,
          runningMode,
          content,
          pageInstructions,
          attachments
        }),
        { actionID, cases, runningMode, content, pageInstructions, attachments, sessionInfo }
      );
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `## Error: Bulk Cases PATCH\n\n**Unexpected Error**: ${error.message}\n\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
        }]
      };
    }
  }

• src/tools/cases/bulk-cases-patch.js:16-87 (schema)

  The input schema definition for the bulk_cases_patch tool, including validation rules for parameters like actionID, cases array, runningMode, content, pageInstructions, and attachments.

  static getDefinition() {
    return {
      name: 'bulk_cases_patch',
      description: 'Perform case action on multiple cases simultaneously using PATCH /api/application/v2/cases endpoint. In Infinity, actions are performed synchronously. In Launchpad, actions are performed asynchronously in the background. Only supports case-wide actions that update cases directly - assignment-level actions like Transfer and Adjust Assignment SLA are not supported.',
      inputSchema: {
        type: 'object',
        properties: {
          actionID: {
            type: 'string',
            description: 'Action ID for case/stage action (Example: "pyUpdateCaseDetails", "pyApproval"). CRITICAL: Action IDs are CASE-SENSITIVE and have no spaces even if display names do ("Edit details" → "pyUpdateCaseDetails"). Use get_case to find correct ID from availableActions array - use "ID" field not "name" field. This action must be a case-wide action that updates cases directly.'
          },
          cases: {
            type: 'array',
            description: 'Array of case objects to perform the action on. Each case object must contain an ID property with the full case handle. Cannot be empty.',
            items: {
              type: 'object',
              properties: {
                ID: {
                  type: 'string',
                  description: 'Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces.'
                }
              },
              required: ['ID']
            },
            minItems: 1
          },
          runningMode: {
            type: 'string',
            enum: ['async'],
            description: 'Execution mode for Launchpad only. "async" schedules the action to be performed in the background rather than immediately. Not applicable for Infinity which always executes synchronously. Currently, only async runningMode is implemented in Launchpad.'
          },
          content: {
            type: 'object',
            description: 'A map of scalar properties and embedded page properties to be set during action execution. Same format as single case action content.'
          },
          pageInstructions: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                instruction: {
                  type: 'string',
                  enum: ['UPDATE', 'REPLACE', 'DELETE', 'APPEND', 'INSERT', 'MOVE'],
                  description: 'Page instruction type. UPDATE (add fields to page), REPLACE (replace entire page), DELETE (remove page), APPEND (add item to page list), INSERT (insert item in page list), MOVE (reorder page list items)'
                },
                target: {
                  type: 'string',
                  description: 'Target embedded page name'
                },
                content: {
                  type: 'object',
                  description: 'Content to set on the embedded page (required for UPDATE and REPLACE)'
                }
              },
              required: ['instruction', 'target'],
              description: 'Page operation for embedded pages. Use REPLACE instruction to set embedded page references with full object including pzInsKey. Example: {"instruction": "REPLACE", "target": "PageName", "content": {"Property": "value", "pyID": "ID-123", "pzInsKey": "CLASS-NAME ID-123"}}'
            },
            description: 'Optional list of page-related operations for embedded pages, page lists, or page groups. Required for setting embedded page references.'
          },
          attachments: {
            type: 'array',
            description: 'A list of attachments to be added to specific attachment fields during action execution.',
            items: {
              type: 'object'
            }
          },
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: ['actionID', 'cases']
      }
    };
  }

• src/tools/cases/bulk-cases-patch.js:18-18 (registration)

  Tool name registration within the getDefinition method.

  name: 'bulk_cases_patch',