@pnp/sp/sharing

Note: This API is still considered "beta" meaning it may change and some behaviors may differ across tenants by version. It is also supported only in SharePoint Online.

One of the newer abilities in SharePoint is the ability to share webs, files, or folders with both internal and external folks. It is important to remember that these settings are managed at the tenant level and ? override anything you may supply as an argument to these methods. If you receive an InvalidOperationException when using these methods please check your tenant sharing settings to ensure sharing is not blocked before ?submitting an issue.

Imports

In previous versions of this library the sharing methods were part of the inheritance stack for SharePointQueryable objects. Starting with v2 this is no longer the case and they are now selectively importable. There are four objects within the SharePoint hierarchy that support sharing: Item, File, Folder, and Web. You can import the sharing methods for all of them, or for individual objects.

Import All

To import and attach the sharing methods to all four of the sharable types include all of the sharing sub module:

import "@pnp/sp/sharing";
import "@pnp/sp/webs";
import "@pnp/sp/site-users/web";
import { sp } from "@pnp/sp";

const user = await sp.web.siteUsers.getByEmail("user@site.com")();
const r = await sp.web.shareWith(user.LoginName);

Selective Import

Import only the web's sharing methods into the library

import "@pnp/sp/sharing/web";
import "@pnp/sp/webs";
import "@pnp/sp/site-users/web";
import { sp } from "@pnp/sp";

const user = await sp.web.siteUsers.getByEmail("user@site.com")();
const r = await sp.web.shareWith(user.LoginName);

getShareLink

Applies to: Item, Folder, File

Creates a sharing link for the given resource with an optional expiration.

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import { SharingLinkKind, IShareLinkResponse } from "@pnp/sp/sharing";
import { dateAdd } from "@pnp/core";

const result = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/folder1").getShareLink(SharingLinkKind.AnonymousView);

console.log(JSON.stringify(result, null, 2));


const result2 = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/folder1").getShareLink(SharingLinkKind.AnonymousView, dateAdd(new Date(), "day", 5));

console.log(JSON.stringify(result2, null, 2));

shareWith

Applies to: Item, Folder, File, Web

Shares the given resource with the specified permissions (View or Edit) and optionally sends an email to the users. You can supply a single string for the loginnames parameter or an array of loginnames. The folder method takes an optional parameter "shareEverything" which determines if the shared permissions are pushed down to all items in the folder, even those with unique permissions.

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import "@pnp/sp/folders/web";
import "@pnp/sp/files/web";
import { ISharingResult, SharingRole } from "@pnp/sp/sharing";

const result = await sp.web.shareWith("i:0#.f|membership|user@site.com");

console.log(JSON.stringify(result, null, 2));

// Share and allow editing
const result2 = await sp.web.shareWith("i:0#.f|membership|user@site.com", SharingRole.Edit);

console.log(JSON.stringify(result2, null, 2));


// share folder
const result3 = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/folder1").shareWith("i:0#.f|membership|user@site.com");

// Share folder with edit permissions, and provide params for requireSignin and propagateAcl (apply to all children)
await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").shareWith("i:0#.f|membership|user@site.com", SharingRole.Edit, true, true);

// Share a file
await sp.web.getFileByServerRelativeUrl("/sites/dev/Shared Documents/test.txt").shareWith("i:0#.f|membership|user@site.com");

// Share a file with edit permissions
await sp.web.getFileByServerRelativeUrl("/sites/dev/Shared Documents/test.txt").shareWith("i:0#.f|membership|user@site.com", SharingRole.Edit);

shareObject & shareObjectRaw

Applies to: Web

Allows you to share any shareable object in a web by providing the appropriate parameters. These two methods differ in that shareObject will try and fix up your query based on the supplied parameters where shareObjectRaw will send your supplied json object directly to the server. The later method is provided for the greatest amount of flexibility.

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import { ISharingResult, SharingRole } from "@pnp/sp/sharing";

// Share an object in this web
const result = await sp.web.shareObject("https://mysite.sharepoint.com/sites/dev/Docs/test.txt", "i:0#.f|membership|user@site.com", SharingRole.View);

// Share an object with all settings available
await sp.web.shareObjectRaw({
    url: "https://mysite.sharepoint.com/sites/dev/Docs/test.txt",
    peoplePickerInput: [{ Key: "i:0#.f|membership|user@site.com" }],
    roleValue: "role: 1973741327",
    groupId: 0,
    propagateAcl: false,
    sendEmail: true,
    includeAnonymousLinkInEmail: false,
    emailSubject: "subject",
    emailBody: "body",
    useSimplifiedRoles: true,
});

unshareObject

Applies to: Web

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import { ISharingResult } from "@pnp/sp/sharing";

const result = await sp.web.unshareObject("https://mysite.sharepoint.com/sites/dev/Docs/test.txt");

checkSharingPermissions

Applies to: Item, Folder, File

Checks Permissions on the list of Users and returns back role the users have on the Item.

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing/folders";
import "@pnp/sp/folders/web";
import { SharingEntityPermission } from "@pnp/sp/sharing";

// check the sharing permissions for a folder
const perms = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").checkSharingPermissions([{ alias: "i:0#.f|membership|user@site.com" }]);

getSharingInformation

Applies to: Item, Folder, File

Get Sharing Information.

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import "@pnp/sp/folders";
import { ISharingInformation } from "@pnp/sp/sharing";

// Get the sharing information for a folder
const info = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").getSharingInformation();

getObjectSharingSettings

Applies to: Item, Folder, File

Gets the sharing settings

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import "@pnp/sp/folders";
import { IObjectSharingSettings } from "@pnp/sp/sharing";

// Gets the sharing object settings
const settings: IObjectSharingSettings = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").getObjectSharingSettings();

unshare

Applies to: Item, Folder, File

Unshares a given resource

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import "@pnp/sp/folders";
import { ISharingResult } from "@pnp/sp/sharing";

const result: ISharingResult = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").unshare();

deleteSharingLinkByKind

Applies to: Item, Folder, File

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import "@pnp/sp/folders";
import { ISharingResult, SharingLinkKind } from "@pnp/sp/sharing";

const result: ISharingResult = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").deleteSharingLinkByKind(SharingLinkKind.AnonymousEdit);

unshareLink

Applies to: Item, Folder, File

import { sp } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/sharing";
import "@pnp/sp/folders";
import { SharingLinkKind } from "@pnp/sp/sharing";

await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").unshareLink(SharingLinkKind.AnonymousEdit);

// specify the sharing link id if available
await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").unshareLink(SharingLinkKind.AnonymousEdit, "12345");