Working With: SP.Utilities.Utility

Added in 2.0.5

Through the REST api you are able to call a subset of the SP.Utilities.Utility methods. We have explicitly defined some of these methods and provided a method to call any others in a generic manner. These methods are exposed on pnp.sp.utility and support batching and caching.

sendEmail

This methods allows you to send an email based on the supplied arguments. The method takes a single argument, a plain object defined by the EmailProperties interface (shown below).

EmailProperties

export interface EmailProperties {

    To: string[];
    CC?: string[];
    BCC?: string[];
    Subject: string;
    Body: string;
    AdditionalHeaders?: TypedHash<string>;
    From?: string;
}

Usage

You must define the To, Subject, and Body values - the remaining are optional.

import pnp, { EmailProperties } from "sp-pnp-js";

const emailProps: EmailProperties = {
    To: ["user@site.com"],
    CC: ["user2@site.com", "user3@site.com"],
    Subject: "This email is about...",
    Body: "Here is the body. <b>It supports html</b>",
};

pnp.sp.utility.sendEmail(emailProps).then(_ => {

    console.log("Email Sent!");
});

getCurrentUserEmailAddresses

This method returns the current user's email addresses known to SharePoint.

import pnp from "sp-pnp-js";

pnp.sp.utility.getCurrentUserEmailAddresses().then((addressString: string) => {

    console.log(addressString);
});

resolvePrincipal

Gets information about a principal that matches the specified Search criteria

import pnp, { PrincipalType, PrincipalSource, PrincipalInfo } from "sp-pnp-js";

pnp.sp.utility.resolvePrincipal("user@site.com",
    PrincipalType.User,
    PrincipalSource.All,
    true,
    false).then((principal: PrincipalInfo) => {


        console.log(principal);
    });

searchPrincipals

Gets information about the principals that match the specified Search criteria.

import pnp, { PrincipalType, PrincipalSource, PrincipalInfo } from "sp-pnp-js";

pnp.sp.utility.searchPrincipals("john",
    PrincipalType.User,
    PrincipalSource.All,
    "",
    10).then((principals: PrincipalInfo[]) => {

        console.log(principals);
    });

createEmailBodyForInvitation

Gets the external (outside the firewall) URL to a document or resource in a site.

import pnp from "sp-pnp-js";

pnp.sp.utility.createEmailBodyForInvitation("https://contoso.sharepoint.com/sites/dev/SitePages/DevHome.aspx").then((r: string) => {

    console.log(r);
});

expandGroupsToPrincipals

Resolves the principals contained within the supplied groups

import pnp, { PrincipalInfo } from "sp-pnp-js";

pnp.sp.utility.expandGroupsToPrincipals(["Dev Owners", "Dev Members"]).then((principals: PrincipalInfo[]) => {

    console.log(principals);
});

// optionally supply a max results count. Default is 30.
pnp.sp.utility.expandGroupsToPrincipals(["Dev Owners", "Dev Members"], 10).then((principals: PrincipalInfo[]) => {

    console.log(principals);
});

createWikiPage

import pnp, { CreateWikiPageResult } from "sp-pnp-js";

pnp.sp.utility.createWikiPage({
    ServerRelativeUrl: "/sites/dev/SitePages/mynewpage.aspx",
    WikiHtmlContent: "This is my <b>page</b> content. It supports rich html.",
}).then((result: CreateWikiPageResult) => {

    // result contains the raw data returned by the service
    console.log(result.data);

    // result contains a File instance you can use to further update the new page
    result.file.get().then(f => {
        
        console.log(f);
    });
});

Call Other Methods

Even if a method does not have an explicit implementation on the utility api you can still call it using the UtilityMethod class. In this example we will show calling the GetLowerCaseString method, but the technique works for any of the utility methods.

import pnp, { UtilityMethod } from "sp-pnp-js";

// the first parameter is the web url. You can use an empty string for the current web,
// or specify it to call other web's. The second parameter is the method name.
const method = new UtilityMethod("", "GetLowerCaseString");

// you must supply the correctly formatted parameters to the execute method which
// is generic and types the result as the supplied generic type parameter.
method.excute<string>({
    sourceValue: "HeRe IS my StrINg",
    lcid: 1033,
}).then((s: string) => {

    console.log(s);
});