InstanceService.AddInstanceUser

Reference

void AddInstanceUser(Guid instanceId, Guid userId, bool recursiveAccess = false)

Use AddInstanceUser to grant a user access to a specific Protrak instance. This API is commonly used for user provisioning, access management workflows, and role-based access control scenarios.

Parameters

• instanceId: The unique identifier of the instance to which user access should be granted.
• userId: The unique identifier of the user who should be granted access to the instance.
• recursiveAccess: (Optional) When true, grants access to child instances and related objects recursively. Default is false.

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 already has access to the instance, the operation completes successfully without error.
• When recursiveAccess is true, the operation may take longer as it processes all related instances.
• Access permissions are applied asynchronously and may take time to propagate in case of deep hierarchy.
• The user's effective permissions depend on their role assignments and instance-specific access rules.
• This operation only grants instance-level access; users still need appropriate roles to perform specific actions.

Usage

try {
    // Grant access to a specific instance
    InstanceService.AddInstanceUser(instanceId, userId, false);
    Console.WriteLine($"User {userId} granted access to 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: External User Provisioning

try {
    // Find or create the attorney user
    var attorneyUser = UserService.GetUserByEmail("attorney@lawfirm.com");
    
    if (attorneyUser != null) {
        // Grant recursive access to both attorney firm and the specific task
        InstanceService.AddInstanceUser(attorneyFirmId, attorneyUser.Id, true);
        InstanceService.AddInstanceUser(taskId, attorneyUser.Id, true);
        
        Console.WriteLine($"Attorney {attorneyUser.UserName} granted access to firm and task");
    }
} catch (Exception ex) {
    Console.WriteLine($"Error provisioning attorney access: {ex.Message}");
}

Example: Department Access Management

try {
    // Get user by email from user profile
    var userProfile = InstanceService.GetInstance(userProfileId);
    var emailAttr = userProfile.Attributes.FirstOrDefault(a => a.Name == "UserEmail");
    
    if (emailAttr?.TextValue != null) {
        var user = UserService.GetUserByEmail(emailAttr.TextValue);
        
        if (user != null) {
            // Check if user has required role (faculty member)
            var requiredRoles = new[] { "Faculty", "Professor", "Researcher" };
            
            if (user.Roles.Any(role => requiredRoles.Contains(role))) {
                InstanceService.AddInstanceUser(departmentId, user.Id, false);
                Console.WriteLine($"Department access granted to {user.UserName}");
            } else {
                throw new Exception("User is NOT faculty member, cannot associate Department.");
            }
        }
    }
} catch (Exception ex) {
    Console.WriteLine($"Error granting department access: {ex.Message}");
}

Example: Conditional Access Based on User Status

try {
    var existingUser = UserService.GetUserByEmail("company.contact@company.com");
    
    if (existingUser != null) {
        // Activate user if inactive
        if (!existingUser.IsActive) {
            UserService.ActivateUser(existingUser.Id);
            Console.WriteLine($"User {existingUser.UserName} activated");
        }
        
        // Grant recursive access to company instance
        InstanceService.AddInstanceUser(companyId, existingUser.Id, true);
        Console.WriteLine($"Company access granted to {existingUser.UserName}");
    } else {
        Console.WriteLine("User not found - consider creating new user first");
    }
} catch (Exception ex) {
    Console.WriteLine($"Error managing company user access: {ex.Message}");
}

Troubleshooting

• If AccessDeniedException occurs, verify that the current user has "Manage Access" or "Admin" permissions for the instance.
• If the operation succeeds but the user cannot access the instance, check that their role permits the required operations on that instance type.
• If recursive access is not working as expected, verify that child instances exist and the parent-child relationships are properly configured.
• For external user provisioning, ensure the user account exists and is active before granting access.
• If users cannot see the instance after access is granted, check that their organizational context matches the instance's organizational hierarchy.
• When using email-based user lookup, ensure the email addresses are exact matches and the users exist in the system.
• For role-based access control, verify that users have the required roles before granting instance access.
• If access permissions are not taking effect immediately, allow time for cache refresh or ask users to refresh their sessions.
• For automated provisioning scenarios, always check if the user already has access to avoid duplicate operations.
• When granting access in trigger programs, ensure the operation doesn't create infinite loops or circular dependencies.