function Grant-RightsToSSRSFolder {
<#
.SYNOPSIS
    Grants Rights to a Folder on the SSRS Server
#>

    [CmdletBinding()]
    Param(
        [Parameter(Position=0,Mandatory=$true)]
        [Alias("Roles")]
        [string[]]$roleNames,

        [Parameter(Position=1,Mandatory=$false)]
        [Alias("User")]
        [string]$userName,

        [Parameter(Position=2,Mandatory=$false)]
        [Alias("Folder")]
        [string]$folderName,

        [Parameter(Position=3,Mandatory=$false)]
        [Alias("ReportServerUrl")]
        [string]$reportServerEndpoint
    )

    $logLead  = (Get-LogLeadName);

    try
    {
        if (!(Test-IsWebServer) -and [String]::IsNullOrEmpty($reportServerEndpoint))
        {
            Write-Warning "$logLead : This function can only be automatically executed on a web tier server.  To run, call the function with the appropriate parameters."
            return
        }

        [xml]$config = Get-ReportServerConfiguration -WarningAction SilentlyContinue

        if ($null -ne $config)
        {
            $reportServerEndpointNode = $config.appSettings.SelectSingleNode("//add[@key=""ReportServer""]/@value")
            $reportFolderNode = $config.appSettings.SelectSingleNode("//add[@key=""ReportServerPath""]/@value")
            $reportUserNode = $config.appSettings.SelectSingleNode("//add[@key=""ReportServerUserName""]/@value")
        }

        if ((($null -eq $reportServerEndpointNode) -or ([String]::IsNullOrEmpty($reportServerEndpointNode.Value))) -and [String]::IsNullOrEmpty($reportServerEndpoint))
        {
            Write-Warning "$logLead : Could not read the value for the ""ReportServer"" appSetting from the machine.config and no report server URL was provided as a parameter.  Execution cannot continue."
            return;
        }

        if ((($null -eq $reportFolderNode) -or ([String]::IsNullOrEmpty($reportFolderNode.Value))) -and [String]::IsNullOrEmpty($folderName))
        {
            Write-Warning "$logLead : Could not read the value for the ""ReportServerPath"" appSetting from the machine.config and no folder name was provided as a parameter.  Execution cannot continue."
            return;
        }

        if ((($null -eq $reportUserNode) -or ([String]::IsNullOrEmpty($reportUserNode.Value))) -and [String]::IsNullOrEmpty($userName))
        {
            Write-Warning "$logLead : Could not read the value for the ""ReportServerUserName"" appSetting from the machine.config and no user name was provided as a parameter.  Execution cannot continue."
            return;
        }

        $proxyUrlToUse = IsNull $reportServerEndpoint $reportServerEndpointNode.Value
		$proxy = New-SSRSProxy $proxyUrlToUse
        $proxyNameSpace = $proxy.GetType().Namespace

        $folderToUse = IsNull $folderName $reportFolderNode.Value
        $userToUse = IsNull $userName $reportUserNode.Value

        $normalizedFolder = "/" + $folderToUse.TrimStart("/")

        # Make sure the folder exists
        try
        {
            $folderType = $proxy.GetItemType($normalizedFolder)
        }
        catch
        {
            Write-Warning ("$logLead : The folder {0} does not exist.  Execution cannot continue" -f $normalizedFolder)
            return
        }

        ## TODO: cbrand ~ candidate for [string]::IsNullOrEmpty() ?
        if (($null -eq $folderType) -or ($folderType -eq "Unknown"))
        {
            Write-Warning ("$logLead : The folder {0} does not exist.  Execution cannot continue" -f $normalizedFolder)
            return
        }

        $folderPolicies = $proxy.GetPolicies($normalizedFolder, [ref]$false)
        $userPolicies = $folderPolicies | Where-Object {$_.GroupUserName -eq $userToUse}

        if ($null -eq $userPolicies)
        {
            # Add a Policy for the User
            Write-Output ("$logLead : Creating User Policy")

            $policy = New-Object "${proxyNameSpace}.Policy"
            $policy.GroupUserName = $userToUse
            $folderPolicies += $policy

            [array]$userPolicies += $policy
        }

        # Add the Role to the User Policy
        Write-Output ("$logLead : Creating User Role")

        $rolesDirty = $false;
        foreach ($roleToAdd in $roleNames)
        {
            if ($userPolicies | Where-Object {$_.Roles.Name -eq $roleToAdd})
            {
                Write-Output ("$logLead : User {0} already has role {1} on folder {2}" -f $userToUse, $roleToAdd, $folderToUse)
                continue;
            }

            $role = New-Object "${proxyNameSpace}.Role"
            $role.Name = $roleToAdd
            ($userPolicies | Select-Object -First 1).Roles += $role
            Write-Output ("$logLead : User {0} granted role {1} on folder {2}" -f $userToUse, $roleToAdd, $folderToUse)
            $rolesDirty = $true
        }

        if ($rolesDirty)
        {
            $proxy.SetPolicies($normalizedFolder, $folderPolicies)
            Write-Output "$logLead : Role Changes Committed"
        }
        else
        {
            Write-Output "$logLead : No Role Changes Required"
        }
    }
    finally
    {
        if ($null -ne $SSRSProxy)
        {
            $SSRSProxy.Dispose()
        }

        if ($null -ne $SSRSExecutionProxy)
        {
           $SSRSExecutionProxy.Dispose()
        }
    }
}

#region Private Functions