Set-Role.ps1
|
function Set-Role { <# .SYNOPSIS Sets or creates a Role entry in Appclusive. .DESCRIPTION Sets or creates a Role entry in Appclusive. By updating an Role entry you can specify, if you want to update the Description, MailAddress, Name, RoleType, PermissionsToAdd, PermissionsToRemove or any combination thereof. For updating Name or RoleType you need to use the Argument '-NewName'/'-NewRoleType' .OUTPUTS default .EXAMPLE Set-Role -Name "ArbitraryRole" -RoleType External -svc $svc -CreateIfNotExist; RoleType : External MailAddress : Id : 42 Tid : 11111111-1111-1111-1111-111111111111 Name : ArbitraryRole Description : CreatedById : 1 ModifiedById : 1 Created : 23.08.2016 11:08:14 +02:00 Modified : 23.08.2016 11:08:14 +02:00 RowVersion : Permissions : {} Users : {} Tenant : CreatedBy : ModifiedBy : Create a new Role entry if it does not exist. .EXAMPLE Set-Role -Name "ArbitraryName" -Description "UpdatedDescription" -NewName "UpdatedName" RoleType : Distribution MailAddress : Id : 42 Tid : 11111111-1111-1111-1111-111111111111 Name : UpdatedName Description : UpdatedDescription CreatedById : 1 ModifiedById : 1 Created : 23.08.2016 11:08:14 +02:00 Modified : 23.08.2016 11:08:14 +02:00 RowVersion : Permissions : {} Users : {} Tenant : CreatedBy : ModifiedBy : Update an existing Role with new Name and new Description. .EXAMPLE Set-Role -Id 42 -RoleType Distribution -MailAddress "arbitrary@example.com" -NewName "UpdatedName" RoleType : Distribution MailAddress : arbitrary@example.com Id : 42 Tid : 11111111-1111-1111-1111-111111111111 Name : UpdatedName Description : CreatedById : 1 ModifiedById : 1 Created : 23.08.2016 11:08:14 +02:00 Modified : 23.08.2016 11:08:14 +02:00 RowVersion : Permissions : {} Users : {} Tenant : CreatedBy : ModifiedBy : Update an existing Role with new Name and MailAddress and RoleType. .EXAMPLE Set-Role -Id 42 -PermissionsToAdd @("Apc:NodesCanRead","Apc:NodesCanCreate") -CreateIfNotExist RoleType : Distribution MailAddress : Id : 42 Tid : 11111111-1111-1111-1111-111111111111 Name : ArbitraryName Description : CreatedById : 1 ModifiedById : 1 Created : 23.08.2016 11:08:14 +02:00 Modified : 23.08.2016 11:08:14 +02:00 RowVersion : Permissions : {} Users : {} Tenant : CreatedBy : ModifiedBy : Create/Update Role by adding specified permissions .EXAMPLE Set-Role -Id 42 -PermissionsToRemove @("Apc:NodesCanRead","Apc:NodesCanCreate") RoleType : Distribution MailAddress : Id : 42 Tid : 11111111-1111-1111-1111-111111111111 Name : ArbitraryName Description : CreatedById : 1 ModifiedById : 1 Created : 23.08.2016 11:08:14 +02:00 Modified : 23.08.2016 11:08:14 +02:00 RowVersion : Permissions : {} Users : {} Tenant : CreatedBy : ModifiedBy : Update an existing Role by removing the specified permissions .LINK Online Version: http://dfch.biz/biz/dfch/PS/Appclusive/Client/Set-Role/ Set-Role: http://dfch.biz/biz/dfch/PS/Appclusive/Client/Set-Role/ .NOTES See module manifest for dependencies and further requirements. #> [CmdletBinding( SupportsShouldProcess = $false , ConfirmImpact = 'Low' , HelpURI = 'http://dfch.biz/biz/dfch/PS/Appclusive/Client/Set-Role/' )] [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")] Param ( [Parameter(Mandatory = $true, ParameterSetName = 'id', Position = 0)] [ValidateRange(1, [long]::MaxValue)] [long] $Id , [Parameter(Mandatory = $true, ParameterSetName = 'create', Position = 0)] [Parameter(Mandatory = $true, ParameterSetName = 'name', Position = 0)] [ValidateNotNullOrEmpty()] [Alias('n')] [string] $Name , [Parameter(Mandatory = $true, ParameterSetName = 'create', Position = 1)] [Parameter(Mandatory = $false, ParameterSetName = 'name', Position = 1)] [Parameter(Mandatory = $false, ParameterSetName = 'id', Position = 1)] [ValidateSet('Default', 'Security', 'Distribution', 'BuiltIn', 'External')] [string] $RoleType , [Parameter(Mandatory = $false)] [ValidateNotNullOrEmpty()] [string] $MailAddress , [Parameter(Mandatory = $false)] [ValidateNotNullOrEmpty()] [string] $Description , # Specifies the permissions which should be added/removed [Parameter(Mandatory = $false)] [Alias('add')] [string[]] $PermissionsToAdd = @() , [Parameter(Mandatory = $false, ParameterSetName = 'name')] [Parameter(Mandatory = $false, ParameterSetName = 'id')] [Alias('remove')] [string[]] $PermissionsToRemove = @() , [Parameter(Mandatory = $false, ParameterSetName = 'id')] [Parameter(Mandatory = $false, ParameterSetName = 'name')] [ValidateNotNullOrEmpty()] [string] $NewName , # Specifies to create a entity if it does not exist [Parameter(Mandatory = $true, ParameterSetName = 'create')] [Alias("c")] [switch] $CreateIfNotExist = $false , # Service reference to Appclusive [Parameter(Mandatory = $false)] [Alias('Services')] [hashtable] $svc = (Get-Variable -Name $MyInvocation.MyCommand.Module.PrivateData.MODULEVAR -ValueOnly).Services , # Specifies the return format of the Cmdlet [ValidateSet('default', 'json', 'json-pretty', 'xml', 'xml-pretty')] [Parameter(Mandatory = $false)] [alias('ReturnFormat')] [string] $As = 'default' ) Begin { trap { Log-Exception $_; break; } $datBegin = [datetime]::Now; [string] $fn = $MyInvocation.MyCommand.Name; Log-Debug -fn $fn -msg ("CALL. svc '{0}'. Name '{1}'." -f ($svc -is [Object]), $Name) -fac 1; # Parameter validation Contract-Requires ($svc.Core -is [biz.dfch.CS.Appclusive.Api.Core.Core]) "Connect to the server before using the Cmdlet"; if ($PSBoundParameters.ContainsKey('PermissionsToAdd') -and $PSBoundParameters.ContainsKey('PermissionsToRemove')) { $commonPermissionEntries = Compare-Object $PermissionsToAdd $PermissionsToRemove -PassThru -IncludeEqual -ExcludeDifferent; Contract-Assert($commonPermissionEntries.Count -eq 0) "Same permission name(s) found in 'PermissionsToAdd' and 'PermissionsToRemove'"; } } Process { trap { Log-Exception $_; break; } # Default test variable for checking function response codes. [Boolean] $fReturn = $false; # Return values are always and only returned via OutputParameter. $OutputParameter = $null; $AddedEntity = $null; if($PSCmdlet.ParameterSetName -eq 'id') { $FilterExpression = "Id eq {0}L" -f $Id; $entity = $svc.Core.Roles.AddQueryOption('$filter', $FilterExpression).AddQueryOption('$top',1) | Select; Contract-Assert ($entity) "Entity does not exist"; } else { $currentTenant = Get-Tenant -svc $svc -Current; $FilterExpression = "(tolower(Name) eq '{0}' and Tid eq guid'{1}')" -f $Name.ToLower(), $currentTenant.Id; $entity = $svc.Core.Roles.AddQueryOption('$filter', $FilterExpression).AddQueryOption('$top',1) | Select; Contract-Assert ($CreateIfNotExist -or $entity) "Entity does not exist. Use '-CreateIfNotExist' to create the resource"; } if($PSCmdlet.ParameterSetName -eq 'create') { $entity = New-Object biz.dfch.CS.Appclusive.Api.Core.Role; $svc.Core.AddToRoles($entity); $AddedEntity = $entity; $entity.Name = $Name; $entity.RoleType = $RoleType $entity.Created = [System.DateTimeOffset]::Now; $entity.Modified = $entity.Created; $entity.CreatedById = 0; $entity.ModifiedById = 0; } else { if($PSBoundParameters.ContainsKey('NewName')) { $entity.Name = $NewName; } if($PSBoundParameters.ContainsKey('RoleType')) { $entity.RoleType = $RoleType; } } if($PSBoundParameters.ContainsKey('Description')) { $entity.Description = $Description; } if($PSBoundParameters.ContainsKey('MailAddress')) { $entity.MailAddress = $MailAddress; } $svc.Core.UpdateObject($entity); $null = $svc.Core.SaveChanges(); $originalPermissions = Get-Role -Id $entity.Id -svc $svc -ExpandPermissions; if($PSBoundParameters.ContainsKey('PermissionsToAdd')) { # assert, that specified permissions do not contain duplicates Contract-Assert($PermissionsToAdd.Count -eq ($PermissionsToAdd | Select -Unique).Count) "Duplicates found in PermissionsToAdd"; $permissionEntitiesToBeAdded = New-Object System.Collections.ArrayList; foreach($permissionName in $PermissionsToAdd) { $query = "Name eq '{0}'" -f $permissionName; $apcPermission = $svc.Core.Permissions.AddQueryOption('$filter', $query).AddQueryOption('$top', 1) | Select; Contract-Assert($apcPermission) ("Permissions with Name '{0}' not found." -f $permissionName); if (!$originalPermissions -or !$originalPermissions.Name.Contains($permissionName)) { $null = $permissionEntitiesToBeAdded.Add($apcPermission); } } } if($PSBoundParameters.ContainsKey('PermissionsToRemove')) { # assert, that specified permissions do not contain duplicates Contract-Assert($PermissionsToRemove.Count -eq ($PermissionsToRemove | Select -Unique).Count) "Duplicates found in PermissionsToAdd"; $permissionEntitiesToBeRemoved = New-Object System.Collections.ArrayList; $permissionsCanBeRemoved = $true; foreach($permissionName in $PermissionsToRemove) { $query = "Name eq '{0}'" -f $permissionName; $apcPermission = $svc.Core.Permissions.AddQueryOption('$filter', $query).AddQueryOption('$top', 1) | Select; Contract-Assert($apcPermission) ("Permissions with Name '{0}' not found." -f $permissionName); # check, if every specified permission can be removed if (!$originalPermissions -or !$originalPermissions.Name.Contains($permissionName)) { $permissionsCanBeRemoved = $false; continue; } $null = $permissionEntitiesToBeRemoved.Add($apcPermission); } Contract-Assert($permissionsCanBeRemoved) "One or more of the specified permissions cannot be removed as they are not linked to the corresponding role"; } foreach($apcPermission in $permissionEntitiesToBeAdded) { $svc.Core.AddLink($entity, 'Permissions', $apcPermission); $null = $svc.Core.SaveChanges(); } foreach($apcPermission in $permissionEntitiesToBeRemoved) { $svc.Core.DeleteLink($entity, 'Permissions', $apcPermission); $null = $svc.Core.SaveChanges(); } $r = $entity; $OutputParameter = Format-ResultAs $r $As; $fReturn = $true; } End { $datEnd = [datetime]::Now; Log-Debug -fn $fn -msg ("RET. fReturn: [{0}]. Execution time: [{1}]ms. Started: [{2}]." -f $fReturn, ($datEnd - $datBegin).TotalMilliseconds, $datBegin.ToString('yyyy-MM-dd HH:mm:ss.fffzzz')) -fac 2; # Return values are always and only returned via OutputParameter. return $OutputParameter; } } # function if($MyInvocation.ScriptName) { Export-ModuleMember -Function Set-Role; } # # Copyright 2016 d-fens GmbH # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # |