create_case_participant
Add a participant to a Pega case with specified role and access permissions. Input case ID, user details, and role ID to assign permissions and integrate into case access control.
Instructions
Create a new participant in a Pega case with specified role and participant information. Adds users to case access control with appropriate permissions and role assignments.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| caseID | Yes | Full case handle (case ID) to add participant to. Example: "ON6E5R-DIYRecipe-Work-RecipeCollection R-1008". Must be a complete case identifier including spaces and special characters. | |
| content | Yes | Participant information object containing user details such as name, email, phone, and other contact information. Structure matches Data-Party schema. | |
| eTag | Yes | Required eTag unique value for optimistic locking from a previous case or participant API call. Prevents concurrent modification conflicts. | |
| pageInstructions | No | Optional list of page-related operations for embedded pages, page lists, or page groups included in the participant creation view. | |
| participantRoleID | Yes | Role ID to assign to the participant. This determines the permissions and access level the participant will have for the case. | |
| viewType | No | Type of view data to return. "form" returns form UI metadata, "none" returns no UI resources (default: "form") | form |
Implementation Reference
- The execute method implements the core logic of the create_case_participant tool, including parameter validation, automatic eTag fetching if not provided, session handling, and delegation to the Pega API via pegaClient.createCaseParticipant.async execute(params) { const { caseID, eTag, content, participantRoleID, viewType, pageInstructions } = params; let sessionInfo = null; try { sessionInfo = this.initializeSessionConfig(params); // Validate required parameters using base class const requiredValidation = this.validateRequiredParams(params, ['caseID', 'content', 'participantRoleID']); if (requiredValidation) { return requiredValidation; } // Validate enum parameters const enumValidation = this.validateEnumParams(params, { viewType: ['form', 'none'] }); if (enumValidation) { return enumValidation; } // Auto-fetch eTag if not provided let finalETag = eTag; let autoFetchedETag = false; if (!finalETag) { try { console.log(`Auto-fetching latest eTag for participant operation on ${caseID}...`); const caseResponse = await this.pegaClient.getCase(caseID.trim()); if (!caseResponse || !caseResponse.success) { const errorMsg = `Failed to auto-fetch eTag: ${caseResponse?.error?.message || 'Unknown error'}`; return { error: errorMsg }; } finalETag = caseResponse.eTag; autoFetchedETag = true; console.log(`Successfully auto-fetched eTag: ${finalETag}`); if (!finalETag) { const errorMsg = 'Auto-fetch succeeded but no eTag was returned from get_case. This may indicate a server issue.'; return { error: errorMsg }; } } catch (error) { const errorMsg = `Failed to auto-fetch eTag: ${error.message}`; return { error: errorMsg }; } } // Validate eTag format (should be a timestamp-like string) if (typeof finalETag !== 'string' || finalETag.trim().length === 0) { return { error: 'Invalid eTag parameter. Must be a non-empty string representing case save date time.' }; } return await this.executeWithErrorHandling( `Create Participant: ${caseID}`, async () => await this.pegaClient.createCaseParticipant(caseID.trim(), { eTag: finalETag, content, participantRoleID, viewType, pageInstructions }), { caseID: caseID.trim(), participantRoleID, sessionInfo } ); } catch (error) { return { content: [{ type: 'text', text: `## Error: Create Participant: ${caseID}\\n\\n**Unexpected Error**: ${error.message}\\n\\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\\n` : ''}*Error occurred at: ${new Date().toISOString()}*` }] }; } }
- The static getDefinition() method provides the MCP tool definition including name, description, and detailed inputSchema with types, descriptions, enums, and required fields.static getDefinition() { return { name: 'create_case_participant', description: 'Create a new participant in a Pega case with specified role and participant information. If no eTag is provided, automatically fetches the latest eTag from the case for seamless operation. Adds users to case access control with appropriate permissions and role assignments.', inputSchema: { type: 'object', properties: { caseID: { type: 'string', description: 'Full case handle (case ID) to add participant to. Example: "ON6E5R-DIYRecipe-Work-RecipeCollection R-1008". Must be a complete case identifier including spaces and special characters.' }, eTag: { type: 'string', description: 'Optional eTag unique value representing the most recent save date time (pxSaveDateTime) of the case. If not provided, the tool will automatically fetch the latest eTag from the case. For manual eTag management, provide the eTag from a previous case operation. Used for optimistic locking to prevent concurrent modification conflicts.' }, content: { type: 'object', description: 'Participant information object containing user details such as name, email, phone, and other contact information. Structure matches Data-Party schema.', properties: { pyFirstName: { type: 'string', description: 'First name of the participant' }, pyLastName: { type: 'string', description: 'Last name of the participant' }, pyEmail1: { type: 'string', description: 'Email address of the participant' }, pyPhoneNumber: { type: 'string', description: 'Phone number of the participant' }, pyWorkPartyUri: { type: 'string', description: 'Unique identifier for the participant' }, pyFullName: { type: 'string', description: 'Full name of the participant' }, pyTitle: { type: 'string', description: 'Title of the participant' } } }, participantRoleID: { type: 'string', description: 'Role ID to assign to the participant. This determines the permissions and access level the participant will have for the case.' }, viewType: { type: 'string', enum: ['form', 'none'], description: 'Type of view data to return. "form" returns form UI metadata, "none" returns no UI resources (default: "form")', default: 'form' }, pageInstructions: { type: 'array', items: { type: 'object', properties: { instruction: { type: 'string', enum: ['UPDATE', 'REPLACE', 'DELETE', 'APPEND', 'INSERT', 'MOVE'], description: 'The type of page instruction: 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: 'The 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.' }, sessionCredentials: getSessionCredentialsSchema() }, required: ['caseID', 'content', 'participantRoleID'] } }; }
- src/api/pega-client.js:836-840 (helper)PegaClient wrapper method invoked by the tool handler to perform the actual createCaseParticipant API call, with feature availability check.async createCaseParticipant(caseID, options = {}) { if (!this.isFeatureAvailable('participants')) { this.throwUnsupportedFeatureError('participants', 'createCaseParticipant'); } return this.client.createCaseParticipant(caseID, options);
- src/registry/tool-loader.js:124-133 (registration)Dynamic registration logic in tool loader that instantiates the tool class and registers it in the loadedTools map by its name from getDefinition().const toolName = ToolClass.getDefinition().name; this.loadedTools.set(toolName, { instance: toolInstance, class: ToolClass, category: category, filename: filename }); return toolInstance;