Add-KFPermission

Syntax

Add-KFPermission 
  [-Permissions] <list-of-permissions>
  [-Item <list-item>]
  [-CopyCurrentPermissions[:$false]]
  [-BreakPermissionInheritance[:$true]]
  [-ThrowResolveErrors[:$false]]
  [-ThrowErrors[:$true]]

Support

>= kenaflow 1.0.0

Return

Nothing.

Description

Use this cmdlet to add permissions to a list item.

Add means that it does not remove or replace permissions! If you plan to replace all current permissions with a new set of permissions please use cmdlet Set-KFPermission.

The -Permissons parameter gets a single permission object or a list of permission objects of the following form.

The permission object is specified as a PowerShell Hashtable:

@{
   User = <string-or-object>;
   PermissionsSets = @(<permission-set-name>[, <permission-set-name>[, ...]]);
   Quick = "CRUDMA";
)

The User property of the permission object can be:

  • List of strings or objects
  • string, that describe the user
  • object as (array of) SharePoint FieldUserValue

Such a "string" of the User property of the permission object can be:

  • a user login name
  • an email address
  • a SharePoint field of the currently processed or with -Item specified list item
  • a combination of all of them separated by "," or ";"

Examples:

  • User = @($item["Author"])
  • User = $item["Author"]
  • User = @($item["Author"], $item["Editor"])
  • User = "{{Author}}"
  • User = "{{Author}},{{Editor}}"
  • User = @($item["Author"], "{{Editor}},sharepoint\ingo", "ingo@sharepoint.farm")

The kenaflow template engine is used to resolve the given strings. Templates

Also SharePoint groups are resolved. E.g. User = @("Intranet Owners")

The parameter -PermissionSets is a PowerShell list of one or more names of valid / existing SharePoint permission sets, such as "Full Control" or "Design". - Custom permission sets can be named too. But the have to exist!

The parameter -Quick is a kind of shortcut to -PermissionSets. kenaflow can create it's own permission sets as specified in the _wfconfig.ps1 file. They have to be created using program switch --createpermissionsets. This permission sets are by default named as:

  • kenaflow Create => C
  • kenaflow Read => R
  • kenaflow Update => U
  • kenaflow Delete => D
  • kenaflow Manage => M
  • kenaflow Approve => A

The first letter(s) in combination can be used in parameter -Quick to specify these permission sets. - But they have to be configured in _wfconfig.ps1 and must exist in SharePoint! - For example: Quick="CUD" => "Create", "Update", "Delete" - but not "Read".

The base permissions of each of the kenaflow defined permission sets can be found here: Permissions.

This is an example for a valid permission object - if the kenaflow permission sets are configured.

@{
    User = @("{{Author}}", $item["Editor"]);
    PermissionSets = @("Read");
    Quick = "CUD"
}

Multiple permission objects can be specified as a list:

@(
    @{User="sharepoint\ingo"; Quick="CUD"},
    @{User="sharepoint\kenaflow";PermissionSets=@("Full Control")}
)

Parameters

[-Permissions] <list-of-permissions>

One or more permission objects as described above.

[-Item <list-item>]

The list item to be processed.

[-BreakPermissionInheritance[:$true]]

Permissions can only be added to the list item if it has its own permissions - and not inherited permissions from its parent. If an item with active permission inheritance is given the inheritance will be stopped by default. But if you specify -BreakPermissionInheritance:$false the cmdlet will fail and stop if the list item has active permission inheritance.

[-CopyCurrentPermissions[:$false]]

If the cmdlet stop permission inheritance it can copy the permissions of the parent or start with a blank set of permissions which is the default.

[-ThrowResolveErrors[:$false]]

kenaflow tries to resolve the given User property of each permission object. If this fails and -ThrowResolveErrors is specified the cmdlet will fail. Otherwise the not existing or not successfully resolved principal is skipped.

[-ThrowErrors[:$true]]

This is a default parameter for all kenaflow cmdlets. If set to $true (default!) the engine will pass exception within the cmdlet to the script for further handling.

Examples

Add-KFPermission -Permissions @(
    @{
        User = "user1@sharepoint.farm";
        PermissionSets = @("Full Control", "Contribute");
        Quick="CRUDMA";
    },
    @{
        User = "user2@sharepoint.farm";
        PermissionSets = "Read";
        Quick="CRUDMA";
    }    
)

$newEditor = "sharepoint\user3"

Add-KFPermission -Permissions @(
    @{ User="{{Author}}"; Quick="RM" },
    @{ User="{{currentEditor}}"; Quick="RM" },
    @{ User=$newEditor; Quick="RM" }
)