Resolve-KFPrincipal

Syntax

Resolve-KFPrincipal 
  -Principal <object> 
  [-Item <item>]
  [-ClientContext <client-context>]
  [-AsObjects[:$false]]
  [-ThrowResolveErrors[:$false]]
  [-MaxLevel <int> (999999)]
  [-ResolveAtADLevel:[$true]]
  [-Flat:[$false]] [-Unique:[$false]]
  [-ThrowErrors[:$true]]

Support

>= kenaflow 2.0.38

Return

List of objects of type kenaflow.Cmdlets.ResolveKFPrincipalResult:

namespace kenaflow.Cmdlets
{
    public class ResolveKFPrincipalResult
    {
        public enum ResolveKFPrincipalResultObjectType { 
		    Unknown, 
		    SPGroup, 
			ADSecurityGroup, 
			ADDistributionGroup, 
			ADUser, 
			SPUserADUser, 
			SPUserADGroup 
		}

        public bool AD { get; internal set; }
        public ResolveKFPrincipalResultObjectType ObjectType { get; internal set; }
        public string LoginName { get; internal set; }
        public string Title { get; internal set; }
        public string EMail { get; internal set; }
        public string ParentLogin { get; internal set; }
        public object Object { get; internal set; }
        public List<ResolveKFPrincipalResult> SubPrincipals { get; internal set; }
    }
}

Description

This cmdlet is only available in SharePoint workflows!

This cmdlet can be used to resolve all sorts of strings, including templates with placeholders, to resolve principals.

"Principals" are:

  • SharePoint users objects
  • SharePoint group objects
  • Active Directory user objects
  • Active Directory security group objects

The cmdlet is able to resolve all of them as long as it is able to connect to the active directory where the AD objects are is.

It is not possible currently to resolve Azure Active Directory objects in case of SharePoint Online. The cmdlet will only resolve and return SharePoint objects.

Example:

Resolve-KFPrincipal -Principal "{{Author}}"

This resolves the user contained in the "Author" field of the current list item. (This will not work for site workflows except you specify a list item with parameter -Item.)

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

The "Author" will be resolved as a SharePoint user. But also - as "SubPrincipal" in the return object - as an Active Directory user.

If you specify -Flat the SharePoint user and its Active Directory user will return as a flat list at the same hierarchy level.... like @( <sharepoint-user> , <ad-user> ) (pseudo code!).

If you specify -ResolveAtADLevel:$false Active Directory objects are not resolved. In the example you would only get the SharePoint user object.

Another Example:

You have a custom list with a field "Responsible" of type "Person" with setting "Person or Group". - You have a list item with value "Intranet Members" in the field. - "Intranet Members" is a default SharePoint group on you site. It contains some SharePoint users, some AD security groups and some SharePoint groups.

The cmdlet would resolve all of them with its default settings. These calls are the same:

  • Resolve-KFPrincipal -Principal $item["Responsible"]
  • Resolve-KFPrincipal -Principal @($item["Responsible"])
  • Resolve-KFPrincipal -Principal "{{Responsible}}"
  • Resolve-KFPrincipal -Principal @("{{Responsible}}")

First "Responsible" is resolved as SharePoint group object. All members of this group are analysed. That could be SharePoint users and AD security groups. (A SharePoint group cannot contain other SharePoint groups.) All AD security groups are resolved. If they contain other AD security groups they are also resolved. And so on. To the last level where all group members are AD users. - You can specify -MaxLevel to stop the resolving at the depth indicated. - - The return object is hierarchical. That means that you can see the resolved structure in the return object and go into deep using property SubPrincipals.

You can - as described before - use -Flat to receive a flat list of all objects. If using -Flat you can additionally use -Unique to remove duplicate objects from the return object.

A word to -ThrowResolveErrors: SharePoint user objects "normally" belong to existing Active Directory objects. But in AD the can be deleted. They are not deleted in SharePoint too because list items are referencing to them, e.g. in the fields "Author" or "Editor". If kenaflow tries to resolve this principals it will get an error because the objects are invalid or the corresponding AD user objects do not exist. In this case the cmdlet will "silently continue" if the -ThrowResolveErrors is not specified!

The cmdlet can also be called with the name(s) of a user(s) or group(s) as string, e.g.:

  • Resolve-KFPrincipal -Principal "Intranet Members"
  • Resolve-KFPrincipal -Principal "Intranet Members;Intranet Visitors"
  • Resolve-KFPrincipal -Principal "Intranet Members,Intranet Visitors"
  • Resolve-KFPrincipal -Principal @("Intranet Members")
  • Resolve-KFPrincipal -Principal @("Intranet Members","Intranet Visitors")

You can combine it with template processing:
Resolve-KFPrincipal -Principal "Intranet Members,{{Author}};{{Editor}};ingo@sharepoint.farm"
which is the same as
Resolve-KFPrincipal -Principal @("Intranet Members","{{Author}}";$item["Editor"];"ingo@sharepoint.farm")

Parameters

-Principal <object>

The object(s) (list, string, SharePoint User Field value, SharePoint User Field value array) that are to be resolved.

[-Item <item>]

The SharePoint list item that is used for template processing (e.g. "{{Author}}")

[-ClientContext <client-context>]

A SharePoint client context is necessary to resolve SharePoint objects. If nothing is specified the client context is used from the given item (-Item) or from the current processed list item. - But if you need for some reasons to specify your own client context you can use this parameter.

[-AsObjects[:$false]]

You will not receive a return object of type kenaflow.Cmdlets.ResolveKFPrincipalResult but as raw Active Directory object or SharePoint client object model objects. - Active Directory objects are comming from .NET namespace System.DirectoryServices.AccountManagement.

[-ThrowResolveErrors[:$false]]

If the resolve of a given string or whatever failed not the complete execution of the cmdlet will fail. You get the found pricinals in the return object.

[-MaxLevel <int> (999999)]

Specifies the depth of the SharePoint Group and Active Directory analysis. - You could specify 1 to just resolve the very first level.

[-ResolveAtADLevel:[$true]]

If set to $false it will not resolve at Active Directory level.

[-Flat:[$false]]

If specified you get a flat list not a hierarchical tree.

[-Unique:[$false]]

In case of a -Flat list you get resolved objects only once.

[-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.

Example

Have a look at the section "Description" above.

Discussion