Bitrix24 MCP Server

# User Management Guide This guide explains how to use the new user management tools in the Bitrix24 MCP Server to identify users by name instead of just IDs, making your CRM data more human-readable and meaningful. ## 🎯 Overview The user management tools solve a common problem in CRM systems: seeing cryptic user IDs instead of actual names. These tools allow you to: - **Identify Users**: Get actual names instead of just numeric IDs - **Resolve User References**: Convert user IDs to readable names in bulk - **Enhance CRM Data**: Automatically add user names to contacts, deals, leads, and companies - **Improve Reporting**: Generate more meaningful reports with actual user names ## 👥 Core User Management Tools ### 1. Get Individual User Information Retrieve detailed information about a specific user by their ID. ```bash # Get specific user details Get user information for user ID 123 # Example response includes: # - ID: "123" # - NAME: "John" # - LAST_NAME: "Smith" # - EMAIL: "john.smith@company.com" # - WORK_POSITION: "Sales Manager" # - ACTIVE: "Y" ``` **Use Cases:** - Verify user details before assignments - Get contact information for team members - Check user status and permissions ### 2. Get All Users in System Retrieve a complete list of all users with their names and details. ```bash # Get all users Get all users in the system with their names and details # Get all users including inactive ones Get all users in the system including inactive users ``` **Key Information Provided:** - Full name (first + last) - Email address - Work position/title - Active status - Department information - Contact details ### 3. Resolve Multiple User IDs to Names Convert multiple user IDs to readable names in a single operation. ```bash # Resolve multiple user IDs Resolve user IDs [123, 456, 789, 101] to user names # Example response: # { # "123": "John Smith", # "456": "Maria Garcia", # "789": "Robert Johnson", # "101": "Sarah Wilson" # } ``` **Benefits:** - Efficient bulk resolution - Perfect for processing lists of user IDs - Handles missing or invalid IDs gracefully ## 📊 Enhanced CRM Data with User Names ### 4. Contacts with User Names Get contacts with all user references resolved to actual names. ```bash # Get contacts with user names resolved Get contacts with user names resolved showing who created, modified, or is assigned to each contact # Filter contacts with user names Get contacts with user names resolved with filter {"ASSIGNED_BY_ID": "123"} # Limit results with user names Get contacts with user names resolved limited to 10 results ``` **Enhanced Fields You'll See:** - `ASSIGNED_BY_ID: "123"` → `ASSIGNED_BY_ID_NAME: "John Smith"` - `CREATED_BY_ID: "456"` → `CREATED_BY_ID_NAME: "Maria Garcia"` - `MODIFY_BY_ID: "789"` → `MODIFY_BY_ID_NAME: "Robert Johnson"` ### 5. Deals with User Names Get deals with complete user information for better deal management. ```bash # Get deals with user names resolved Get deals with user names resolved showing assigned users, creators, and modifiers by name # Order deals by creation date with user names Get deals with user names resolved ordered by DATE_CREATE descending # Filter deals by assigned user with names Get deals with user names resolved with filter {"ASSIGNED_BY_ID": "123"} ``` **Deal Management Benefits:** - Quickly identify deal owners - Track deal history and modifications - Understand team workload distribution ### 6. Leads with User Names Get leads with enhanced user information for better lead management. ```bash # Get leads with user names resolved Get leads with user names resolved with complete user information # Filter leads by status with user names Get leads with user names resolved with filter {"STATUS_ID": "NEW"} # Order leads by priority with user names Get leads with user names resolved ordered by DATE_CREATE descending ``` **Lead Tracking Benefits:** - Clear lead ownership visibility - Better lead assignment tracking - Enhanced lead conversion analysis ### 7. Companies with User Names Get companies with complete user relationship information. ```bash # Get companies with user names resolved Get companies with user names resolved showing all user relationships # Filter companies by assigned user with names Get companies with user names resolved with filter {"ASSIGNED_BY_ID": "456"} # Order companies by size with user names Get companies with user names resolved ordered by TITLE ascending ``` **Company Management Benefits:** - Account ownership clarity - Relationship history tracking - Territory management visibility ## 🔧 Practical Implementation Examples ### Example 1: Daily Team Overview ```bash # Step 1: Get all team members Get all users in the system with their names and details # Step 2: Get today's deals with user names Get deals with user names resolved with filter {">=DATE_CREATE": "2025-01-11"} # Step 3: Check lead assignments Get leads with user names resolved ordered by DATE_CREATE descending ``` ### Example 2: Account Management Review ```bash # Step 1: Get specific account's deals Get deals with user names resolved with filter {"COMPANY_ID": "789"} # Step 2: Get account's contacts Get contacts with user names resolved with filter {"COMPANY_ID": "789"} # Step 3: Check account ownership Get companies with user names resolved with filter {"ID": "789"} ``` ### Example 3: User Performance Analysis ```bash # Step 1: Get user's assigned deals Get deals with user names resolved with filter {"ASSIGNED_BY_ID": "123"} # Step 2: Get user's created contacts Get contacts with user names resolved with filter {"CREATED_BY_ID": "123"} # Step 3: Get user's leads Get leads with user names resolved with filter {"ASSIGNED_BY_ID": "123"} ``` ### Example 4: Team Workload Distribution ```bash # Step 1: Get all users Get all users in the system with their names and details # Step 2: Get deals by user with names Get deals with user names resolved ordered by ASSIGNED_BY_ID # Step 3: Get contacts by user with names Get contacts with user names resolved ordered by ASSIGNED_BY_ID ``` ## 🎯 Common Use Cases ### 1. Reporting and Analytics **Before User Management:** ``` Deal ID: 456 Assigned to: 123 Created by: 789 ``` **After User Management:** ``` Deal ID: 456 Assigned to: 123 (John Smith) Created by: 789 (Maria Garcia) ``` ### 2. Team Management ```bash # Check team assignments Get deals with user names resolved showing current deal assignments # Review team productivity Get contacts with user names resolved showing contact creation by team members # Monitor lead distribution Get leads with user names resolved showing lead assignments across team ``` ### 3. Account Ownership Tracking ```bash # Identify account owners Get companies with user names resolved showing account assignments # Track account interactions Get contacts with user names resolved filtered by company showing who's been in contact # Monitor account development Get deals with user names resolved filtered by company showing deal progression ``` ### 4. Historical Analysis ```bash # Track changes over time Get deals with user names resolved showing who modified deals and when # Analyze team evolution Get contacts with user names resolved showing creation patterns by team members # Review assignment changes Get leads with user names resolved showing assignment history ``` ## 💡 Best Practices ### 1. Start with User Directory Always begin by understanding your user base: ```bash # Get complete user directory Get all users in the system with their names and details ``` ### 2. Use Consistent Naming When working with user IDs, consistently use the enhanced tools: ```bash # Instead of: Get latest deals # Use: Get deals with user names resolved ``` ### 3. Combine with Filtering Use user names for better filtering: ```bash # Find deals for specific user Get deals with user names resolved with filter {"ASSIGNED_BY_ID": "123"} ``` ### 4. Regular User Updates Keep user information current: ```bash # Regularly check user directory Get all users in the system with their names and details ``` ## 🔍 Troubleshooting ### Common Issues 1. **User ID not found**: The system gracefully handles missing users by showing "User [ID]" 2. **Inactive users**: Include inactive users in searches if needed 3. **Permission issues**: Ensure webhook has user access permissions 4. **Rate limiting**: User resolution is optimized but large datasets may take time ### Error Handling The system automatically handles: - Missing user IDs - Inactive users - Permission restrictions - API rate limits ### Performance Tips 1. **Batch operations**: Use bulk resolution for multiple IDs 2. **Filtered queries**: Use filters to reduce data volume 3. **Specific fields**: Request only needed user information 4. **Caching**: User information is cached for efficiency ## 📋 Quick Reference ### Essential Commands ```bash # User directory Get all users in the system with their names and details # Resolve specific users Resolve user IDs [123, 456, 789] to user names # Enhanced CRM data Get contacts with user names resolved Get deals with user names resolved Get leads with user names resolved Get companies with user names resolved ``` ### Key Benefits - **Human-readable data**: Names instead of IDs - **Better team understanding**: Clear ownership visibility - **Improved reporting**: Meaningful analytics - **Enhanced collaboration**: Easy team member identification - **Historical tracking**: Complete audit trail with names This user management system transforms your CRM from a system of numbers into a human-centric platform where you can easily understand who's doing what, when, and why.