get_participant_roles

Instructions

Implementation Reference

• src/tools/participants/get-participant-roles.js:36-63 (handler)

  The execute() method of GetParticipantRolesTool - the main handler that validates inputs and calls pegaClient.getParticipantRoles(caseID.trim())

  async execute(params) {
    const { caseID } = params;
    let sessionInfo = null;
  
    try {
      sessionInfo = this.initializeSessionConfig(params);
  
      // Validate required parameters using base class
      const requiredValidation = this.validateRequiredParams(params, ['caseID']);
      if (requiredValidation) {
        return requiredValidation;
      }
  
      // Execute with standardized error handling
      return await this.executeWithErrorHandling(
        `Participant Roles: ${caseID}`,
        async () => await this.pegaClient.getParticipantRoles(caseID.trim()),
        { caseID: caseID.trim(), sessionInfo }
      );
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `## Error: Participant Roles: ${caseID}\n\n**Unexpected Error**: ${error.message}\n\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
        }]
      };
    }
  }

• src/tools/participants/get-participant-roles.js:15-31 (schema)

  Tool definition and inputSchema - defines the 'get_participant_roles' tool name, description, and input schema requiring caseID (string) with optional sessionCredentials

  static getDefinition() {
    return {
      name: 'get_participant_roles',
      description: 'Retrieve list of participant roles for a specific Pega case. Returns available roles that can be assigned to case participants for access control and permission management.',
      inputSchema: {
        type: 'object',
        properties: {
          caseID: {
            type: 'string',
            description: 'Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces."ON6E5R-DIYRecipe-Work-RecipeCollection R-1008". a complete case identifier including spaces and special characters.'
          },
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: ['caseID']
      }
    };
  }

• src/registry/tool-loader.js:37-103 (registration)

  The ToolLoader.loadToolFile() method that dynamically discovers and registers tools including GetParticipantRolesTool by scanning the participants directory and calling getDefinition().name

  }
  
  /**
   * Scan for tool categories (subdirectories in tools/)
   * @returns {Promise<Array>} Array of category names
   */
  async scanCategories() {
    try {
      const entries = await fs.readdir(this.toolsPath, { withFileTypes: true });
      const categories = [];
      
      for (const entry of entries) {
        if (entry.isDirectory()) {
          categories.push(entry.name);
        }
      }
      
      return categories.sort();
    } catch (error) {
      if (error.code === 'ENOENT') {
        console.warn(`Tools directory not found: ${this.toolsPath}`);
        return [];
      }
      throw error;
    }
  }
  
  /**
   * Load all tools from a specific category directory
   * @param {string} category - Category name
   * @returns {Promise<Array>} Array of tool class instances
   */
  async loadCategoryTools(category) {
    const categoryPath = resolve(this.toolsPath, category);
    const tools = [];
    
    try {
      const files = await fs.readdir(categoryPath);
      const jsFiles = files.filter(file => file.endsWith('.js'));
      
      for (const file of jsFiles) {
        try {
          const tool = await this.loadToolFile(categoryPath, file, category);
          if (tool) {
            tools.push(tool);
          }
        } catch (error) {
          console.warn(`Failed to load tool ${file} in category ${category}:`, error.message);
          // Continue loading other tools even if one fails
        }
      }
      
      return tools.sort((a, b) => a.constructor.name.localeCompare(b.constructor.name));
    } catch (error) {
      console.warn(`Failed to read category directory ${category}:`, error.message);
      return [];
    }
  }
  
  /**
   * Load a single tool file
   * @param {string} categoryPath - Path to category directory
   * @param {string} filename - Tool filename
   * @param {string} category - Category name
   * @returns {Promise<Object|null>} Tool instance or null if invalid
   */
  async loadToolFile(categoryPath, filename, category) {

• src/api/pega-client.js:789-793 (helper)

  The PegaClient.getParticipantRoles() method - delegates to the underlying API client, with a feature availability check for 'participants'

  async getParticipantRoles(caseID) {
    if (!this.isFeatureAvailable('participants')) {
      this.throwUnsupportedFeatureError('participants', 'getParticipantRoles');
    }
    return this.client.getParticipantRoles(caseID);

• src/utils/tool-schema.js:10-46 (helper)

  The getSessionCredentialsSchema() utility used by the tool's input schema to define optional session credential parameters

  export function getSessionCredentialsSchema() {
    return {
      type: 'object',
      description: '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.',
      properties: {
        sessionId: {
          type: 'string',
          description: 'Optional session ID. If not provided, a new session will be created.'
        },
        baseUrl: {
          type: 'string',
          description: 'Pega base URL (required if providing credentials)'
        },
        apiVersion: {
          type: 'string',
          description: 'API version (optional, defaults to v2)',
          default: 'v2'
        },
        clientId: {
          type: 'string',
          description: 'OAuth2 client ID (required for OAuth mode)'
        },
        clientSecret: {
          type: 'string',
          description: 'OAuth2 client secret (required for OAuth mode)'
        },
        accessToken: {
          type: 'string',
          description: 'Direct access token (required for token mode)'
        },
        tokenExpiry: {
          type: 'number',
          description: 'Token expiry in seconds from now (optional for token mode)'
        }
      }
    };
  }