InstanceService.GetInstanceUsers

Reference

PagedData<InstanceUser> GetInstanceUsers(Guid instanceId, int skip = 0, int take = 100, string userNameKeyword = "", bool includeAdmin = false)

Use GetInstanceUsers to retrieve users who have access to or are associated with a specific Protrak instance. This API is commonly used to get users by their roles for notification purposes, access control, or user management scenarios.

Parameters

• instanceId: The unique identifier of the instance for which to retrieve associated users.
• skip: (Optional) Number of records to skip for pagination. Default is 0.
• take: (Optional) Number of records to retrieve. Default is 100. Use int.MaxValue to get all users.
• userNameKeyword: (Optional) Keyword to filter users by name. Default is empty string (no filtering).
• includeAdmin: (Optional) When true, includes admin users in the results. Default is false.

Returns

PagedData<InstanceUser>:

• Collection of InstanceUser objects containing user information and their relationship to the instance.
• Each InstanceUser contains a User object with roles, contact information, and access details.
• Includes pagination metadata (TotalCount, Skip, Take).
• Returns empty collection if no users are associated with the instance.

Error Handling & Caveats

• If the instance does not exist or the user lacks permission to view it, an AccessDeniedException is thrown.
• If the instanceId is empty or invalid, an ArgumentException is thrown.
• The API enforces access control based on the current user's permissions.
• Only users that the current user has permission to view are returned in the results.
• User permissions are calculated based on instance-level access rights and role assignments.
• Results may vary based on the current user's access level and organizational context.
• Always check for null or empty Items collection before iterating.
• Use includeAdmin = true when you need to include administrative users in the results.
• The userNameKeyword parameter performs case-insensitive matching against user display names.

Usage

try {
    // Get all users associated with an instance (typically for notifications)
    var instanceUsers = InstanceService.GetInstanceUsers(instanceId);
    
    if (instanceUsers?.Items != null && instanceUsers.Items.Any()) {
        Console.WriteLine($"Found {instanceUsers.TotalCount} users associated with this instance");
        foreach (var instanceUser in instanceUsers.Items) {
            var user = instanceUser.User;
            Console.WriteLine($"User: {user.FirstName} {user.LastName} ({user.Username})");
            if (user.Roles?.Any() == true) {
                Console.WriteLine($"  Roles: {string.Join(", ", user.Roles)}");
            }
        }
    }
} catch (AccessDeniedException ex) {
    // Handle permission errors
} catch (Exception ex) {
    // Handle other errors
    Console.WriteLine($"Error retrieving instance users: {ex.Message}");
}

Example: Getting Users by Role for Notifications

public List<UserValue> GetInstanceUsersByRole(Guid instanceId, string[] roles)
{
    var recipients = new List<UserValue>();
    
    try {
        var instanceUsers = InstanceService.GetInstanceUsers(instanceId, 0, 50);
        
        var userList = (from instanceUser in instanceUsers.Items
                       from role in instanceUser.User.Roles
                       where roles.Contains(role)
                       select instanceUser.User).ToList();

        foreach (var user in userList)
        {
            var isUserExists = recipients.Any(r => r.UserId == user.Id);
            if (!isUserExists)
            {
                recipients.Add(new UserValue
                {
                    UserId = user.Id,
                    DisplayName = user.FirstName + " " + user.LastName,
                    EmailAddress = user.EmailAddress
                });
            }
        }
    } catch (Exception ex) {
        Console.WriteLine($"Error retrieving users by role: {ex.Message}");
    }
    
    return recipients;
}

// Usage example
var roles = new string[] { "ProjectManager", "TeamLead" };
var managerUsers = GetInstanceUsersByRole(projectId, roles);
Console.WriteLine($"Found {managerUsers.Count} managers for notifications");

Example: Getting Users with Name Filtering

try {
    // Get users whose names contain "John" (case-insensitive)
    var instanceUsers = InstanceService.GetInstanceUsers(instanceId, 0, 50, "John");
    
    if (instanceUsers?.Items != null && instanceUsers.Items.Any()) {
        Console.WriteLine($"Found {instanceUsers.TotalCount} users matching 'John'");
        foreach (var instanceUser in instanceUsers.Items) {
            var user = instanceUser.User;
            Console.WriteLine($"- {user.FirstName} {user.LastName} ({user.Username})");
        }
    } else {
        Console.WriteLine("No users found matching the search criteria");
    }
} catch (Exception ex) {
    Console.WriteLine($"Error filtering users by name: {ex.Message}");
}

Troubleshooting

• If no users are returned, verify that users have been granted access to the instance and that access control is properly configured.
• If AccessDeniedException occurs, ensure the current user has permission to view user information for the specified instance.
• Always check for null or empty Items collection before iterating: instanceUsers?.Items != null && instanceUsers.Items.Any().
• For performance with large user sets, consider using appropriate skip/take values for pagination instead of int.MaxValue.
• If role-based filtering returns unexpected results, verify that user roles are correctly assigned and match the role names used in the filter.
• The API returns InstanceUser objects, not User objects directly - access the user through instanceUser.User.
• The userNameKeyword parameter performs case-insensitive partial matching against user display names (first name + last name).
• Use includeAdmin = true when you need administrative users included in results, such as for system-wide notifications or user management scenarios.
• Default pagination (skip=0, take=100) is suitable for most UI scenarios - adjust based on your specific requirements.
• Empty userNameKeyword returns all users; non-empty values filter the results to matching names only.