Skip to main content

InstanceService.RemoveInstanceUser

Reference​

void RemoveInstanceUser(Guid instanceId, Guid userId)

Use RemoveInstanceUser to revoke a user's access to a specific Protrak instance. This API is commonly used for user deactivation workflows, access management, and security compliance scenarios.

Parameters​

  • instanceId: The unique identifier of the instance from which user access should be revoked.
  • userId: The unique identifier of the user whose access should be removed from the instance.

Returns​

void: This method does not return a value. Success is indicated by the absence of exceptions.

Error Handling & Caveats​

  • If the instance does not exist, an ArgumentException or NotFoundException is thrown.
  • If the user does not exist, an ArgumentException or NotFoundException is thrown.
  • If the current user lacks permission to manage instance access, an AccessDeniedException is thrown.
  • If the user does not have access to the instance, the operation completes successfully without error.
  • Removing access does not affect other sources of access (role-based, organizational hierarchy, etc.).
  • The user may still have access to the instance through other means (group membership, inherited permissions).
  • Access revocation is applied immediately but may take time to propagate across distributed systems.
  • This operation only removes instance-level access; it does not affect the user's roles or other permissions.

Usage​

try {
    // Remove user access from a specific instance
    InstanceService.RemoveInstanceUser(instanceId, userId);
    Console.WriteLine($"User {userId} access removed from instance {instanceId}");
} catch (AccessDeniedException ex) {
    Console.WriteLine("You don't have permission to manage access for this instance.");
} catch (ArgumentException ex) {
    Console.WriteLine($"Invalid parameter: {ex.Message}");
}

Example: User Deactivation Workflow (Common Pattern)​

try {
    var companyId = GetCompanyInstanceId();
    var userEmail = "departing.employee@company.com";
    
    // Find user by email
    var user = UserService.GetUserByEmail(userEmail);
    
    if (user != null) {
        // Remove user access from company instance
        InstanceService.RemoveInstanceUser(companyId, user.Id);
        Console.WriteLine($"Company access removed for {user.UserName}");
    } else {
        Console.WriteLine($"User with email {userEmail} not found");
    }
} catch (Exception ex) {
    Console.WriteLine($"Error removing user access: {ex.Message}");
}

Example: Post-Disconnect Trigger Pattern​

try {
    var attorneyFirmId = GetDisconnectedFirmId();
    var disconnectedUserId = GetDisconnectedUserId();
    
    // Remove attorney user when disconnected from firm
    var user = UserService.GetUser(disconnectedUserId);
    
    if (user != null) {
        InstanceService.RemoveInstanceUser(attorneyFirmId, user.Id);
        Console.WriteLine($"Attorney {user.UserName} access removed from firm due to disconnection");
    }
} catch (Exception ex) {
    Console.WriteLine($"Error in post-disconnect cleanup: {ex.Message}");
}

Example: Bulk Access Removal for Security​

try {
    var sensitiveProjectId = Guid.Parse("550e8400-e29b-41d4-a716-446655440000");
    var contractorUsers = GetUsersByRole("Contractor");
    
    Console.WriteLine($"Removing access for {contractorUsers.Count} contractors");
    
    foreach (var contractor in contractorUsers) {
        try {
            InstanceService.RemoveInstanceUser(sensitiveProjectId, contractor.UserId);
            Console.WriteLine($"Contractor access removed: {contractor.UserName}");
        } catch (AccessDeniedException ex) {
            Console.WriteLine($"Insufficient permissions to remove access for {contractor.UserName}");
        } catch (Exception ex) {
            Console.WriteLine($"Error removing access for {contractor.UserName}: {ex.Message}");
        }
    }
    
    Console.WriteLine("Security access cleanup completed");
} catch (Exception ex) {
    Console.WriteLine($"Error during security cleanup: {ex.Message}");
}

Example: Conditional Access Removal with Validation​

try {
    // Check if user currently has access before removing
    var instanceUsers = InstanceService.GetInstanceUsers(instanceId, 0, int.MaxValue);
    var userHasAccess = instanceUsers?.Items?.Any(iu => iu.User.Id == userToRemove) == true;
    
    if (userHasAccess) {
        InstanceService.RemoveInstanceUser(instanceId, userToRemove);
        Console.WriteLine($"Access removed for user {userToRemove}");
        
        // Log the removal for audit purposes
        LogAccessRemoval(instanceId, userToRemove, "Access revoked by administrator");
    } else {
        Console.WriteLine($"User {userToRemove} does not have direct access to instance {instanceId}");
    }
} catch (Exception ex) {
    Console.WriteLine($"Error validating and removing user access: {ex.Message}");
}

Troubleshooting​

  • If AccessDeniedException occurs, verify that the current user has "Manage Access" or "Admin" permissions for the instance.
  • If the user still has access after removal, check for other sources of access such as role assignments or organizational permissions.
  • If removal seems to have no effect, verify that the user's access was granted directly to the instance rather than inherited.
  • When using email-based user lookup, verify the email address is correct and the user exists in the system.
  • If working with attorney or external user management, coordinate with the related firm/organization instances.
  • For post-disconnect trigger scenarios, ensure the operation doesn't interfere with other automated processes.
  • When removing access in bulk operations, handle individual failures gracefully to avoid stopping the entire process.
  • Always validate that the user actually has access before attempting removal to avoid unnecessary operations.